@bovinphang/frontend-craft 2.8.0 → 2.9.0

package/CONTRIBUTING.md

@@ -1,361 +1,371 @@
-# Contributing Guide
-
-Thanks for your interest in `frontend-craft`. Issues, pull requests, documentation fixes, runtime adapters, and better examples are all welcome.
-
-**Simplified Chinese:** [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)
-
-## Development Setup
-
-- Node.js >= 22 for the universal installer and OpenClaw package build.
-- Git.
-- Run `npm install` before local development.
-
-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                         # 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
-
-```
-├── agents/          # Agent definitions (Markdown + YAML frontmatter)
-├── bin/             # CLI entry point (frontend-craft.ts)
-├── commands/        # Custom commands (fec-init, fec-review, fec-scaffold)
-├── docs/            # Runtime installation docs and localized READMEs
-├── hooks/           # Hook configuration (hooks.json)
-├── scripts/         # Source-run maintenance scripts (build, packaging, publishing checks)
-├── skills/          # Skill definitions (SKILL.md, metadata.json)
-├── src/             # Source code
-│   ├── hooks/       # Runtime hook source bundled to dist/hooks/
-│   ├── install/     # Installer core (CLI, interactive wizard, runtime converters)
-│   └── openclaw/    # OpenClaw runtime TypeScript source
-├── templates/       # Templates (Claude/Codex/OpenClaw configs + shared rules)
-├── tests/           # Test suite
-│   ├── converters/  # Converter tests
-│   └── install/     # Installer tests (CLI, E2E, all-runtimes dry-run)
-└── package.json     # Project configuration and scripts
-```
-
-## Local Development and Debugging
-
-```bash
-# 1. Install dependencies
-npm install
-
-# 2. Build dist/bin and dist/hooks
-npm run build
-
-# 3. Install to a specific runtime (e.g., claude)
-node dist/bin/frontend-craft.js install claude --local --dry-run  # preview first
-node dist/bin/frontend-craft.js install claude --local            # actual install
-
-# 4. Install to all runtimes
-node dist/bin/frontend-craft.js install --all --dry-run
-
-# 5. List all supported runtimes
-node dist/bin/frontend-craft.js list
-```
-
-`npm run build` runs `clean`, `typecheck`, and `scripts/build-dist.ts`. Run it before using `dist/bin/frontend-craft.js` or the bundled hook scripts locally.
-
-## Testing
-
-Tests use Node.js built-in `node:test` with `assert/strict`.
-
-```bash
-# Run all tests
-npm test
-
-# Run a single test file
-node --import tsx --test tests/install/cli.test.ts
-
-# Run installer tests
-node --import tsx --test tests/install/*.test.ts
-
-# Run converter tests
-node --import tsx --test tests/converters/*.test.ts
-
-# Run all-runtimes dry-run test
-node --import tsx --test tests/install/all-runtimes-dry.test.ts
-```
-
-For testing the interactive installation wizard, set `FRONTEND_CRAFT_FORCE_INTERACTIVE=1`:
-
-```bash
-FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
-```
-
-`npm test` runs `npm run build` first, then executes the curated converter and installer test suite from `tests/`.
-
-## OpenClaw Build
-
-The OpenClaw runtime has its own build pipeline:
-
-```bash
-npm run build:openclaw          # Bundle TypeScript to dist/openclaw/ via esbuild
-npm run typecheck:openclaw      # TypeScript type checking
-npm run check:openclaw-dist     # Verify dist integrity
-npm run pack:openclaw           # Full build + verify + package
-```
-
-Source: `src/openclaw/` (TypeScript) → `dist/openclaw/index.js` (bundled ESM).
-TypeScript config: `tsconfig.openclaw.json`.
-
-## Standalone Skill Packages
-
-The canonical skill sources live under `skills/<skill-id>/`. Do not edit generated files under `skill-packages/` by hand.
-
-```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               # 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.
-
-When changing a skill, keep these source files aligned:
-
-- `skills/<skill-id>/SKILL.md` — canonical runtime instruction.
-- `skills/metadata.json` — publish metadata, category, tags, keywords, platform targets, and package version.
-- `skills/eval_queries.json` — positive and negative trigger examples used by routing quality checks.
-- `README.md` and localized README summaries when the public skill list or user-facing behavior changes.
-
-## NPM Scripts
-
-Use `package.json` scripts as the public development entrypoints.
-
-| Script                         | Purpose                                                                          |
-| ------------------------------ | -------------------------------------------------------------------------------- |
-| `npm run clean`                | Remove `dist/`.                                                                  |
-| `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.                     |
-| `npm run audit:skills`         | Build, then report skill instruction size and description overlap signals.       |
-| `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 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`.                                                         |
-| `npm run prepublishOnly`       | Sync versions and run tests before npm publish.                                  |
-
-For common change types:
-
-- Skill changes: run `npm test`, `npm run audit:skills`, `npm run pack:skills`, and `npm run check:skills-publish`.
-- OpenClaw changes: run `npm run typecheck:openclaw` and `npm run pack:openclaw`.
-- Release packaging: run `npm run pack:all`; `prepublishOnly` also runs version sync and tests before publish.
-
-## Source Maintenance Files
-
-Maintenance scripts live under `scripts/` and run from source with `tsx`; they are not published as `dist/scripts`.
-
-| File                                       | Purpose                              |
-| ------------------------------------------ | ------------------------------------ |
-| `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     |
-| `scripts/check-skills-publish.ts`          | Standalone skill package verifier    |
-| `scripts/skill-packaging.ts`               | Shared skill packaging helpers       |
-| `scripts/openclaw/build.ts`                | OpenClaw esbuild bundler             |
-| `scripts/openclaw/pack-openclaw.ts`        | OpenClaw packaging                   |
-| `scripts/openclaw/verify-openclaw-dist.ts` | Verify OpenClaw dist completeness    |
-
-## Runtime Hook Scripts
-
-Hook scripts live under `src/hooks/` and are bundled into `dist/hooks/` for published runtime use. Maintenance scripts live under `scripts/` and run from source with `tsx`; they are not published as `dist/scripts`.
-
-| Source file                        | Bundled output                      | Purpose                |
-| ---------------------------------- | ----------------------------------- | ---------------------- |
-| `src/hooks/run-tests.ts`           | `dist/hooks/run-tests.js`           | Test runner helper     |
-| `src/hooks/format-changed-file.ts` | `dist/hooks/format-changed-file.js` | Format changed files   |
-| `src/hooks/security-check.ts`      | `dist/hooks/security-check.js`      | Security scanning      |
-| `src/hooks/notify.ts`              | `dist/hooks/notify.js`              | Notification script    |
-| `src/hooks/session-start.ts`       | `dist/hooks/session-start.js`       | Session initialization |
-
-## Architecture Overview
-
-The universal installer follows this architecture:
-
-```
-bin/frontend-craft.ts
-  └─ src/install/cli.ts              # CLI entry (parse commands: install/list/version/uninstall)
-       ├─ src/install/registry.ts    # Runtime registry (names + installer map)
-       ├─ src/install/converters/     # Per-runtime adapters (claude, codex, cursor, copilot, etc.)
-       ├─ src/install/interactive.ts # Interactive wizard (runtime/location prompts)
-       ├─ src/install/runtime-homes.ts # Global/local directory conventions
-       └─ src/install/types.ts       # Shared TypeScript types
-```
-
-Each runtime converter under `src/install/converters/` implements the `InstallContext` interface from `types.ts`, writing skills, agents, commands, hooks, and templates to the target runtime's configuration directory.
-
-## Branch Strategy
-
-- `main` - stable release branch.
-- `develop` - development branch, if used.
-- `feature/<name>` - new features.
-- `fix/<name>` - bug fixes.
-- `docs/<name>` - documentation updates.
-
-## Commit Convention
-
-Use [Conventional Commits](https://www.conventionalcommits.org/):
-
-```text
-<type>(<scope>): <description>
-
-[optional body]
-[optional footer]
-```
-
-Common types:
-
-| Type       | Meaning                        |
-| ---------- | ------------------------------ |
-| `feat`     | New feature                    |
-| `fix`      | Bug fix                        |
-| `docs`     | Documentation                  |
-| `refactor` | Refactoring                    |
-| `test`     | Tests                          |
-| `chore`    | Build, tooling, or maintenance |
-
-Examples:
-
-```text
-feat(skills): add e2e testing skill
-fix(hooks): resolve Windows path handling
-docs(readme): update installation steps
-```
-
-## Language and Documentation Policy
-
-English is the source language for public project governance, runtime documentation, release notes, and GitHub collaboration templates. Localized README files should stay user-focused and link back to English docs for detailed contributor or maintainer workflows.
-
-When a pull request changes public behavior, installation steps, runtimes, agents, skills, commands, or hooks:
-
-- Update `README.md` and `CHANGELOG.md` first (and [`CHANGELOG.zh-CN.md`](CHANGELOG.zh-CN.md) when the change is release-noteworthy for Chinese readers).
-- Sync user-facing summaries in `README.zh-CN.md`, `docs/zh-TW/README.md`, `docs/ja-JP/README.md`, and `docs/ko-KR/README.md` when the change affects users.
-- Claude Code Marketplace install and update steps are maintained in [`docs/runtimes/claude.md`](docs/runtimes/claude.md) and [`docs/runtimes/claude.zh-CN.md`](docs/runtimes/claude.zh-CN.md). When that flow changes, update those files (the root README and localized READMEs only link there).
-- If translations cannot be completed in the same pull request, open or link a follow-up issue and mention it in the PR description.
-- Keep code examples, runtime names, command names, file paths, and package names consistent across languages.
-
-Issues and pull requests are easiest to review in English. If you are more comfortable writing in Chinese, that is also welcome; maintainers can help translate titles and summaries when needed.
-
-## Adding a Skill
-
-1. Create a directory under `skills/`, for example `skills/fec-my-skill/`.
-2. Add `SKILL.md` with YAML frontmatter and concise instructions:
-
-```markdown
----
-name: fec-my-skill
-description: Use when the user needs ...
----
-
-# Skill Title
-
-## When to Use
-
-- ...
-
-## Core Rules
-
-- ...
-```
-
-3. Add an entry to `skills/metadata.json` with `id`, display `name`, taxonomy `category`, `tags`, `summary`, publish metadata, `keywords`, and `platforms`. The `version`, `license`, `homepage`, and `repository` fields should match `package.json`.
-4. Add positive and negative trigger examples to `skills/eval_queries.json`.
-5. Add the skill to the Skills table in `README.md`.
-6. Update the repository tree in `README.md` and localized README files if the visible structure changes.
-7. Run `npm test`, `npm run pack:skills`, and `npm run check:skills-publish`.
-
-## Adding an Agent
-
-1. Create `agents/my-agent.md`.
-2. Define the YAML frontmatter:
-
-```markdown
----
-name: my-agent
-description: Use this agent when ...
-tools: Read, Edit, Write, Glob, Grep, Bash
-model: sonnet
-skills:
-  - relevant-skill
----
-```
-
-1. Update the Agents table in `README.md`.
-2. Sync `README.zh-CN.md`, `docs/*/README.md`, and `.claude-plugin/marketplace.json` when counts or user-facing descriptions change.
-
-## Adding a Command
-
-1. Create `commands/my-command.md`.
-2. Use YAML frontmatter and Markdown steps.
-3. Update the Commands table in `README.md` and localized user-facing summaries as needed.
-
-## Adding a Rule Template
-
-1. Create `templates/shared/rules/my-rule.md`.
-2. Add it to the copy list in `commands/fec-init.md`.
-3. Update `templates/claude/CLAUDE.md` rule import examples when applicable.
-
-## Universal Installer
-
-- Entry point: `bin/frontend-craft.ts` (compiled to `dist/bin/frontend-craft.js`).
-- Implementation: `src/install/` (converters, registry, path helpers).
-- Interactive prompts and input parsing: `src/install/interactive.ts` (tests may set `FRONTEND_CRAFT_FORCE_INTERACTIVE=1` to exercise stdin-fed prompts).
-- Register a new runtime in `src/install/registry.ts`.
-- Add the runtime installer under `src/install/converters/`.
-- Follow global directory conventions from `src/install/runtime-homes.ts`.
-- Add or update tests under `tests/install/`.
-
-## Adding a Hook
-
-1. Update `hooks/hooks.json`.
-2. Put runtime hook scripts under `src/hooks/` and prefer cross-platform Node.js.
-3. Add each new hook entrypoint to `scripts/build-dist.ts` so `npm run build` bundles it into `dist/hooks/`.
-4. In `hooks/hooks.json`, use **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`** for bundled hook entrypoints (Claude Code substitutes the root at runtime; see the official [Plugins reference](https://code.claude.com/docs/en/plugins-reference)). The Claude installer in this repo also expands **`${CLAUDE_PLUGIN_ROOT}`** and legacy **`${FRONTEND_CRAFT_ROOT}`** to absolute paths when it writes `hooks.json` under `.claude/`.
-5. Keep repository maintenance scripts under `scripts/`; do not reference them directly from runtime hook configuration.
-6. Update the Hooks table in `README.md`.
-
-## Pull Request Checklist
-
-Before opening a pull request:
-
-- [ ] The change is scoped and described clearly.
-- [ ] `npm test` passes.
-- [ ] Skill changes pass `npm run audit:skills`, `npm run pack:skills`, and `npm run check:skills-publish`.
-- [ ] `npm run typecheck:openclaw` and `npm run pack:openclaw` pass when OpenClaw code or templates are affected.
-- [ ] `README.md` and `CHANGELOG.md` are updated when user-facing behavior changes (and `CHANGELOG.zh-CN.md` when you ship Chinese-facing release notes).
-- [ ] Localized README files are synced, or a follow-up translation issue is linked.
-- [ ] New runtime, agent, skill, command, hook, or template changes include relevant tests or dry-run coverage.
-- [ ] Release packaging changes pass `npm run pack:all` or are covered by the `prepublishOnly` publish gate.
-- [ ] Security-sensitive changes have been reviewed against `SECURITY.md`.
-
-## Code Style
-
-- Prefer clear Markdown with stable headings and tables.
-- Keep skill and agent descriptions concise because model routing depends on them.
-- Use cross-platform Node.js scripts for automation.
-- Avoid shell-specific assumptions unless a runtime explicitly requires them.
-
-## Reporting Issues
-
-Use [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) for bugs and feature requests. Include the runtime, operating system, Node.js version, exact command, expected behavior, and actual behavior whenever possible.
-
-Do not file security-sensitive vulnerabilities as public issues. Follow [SECURITY.md](SECURITY.md) instead.
+# Contributing Guide
+
+Thanks for your interest in `frontend-craft`. Issues, pull requests, documentation fixes, runtime adapters, and better examples are all welcome.
+
+**Simplified Chinese:** [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)
+
+## Development Setup
+
+- Node.js >= 22 for the universal installer and OpenClaw package build.
+- Git.
+- pnpm 12.4.1 (pinned in package.json); installing pnpm through npm requires Node.js >=22.13. The published plugin still supports Node.js >=22.0.0.
+- pnpm-lock.yaml is the sole dependency lockfile. pnpm-workspace.yaml permits esbuild build scripts and explicitly skips optional SDK/native setup not used by this project.
+- Run `pnpm install --frozen-lockfile` before local development.
+
+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):
+
+`pnpm lint` checks source code and both content languages. `pnpm format:check` checks changed source/config files without modifying them. `pnpm test` recursively discovers `tests/**/*.test.ts`, so new tests need no script-list update.
+
+```bash
+pnpm test                         # General validation
+pnpm run pack:skills              # Skill changes
+pnpm run check:skills-publish     # Skill changes
+pnpm run typecheck:openclaw       # OpenClaw changes
+```
+
+See the Development Scripts section and Pull Request Checklist for complete scenario-specific checks.
+
+## Project Structure
+
+```
+├── agents/          # Agent definitions (Markdown + YAML frontmatter)
+├── bin/             # CLI entry point (frontend-craft.ts)
+├── commands/        # Custom commands (fec-init, fec-review, fec-scaffold)
+├── docs/            # Runtime installation docs and localized READMEs
+├── hooks/           # Hook configuration (hooks.json)
+├── scripts/         # Source-run maintenance scripts (build, packaging, publishing checks)
+├── skills/          # Skill definitions (SKILL.md, metadata.json)
+├── src/             # Source code
+│   ├── hooks/       # Runtime hook source bundled to dist/hooks/
+│   ├── install/     # Installer core (CLI, interactive wizard, runtime converters)
+│   └── openclaw/    # OpenClaw runtime TypeScript source
+├── templates/       # Templates (Claude/Codex/OpenClaw configs + shared rules)
+├── tests/           # Test suite
+│   ├── converters/  # Converter tests
+│   └── install/     # Installer tests (CLI, E2E, all-runtimes dry-run)
+└── package.json     # Project configuration and scripts
+```
+
+## Local Development and Debugging
+
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Build dist/bin and dist/hooks
+pnpm run build
+
+# 3. Install to a specific runtime (e.g., claude)
+node dist/bin/frontend-craft.js install claude --local --dry-run  # preview first
+node dist/bin/frontend-craft.js install claude --local            # actual install
+
+# 4. Install to all runtimes
+node dist/bin/frontend-craft.js install --all --dry-run
+
+# 5. List all supported runtimes
+node dist/bin/frontend-craft.js list
+```
+
+`pnpm run build` runs `clean`, `typecheck`, and `scripts/build-dist.ts`. Run it before using `dist/bin/frontend-craft.js` or the bundled hook scripts locally.
+
+## Testing
+
+Tests use Node.js built-in `node:test` with `assert/strict`.
+
+```bash
+# Run all tests
+pnpm test
+
+# Run a single test file
+node --import tsx --test tests/install/cli.test.ts
+
+# Run installer tests
+node --import tsx --test tests/install/*.test.ts
+
+# Run converter tests
+node --import tsx --test tests/converters/*.test.ts
+
+# Run all-runtimes dry-run test
+node --import tsx --test tests/install/all-runtimes-dry.test.ts
+```
+
+For testing the interactive installation wizard, set `FRONTEND_CRAFT_FORCE_INTERACTIVE=1`:
+
+```bash
+FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
+```
+
+`pnpm test` runs `pnpm run build` first, then executes the curated converter and installer test suite from `tests/`.
+
+## OpenClaw Build
+
+The OpenClaw runtime has its own build pipeline:
+
+```bash
+pnpm run build:openclaw          # Bundle TypeScript to dist/openclaw/ via esbuild
+pnpm run typecheck:openclaw      # TypeScript type checking
+pnpm run check:openclaw-dist     # Verify dist integrity
+pnpm run pack:openclaw           # Full build + verify + package
+```
+
+Source: `src/openclaw/` (TypeScript) → `dist/openclaw/index.js` (bundled ESM).
+TypeScript config: `tsconfig.openclaw.json`.
+
+## Standalone Skill Packages
+
+The canonical skill sources live under `skills/<skill-id>/`. Do not edit generated files under `skill-packages/` by hand.
+
+```bash
+pnpm run pack:skills            # Build one standalone package per skill
+pnpm run check:skills-publish   # Verify package metadata, index, and copied references
+pnpm run pack:all               # Build + test + OpenClaw package + standalone skill packages
+```
+
+`pnpm 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.
+
+When changing a skill, keep these source files aligned:
+
+- `skills/<skill-id>/SKILL.md` — canonical runtime instruction.
+- `skills/metadata.json` — publish metadata, category, tags, keywords, platform targets, and package version.
+- `skills/eval_queries.json` — positive and negative trigger examples used by routing quality checks.
+- `README.md` and localized README summaries when the public skill list or user-facing behavior changes.
+
+## Development Scripts
+
+Use `package.json` scripts as the public development entrypoints.
+
+| Script                         | Purpose                                                                          |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| `pnpm run lint` | Check code and bilingual content declarations. |
+| `pnpm run format:check` | Check changed source formatting. |
+| `pnpm run check:content` | Validate YAML, names, references and localization structure. |
+| `pnpm run clean`                | Remove `dist/`.                                                                  |
+| `pnpm run typecheck`            | Run main TypeScript checks plus checked skill support scripts.                   |
+| `pnpm run build`                | Run `clean`, `typecheck`, and bundle CLI/hooks via `scripts/build-dist.ts`.      |
+| `pnpm test`                     | Build, then run the curated `node:test` suite with `tsx`.                        |
+| `pnpm run build:openclaw`       | Build the main project, then bundle OpenClaw runtime output.                     |
+| `pnpm run audit:skills`         | Build, then report skill instruction size and description overlap signals.       |
+| `pnpm run typecheck:openclaw`   | Run TypeScript checking for OpenClaw with `tsconfig.openclaw.json`.              |
+| `pnpm run check:openclaw-dist`  | Verify the generated OpenClaw dist output.                                       |
+| `pnpm run pack:openclaw`        | Build, verify, and package the OpenClaw plugin.                                  |
+| `pnpm run pack:skills`          | Build first, then create standalone packages under `skill-packages/`.            |
+| `pnpm run check:skills-publish` | Build first, then verify standalone skill package metadata and copied files.     |
+| `pnpm run pack:all`             | Build, run tests, package OpenClaw, package skills, and verify skill output.     |
+| `pnpm run sync:version`         | Sync package version metadata across release manifests.                          |
+| `pnpm run version`              | Sync versioned manifests without automatically staging files.    |
+| `pnpm run prepack`              | Build before `npm pack`.                                                         |
+| `pnpm run prepublishOnly`       | Sync versions and run tests before npm publish.                                  |
+
+For common change types:
+
+- Skill changes: run `pnpm test`, `pnpm run audit:skills`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
+- OpenClaw changes: run `pnpm run typecheck:openclaw` and `pnpm run pack:openclaw`.
+- Release packaging: CI runs `pnpm run pack:all`; `prepublishOnly` also runs version sync and tests before publish.
+
+## Source Maintenance Files
+
+Maintenance scripts live under `scripts/` and run from source with `tsx`; they are not published as `dist/scripts`.
+
+| File                                       | Purpose                              |
+| ------------------------------------------ | ------------------------------------ |
+| `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     |
+| `scripts/check-skills-publish.ts`          | Standalone skill package verifier    |
+| `scripts/skill-packaging.ts`               | Shared skill packaging helpers       |
+| `scripts/openclaw/build.ts`                | OpenClaw esbuild bundler             |
+| `scripts/openclaw/pack-openclaw.ts`        | OpenClaw packaging                   |
+| `scripts/openclaw/verify-openclaw-dist.ts` | Verify OpenClaw dist completeness    |
+
+## Runtime Hook Scripts
+
+Hook scripts live under `src/hooks/` and are bundled into `dist/hooks/` for published runtime use. Maintenance scripts live under `scripts/` and run from source with `tsx`; they are not published as `dist/scripts`.
+
+| Source file                        | Bundled output                      | Purpose                |
+| ---------------------------------- | ----------------------------------- | ---------------------- |
+| `src/hooks/cleanup-claude-cache.ts` | `dist/hooks/fec-cleanup-claude-cache.js` | Cache cleanup |
+| `src/hooks/run-tests.ts`           | `dist/hooks/fec-run-tests.js`           | Test runner helper     |
+| `src/hooks/format-changed-file.ts` | `dist/hooks/fec-format-changed-file.js` | Format changed files   |
+| `src/hooks/security-check.ts`      | `dist/hooks/fec-security-check.js`      | Security scanning      |
+| `src/hooks/notify.ts`              | `dist/hooks/fec-notify.js`              | Notification script    |
+| `src/hooks/session-start.ts`       | `dist/hooks/fec-session-start.js`       | Session initialization |
+
+## Architecture Overview
+
+The universal installer follows this architecture:
+
+```
+bin/frontend-craft.ts
+  └─ src/install/cli.ts              # CLI entry (parse commands: install/list/version/uninstall)
+       ├─ src/install/registry.ts    # Runtime registry (names + installer map)
+       ├─ src/install/converters/     # Per-runtime adapters (claude, codex, cursor, copilot, etc.)
+       ├─ src/install/interactive.ts # Interactive wizard (runtime/location prompts)
+       ├─ src/install/runtime-homes.ts # Global/local directory conventions
+       └─ src/install/types.ts       # Shared TypeScript types
+```
+
+Each runtime converter under `src/install/converters/` implements the `InstallContext` interface from `types.ts`, writing skills, agents, commands, hooks, and templates to the target runtime's configuration directory.
+
+## Branch Strategy
+
+- `main` - stable release branch.
+- `develop` - development branch, if used.
+- `feature/<name>` - new features.
+- `fix/<name>` - bug fixes.
+- `docs/<name>` - documentation updates.
+
+## Commit Convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+[optional footer]
+```
+
+Common types:
+
+| Type       | Meaning                        |
+| ---------- | ------------------------------ |
+| `feat`     | New feature                    |
+| `fix`      | Bug fix                        |
+| `docs`     | Documentation                  |
+| `refactor` | Refactoring                    |
+| `test`     | Tests                          |
+| `chore`    | Build, tooling, or maintenance |
+
+Examples:
+
+```text
+feat(skills): add e2e testing skill
+fix(hooks): resolve Windows path handling
+docs(readme): update installation steps
+```
+
+## Language and Documentation Policy
+
+English is the source language for public project governance, runtime documentation, release notes, and GitHub collaboration templates. Localized README files should stay user-focused and link back to English docs for detailed contributor or maintainer workflows.
+
+When a pull request changes public behavior, installation steps, runtimes, agents, skills, commands, or hooks:
+
+- Update `README.md` and `CHANGELOG.md` first (and [`CHANGELOG.zh-CN.md`](CHANGELOG.zh-CN.md) when the change is release-noteworthy for Chinese readers).
+- Sync user-facing summaries in `README.zh-CN.md`, `docs/zh-TW/README.md`, `docs/ja-JP/README.md`, and `docs/ko-KR/README.md` when the change affects users.
+- Claude Code Marketplace install and update steps are maintained in [`docs/runtimes/claude.md`](docs/runtimes/claude.md) and [`docs/runtimes/claude.zh-CN.md`](docs/runtimes/claude.zh-CN.md). When that flow changes, update those files (the root README and localized READMEs only link there).
+- If translations cannot be completed in the same pull request, open or link a follow-up issue and mention it in the PR description.
+- Keep code examples, runtime names, command names, file paths, and package names consistent across languages.
+
+Issues and pull requests are easiest to review in English. If you are more comfortable writing in Chinese, that is also welcome; maintainers can help translate titles and summaries when needed.
+
+## Adding a Skill
+
+1. Create a directory under `skills/`, for example `skills/fec-my-skill/`.
+2. Add `SKILL.md` with YAML frontmatter and concise instructions:
+
+```markdown
+---
+name: fec-my-skill
+description: Use when the user needs ...
+---
+
+# Skill Title
+
+## When to Use
+
+- ...
+
+## Core Rules
+
+- ...
+```
+
+3. Add an entry to `skills/metadata.json` with `id`, display `name`, taxonomy `category`, `tags`, `summary`, publish metadata, `keywords`, and `platforms`. The `version`, `license`, `homepage`, and `repository` fields should match `package.json`.
+4. Add positive and negative trigger examples to `skills/eval_queries.json`.
+5. Add the skill to the Skills table in `README.md`.
+6. Update the repository tree in `README.md` and localized README files if the visible structure changes.
+7. Run `pnpm test`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
+
+## Adding an Agent
+
+1. Create `agents/my-agent.md`.
+2. Define the YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: Use this agent when ...
+tools: Read, Edit, Write, Glob, Grep, Bash
+model: sonnet
+skills:
+  - relevant-skill
+---
+```
+
+1. Update the Agents table in `README.md`.
+2. Sync `README.zh-CN.md`, `docs/*/README.md`, and `.claude-plugin/marketplace.json` when counts or user-facing descriptions change.
+
+## Adding a Command
+
+1. Create `commands/my-command.md`.
+2. Use YAML frontmatter and Markdown steps.
+3. Update the Commands table in `README.md` and localized user-facing summaries as needed.
+
+## Adding a Rule Template
+
+1. Create `templates/shared/rules/my-rule.md`.
+2. Add it to the copy list in `commands/fec-init.md`.
+3. Update `templates/claude/CLAUDE.md` rule import examples when applicable.
+
+## Universal Installer
+
+- Entry point: `bin/frontend-craft.ts` (compiled to `dist/bin/frontend-craft.js`).
+- Implementation: `src/install/` (converters, registry, path helpers).
+- Interactive prompts and input parsing: `src/install/interactive.ts` (tests may set `FRONTEND_CRAFT_FORCE_INTERACTIVE=1` to exercise stdin-fed prompts).
+- Register a new runtime in `src/install/registry.ts`.
+- Add the runtime installer under `src/install/converters/`.
+- Follow global directory conventions from `src/install/runtime-homes.ts`.
+- Add or update tests under `tests/install/`.
+
+## Adding a Hook
+
+1. Update `hooks/hooks.json`.
+2. Put runtime hook scripts under `src/hooks/` and prefer cross-platform Node.js.
+3. Add each new hook entrypoint to `scripts/build-dist.ts` so `pnpm run build` bundles it into `dist/hooks/`.
+4. In `hooks/hooks.json`, use **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`** for bundled hook entrypoints (Claude Code substitutes the root at runtime; see the official [Plugins reference](https://code.claude.com/docs/en/plugins-reference)). The Claude installer in this repo also expands **`${CLAUDE_PLUGIN_ROOT}`** and legacy **`${FRONTEND_CRAFT_ROOT}`** to absolute paths when it writes `hooks.json` under `.claude/`.
+5. Keep repository maintenance scripts under `scripts/`; do not reference them directly from runtime hook configuration.
+6. Update the Hooks table in `README.md`.
+
+## Pull Request Checklist
+
+Before opening a pull request:
+
+- [ ] The change is scoped and described clearly.
+- [ ] `pnpm test` passes.
+- [ ] Skill changes pass `pnpm run audit:skills`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
+- [ ] `pnpm run typecheck:openclaw` and `pnpm run pack:openclaw` pass when OpenClaw code or templates are affected.
+- [ ] `README.md` and `CHANGELOG.md` are updated when user-facing behavior changes (and `CHANGELOG.zh-CN.md` when you ship Chinese-facing release notes).
+- [ ] Localized README files are synced, or a follow-up translation issue is linked.
+- [ ] New runtime, agent, skill, command, hook, or template changes include relevant tests or dry-run coverage.
+- [ ] Release packaging changes pass `pnpm run pack:all` or are covered by the `prepublishOnly` publish gate.
+- [ ] Security-sensitive changes have been reviewed against `SECURITY.md`.
+
+## Code Style
+
+- Prefer clear Markdown with stable headings and tables.
+- Keep skill and agent descriptions concise because model routing depends on them.
+- Use cross-platform Node.js scripts for automation.
+- Avoid shell-specific assumptions unless a runtime explicitly requires them.
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) for bugs and feature requests. Include the runtime, operating system, Node.js version, exact command, expected behavior, and actual behavior whenever possible.
+
+Do not file security-sensitive vulnerabilities as public issues. Follow [SECURITY.md](SECURITY.md) instead.
+
+When changing review or diagram capabilities, synchronize scope defaults, natural-language examples, tool prerequisites, QA limits, and coverage reporting across README translations and runtime guides. See [review scope and technical diagram delivery](docs/review-and-diagram-workflows.md).