viepilot 1.9.2 → 1.9.5

package/CHANGELOG.md

@@ -15,6 +15,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - None yet.
 
+### Changed
+
+- None yet.
+
+## [1.9.5] - 2026-04-02
+
+### Added
+
+- **M1.29 / Phase 35 (ENH-022)** — Crystallize **Step 4** ghi thêm **`.viepilot/architecture/<diagram>.mermaid`** (raw Mermaid, mirror khối fenced trong `ARCHITECTURE.md`); bảng tên canonical + policy trong `workflows/crystallize.md`; template `templates/project/ARCHITECTURE.md` có **Diagram source files** và dòng path từng section; **vp-crystallize** 0.5.2, **vp-audit** 0.3.2; `docs/skills-reference.md`; `tests/unit/vp-enh022-crystallize-architecture-files-contracts.test.js` (**308** tests).
+
+## [1.9.4] - 2026-04-02
+
+### Fixed
+
+- **Installer / Claude Code** — `npx viepilot install --target claude-code` giờ **copy** (hoặc symlink nếu `VIEPILOT_SYMLINK_SKILLS=1`) toàn bộ `skills/vp-*` vào **`~/.claude/skills/`**, không chỉ `~/.cursor/skills/`. `uninstall --target claude-code` gỡ `~/.claude/skills/vp-*`. (`lib/viepilot-install.cjs`, `bin/viepilot.cjs`; tests + `docs/user/claude-code-setup.md`, FAQ).
+
+## [1.9.3] - 2026-04-02
+
+### Added
+
+- **M1.29 / Phase 34 (FEAT-001)** — Hướng dẫn ViePilot trên **Claude Code**: `docs/user/claude-code-setup.md` (installer `npx viepilot install --target claude-code`, map `vp-*` → `~/.claude/skills`, `vp-tools info`, chuỗi request → evolve → auto); cross-links trong `docs/getting-started.md`, `docs/user/quick-start.md`, `docs/user/faq.md`, `docs/README.md`; `tests/unit/vp-feat001-claude-code-docs-contracts.test.js`; README test metrics **299** / **15** suites.
+
 ## [1.9.2] - 2026-04-03
 
 ### Changed

package/README.md

@@ -2,15 +2,15 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-1.9.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.9.5-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-297%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-308%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Versioning:** Shield **1.9.2** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.2**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.9.5** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.5**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
 
 ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) phát triển dự án một cách **tự động**, **có kiểm soát**, và **có thể khôi phục**. Thiết kế theo các tiêu chuẩn chuyên nghiệp: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
@@ -28,13 +28,13 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~27,113+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~27,991+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **297** (14 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + viepilot-info/update/install) |
-| ViePilot phases (local `.viepilot`) | **32** phase cycles — **M1.28** FEAT-010 (**v1.9.1**); patch **v1.9.2** (ENH-019~021); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
+| Tests | **308** (16 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + FEAT-001 Claude Code + ENH-022 crystallize architecture files + viepilot-info/update/install) |
+| ViePilot phases (local `.viepilot`) | **34** phase cycles — **M1.29** FEAT-001 (**v1.9.3** doc); patch **v1.9.4** (Claude installer); **M1.28** FEAT-010 (**v1.9.1**); **v1.9.2** (ENH-019~021); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
 > Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
@@ -48,14 +48,14 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
 | CLI Tools | 2 | vp-tools.cjs (**17** subcommands) + viepilot.cjs (guided installer) |
-| Test Files | 14 | Jest: 13 unit + 1 integration (contracts, installer, info/update, FEAT-009, FEAT-010, ENH-021, scope policy, …) |
+| Test Files | 15 | Jest: 14 unit + 1 integration (contracts, installer + Claude paths, info/update, FEAT-009, FEAT-010, FEAT-001, ENH-021, scope policy, …) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.2** (ENH-019~021: `/research-ui` stress + **implementation routing guard**); **v1.9.1** FEAT-010; **v1.9.0** FEAT-009
+Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.4** (Claude Code **installer** ~/.claude/skills); **v1.9.3** FEAT-001 doc; **v1.9.2** (ENH-019~021); **v1.9.1** FEAT-010; **v1.9.0** FEAT-009
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
@@ -65,7 +65,7 @@ Tổng thể / Overall:  ██████████████████
 | Project Templates (12) | ✅ Hoàn thiện | Placeholders cho customization (+ `VIEPILOT-META` FEAT-009) |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
 | CLI Tools (18) | ✅ Hoàn thiện | vp-tools 17 subcommands + viepilot installer; bundle `info` / `update` |
-| Tests (297) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010, ENH-021, info/update |
+| Tests (304) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010/001, ENH-021, info/update |
 | CI/CD | ✅ Hoàn thiện | GitHub Actions, Node 18/20/22 matrix, coverage >80% |
 | Documentation | ✅ Hoàn thiện | dev/, user/, api/, videos/, examples/, troubleshooting |
 | Standards | ✅ Hoàn thiện | SemVer, Conventional Commits, Keep a Changelog |
