viepilot 1.6.1 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Planned
+
+- **M1.25 / Phase 29 (ENH-018)** — **Crystallize + ARCHITECTURE**: Mermaid diagrams **complexity-gated** from brainstorm; six diagram kinds with required/optional/N/A; vp-audit / vp-auto / vp-debug alignment; target **1.8.0** on complete.
+
+### Added
+
+## [1.8.0] - 2026-04-01
+
+### Added
+
+- **M1.25 / Phase 29 (ENH-018) completed** — complexity-gated Mermaid architecture contract shipped: brainstorm inputs + crystallize matrix (`required|optional|N/A`) for six diagram types, architecture template sections with N/A rationale policy, and skill/workflow alignment across `vp-crystallize`, `vp-audit`, `vp-debug`, and `autonomous`.
+
+## [1.7.0] - 2026-04-01
+
+### Added
+
+- **M1.24 / Phase 28 (ENH-017) completed** — Node-native installer flow shipped: `lib/viepilot-install.cjs` (`buildInstallPlan`/`applyInstallPlan`), `bin/viepilot.cjs install` no longer spawns `bash`, `install.sh` now thin wrapper to Node, and Jest coverage for dry-run/apply/wrapper paths.
+
+### Documentation
+
+- `docs/troubleshooting.md`, `docs/dev/deployment.md` — updated install engine behavior (`npx viepilot install` Node-native, `install.sh` wrapper), Windows guidance, and reinstall semantics with `dev-install.sh`.
+
 ## [1.6.1] - 2026-04-01
 
 ### Enhanced
@@ -252,7 +274,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/0-CODE/viepilot/compare/v1.7.0...v1.8.0
 [0.10.0]: https://github.com/0-CODE/viepilot/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/0-CODE/viepilot/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/0-CODE/viepilot/compare/v0.8.1...v0.8.2

package/bin/viepilot.cjs

@@ -5,9 +5,15 @@
  */
 
 const path = require('path');
-const { spawnSync } = require('child_process');
 const readline = require('readline');
 const fs = require('fs');