@@ -393,7 +393,7 @@ viepilot/
 ├── bin/                           # CLI tools
 │   └── vp-tools.cjs               # 17 subcommands; uses ../lib/cli-shared.cjs, viepilot-info/update.cjs
 │
-├── tests/                         # Test suite (267 tests)
+├── tests/                         # Test suite (308 tests)
 │   ├── unit/                      # Unit tests
 │   │   ├── validators.test.js     # CLI subprocess + in-process coverage tests
 │   │   └── ai-provider-compat.test.js  # 142 AI compat tests

package/bin/viepilot.cjs

@@ -32,14 +32,14 @@ Usage:
   viepilot --list-targets
 
 Install options:
-  --target <id|id,id|all>   Target profile(s): claude-code,cursor-agent,cursor-ide
+  --target <id|id,id|all>   Target profile(s): claude-code (mirrors vp-* to ~/.claude/skills), cursor-agent, cursor-ide
   --yes                      Non-interactive mode (skip confirmations)
   --dry-run                  Print actions only (Node installer; no bash)
   --list-targets             Print supported targets and exit
   --help                     Show help
 
 Uninstall options:
-  --target <id|id,id|all>   Remove installed assets for selected profile(s)
+  --target <id|id,id|all>   Remove assets (claude-code: ~/.claude/skills/vp-*; cursor-*: ~/.cursor/skills/vp-*; shared: ~/.cursor/viepilot)
   --yes                     Non-interactive mode (skip confirmations)
   --dry-run                 Print actions only, do not remove files
 `);
@@ -246,7 +246,7 @@ async function interactiveTargetSelection() {
 }
 
 /**
- * One install applies the same file bundle for every target id (profiles are informational).
+ * Core bundle (workflows, bin, ~/.cursor/viepilot) is shared; `claude-code` additionally mirrors vp-* skills into ~/.claude/skills.
  * @param {string[]} selectedTargets
  * @param {boolean} dryRun
  * @returns {{ ok: boolean, code: number }}
@@ -264,7 +264,7 @@ function runInstallViaNode(selectedTargets, dryRun) {
 
   let plan;
   try {
-    plan = buildInstallPlan(pkgRoot, env, { wantPathShim });
+    plan = buildInstallPlan(pkgRoot, env, { wantPathShim, installTargets: selectedTargets });
   } catch (err) {
     console.error(err.message);
     return { ok: false, code: 1 };
@@ -273,7 +273,10 @@ function runInstallViaNode(selectedTargets, dryRun) {
   console.log('');
   console.log('ViePilot install (Node — no bash required)');
   console.log(`  Package: ${pkgRoot}`);
-  console.log(`  Targets (informational): ${selectedTargets.join(', ')}`);
+  console.log(`  Targets: ${selectedTargets.join(', ')}`);
+  if (selectedTargets.includes('claude-code')) {
+    console.log('  (claude-code → also ~/.claude/skills/vp-*)');
+  }
 
   const applied = applyInstallPlan(plan, { dryRun });
   if (applied.logs.length > 0) {
@@ -332,7 +335,8 @@ async function installCommand(rawArgs) {
     else console.log(`- ${r.target}: failed (exit ${r.code})`);
   }
   console.log('\nNext actions:');
-  console.log('- Open project in Cursor/Claude and run /vp-status');
+  console.log('- Cursor: open project and run /vp-status');
+  console.log('- Claude Code: restart session if needed so ~/.claude/skills/vp-* is picked up; then /vp-status');
   console.log('- If needed, run /vp-brainstorm then /vp-crystallize');
 
   return failed.length === 0 ? 0 : 1;
@@ -356,6 +360,17 @@ function computeUninstallPaths(targets) {
     }
   }
 
+  if (targets.some((t) => t === 'claude-code')) {
+    const claudeSkills = path.join(home, '.claude', 'skills');
+    if (fs.existsSync(claudeSkills)) {
+      for (const entry of fs.readdirSync(claudeSkills)) {
+        if (entry.startsWith('vp-')) {
+          paths.push(path.join(claudeSkills, entry));
+        }
+      }
+    }
+  }
+
   paths.push(vpRoot);
   paths.push('/usr/local/bin/vp-tools');
   paths.push('/usr/local/bin/viepilot');

package/docs/README.md

@@ -22,6 +22,7 @@
 | Document | Description |
 |----------|-------------|
 | [Quick Start](user/quick-start.md) | Install, brainstorm, crystallize, auto — 5 min guide |
+| [Claude Code setup](user/claude-code-setup.md) | Cài ViePilot trên Claude Code (`~/.claude/skills`, CLI, workflows) |
 | [FAQ](user/faq.md) | Frequently asked questions |
 
 #### Features
@@ -116,9 +117,9 @@
 | `/vp-status` | "status", "tiến độ" | Progress dashboard |
 | `/vp-info` | "version", "phiên bản" | Bundle version, npm latest, inventory |
 | `/vp-update` | "upgrade viepilot", "npm" | Upgrade ViePilot via npm |
-| `/vp-request` | "request", "feature", "bug" | Add feature/bug |
+| `/vp-request` | "request", "feature", "bug" | Log backlog; sau đó evolve + auto (ENH-021) |
 | `/vp-ui-components` | "ui components", "21st.dev" | Curate and reuse UI component library |
-| `/vp-evolve` | "evolve", "milestone mới" | New milestone |
+| `/vp-evolve` | "evolve", "milestone mới" | Planning (ROADMAP/phase); implement bằng `/vp-auto` |
 | `/vp-docs` | "docs", "documentation" | Generate docs |
 | `/vp-task` | "task", "manual" | Manual task control |
 | `/vp-debug` | "debug", "investigate" | Debug issues |
@@ -127,4 +128,4 @@
 
 ---
 
-*Last updated: 2026-04-01 — ViePilot framework **v1.9.0** (M1.27 FEAT-009: global profiles + docs workflow §0A); see `CHANGELOG.md` and `docs/dev/global-profiles.md`.*
+*Last updated: 2026-04-02 — ViePilot framework **v1.9.4** (Claude Code installer → `~/.claude/skills`; FEAT-001 doc v1.9.3; ENH-021 routing; M1.27 FEAT-009 profiles); see `CHANGELOG.md`, [Claude Code setup](user/claude-code-setup.md), `docs/user/features/autonomous-mode.md`.*

package/docs/getting-started.md

@@ -27,6 +27,10 @@ cd viepilot
 ./install.sh
 ```
 
+### Claude Code
+
+Nếu bạn dùng **Claude Code** thay vì Cursor, làm theo [ViePilot trên Claude Code](user/claude-code-setup.md) (skills trong `~/.claude/skills`, installer `npx viepilot install --target claude-code`, và verify `vp-tools info`).
+
 ## Step 2: Brainstorm Your Project
 
 Start a new project by brainstorming:

package/docs/skills-reference.md

@@ -78,6 +78,7 @@ Complete reference for all ViePilot skills.
 ├── AI-GUIDE.md
 ├── PROJECT-META.md
 ├── ARCHITECTURE.md
+├── architecture/   (*.mermaid diagram sidecars — ENH-022, mirror fenced blocks)
 ├── PROJECT-CONTEXT.md
 ├── SYSTEM-RULES.md
 ├── ROADMAP.md
@@ -201,7 +202,7 @@ AI pauses for user input when:
 
 ## /vp-evolve
 
-**Purpose**: Nâng cấp hoặc mở rộng dự án
+**Purpose**: Nâng cấp hoặc mở rộng dự án (**planning** — ROADMAP, phase, tasks; implement sau bằng **`/vp-auto`**; xem **Implementation routing (ENH-021)** ở đầu file).
 
 ### Modes
 | Mode | Description |
@@ -278,7 +279,7 @@ CHANGELOG.md (updated)
 
 ## /vp-request
 
-**Purpose**: Tạo và quản lý requests (Bug, Feature, Enhancement, Tech Debt, Brainstorm tiếp)
+**Purpose**: Tạo và quản lý requests (Bug, Feature, Enhancement, Tech Debt, Brainstorm tiếp). **Không** thay **`/vp-evolve`** (plan) hay **`/vp-auto`** (implement); chuỗi khuyến nghị: request → evolve → auto (**ENH-021**).
 
 ### Flags
 | Flag | Description |
@@ -427,6 +428,7 @@ CHANGELOG.md (updated)
 4. **CLI coverage** — mỗi command có documentation không
 5. **docs/ sync** — docs/ có match với thực tế (skills count, workflows count) không
 6. **ROOT drift** — README.md badges, ROADMAP.md status có up-to-date không
+7. **ENH-022 (architecture sidecars)** — khi matrix có Mermaid thực tế, gợi ý kiểm `.viepilot/architecture/<type>.mermaid` khớp `ARCHITECTURE.md`
 
 ### Output
 - Audit report với danh sách gaps

package/docs/user/claude-code-setup.md