+const os = require('os');
+const { buildInstallPlan, applyInstallPlan, resolveViepilotPackageRoot } = require(path.join(
+  __dirname,
+  '..',
+  'lib',
+  'viepilot-install.cjs',
+));
 
 const TARGETS = [
   { id: 'claude-code', label: 'Claude Code' },
@@ -28,7 +34,7 @@ Usage:
 Install options:
   --target <id|id,id|all>   Target profile(s): claude-code,cursor-agent,cursor-ide
   --yes                      Non-interactive mode (skip confirmations)
-  --dry-run                  Print actions only, do not execute installers
+  --dry-run                  Print actions only (Node installer; no bash)
   --list-targets             Print supported targets and exit
   --help                     Show help
 
@@ -239,28 +245,48 @@ async function interactiveTargetSelection() {
   return runKeyboardSelector(TARGETS, 'multi', 'Select install targets');
 }
 
-function handlerForTarget(target) {
-  const root = path.join(__dirname, '..');
-  return {
-    script: path.join(root, 'install.sh'),
-    env: { VIEPILOT_AUTO_YES: '1', VIEPILOT_INSTALL_PROFILE: target },
+/**
+ * One install applies the same file bundle for every target id (profiles are informational).
+ * @param {string[]} selectedTargets
+ * @param {boolean} dryRun
+ * @returns {{ ok: boolean, code: number }}
+ */
+function runInstallViaNode(selectedTargets, dryRun) {
+  const fallbackRoot = path.join(__dirname, '..');
+  const pkgRoot = resolveViepilotPackageRoot(fallbackRoot) || fallbackRoot;
+  const profile = selectedTargets[0] || 'cursor-ide';
+  const env = {
+    ...process.env,
+    VIEPILOT_AUTO_YES: '1',
+    VIEPILOT_INSTALL_PROFILE: profile,
   };
-}
+  const wantPathShim = env.VIEPILOT_ADD_PATH === '1';
 
-function runInstaller(target, dryRun) {
-  const config = handlerForTarget(target);
-  const commandLabel = `${config.script} [profile=${target}]`;
-  if (dryRun) {
-    console.log(`[dry-run] ${commandLabel}`);
-    return { ok: true, target, dryRun: true };
+  let plan;
+  try {
+    plan = buildInstallPlan(pkgRoot, env, { wantPathShim });
+  } catch (err) {
+    console.error(err.message);
+    return { ok: false, code: 1 };
   }
 
-  const result = spawnSync('bash', [config.script], {
-    stdio: 'inherit',
-    env: { ...process.env, ...config.env },
-    cwd: path.join(__dirname, '..'),
-  });
-  return { ok: result.status === 0, target, code: result.status ?? 1 };
+  console.log('');
+  console.log('ViePilot install (Node — no bash required)');
+  console.log(`  Package: ${pkgRoot}`);
+  console.log(`  Targets (informational): ${selectedTargets.join(', ')}`);
+
+  const applied = applyInstallPlan(plan, { dryRun });
+  if (applied.logs.length > 0) {
+    console.log('');
+    console.log(applied.logs.join('\n'));
+  }
+  if (!applied.ok && applied.errors.length > 0) {
+    const first = applied.errors[0];
+    const msg = first.error && first.error.message ? first.error.message : String(first.error);
+    console.error(msg);
+  }
+
+  return { ok: applied.ok, code: applied.ok ? 0 : 1 };
 }
 
 async function installCommand(rawArgs) {
@@ -290,7 +316,13 @@ async function installCommand(rawArgs) {
   }
 
   console.log(`\nSelected targets: ${selectedTargets.join(', ')}`);
-  const results = selectedTargets.map((target) => runInstaller(target, options.dryRun));
+  const run = runInstallViaNode(selectedTargets, options.dryRun);
+  const results = selectedTargets.map((target) => ({
+    ok: run.ok,
+    target,
+    dryRun: options.dryRun,
+    code: run.code,
+  }));
   const failed = results.filter((r) => !r.ok);
 
   console.log('\nInstall summary:');
@@ -307,7 +339,7 @@ async function installCommand(rawArgs) {
 }
 
 function computeUninstallPaths(targets) {
-  const home = process.env.HOME || '';
+  const home = process.env.HOME || os.homedir() || '';
   const cursorSkills = path.join(home, '.cursor', 'skills');
   const vpRoot = path.join(home, '.cursor', 'viepilot');
   const paths = [];

package/docs/dev/deployment.md

@@ -24,11 +24,10 @@ cd viepilot
 ./install.sh
 ```
 
-`install.sh` copies:
+`install.sh` is a thin **bash** wrapper: optional **cloc** / **PATH** prompts, then **`node bin/viepilot.cjs install`** (same **Node** engine as `npx viepilot install`). It installs to:
 - `skills/vp-*/` → `~/.cursor/skills/`
-- `workflows/` → `~/.cursor/viepilot/workflows/`
-- `templates/` → `~/.cursor/viepilot/templates/`
-- `bin/vp-tools.cjs` → `~/.local/bin/vp-tools`
+- `workflows/`, `templates/`, `bin/`, `lib/` → `~/.cursor/viepilot/…`
+- Optional PATH symlinks (Unix) via `VIEPILOT_ADD_PATH=1`
 
 ### Method 3: Development Mode
 

package/docs/troubleshooting.md

@@ -68,6 +68,43 @@ chmod +x install.sh
 
 ---
 
+### `npx viepilot install` vs dev clone — upgrade / cài lại có “conflict” không?
+
+**Không có** giao diện merge từng file. Hành vi phụ thuộc **script nào** chạy:
+
+| Cách cài | Script | Trước khi ghi file mới |
+|----------|--------|-------------------------|
+| **`npx viepilot install`** (mọi `--target`) | **`bin/viepilot.cjs`** + `lib/viepilot-install.cjs` (Node, **không** bash) | **Không** xóa `~/.cursor/skills/vp-*` hay `~/.cursor/viepilot`; copy đè tương đương **`cp -r`**. File cùng tên bị ghi đè; file **chỉ còn ở bản cũ** có thể **vẫn nằm lại** (orphan). |
+| **`./install.sh`** từ clone / tarball | Thin **bash** wrapper → gọi `node bin/viepilot.cjs install` | Cùng engine Node như NPX; bash chỉ còn prompt (cloc, PATH) khi không `VIEPILOT_AUTO_YES=1`. |
+| **`./dev-install.sh`** từ clone repo | `dev-install.sh` | **Có** xóa sạch `vp-*` skills + **`rm -rf ~/.cursor/viepilot`** rồi cài lại → gần như cài mới hoàn toàn. |
+
+`npx viepilot install` chạy **trực tiếp** Node installer — **không** spawn `bash install.sh`. `install.sh` dùng khi bạn chạy tay từ repo và muốn prompt cloc/PATH giống trước.
+
+**Muốn cài sạch sau bản cũ** (tránh sót file):
+
+```bash
+npx viepilot uninstall --yes
+npx viepilot install --target cursor-agent --yes
+```
+
+(Chọn lại `--target` đúng profile bạn dùng.)
+
+---
+
+### Windows / đa OS: `install.sh` và `npx viepilot install` chạy thế nào?
+
+**`npx viepilot install`** dùng **Node** (`lib/viepilot-install.cjs`) — **không** cần Bash. **`./install.sh`** là wrapper Bash (prompt cloc/PATH) rồi gọi `node bin/viepilot.cjs install …`. **`dev-install.sh`** vẫn là Bash đầy đủ (xóa + copy).
+
+| OS | `npx viepilot install` | `./install.sh` |
+|----|------------------------|----------------|
+| **macOS**, **Linux** | Chỉ cần Node trên PATH | Bash → Node (cùng engine với NPX) |
+| **Windows (CMD/PowerShell)** | Chạy được với Node | Cần Git Bash / WSL cho file `.sh`, hoặc: `node bin\viepilot.cjs install --target cursor-agent --yes` |
+| **PATH `/usr/local/bin`** | Tùy chọn trong installer (Unix); Windows bỏ qua / PATH thủ công | |
+
+Với ViePilot **Node-native install**, lỗi **`bash: command not found`** khi chạy **`npx viepilot install`** không còn điển hình — nếu vẫn gặp trên bản cũ, hãy nâng ViePilot hoặc dùng `node bin/viepilot.cjs install …` từ source.
+
+---
+
 ### `vp-tools: command not found`
 
 **Cause**: ViePilot bin not in PATH.

package/install.sh

@@ -1,23 +1,22 @@
 #!/bin/bash
 
-# ViePilot Installation Script
-# Installs ViePilot skills and tools to Cursor/Claude environment
+# ViePilot installation — thin wrapper around the Node installer (bin/viepilot.cjs).
+# Implements prompts + optional cloc install here; file copy/symlink/chmod/path is in lib/viepilot-install.cjs.
 #
-# Optional: VIEPILOT_SYMLINK_SKILLS=1 — symlink skills/* into ~/.cursor/skills/ (absolute paths)
+# Optional: VIEPILOT_SYMLINK_SKILLS=1 — passed through to Node (symlink skills into ~/.cursor/skills/)
+# Optional: VIEPILOT_INSTALL_DRY_RUN=1 — runs `viepilot install --dry-run` (for CI/tests)
 
 set -e
 
-# Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
-NC='\033[0m' # No Color
+NC='\033[0m'
 
-# Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR" || exit 1
 
-# Default installation paths
 CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
 VIEPILOT_DIR="$HOME/.cursor/viepilot"
 AUTO_YES="${VIEPILOT_AUTO_YES:-0}"
@@ -30,7 +29,6 @@ echo " VIEPILOT INSTALLER"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo -e "${NC}"
 
-# Check if running from viepilot directory
 if [ ! -f "$SCRIPT_DIR/README.md" ] || [ ! -d "$SCRIPT_DIR/skills" ]; then
     echo -e "${RED}Error: Please run this script from the viepilot directory${NC}"
     exit 1
@@ -40,6 +38,7 @@ echo -e "${YELLOW}Installation paths:${NC}"
 echo "  Skills: $CURSOR_SKILLS_DIR"
 echo "  ViePilot: $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
+echo "  Engine: Node (bin/viepilot.cjs) — no bash copy logic"
 echo ""
 
 install_cloc_best_effort() {
@@ -86,7 +85,6 @@ install_cloc_best_effort() {
     fi
 }
 
-# Confirm installation
 if [ "$AUTO_YES" != "1" ]; then
     read -p "Continue with installation? (y/n) " -n 1 -r
     echo
@@ -99,105 +97,29 @@ else
 fi
 
 echo ""
-echo -e "${BLUE}Installing...${NC}"
-
-# Create directories
-echo "  Creating directories..."
-mkdir -p "$CURSOR_SKILLS_DIR"
-mkdir -p "$VIEPILOT_DIR/workflows"
-mkdir -p "$VIEPILOT_DIR/templates/project"
-mkdir -p "$VIEPILOT_DIR/templates/phase"
-mkdir -p "$VIEPILOT_DIR/bin"
-mkdir -p "$VIEPILOT_DIR/lib"
-mkdir -p "$VIEPILOT_DIR/ui-components"
-
-# Install skills (copy default; VIEPILOT_SYMLINK_SKILLS=1 for dev-style live links)
-echo "  Installing skills..."
-for skill_dir in "$SCRIPT_DIR/skills"/*; do
-    if [ -d "$skill_dir" ]; then
-        skill_name=$(basename "$skill_dir")
-        if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
-            if command -v realpath >/dev/null 2>&1; then
-                skill_abs=$(realpath "$skill_dir")
-            else
-                skill_abs=$(cd "$skill_dir" && pwd)
-            fi
-            ln -sfn "$skill_abs" "$CURSOR_SKILLS_DIR/$skill_name"
-            echo "    ✓ $skill_name (symlink)"
-        else
-            cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
-            echo "    ✓ $skill_name"
-        fi
-    fi
-done
-
-# Install workflows
-echo "  Installing workflows..."
-cp -r "$SCRIPT_DIR/workflows"/* "$VIEPILOT_DIR/workflows/"
-echo "    ✓ workflows"
-
-# Install templates
-echo "  Installing templates..."
-cp -r "$SCRIPT_DIR/templates/project"/* "$VIEPILOT_DIR/templates/project/"
-cp -r "$SCRIPT_DIR/templates/phase"/* "$VIEPILOT_DIR/templates/phase/"
-echo "    ✓ templates"
-
-# Install stock UI components
-echo "  Installing stock UI components..."
-if [ -d "$SCRIPT_DIR/ui-components" ]; then
-    cp -r "$SCRIPT_DIR/ui-components"/* "$VIEPILOT_DIR/ui-components/"
-    echo "    ✓ ui-components"
-fi
-
-# Install CLI tools
-echo "  Installing CLI tools..."
-cp "$SCRIPT_DIR/bin/vp-tools.cjs" "$VIEPILOT_DIR/bin/"
-cp "$SCRIPT_DIR/bin/viepilot.cjs" "$VIEPILOT_DIR/bin/"
-cp "$SCRIPT_DIR/lib/cli-shared.cjs" "$VIEPILOT_DIR/lib/"
-chmod +x "$VIEPILOT_DIR/bin/vp-tools.cjs"
-chmod +x "$VIEPILOT_DIR/bin/viepilot.cjs"
-echo "    ✓ vp-tools.cjs + viepilot.cjs + lib/cli-shared.cjs"
-
-echo "  Checking optional dependency for README metric sync..."
+echo -e "${BLUE}Preparing Node installer...${NC}"
 install_cloc_best_effort
 
-# Create symlink in PATH (optional)
 echo ""
 if [ "$AUTO_YES" != "1" ]; then
-    read -p "Add vp-tools + viepilot to PATH? (creates symlink in /usr/local/bin) (y/n) " -n 1 -r
+    read -p "Add vp-tools + viepilot to PATH? (symlinks via Node installer, often /usr/local/bin) (y/n) " -n 1 -r
     echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        export VIEPILOT_ADD_PATH=1
+    fi
 else
-    REPLY=$([ "$ADD_PATH_CHOICE" = "1" ] && echo "y" || echo "n")
-fi
-if [[ $REPLY =~ ^[Yy]$ ]]; then
-    if [ -w "/usr/local/bin" ]; then
-        ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
-        ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
-        echo "    ✓ vp-tools + viepilot added to PATH"
-    else
-        echo -e "${YELLOW}    Note: Need sudo to create symlink${NC}"
-        sudo ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
-        sudo ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
-        echo "    ✓ vp-tools + viepilot added to PATH"
+    if [ "$ADD_PATH_CHOICE" = "1" ]; then
+        export VIEPILOT_ADD_PATH=1
     fi
 fi
 
+export VIEPILOT_AUTO_YES=1
+
+NODE_ARGS=(install --target "$INSTALL_PROFILE" --yes)
+if [ "${VIEPILOT_INSTALL_DRY_RUN:-0}" = "1" ]; then
+    NODE_ARGS+=(--dry-run)
+fi
+
 echo ""
-echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo -e "${GREEN} INSTALLATION COMPLETE ✓${NC}"
-echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-echo ""
-echo "Installed:"
-echo "  - Skills: $CURSOR_SKILLS_DIR/vp-*"
-echo "  - Workflows: $VIEPILOT_DIR/workflows/"
-echo "  - Templates: $VIEPILOT_DIR/templates/"
-echo "  - CLI: $VIEPILOT_DIR/bin/vp-tools.cjs"
-echo ""
-echo "Quick Start:"
-echo "  1. Open your project in Cursor"
-echo "  2. Run: /vp-brainstorm"
-echo "  3. After brainstorm: /vp-crystallize"
-echo "  4. Start coding: /vp-auto"
-echo ""
-echo "Documentation: $SCRIPT_DIR/docs/getting-started.md"
-echo ""
+echo -e "${BLUE}Running: node bin/viepilot.cjs ${NODE_ARGS[*]}${NC}"
+exec node "$SCRIPT_DIR/bin/viepilot.cjs" "${NODE_ARGS[@]}"

package/lib/viepilot-install.cjs

@@ -0,0 +1,427 @@
+/**
+ * ViePilot filesystem install plan — Node implementation (ENH-017 / Phase 28).
+ * Mirrors install.sh steps as a structured plan for dry-run and (later) execution.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { resolveViepilotPackageRoot } = require('./viepilot-info.cjs');
+
+/**
+ * @param {Record<string, string | undefined>} [envSource]
+ * @returns {{ autoYes: boolean, profile: string, addPath: boolean, symlinkSkills: boolean }}
+ */
+function normalizeInstallEnv(envSource = process.env) {
+  return {
+    autoYes: envSource.VIEPILOT_AUTO_YES === '1',
+    profile: envSource.VIEPILOT_INSTALL_PROFILE || 'cursor-ide',
+    addPath: envSource.VIEPILOT_ADD_PATH === '1',
+    symlinkSkills: envSource.VIEPILOT_SYMLINK_SKILLS === '1',
+  };
+}
+
+/**
+ * Same guard as install.sh: README.md + skills/ directory.
+ * @param {string} root - viepilot package root
+ */
+function validateViepilotPackageRoot(root) {
+  const readme = path.join(root, 'README.md');
+  const skillsDir = path.join(root, 'skills');
+  if (!fs.existsSync(readme)) {
+    const err = new Error('Please run this from the viepilot package root (README.md missing)');
+    err.code = 'VIEPILOT_LAYOUT';
+    throw err;
+  }
+  if (!fs.existsSync(skillsDir) || !fs.statSync(skillsDir).isDirectory()) {
+    const err = new Error('Please run this from the viepilot package root (skills/ missing)');
+    err.code = 'VIEPILOT_LAYOUT';
+    throw err;
+  }
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {string[]}
+ */
+function listSkillDirNames(packageRoot) {
+  const skillsDir = path.join(packageRoot, 'skills');
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+
+/**
+ * @param {string} packageRoot
+ * @param {string} subdir - relative to package root
+ */
+function listDirEntries(packageRoot, subdir) {
+  const full = path.join(packageRoot, subdir);
+  if (!fs.existsSync(full)) return [];
+  return fs.readdirSync(full, { withFileTypes: true });
+}
+
+/**
+ * Build an ordered install plan (no I/O besides reading source tree layout).
+ *
+ * @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).
+ * @returns {{ version: number, packageRoot: string, env: ReturnType<typeof normalizeInstallEnv>, home: string, paths: object, steps: object[] }}
+ */
+function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
+  const root = path.resolve(packageRoot);
+  validateViepilotPackageRoot(root);
+  const env = normalizeInstallEnv(envSource);
+  const home =
+    opts.overrideHomedir != null ? path.resolve(opts.overrideHomedir) : os.homedir();
+  const cursorSkillsDir = path.join(home, '.cursor', 'skills');
+  const viepilotDir = path.join(home, '.cursor', 'viepilot');
+
+  let wantPathShim = opts.wantPathShim;
+  if (wantPathShim === undefined) {
+    wantPathShim = env.autoYes && env.addPath;
+  }
+
+  /** @type {object[]} */
+  const steps = [];
+
+  const mkdirTargets = [
+    cursorSkillsDir,
+    path.join(viepilotDir, 'workflows'),
+    path.join(viepilotDir, 'templates', 'project'),
+    path.join(viepilotDir, 'templates', 'phase'),
+    path.join(viepilotDir, 'bin'),
+    path.join(viepilotDir, 'lib'),
+    path.join(viepilotDir, 'ui-components'),
+  ];
+  for (const dir of mkdirTargets) {
+    steps.push({ kind: 'mkdir', path: dir });
+  }
+
+  for (const name of listSkillDirNames(root)) {
+    const src = path.join(root, 'skills', name);
+    const dest = path.join(cursorSkillsDir, 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);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  for (const ent of listDirEntries(root, path.join('templates', 'project'))) {
+    const src = path.join(root, 'templates', 'project', ent.name);
+    const dest = path.join(viepilotDir, 'templates', 'project', ent.name);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  for (const ent of listDirEntries(root, path.join('templates', 'phase'))) {
+    const src = path.join(root, 'templates', 'phase', ent.name);
+    const dest = path.join(viepilotDir, 'templates', 'phase', ent.name);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  const uiRoot = path.join(root, 'ui-components');
+  if (fs.existsSync(uiRoot)) {
+    for (const ent of listDirEntries(root, 'ui-components')) {
+      const src = path.join(root, 'ui-components', ent.name);
+      const dest = path.join(viepilotDir, 'ui-components', ent.name);
+      if (ent.isDirectory()) {
+        steps.push({ kind: 'copy_dir', from: src, to: dest });
+      } else if (ent.isFile()) {
+        steps.push({ kind: 'copy_file', from: src, to: dest });
+      }
+    }
+  }
+
+  const binFiles = ['vp-tools.cjs', 'viepilot.cjs'];
+  for (const f of binFiles) {
+    steps.push({
+      kind: 'copy_file',
+      from: path.join(root, 'bin', f),
+      to: path.join(viepilotDir, 'bin', f),
+    });
+  }
+  steps.push({
+    kind: 'copy_file',
+    from: path.join(root, 'lib', 'cli-shared.cjs'),
+    to: path.join(viepilotDir, 'lib', 'cli-shared.cjs'),
+  });
+
+  for (const f of binFiles) {
+    steps.push({
+      kind: 'chmod',
+      path: path.join(viepilotDir, 'bin', f),
+      mode: 0o755,
+    });
+  }
+
+  steps.push({
+    kind: 'note',
+    id: 'cloc_optional',
+    message:
+      'Check optional cloc for README metrics (brew/apt/dnf/choco); installation continues if missing.',
+  });
+
+  if (wantPathShim) {
+    steps.push({
+      kind: 'path_shim',
+      links: [
+        { path: '/usr/local/bin/vp-tools', target: path.join(viepilotDir, 'bin', 'vp-tools.cjs') },
+        { path: '/usr/local/bin/viepilot', target: path.join(viepilotDir, 'bin', 'viepilot.cjs') },
+      ],
+      note: 'Unix typical; on Windows native, PATH shim may be skipped or manual.',
+    });
+  }
+
+  return {
+    version: 1,
+    packageRoot: root,
+    env,
+    home,
+    paths: {
+      cursorSkillsDir,
+      viepilotDir,
+    },
+    steps,
+  };
+}
+
+/**
+ * Human-readable lines for dry-run output.
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @returns {string[]}
+ */
+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(`  viepilot: ${plan.paths.viepilotDir}`);
+  lines.push('');
+  for (let i = 0; i < plan.steps.length; i++) {
+    const s = plan.steps[i];
+    const n = i + 1;
+    switch (s.kind) {
+      case 'mkdir':
+        lines.push(`${n}. mkdir -p ${s.path}`);
+        break;
+      case 'copy_file':
+        lines.push(`${n}. copy ${s.from} -> ${s.to}`);
+        break;
+      case 'copy_dir':
+        lines.push(`${n}. copyDir ${s.from} -> ${s.to}`);
+        break;
+      case 'symlink_dir':
+        lines.push(`${n}. symlink ${s.target} -> ${s.sourceAbsolute}`);
+        break;
+      case 'chmod':
+        lines.push(`${n}. chmod ${s.mode.toString(8)} ${s.path}`);
+        break;
+      case 'note':
+        lines.push(`${n}. note: ${s.message}`);
+        break;
+      case 'path_shim':
+        lines.push(`${n}. path shim: ${s.links.map((l) => `${l.path} -> ${l.target}`).join('; ')}`);
+        if (s.note) lines.push(`    (${s.note})`);
+        break;
+      default:
+        lines.push(`${n}. ${JSON.stringify(s)}`);
+    }
+  }
+  return lines;
+}
+
+function removePathIfExists(p) {
+  if (fs.existsSync(p)) {
+    fs.rmSync(p, { recursive: true, force: true });
+  }
+}
+
+function ensureDirForFile(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function copyDirRecursive(src, dest) {
+  removePathIfExists(dest);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true });
+    return;
+  }
+  fs.mkdirSync(dest, { recursive: true });
+  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, ent.name);
+    const d = path.join(dest, ent.name);
+    if (ent.isDirectory()) {
+      copyDirRecursive(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function symlinkSkillDir(sourceAbsolute, target) {
+  removePathIfExists(target);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const linkType = process.platform === 'win32' ? 'dir' : 'dir';
+  fs.symlinkSync(sourceAbsolute, target, linkType);
+}
+
+/**
+ * Same messaging as install.sh install_cloc_best_effort (non-blocking; no interactive install here).
+ * @param {ReturnType<typeof normalizeInstallEnv>} env
+ * @returns {string[]}
+ */
+function getClocGuidanceLines(env) {
+  const lines = [];
+  try {
+    const { execFileSync } = require('child_process');
+    execFileSync('cloc', ['--version'], { stdio: 'ignore' });
+    lines.push('  ✓ cloc detected');
+    return lines;
+  } catch (_e) {
+    /* continue */
+  }
+  lines.push('  cloc not found.');
+  lines.push('  README metric auto-sync can still run with fallback, but LOC refresh will be skipped.');
+  lines.push('  Suggested install:');
+  lines.push('    - macOS: brew install cloc');
+  lines.push('    - Ubuntu/Debian: sudo apt-get install -y cloc');
+  lines.push('    - Windows: choco install cloc');
+  if (!env.autoYes) {
+    lines.push('  (Interactive cloc install omitted in Node installer; set AUTO_YES and use OS package manager.)');
+  }
+  return lines;
+}
+
+/**
+ * Apply install plan to disk (or dry-run log only).
+ *
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ ok: boolean, logs: string[], errors: { step: object, error: Error }[] }}
+ */
+function applyInstallPlan(plan, options = {}) {
+  const dryRun = !!options.dryRun;
+  /** @type {string[]} */
+  const logs = [];
+  /** @type {{ step: object, error: Error }[]} */
+  const errors = [];
+
+  for (const step of plan.steps) {
+    try {
+      switch (step.kind) {
+        case 'mkdir':
+          if (dryRun) logs.push(`[dry-run] mkdir -p ${step.path}`);
+          else fs.mkdirSync(step.path, { recursive: true });
+          break;
+        case 'copy_file':
+          if (dryRun) logs.push(`[dry-run] copy ${step.from} -> ${step.to}`);
+          else {
+            if (!fs.existsSync(step.from)) {
+              throw new Error(`Missing source: ${step.from}`);
+            }
+            ensureDirForFile(step.to);
+            fs.copyFileSync(step.from, step.to);
+          }
+          break;
+        case 'copy_dir':
+          if (dryRun) logs.push(`[dry-run] copyDir ${step.from} -> ${step.to}`);
+          else {
+            if (!fs.existsSync(step.from)) {
+              throw new Error(`Missing source dir: ${step.from}`);
+            }
+            copyDirRecursive(step.from, step.to);
+          }
+          break;
+        case 'symlink_dir':
+          if (dryRun) {
+            logs.push(`[dry-run] symlink ${step.target} -> ${step.sourceAbsolute}`);
+          } else {
+            symlinkSkillDir(step.sourceAbsolute, step.target);
+          }
+          break;
+        case 'chmod':
+          if (dryRun) logs.push(`[dry-run] chmod ${step.mode.toString(8)} ${step.path}`);
+          else {
+            try {
+              fs.chmodSync(step.path, step.mode);
+            } catch (e) {
+              logs.push(`chmod skipped: ${step.path} (${e.message})`);
+            }
+          }
+          break;
+        case 'note':
+          if (step.id === 'cloc_optional') {
+            logs.push(...getClocGuidanceLines(plan.env));
+          } else {
+            logs.push(`note: ${step.message}`);
+          }
+          break;
+        case 'path_shim':
+          if (process.platform === 'win32') {
+            logs.push('path_shim: skipped on Windows (add ~/.cursor/viepilot/bin to PATH manually if needed).');
+            break;
+          }
+          if (dryRun) {
+            logs.push(`[dry-run] path_shim: ${step.links.map((l) => `${l.path} -> ${l.target}`).join('; ')}`);
+            break;
+          }
+          for (const L of step.links) {
+            try {
+              removePathIfExists(L.path);
+              fs.mkdirSync(path.dirname(L.path), { recursive: true });
+              fs.symlinkSync(L.target, L.path, 'file');
+              logs.push(`path_shim: ${L.path} -> ${L.target}`);
+            } catch (e) {
+              logs.push(`path_shim failed ${L.path}: ${e.message} (try sudo or adjust permissions)`);
+            }
+          }
+          break;
+        default:
+          logs.push(`unknown step kind: ${JSON.stringify(step)}`);
+      }
+    } catch (e) {
+      errors.push({ step, error: e });
+      return { ok: false, logs, errors };
+    }
+  }
+
+  return { ok: true, logs, errors };
+}
+
+module.exports = {
+  resolveViepilotPackageRoot,
+  normalizeInstallEnv,
+  validateViepilotPackageRoot,
+  listSkillDirNames,
+  buildInstallPlan,
+  formatPlanLines,
+  applyInstallPlan,
+  getClocGuidanceLines,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "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

@@ -32,6 +32,10 @@ Auto-detect nếu đang chạy trong viepilot framework repo để thêm framewo
 - `CHANGELOG.md` vs recent git commits
 - Placeholder URLs trong `docs/` (`your-org`, `YOUR_USERNAME`, v.v.)
 - Features mới (từ phases gần đây) chưa có documentation
+- `ARCHITECTURE.md` diagram applicability matrix consistency:
+  - `required` diagrams must have Mermaid content
+  - `optional` diagrams may be omitted/merged with explicit note
+  - `N/A` diagrams must have rationale line
 
 **Tier 3 — Stack Best Practices + Code Quality (mọi project, theo stack detect được):**
 - Detect stacks liên quan từ context/project manifests
@@ -66,7 +70,8 @@ Optional flags:
 - `--silent`    : Only output if issues found
 - `--tier1`     : Run Tier 1 (state consistency) only
 - `--tier2`     : Run Tier 2 (docs drift) only
-- `--tier3`     : Run Tier 3 (framework integrity) only
+- `--tier3`     : Run Tier 3 (stack best-practice) only
+- `--tier4`     : Run Tier 4 (framework integrity) only
 </context>
 
 <process>
@@ -90,6 +95,7 @@ Execute workflow from `@$HOME/.cursor/viepilot/workflows/audit.md`
 # README.md version mention
 # CHANGELOG.md vs recent commits
 # Placeholder URLs in docs/
+# ARCHITECTURE.md diagram matrix consistency (required|optional|N/A)
 ```
 
 **Step 3 — Tier 3**: Stack Best Practices + Code Quality

package/skills/vp-crystallize/SKILL.md

@@ -116,6 +116,13 @@ Ask user for:
 - Services definitions
 - Data flow
 - Technology decisions
+- Build **diagram applicability matrix** for:
+  - `system-overview`, `data-flow`, `event-flows`, `module-dependencies`, `deployment`, `user-use-case`
+- For each type assign status: `required` | `optional` | `N/A`
+- Apply generation policy:
+  - `required` => include concrete Mermaid block
+  - `optional` => allow lightweight/merged representation
+  - `N/A` => keep section heading + one-line rationale
 
 ### Step 5: Generate PROJECT-CONTEXT.md
 - Domain knowledge
@@ -177,4 +184,5 @@ Ask user for:
 - [ ] TRACKER.md initialized
 - [ ] Project files created
 - [ ] Git committed
+- [ ] ARCHITECTURE diagram matrix is present and consistent (`required|optional|N/A`)
 </success_criteria>

package/skills/vp-debug/SKILL.md

@@ -28,6 +28,12 @@ Systematic debugging với persistent state tracking. Giúp track vấn đề qu
 - `continue` - Continue current session
 - `list` - List all sessions
 - `close` - Close current session with resolution
+
+**Architecture diagram intake (ENH-018):**
+- If `.viepilot/ARCHITECTURE.md` has diagram applicability matrix, consume it before deep debugging.
+- Prioritize investigation context from diagrams marked `required`.
+- For `optional` diagrams: use when available; do not block debug flow if missing.
+- For `N/A` diagrams: respect rationale and avoid forcing diagram creation during debug.
 </objective>
 
 <execution_context>
@@ -79,11 +85,12 @@ Execute workflow from `@$HOME/.cursor/viepilot/workflows/debug.md`
 
 ### Key Steps
 1. **Start Session**: Gather problem description
-2. **Hypothesize**: Generate possible causes
-3. **Test**: Run tests to confirm/reject hypotheses
-4. **Track**: Log all findings
-5. **Resolve**: Document fix and root cause
-6. **Close**: Mark session complete
+2. **Load Architecture Context**: Read `.viepilot/ARCHITECTURE.md` matrix status (`required|optional|N/A`) and relevant Mermaid diagrams if present
+3. **Hypothesize**: Generate possible causes
+4. **Test**: Run tests to confirm/reject hypotheses
+5. **Track**: Log all findings
+6. **Resolve**: Document fix and root cause
+7. **Close**: Mark session complete
 </process>
 
 <success_criteria>

package/templates/project/ARCHITECTURE.md

@@ -8,6 +8,26 @@
 {{SYSTEM_DIAGRAM}}
 ```
 
+## Architecture Diagram Applicability
+
+> Decide diagram depth from brainstorm complexity signals. Do not force all six as detailed by default.
+
+- **Complexity**: {{ARCH_COMPLEXITY_LEVEL}}  <!-- simple | moderate | complex -->
+- **Services/Modules signal**: {{ARCH_SIGNAL_SERVICES}}
+- **Event-driven signal**: {{ARCH_SIGNAL_EVENTS}}
+- **Deployment signal**: {{ARCH_SIGNAL_DEPLOYMENT}}
+- **User-flow signal**: {{ARCH_SIGNAL_USER_FLOWS}}
+- **Integration signal**: {{ARCH_SIGNAL_INTEGRATIONS}}
+
+| Diagram type | Status (`required|optional|N/A`) | Reason |
+|--------------|----------------------------------|--------|
+| system-overview | {{DIAGRAM_STATUS_SYSTEM_OVERVIEW}} | {{DIAGRAM_REASON_SYSTEM_OVERVIEW}} |
+| data-flow | {{DIAGRAM_STATUS_DATA_FLOW}} | {{DIAGRAM_REASON_DATA_FLOW}} |
+| event-flows | {{DIAGRAM_STATUS_EVENT_FLOWS}} | {{DIAGRAM_REASON_EVENT_FLOWS}} |
+| module-dependencies | {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}} | {{DIAGRAM_REASON_MODULE_DEPENDENCIES}} |
+| deployment | {{DIAGRAM_STATUS_DEPLOYMENT}} | {{DIAGRAM_REASON_DEPLOYMENT}} |
+| user-use-case | {{DIAGRAM_STATUS_USER_USE_CASE}} | {{DIAGRAM_REASON_USER_USE_CASE}} |
+
 ## Services
 
 {{#SERVICES}}
@@ -26,6 +46,36 @@
 {{DATA_FLOW_DIAGRAM}}
 ```
 
+### Event Flows
+
+- **Status**: {{DIAGRAM_STATUS_EVENT_FLOWS}}
+- **Not applicable rationale**: {{DIAGRAM_NA_EVENT_FLOWS}}
+
+```mermaid
+flowchart LR
+  EventSource --> EventBus --> Consumer
+```
+
+### Module Dependencies
+
+- **Status**: {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}}
+- **Not applicable rationale**: {{DIAGRAM_NA_MODULE_DEPENDENCIES}}
+
+```mermaid
+flowchart LR
+  UI --> Service --> Repository
+```
+
+### User Use-Case Flows
+
+- **Status**: {{DIAGRAM_STATUS_USER_USE_CASE}}
+- **Not applicable rationale**: {{DIAGRAM_NA_USER_USE_CASE}}
+
+```mermaid
+flowchart TD
+  User --> Action --> Outcome
+```
+
 ## Integration Points
 
 | Service A | Service B | Protocol | Endpoint/Topic |
@@ -62,6 +112,9 @@
 {{DEPLOYMENT_DIAGRAM}}
 ```
 
+- **Status**: {{DIAGRAM_STATUS_DEPLOYMENT}}
+- **Not applicable rationale**: {{DIAGRAM_NA_DEPLOYMENT}}
+
 ## Monitoring & Observability
 
 - **Logging**: {{LOGGING_SOLUTION}}

package/workflows/autonomous.md

@@ -90,6 +90,13 @@ read:
   - context_required files from task file
 ```
 
+Architecture context rule (ENH-018):
+- If `.viepilot/ARCHITECTURE.md` includes a diagram applicability matrix, load only diagrams relevant to current task:
+  - `required`: must be consulted before implementation/debug decisions.
+  - `optional`: consult when directly related; do not block task if absent.
+  - `N/A`: respect rationale; do not force diagram regeneration.
+- If matrix is missing, continue with explicit assumption notes in task logs.
+
 #### Validate Task Contract (required before code)
 Task must include execution-grade details:
 - Objective (specific outcome)

package/workflows/brainstorm.md

@@ -59,6 +59,12 @@ Gợi ý các topics để brainstorm:
    - System components
    - Data flow
    - Technology stack
+   - Diagram applicability signals (for crystallize):
+     - Service/module count and boundaries
+     - Event-driven usage (queues, webhooks, async jobs)
+     - Deployment topology (single node vs multi-env / distributed)
+     - User journey complexity (single actor/simple flow vs multi-actor)
+     - External integration surface (few vs many protocols/services)
 
 3. **Data Model**
    - Core entities
@@ -196,6 +202,18 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 **Scope note (optional):** Nếu không có post-MVP: `Single-release product — no separate horizon epics.`
 
+## Architecture diagram applicability inputs
+
+> Input contract for `/vp-crystallize` Step 4. Keep concise and explicit.
+
+- **Project complexity**: simple | moderate | complex
+- **Services/modules**: {single | multiple} + boundaries
+- **Event-driven**: yes/no + channels (queue/webhook/cron)
+- **Deployment shape**: local-only | single-env cloud | multi-env/distributed
+- **User flow complexity**: simple | multi-step | multi-actor
+- **Integration surface**: low | medium | high
+- **Initial diagram hints** (optional): required / optional / N/A candidates
+
 ## Topics Discussed
 
 ### Topic 1: {Name}

package/workflows/crystallize.md

@@ -229,6 +229,23 @@ Extract from brainstorm:
 - Data flow
 - Technology decisions with rationale
 - Integration points
+
+Before writing diagrams, create a **diagram applicability matrix** from brainstorm signals (complexity, service boundaries, event usage, deployment shape, user-flow complexity, integration surface):
+
+| Diagram type | Status | Rule |
+|--------------|--------|------|
+| `system-overview` | required/optional/N/A | Required if >1 major component or integration boundary |
+| `data-flow` | required/optional/N/A | Required when request/response or data pipeline is central |
+| `event-flows` | required/optional/N/A | Required when async events/webhooks/queues exist |
+| `module-dependencies` | required/optional/N/A | Required when multi-module/layer boundaries matter |
+| `deployment` | required/optional/N/A | Required for multi-env/distributed deployment concerns |
+| `user-use-case` | required/optional/N/A | Required when user journey/actor interactions drive design |
+
+Generation rules:
+- `required`: include explicit ` ```mermaid ` block in `.viepilot/ARCHITECTURE.md`
+- `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.
 </step>
 
 <step name="generate_context">