@@ -0,0 +1,144 @@
+# ViePilot trên Claude Code
+
+Hướng dẫn cài đặt và kiểm tra ViePilot khi bạn dùng **Claude Code** (CLI/IDE), bổ sung cho [Quick Start](quick-start.md) và [Getting Started](../getting-started.md).
+
+## Claude Code vs Cursor (đường dẫn skills)
+
+| | **Cursor** | **Claude Code** |
+|---|------------|-----------------|
+| Skills (global) | `~/.cursor/skills/<id>/SKILL.md` | `~/.claude/skills/<id>/SKILL.md` |
+| Skills (project) | Rules / project config tùy Cursor | `.claude/skills/<id>/SKILL.md` trong repo |
+| Tài liệu chính thức | — | [Extend Claude with skills](https://code.claude.com/docs/en/skills), [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory) |
+
+Bundled skill ViePilot dùng frontmatter `name: vp-*` — trên Claude Code bạn gọi tương đương **`/vp-auto`**, **`/vp-request`**, … như trong [Skills Reference](../skills-reference.md).
+
+**Lưu ý:** Nội dung skill hiện nhắc tới công cụ kiểu Cursor (`ReadFile`, `ApplyPatch`, …). Trên Claude Code, agent sẽ map sang tool tương đương (đọc/ghi file, terminal, …). Phần **workflow** và **chuỗi lệnh** (`/vp-evolve` → `/vp-auto`) vẫn giữ nguyên ý nghĩa.
+
+## Bước 1 — Cài bundle ViePilot (CLI)
+
+Với **`--target claude-code`**, installer (ViePilot **≥ 1.9.4**) **tự copy** toàn bộ `skills/vp-*` vào **`~/.claude/skills/`** (Claude Code mới thấy lệnh `/vp-*`). Đồng thời vẫn mirror vào **`~/.cursor/skills/`** và **`~/.cursor/viepilot/`** (workflows, bin) như trước.
+
+```bash
+npx viepilot install --target claude-code --yes
+```
+
+Hoặc clone repo và chạy từ thư mục gốc package:
+
+```bash
+git clone https://github.com/0-CODE/viepilot.git
+cd viepilot
+npx viepilot install --target claude-code --yes
+```
+
+Kết quả điển hình:
+
+- **`~/.claude/skills/vp-*/SKILL.md`** — dùng trực tiếp trong Claude Code
+- **`~/.cursor/skills/vp-*/`** — giữ cho Cursor / tương thích
+- Workflows, templates, `bin/*.cjs` tới **`~/.cursor/viepilot/`**
+- Seed **`~/.viepilot/profiles/`** và `~/.viepilot/profile-map.md` (xem [Global profiles](../dev/global-profiles.md))
+
+Sau khi cài: **khởi động lại / mở session Claude Code mới** nếu menu `/` chưa thấy `vp-*`.
+
+**Cập nhật sau này:** chạy lại `npx viepilot install --target claude-code --yes` từ bản npm/git mới để refresh cả hai cây skills.
+
+## Bước 2 — Tuỳ chọn: symlink / copy thủ công (bản cũ hoặc chỉ Cursor)
+
+Nếu bạn dùng ViePilot **&lt; 1.9.4** hoặc đã cài **`--target cursor-*`** mà **không** gồm `claude-code`, Claude Code **không** đọc `~/.cursor/skills` — khi đó đồng bộ thủ công vào **`~/.claude/skills/<tên-thư-mục>/SKILL.md`**.
+
+### Cách A — Symlink (khuyến nghị cho máy cá nhân)
+
+```bash
+mkdir -p ~/.claude/skills
+for d in ~/.cursor/skills/vp-*; do
+  [ -d "$d" ] || continue
+  name=$(basename "$d")
+  ln -sfn "$d" "$HOME/.claude/skills/$name"
+done
+```
+
+### Cách B — Copy (ổn cho máy không dùng symlink)
+
+```bash
+mkdir -p ~/.claude/skills
+for d in ~/.cursor/skills/vp-*; do
+  [ -d "$d" ] || continue
+  name=$(basename "$d")
+  rm -rf "$HOME/.claude/skills/$name"
+  cp -R "$d" "$HOME/.claude/skills/$name"
+done
+```
+
+Sau mỗi lần `npm update -g viepilot` hoặc reinstall: với **copy** cần chạy lại lệnh copy; với **symlink** chỉ cần cập nhật phía `~/.cursor/skills`.
+
+### Cách C — Skills chỉ trong một project
+
+Trong repo của bạn:
+
+```bash
+mkdir -p .claude/skills
+# symlink hoặc copy từng vp-* từ clone viepilot hoặc từ ~/.cursor/skills
+```
+
+Commit `.claude/skills/` nếu team cần dùng chung (xì [Where skills live](https://code.claude.com/docs/en/skills#where-skills-live)).
+
+## Bước 3 — Workflows và `execution_context`
+
+Nhiều skill trỏ tới workflow qua đường dẫn kiểu **`~/.cursor/viepilot/workflows/...`**. Sau `npx viepilot install`, thư mục này đã có bản mirror — **giữ nguyên** và đảm bảo skill không bị sandbox chặn đọc `$HOME`.
+
+Nếu bạn **không** dùng installer: từ clone, có thể đọc trực tiếp `workflows/*.md` trong repo hoặc tự mirror sang `~/.cursor/viepilot/workflows/` cho khớp văn bản skill.
+
+## Bước 4 — `vp-tools` trên PATH
+
+**Sau installer**, thử:
+
+```bash
+~/.cursor/viepilot/bin/vp-tools.cjs info
+# hoặc nếu đã thêm vào PATH:
+vp-tools info
+vp-tools info --json
+```
+
+**npm global:**
+
+```bash
+npm i -g viepilot
+vp-tools info
+```
+
+**Chỉ có clone, không cài global:**
+
+```bash
+node /đường-dẫn/tới/viepilot/bin/vp-tools.cjs info --json
+```
+
+Chi tiết lệnh: [CLI Reference](../dev/cli-reference.md).
+
+## Bước 5 — Bootstrap `.viepilot/` cho project đích
+
+Trong thư mục project (không nhất thiết là repo `viepilot`):
+
+1. Mở project trong Claude Code.
+2. Chạy **`/vp-crystallize`** (hoặc tương đương theo skill) để sinh `.viepilot/` — hoặc copy thủ công từ [`templates/project/`](../../templates/project/) theo [Getting Started](../getting-started.md).
+
+Một số repo framework **gitignore** `.viepilot/`; với **ứng dụng của bạn** thường nên **commit** để cả team (và agent) cùng thấy ROADMAP/TRACKER.
+
+## Kiểm tra nhanh
+
+| Bước | Lệnh / hành động | Kỳ vọng |
+|------|------------------|---------|
+| CLI | `vp-tools info` hoặc `node .../vp-tools.cjs info` | In `installedVersion`, `skills[]` |
+| Claude | Gõ `/` trong Claude Code | Thấy các skill `vp-*` đã cài |
+| Project | Có `.viepilot/TRACKER.md` sau crystallize | Theo [FAQ](faq.md) |
+
+## Windows
+
+- Symlink có thể cần quyền Developer Mode hoặc chạy terminal elevated; nếu không, dùng **copy** (cách B).
+- `path_shim` tới `/usr/local/bin` chỉ phù hợp Unix; trên Windows dùng `node ...\vp-tools.cjs` hoặc thêm thư mục chứa `vp-tools.cjs` vào **PATH** thủ công.
+
+## Chuỗi làm việc gợi ý (ENH-021)
+
+1. **`/vp-request`** — ghi yêu cầu  
+2. **`/vp-evolve`** — lên ROADMAP / phase  
+3. **`/vp-auto`** — thực thi task có plan  
+
+Xem thêm: [Autonomous mode](features/autonomous-mode.md), [Troubleshooting](../troubleshooting.md).

package/docs/user/faq.md

@@ -14,6 +14,12 @@ A: Skills được thiết kế cho Cursor IDE. Tuy nhiên, workflows và CLI (`
 
 ---
 
+### Q: Làm sao dùng ViePilot với Claude Code?
+
+A: Chạy `npx viepilot install --target claude-code --yes` (ViePilot **≥ 1.9.4**): installer **tự copy** `vp-*` vào **`~/.claude/skills/`**. Với bản cũ hoặc chỉ target Cursor, symlink/copy thủ công từ `~/.cursor/skills/`. Chi tiết, verify `vp-tools info`, và chuỗi **`/vp-request` → `/vp-evolve` → `/vp-auto`**: xem [ViePilot trên Claude Code](claude-code-setup.md).
+
+---
+
 ### Q: Tôi có cần biết code để dùng ViePilot không?
 
 A: Không nhất thiết. ViePilot giúp AI code cho bạn. Tuy nhiên, để review code và approve control points, hiểu biết cơ bản về programming sẽ hữu ích.
@@ -106,12 +112,13 @@ A: Dùng `/vp-resume` để tiếp tục từ điểm dừng. Nếu có lỗi, d
 
 ### Q: Làm sao thêm feature mới khi project đang chạy?
 
-A: Dùng `/vp-request --feature` — ViePilot sẽ insert phase mới vào roadmap mà không disrupt phases hiện tại.
+A: **`/vp-request --feature`** để **log** yêu cầu (file request + backlog). **`/vp-evolve`** (Add feature / New milestone) để **thêm phase + tasks** trên ROADMAP. **`/vp-auto`** để **implement** theo task plan. (ENH-021: không implement trực tiếp trong thread request/evolve trừ khi bạn explicit bypass.)
 
 ---
 
 ### Q: Khi nào nên dùng `/vp-evolve` vs `/vp-request`?
 
-A: 
-- `/vp-request --feature` — Thêm feature nhỏ vào milestone hiện tại
-- `/vp-evolve` — Bắt đầu milestone mới (M2, M3) với scope lớn hơn
+A:
+- **`/vp-request`** — Ghi nhận bug/feature/enhancement vào `.viepilot/requests/*` + TRACKER; **không** thay thế bước plan/implement.
+- **`/vp-evolve`** — **Planning**: thêm phase trên ROADMAP, tạo `SPEC`/tasks, cập nhật milestone; sau đó gọi **`/vp-auto`**.
+- Milestone **mới** (M2, M3…) hoặc scope lớn → thường bắt đầu bằng **`/vp-evolve`**; ý tưởng rời rạc → có thể **`/vp-request`** trước rồi evolve.

package/docs/user/features/autonomous-mode.md

@@ -36,6 +36,13 @@ Mỗi task:
 - Nếu môi trường runtime có skills ngoài framework, workflow sẽ bỏ qua và ưu tiên skill ViePilot tương đương.
 - Chỉ khi bạn ghi rõ yêu cầu mở rộng (explicit opt-in), agent mới được phép dùng external skills.
 
+### Implementation routing (ENH-021)
+
+- **`/vp-auto`** là **lane mặc định** để **implement** mã shipping sau khi đã có **phase/task plan** trên ROADMAP.
+- **`/vp-request`** chỉ **ghi backlog** (`.viepilot/requests/*`, TRACKER) — **không** thay evolve + auto.
+- **`/vp-evolve`** chỉ **planning** (ROADMAP, thư mục phase, SPEC/tasks) — **không** implement thay `/vp-auto`.
+- **Chuỗi khuyến nghị:** `vp-request` → `vp-evolve` → **`vp-auto`**. Ngoại lệ: user **explicit** (*hotfix*, *sửa trong chat này*) — phải nêu rõ bypass.
+
 ### Doc-first gate (v0.8.2 / BUG-001)
 
 Workflow `autonomous.md` yêu cầu **ghi nhận kế hoạch trong file task** và **`PHASE-STATE` → `in_progress`** trước khi chỉnh sửa deliverable. Xem `workflows/autonomous.md` — *Pre-execution documentation gate*.

package/docs/user/quick-start.md

@@ -31,6 +31,8 @@ Chọn profile cài đặt trong wizard (arrow keys + space + enter):
 - `cursor-agent`
 - `cursor-ide`
 
+Hướng dẫn đầy đủ cho **Claude Code** (symlink/copy skills sang `~/.claude/skills`, PATH, kiểm tra CLI): [ViePilot trên Claude Code](claude-code-setup.md).
+
 Non-interactive:
 ```bash
 npx viepilot install --target cursor-agent --yes

package/lib/viepilot-install.cjs

@@ -76,7 +76,7 @@ function listDirEntries(packageRoot, subdir) {
  *
  * @param {string} packageRoot - absolute viepilot package root
  * @param {Record<string, string | undefined>} [envSource] - defaults to process.env
- * @param {{ wantPathShim?: boolean, overrideHomedir?: string }} [opts] - `overrideHomedir`: absolute fake home for tests only. `wantPathShim`: append /usr/local/bin steps (skipped on Windows at apply time).
+ * @param {{ wantPathShim?: boolean, overrideHomedir?: string, installTargets?: string[] }} [opts] - `overrideHomedir`: absolute fake home for tests only. `wantPathShim`: append /usr/local/bin steps (skipped on Windows at apply time). `installTargets`: when it includes `claude-code`, also mirror `skills/vp-*` into `~/.claude/skills/` (Claude Code discovery).
  * @returns {{ version: number, packageRoot: string, env: ReturnType<typeof normalizeInstallEnv>, home: string, paths: object, steps: object[] }}
  */
 function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
@@ -91,6 +91,10 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
   const viepilotProfilesDir = path.join(viepilotUserDataDir, 'profiles');
   const viepilotProfileMapPath = path.join(viepilotUserDataDir, 'profile-map.md');
 
+  const installTargets = Array.isArray(opts.installTargets) ? opts.installTargets : [];
+  const installClaudeSkills = installTargets.includes('claude-code');
+  const claudeSkillsDir = installClaudeSkills ? path.join(home, '.claude', 'skills') : null;
+
   let wantPathShim = opts.wantPathShim;
   if (wantPathShim === undefined) {
     wantPathShim = env.autoYes && env.addPath;
@@ -133,6 +137,23 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     }
   }
 
+  if (installClaudeSkills && claudeSkillsDir) {
+    steps.push({ kind: 'mkdir', path: claudeSkillsDir });
+    for (const name of listSkillDirNames(root)) {
+      const src = path.join(root, 'skills', name);
+      const dest = path.join(claudeSkillsDir, name);
+      if (env.symlinkSkills) {
+        steps.push({
+          kind: 'symlink_dir',
+          target: dest,
+          sourceAbsolute: path.resolve(src),
+        });
+      } else {
+        steps.push({ kind: 'copy_dir', from: src, to: dest });
+      }
+    }
+  }
+
   for (const ent of listDirEntries(root, 'workflows')) {
     const src = path.join(root, 'workflows', ent.name);
     const dest = path.join(viepilotDir, 'workflows', ent.name);
@@ -223,6 +244,7 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     home,
     paths: {
       cursorSkillsDir,
+      claudeSkillsDir,
       viepilotDir,
       viepilotUserDataDir,
       viepilotProfilesDir,
@@ -241,8 +263,11 @@ function formatPlanLines(plan) {
   const lines = [];
   lines.push('ViePilot install plan (dry-run)');
   lines.push(`  packageRoot: ${plan.packageRoot}`);
-  lines.push(`  profile: ${plan.env.profile} (informational; same file set as install.sh)`);
-  lines.push(`  skills: ${plan.paths.cursorSkillsDir}`);
+  lines.push(`  profile: ${plan.env.profile} (informational; Cursor paths always; Claude Code skills when target includes claude-code)`);
+  lines.push(`  skills (Cursor): ${plan.paths.cursorSkillsDir}`);
+  if (plan.paths.claudeSkillsDir) {
+    lines.push(`  skills (Claude Code): ${plan.paths.claudeSkillsDir}`);
+  }
   lines.push(`  viepilot: ${plan.paths.viepilotDir}`);
   if (plan.paths.viepilotUserDataDir) {
     lines.push(`  userData (~/.viepilot): ${plan.paths.viepilotUserDataDir}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.9.2",
+  "version": "1.9.5",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-audit
 description: "Audit state, docs drift, and stack best-practice compliance — works on any project"
-version: 0.3.1
+version: 0.3.2
 ---
 
 <cursor_skill_adapter>
@@ -49,6 +49,7 @@ Auto-detect nếu đang chạy trong viepilot framework repo để thêm framewo
   - `required` diagrams must have Mermaid content
   - `optional` diagrams may be omitted/merged with explicit note
   - `N/A` diagrams must have rationale line
+- **ENH-022 (recommended check):** when a diagram type is `required` (or `optional` with a real Mermaid block) and crystallize policy applies, verify **`.viepilot/architecture/<type>.mermaid`** exists and that **Diagram source** lines in `ARCHITECTURE.md` match; for `N/A`, sidecar file should be absent (no empty stubs)
 
 **Tier 3 — Stack Best Practices + Code Quality (mọi project, theo stack detect được):**
 - Detect stacks liên quan từ context/project manifests

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.5.1
+version: 0.5.2
 ---
 
 <cursor_skill_adapter>
@@ -38,6 +38,7 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 ├── AI-GUIDE.md          # Navigation cho AI
 ├── PROJECT-META.md      # Metadata dự án
 ├── ARCHITECTURE.md      # System design
+├── architecture/        # ENH-022: *.mermaid sidecars (mirror fenced diagrams)
 ├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
 ├── SYSTEM-RULES.md      # Coding rules & standards
 ├── ROADMAP.md           # MVP phases & tasks + **Post-MVP / Product horizon** block (mandatory)
@@ -143,6 +144,7 @@ Ask user for (confirm proposals từ profile nếu có):
   - `required` => include concrete Mermaid block
   - `optional` => allow lightweight/merged representation
   - `N/A` => keep section heading + one-line rationale
+- **ENH-022:** For each diagram type with real Mermaid, write **`.viepilot/architecture/<type>.mermaid`** (raw source) and keep it **identical** to the body inside the fenced ` ```mermaid ` block in `ARCHITECTURE.md`; omit files for `N/A` or no diagram — see `workflows/crystallize.md` Step 4.
 
 ### Step 5: Generate PROJECT-CONTEXT.md
 - **FEAT-009:** Block `## ViePilot active profile (FEAT-009)` khi có binding
@@ -206,5 +208,6 @@ Ask user for (confirm proposals từ profile nếu có):
 - [ ] Project files created
 - [ ] Git committed
 - [ ] ARCHITECTURE diagram matrix is present and consistent (`required|optional|N/A`)
+- [ ] **ENH-022:** Mỗi diagram Mermaid được sinh có file `.viepilot/architecture/<canonical-name>.mermaid` đồng bộ nội dung với `ARCHITECTURE.md` (không tạo file thừa cho N/A)
 - [ ] **FEAT-009:** Nếu có profile bound — ARCHITECTURE + PROJECT-CONTEXT ghi nguồn profile; nếu không — ghi rõ none / not configured
 </success_criteria>

package/templates/project/ARCHITECTURE.md

@@ -4,6 +4,8 @@
 
 {{SYSTEM_OVERVIEW_DESCRIPTION}}
 
+**Diagram source (when Mermaid):** `.viepilot/architecture/system-overview.mermaid`
+
 ```
 {{SYSTEM_DIAGRAM}}
 ```
@@ -28,6 +30,12 @@
 | deployment | {{DIAGRAM_STATUS_DEPLOYMENT}} | {{DIAGRAM_REASON_DEPLOYMENT}} |
 | user-use-case | {{DIAGRAM_STATUS_USER_USE_CASE}} | {{DIAGRAM_REASON_USER_USE_CASE}} |
 
+## Diagram source files (ENH-022)
+
+When crystallize emits a real Mermaid diagram for a type, it also writes **`.viepilot/architecture/<type>.mermaid`** (raw Mermaid, no markdown fences). Canonical names: `system-overview.mermaid`, `data-flow.mermaid`, `event-flows.mermaid`, `module-dependencies.mermaid`, `deployment.mermaid`, `user-use-case.mermaid`. Types marked **N/A** or without a diagram must **not** get a sidecar file.
+
+Under each diagram section below, when applicable, include **Diagram source** pointing at the matching path. The fenced ` ```mermaid ` body in this file must **mirror** the `.mermaid` file line-for-line.
+
 ## Services
 
 {{#SERVICES}}
@@ -42,12 +50,16 @@
 
 ## Data Flow
 
+**Diagram source (when generated):** `.viepilot/architecture/data-flow.mermaid`
+
 ```
 {{DATA_FLOW_DIAGRAM}}
 ```
 
 ### Event Flows
 
+- **Diagram source (when generated):** `.viepilot/architecture/event-flows.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_EVENT_FLOWS}}
 - **Not applicable rationale**: {{DIAGRAM_NA_EVENT_FLOWS}}
 
@@ -58,6 +70,8 @@ flowchart LR
 
 ### Module Dependencies
 
+- **Diagram source (when generated):** `.viepilot/architecture/module-dependencies.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}}
 - **Not applicable rationale**: {{DIAGRAM_NA_MODULE_DEPENDENCIES}}
 
@@ -68,6 +82,8 @@ flowchart LR
 
 ### User Use-Case Flows
 
+- **Diagram source (when generated):** `.viepilot/architecture/user-use-case.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_USER_USE_CASE}}
 - **Not applicable rationale**: {{DIAGRAM_NA_USER_USE_CASE}}
 
@@ -108,6 +124,8 @@ flowchart TD
 
 ## Deployment Architecture
 
+**Diagram source (when generated):** `.viepilot/architecture/deployment.mermaid`
+
 ```
 {{DEPLOYMENT_DIAGRAM}}
 ```

package/workflows/crystallize.md

@@ -287,6 +287,27 @@ Generation rules:
 - `optional`: may be simplified or merged with a nearby section, but keep section heading discoverable
 - `N/A`: keep heading and add one-line rationale (`Not applicable: ...`) so `vp-audit` and `vp-auto` can interpret intent
 - Never default to “all six detailed diagrams”; diagram depth must scale with project complexity from brainstorm.
+
+### Architecture diagram source files on disk (ENH-022)
+
+When a diagram type is **`required`** or **`optional`** and you emit a **non-empty Mermaid diagram** for it, also persist the **same** diagram body (Mermaid source only — **no** markdown fences) under **`.viepilot/architecture/`** using the canonical filenames below. When status is **`N/A`** or the section has **no** real diagram (placeholder-only / rationale-only), **do not** create the matching `.mermaid` file (and remove a stale file if regenerating a project).
+
+| Diagram type (matrix key) | File (under `.viepilot/architecture/`) |
+|---------------------------|----------------------------------------|
+| `system-overview` | `system-overview.mermaid` |
+| `data-flow` | `data-flow.mermaid` |
+| `event-flows` | `event-flows.mermaid` |
+| `module-dependencies` | `module-dependencies.mermaid` |
+| `deployment` | `deployment.mermaid` |
+| `user-use-case` | `user-use-case.mermaid` |
+
+**Single source of truth (mirror policy):** the line-for-line Mermaid **inside** the ` ```mermaid ` fence in `.viepilot/ARCHITECTURE.md` must match the contents of the paired `.viepilot/architecture/<name>.mermaid` file. If you update one, update the other in the same crystallize pass.
+
+**System overview exception:** if the overview uses a non-Mermaid diagram (e.g. ASCII in a plain ` ``` ` block) and matrix marks `system-overview` as `required`, prefer converting to Mermaid for consistency; if you keep ASCII only, **omit** `system-overview.mermaid` and state that choice in the matrix reason column.
+
+**Discoverability:** in `.viepilot/ARCHITECTURE.md`, under each diagram section that has a sidecar file, add a line with bold label **Diagram source** and an inline-code path `.viepilot/architecture/<filename>.mermaid`.
+
+Create `.viepilot/architecture/` only when at least one `.mermaid` file will be written (empty directory otherwise is unnecessary).
 </step>
 
 <step name="generate_context">
@@ -480,6 +501,7 @@ Display summary:
  │   ├── AI-GUIDE.md
  │   ├── PROJECT-META.md
  │   ├── ARCHITECTURE.md
+ │   ├── architecture/   (*.mermaid sidecars when diagrams generated — ENH-022)
  │   ├── PROJECT-CONTEXT.md
  │   ├── SYSTEM-RULES.md
  │   ├── ROADMAP.md ({phase_count} phases)