viepilot 1.3.1 → 1.8.0

package/CHANGELOG.md

@@ -7,8 +7,57 @@ 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
+
+- **ENH-015** — `dev-install.sh` và `install.sh` hỗ trợ **`VIEPILOT_SYMLINK_SKILLS=1`**: cài skills vào `~/.cursor/skills/` bằng symlink tuyệt đối tới repo (mặc định vẫn copy-first); `docs/dev/contributing.md` documents the flag.
+
+## [1.6.0] - 2026-04-01
+
+### Added
+
+- **M1.23 / Phase 27 (FEAT-008)** — `vp-tools info` and `vp-tools info --json` with `lib/viepilot-info.cjs` (resolve `viepilot` package root without `.viepilot/`, npm latest, skills + workflows inventory); `vp-tools update` with `--dry-run`, `--yes`, `--global` and `lib/viepilot-update.cjs` (local vs global install classification, semver no-op when up to date); Cursor skills `skills/vp-info/SKILL.md` and `skills/vp-update/SKILL.md`; documentation in `docs/skills-reference.md`, `docs/dev/cli-reference.md`, `docs/user/quick-start.md`, and README metrics (16 skills, 18 CLI surface / 17 `vp-tools` subcommands); unit tests `tests/unit/viepilot-info.test.js` and `tests/unit/viepilot-update.test.js`.
+
+## [1.5.1] - 2026-04-01
+
+### Added
+
+- **M1.22 — ENH-001 ~ ENH-005 backlog closed (verification)** — Các enhancement doc-sync + audit drift đã được implement trong các milestone trước (`workflows/autonomous.md`, `workflows/documentation.md`, `workflows/audit.md`, skills `vp-auto` / `vp-docs` / `vp-audit`). Thêm `tests/unit/enh-backlog-workflow-contracts.test.js` để regression-guard contract.
+
+### Enhanced
+
+- **M1.21 / Phase 25 — task 25.5** — `docs/user/features/product-horizon.md` (end-to-end horizon handoff); `templates/project/AI-GUIDE.md` states **load order**: `<product_vision>` + `ROADMAP` horizon before deep implementation; `workflows/crystallize.md` Step 2 reminds to preserve that ordering; `docs/user/quick-start.md`, `docs/README.md`, `docs/skills-reference.md` cross-links.
+- **M1.21 / Phase 25 — task 25.4** — `skills/vp-brainstorm` and `skills/vp-crystallize` bumped to **0.4.0**; objectives/process/success criteria mirror ENH-014 horizon + crystallize gates; `docs/skills-reference.md` documents horizon output and crystallize intake.
+- **M1.21 / Phase 25 — task 25.3** — `templates/project/ROADMAP.md` adds mandatory **Post-MVP / Product horizon** with placeholders (`HORIZON_MODE_LINE`, epic lists, deferred/non-goals); `templates/project/PROJECT-CONTEXT.md` adds `<product_vision>` (**Product vision & phased scope**) aligned with MVP / Post-MVP / Future terminology.
+- **M1.21 / Phase 25 — task 25.2** — `workflows/crystallize.md` Step 1 now **extracts and validates** brainstorm product horizon (inventory, single-release mode, tier conflicts); Step 7 always emits **MVP phases** plus a mandatory **Post-MVP / horizon** block with a **no silent omission** gate before finalizing `ROADMAP.md`; success criteria updated.
+- **M1.21 / Phase 25 — task 25.1** — `workflows/brainstorm.md` now mandates **`## Product horizon`** (MVP / Post-MVP / Future tags, non-goals, deferred capabilities, single-release escape hatch), merge rules when continuing sessions, and user doc `docs/user/features/brainstorm.md` (+ docs index link).
+
 ### Enhanced
 
+- **M1.20 / Phase 24 (FEAT-007) completed** — multi-page UI Direction (`pages/*.html` + hub `index.html`), mandatory `## Pages inventory` in `notes.md` when `pages/` exists, crystallize workflow/skill reads every page + inventory for full site-map architecture, `npm run verify:ui-direction` helper, and docs refresh.
 - **M1.17 / Phase 21 (ENH-013) completed** — realigned README metrics (`npm run readme:sync` with `cloc`) and moved `.viepilot` to local-only (`.gitignore` + untracked index).
 - **M1.15 / Phase 18 (FEAT-004) completed** — npm distribution flow is now fully closed: publish pipeline passes and package released to npm as `viepilot@1.0.1`.
 - **M1.15 / Phase 19 (FEAT-005) completed** — installer now supports keyboard selector UX (arrow/space/enter), added `viepilot uninstall` command (`--target`, `--yes`, `--dry-run`), and switched dev installer to copy-first flow to avoid symlink-based skill discovery failures.
@@ -225,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/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.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.6.1-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-14-purple.svg)](#skills-reference)
+[![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-16-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-202%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-267%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.2.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.2.0**) is the Node package identifier for this repo and may differ; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.6.1** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.6.1**) is the Node package identifier for this repo and may differ; 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,12 +28,12 @@ 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 | **~22,384+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
-| Skills | **14** |
+| Total LOC | **~25,050+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Skills | **16** |
 | Workflows | **12** |
 | Templates | **16** (Project: 11, Phase: 5) |
-| CLI Commands | **14** (`vp-tools` + `viepilot install`) |
-| Tests | **202** (3 files: unit + integration + AI compat) |
+| CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
+| Tests | **267** (9 suites: unit + integration + AI compat + README metrics + UI direction verify + ENH workflow contracts + viepilot-info + viepilot-update) |
 | ViePilot phases (repo) | **15** hoàn thành (xem `.viepilot/TRACKER.md`) |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
@@ -43,29 +43,29 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
 |------------------------|------------------|---------------------|
-| Skill Definitions | **14** | SKILL.md files với trigger, process, success criteria |
+| Skill Definitions | **16** | SKILL.md files với trigger, process, success criteria |
 | Workflow Files | **12** | Step-by-step execution guides |
 | Project Templates | 11 | AI-GUIDE, ARCHITECTURE, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
-| CLI Tools | 2 | vp-tools.cjs (**13** commands) + viepilot.cjs (guided installer) |
-| Test Files | 4 | Jest unit + integration + AI compatibility + README metrics tests (231 tests) |
+| CLI Tools | 2 | vp-tools.cjs (**17** subcommands) + viepilot.cjs (guided installer) |
+| Test Files | 6 | Jest unit + integration + AI compatibility + README metrics + ENH backlog + viepilot-info/update |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  100% 🎉 M1.18 roadmap phases ✅ (v1.2.0)
+Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.6.1** (ENH-015 symlink skills opt-in); M1.23 FEAT-008 (v1.6.0); M1.22 (v1.5.1)
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
-| Core Skills (14) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, request, evolve, docs, task, debug, rollback, audit, ui-components |
+| Core Skills (16) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components |
 | Workflows (12) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
 | Project Templates (11) | ✅ Hoàn thiện | Placeholders cho customization |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
-| CLI Tools (14 commands) | ✅ Hoàn thiện | State management, progress, versioning, checkpoints, guided installer |
-| Tests (202) | ✅ Hoàn thiện | Unit, integration, AI provider compatibility |
+| CLI Tools (18) | ✅ Hoàn thiện | vp-tools 17 subcommands + viepilot installer; bundle `info` / `update` |
+| Tests (267) | ✅ Hoàn thiện | Unit, integration, AI provider compatibility, workflow contracts, viepilot-info, viepilot-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 |
@@ -116,10 +116,12 @@ Tổng thể / Overall:  ██████████████████
 | `/vp-pause` | Lưu state để resume sau / Save state for later | "pause", "dừng" | Control |
 | `/vp-resume` | Khôi phục context và tiếp tục / Restore and continue | "resume", "tiếp tục" | Control |
 | `/vp-status` | Dashboard tiến độ / Progress dashboard | "status", "tiến độ" | Monitor |
+| `/vp-info` | Bundle version, npm latest, skills/workflows inventory | "viepilot version", "phiên bản" | Monitor |
 | `/vp-request` | Bug/Feature/Enhancement/Debt / Ongoing requests | "bug", "feature", "yêu cầu" | Develop |
 | `/vp-ui-components` | Curation + reuse UI component library | "ui components", "21st.dev" | Develop |
 | `/vp-evolve` | Milestone mới, nâng cấp lớn / New milestone, major upgrade | "evolve", "milestone" | Develop |
 | `/vp-docs` | Generate documentation / Tạo tài liệu | "docs", "tài liệu" | Finalize |
+| `/vp-update` | Nâng cấp viepilot qua npm (dry-run / --yes / --global) | "upgrade viepilot", "npm update" | Maintain |
 | `/vp-task` | Quản lý task thủ công / Manual task control | "task" | Manual |
 | `/vp-debug` | Debug có hệ thống với state tracking / Systematic debugging | "debug", "gỡ lỗi" | Debug |
 | `/vp-rollback` | Khôi phục về checkpoint / Rollback to checkpoint | "rollback", "revert" | Recovery |
@@ -332,7 +334,7 @@ Full guide: `docs/dev/deployment.md`.
 
 ```
 viepilot/
-├── skills/                        # 13 Skill definitions
+├── skills/                        # 16 Skill definitions
 │   ├── vp-brainstorm/             # Thu thập ý tưởng
 │   │   └── SKILL.md
 │   ├── vp-crystallize/            # Tạo artifacts
@@ -340,9 +342,11 @@ viepilot/
 │   ├── vp-pause/                  # Save state
 │   ├── vp-resume/                 # Restore state
 │   ├── vp-status/                 # Progress dashboard
+│   ├── vp-info/                   # Bundle info (vp-tools info)
 │   ├── vp-request/                # Bug/Feature/Enhancement
 │   ├── vp-evolve/                 # Milestone/Upgrade
 │   ├── vp-docs/                   # Documentation
+│   ├── vp-update/                 # npm upgrade (vp-tools update)
 │   ├── vp-task/                   # Manual task control
 │   ├── vp-debug/                  # Systematic debugging
 │   ├── vp-rollback/               # Checkpoint recovery
@@ -386,9 +390,9 @@ viepilot/
 │   └── cli-shared.cjs             # Validators, project root, Levenshtein helpers
 │
 ├── bin/                           # CLI tools
-│   └── vp-tools.cjs               # 14 commands (requires ../lib/cli-shared.cjs)
+│   └── vp-tools.cjs               # 17 subcommands; uses ../lib/cli-shared.cjs, viepilot-info/update.cjs
 │
-├── tests/                         # Test suite (231 tests)
+├── tests/                         # Test suite (267 tests)
 │   ├── unit/                      # Unit tests
 │   │   ├── validators.test.js     # CLI subprocess + in-process coverage tests
 │   │   └── ai-provider-compat.test.js  # 142 AI compat tests
@@ -488,7 +492,7 @@ your-project/
 | [Getting Started](docs/getting-started.md) | Hướng dẫn bắt đầu / Quick start guide |
 | [Quick Start (User)](docs/user/quick-start.md) | 5-minute guide |
 | [Skills Reference](docs/skills-reference.md) | Chi tiết từng skill / Detailed skill docs |
-| [CLI Reference](docs/dev/cli-reference.md) | vp-tools 14 commands |
+| [CLI Reference](docs/dev/cli-reference.md) | vp-tools 17 subcommands (`info`, `update`, …) |
 | [Advanced Usage](docs/advanced-usage.md) | Power user features |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues & fixes |
 | [Architecture](docs/dev/architecture.md) | System design |

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/bin/vp-tools.cjs

@@ -23,6 +23,9 @@ const {
   isCheckpointTag,
 } = require(path.join(__dirname, '../lib/cli-shared.cjs'));
 
+const viepilotInfo = require(path.join(__dirname, '../lib/viepilot-info.cjs'));
+const viepilotUpdate = require(path.join(__dirname, '../lib/viepilot-update.cjs'));
+
 // ============================================================================
 // Output Formatting (TTY-aware)
 // ============================================================================
@@ -694,6 +697,133 @@ const commands = {
     }
   },
 
+  /**
+   * Show ViePilot package version, npm latest, skills/workflows inventory (FEAT-008)
+   */
+  info: (args) => {
+    const json = args.includes('--json');
+    const root = viepilotInfo.resolveViepilotPackageRoot(path.join(__dirname, '..'));
+    if (!root) {
+      console.error(
+        formatError(
+          'Could not locate viepilot package root',
+          'Install viepilot globally, use npx from a project with viepilot, or run from a viepilot clone'
+        )
+      );
+      process.exit(1);
+    }
+
+    const report = viepilotInfo.buildInfoReport(root);
+
+    if (json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    console.log(`\n${colors.bold}ViePilot bundle${colors.reset}\n`);
+    console.log(`  ${colors.cyan}Package root:${colors.reset} ${report.packageRoot}`);
+    console.log(`  ${colors.cyan}Installed:${colors.reset}   ${colors.bold}${report.installedVersion}${colors.reset} (${report.packageName})`);
+
+    if (report.latestNpm.ok) {
+      const upToDate = report.latestNpm.version === report.installedVersion;
+      const marker = upToDate ? colors.green : colors.yellow;
+      console.log(
+        `  ${colors.cyan}npm latest:${colors.reset}  ${marker}${report.latestNpm.version}${colors.reset}${upToDate ? ' (matches installed)' : ''}`
+      );
+    } else {
+      console.log(`  ${colors.cyan}npm latest:${colors.reset}  ${colors.gray}(unavailable: ${report.latestNpm.error})${colors.reset}`);
+    }
+
+    if (report.gitHead) {
+      console.log(`  ${colors.cyan}Git HEAD:${colors.reset}   ${report.gitHead.slice(0, 7)}`);
+    }
+
+    console.log(`\n${colors.bold}Skills (${report.skills.length})${colors.reset}`);
+    report.skills.forEach((s) => {
+      const verLabel =
+        s.version === 'unspecified'
+          ? `${colors.gray}unspecified${colors.reset}`
+          : `${colors.bold}v${s.version}${colors.reset}`;
+      console.log(`  ${colors.bold}${s.id.padEnd(22)}${colors.reset}  ${verLabel}  ${colors.gray}${s.relativePath}${colors.reset}`);
+    });
+
+    console.log(`\n${colors.bold}Workflows (${report.workflows.length})${colors.reset} ${colors.gray}— ${viepilotInfo.WORKFLOW_SEMVER_NOTE}${colors.reset}`);
+    report.workflows.forEach((w) => {
+      console.log(`  ${colors.bold}${w.id.padEnd(22)}${colors.reset} ${colors.gray}${w.relativePath}${colors.reset}`);
+    });
+    console.log();
+  },
+
+  /**
+   * Upgrade viepilot via npm (global, local dependency, or --global) — FEAT-008
+   */
+  update: async (args) => {
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    const globalFlag = args.includes('--global');
+    const startDir = path.join(__dirname, '..');
+    const plan = viepilotUpdate.buildUpdatePlan({ startDir, forceGlobal: globalFlag });
+
+    if (!plan.ok) {
+      console.error(formatError(plan.error));
+      process.exit(1);
+    }
+
+    if (plan.alreadyLatest) {
+      console.log(
+        formatSuccess(
+          `viepilot@${plan.installedVersion} is already up to date (npm latest: ${plan.latestVersion}).`
+        )
+      );
+      return;
+    }
+
+    if (plan.latestNpmError) {
+      console.log(formatWarning(`Could not read npm registry (continuing): ${plan.latestNpmError}`));
+    }
+    if (plan.ambiguous) {
+      console.log(
+        formatWarning(
+          'ViePilot install path looks like a source clone or unknown layout; using global npm install. Use --global to make this explicit.'
+        )
+      );
+    }
+
+    console.log(`\n${colors.cyan}Planned:${colors.reset} ${plan.displayCommand}\n`);
+    console.log(
+      `${colors.gray}Rollback (example): npm install -g viepilot@${plan.installedVersion || 'PREVIOUS'}${colors.reset}`
+    );
+
+    if (dryRun) {
+      console.log(`\n${formatInfo('Dry run — no changes applied.')}`);
+      return;
+    }
+
+    if (!isInteractive && !yes) {
+      console.error(
+        formatError(
+          'Non-interactive terminal: use --yes to run npm or --dry-run to preview only',
+          'Example: vp-tools update --dry-run && vp-tools update --yes'
+        )
+      );
+      process.exit(1);
+    }
+
+    if (isInteractive && !yes) {
+      const ok = await confirm('Run npm to apply this update?', false);
+      if (!ok) {
+        console.log(formatWarning('Aborted.'));
+        return;
+      }
+    }
+
+    const result = viepilotUpdate.runNpmUpdate(plan);
+    if (!result.ok) {
+      process.exit(result.code || 1);
+    }
+    console.log(formatSuccess('npm update completed.'));
+  },
+
   /**
    * Check for potential conflicts
    */
@@ -897,6 +1027,26 @@ const commands = {
           'vp-tools git-persistence --strict',
         ],
       },
+      info: {
+        usage: 'vp-tools info [--json]',
+        description: 'Show installed ViePilot version, latest npm version, skills & workflows inventory',
+        options: ['--json: Machine-readable JSON output'],
+        examples: ['vp-tools info', 'vp-tools info --json'],
+      },
+      update: {
+        usage: 'vp-tools update [--dry-run] [--yes] [--global]',
+        description: 'Update viepilot to npm latest (local dependency, global install, or explicit --global)',
+        options: [
+          '--dry-run: Print planned npm command only',
+          '--yes: Run npm without confirmation (CI / scripts)',
+          '--global: Force npm install -g viepilot@latest',
+        ],
+        examples: [
+          'vp-tools update --dry-run',
+          'vp-tools update --yes',
+          'vp-tools update --global --dry-run',
+        ],
+      },
     };
 
     if (command && commandHelp[command]) {
@@ -935,6 +1085,8 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}checkpoints${colors.reset}              List all ViePilot checkpoints (git tags)
   ${colors.bold}tag-prefix${colors.reset} [--raw]       Show project-scoped checkpoint prefix
   ${colors.bold}git-persistence${colors.reset} [--strict] Check commit/push persistence readiness
+  ${colors.bold}info${colors.reset} [--json]            Show ViePilot version, npm latest, skills/workflows
+  ${colors.bold}update${colors.reset} [--dry-run]       Update viepilot via npm (use --yes non-interactive)
   ${colors.bold}conflicts${colors.reset}                Check for potential conflicts
   ${colors.bold}save-state${colors.reset}               Save current state for precise resume
   ${colors.bold}help${colors.reset} [command]           Show help (optionally for specific command)

package/dev-install.sh

@@ -2,6 +2,9 @@
 
 # ViePilot Development Installation Script
 # Installs development build without symlink dependency by default
+#
+# Optional: VIEPILOT_SYMLINK_SKILLS=1 — symlink each skills/vp-* into ~/.cursor/skills/
+# (live edits from this repo; default remains copy for reliability — see FEAT-005)
 
 set -e
 
@@ -25,7 +28,11 @@ echo " VIEPILOT DEV INSTALLER"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo -e "${NC}"
 
-echo -e "${YELLOW}Development mode installation (copy-first for reliability)${NC}"
+if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
+    echo -e "${YELLOW}Development mode installation (skills: SYMLINK → repo)${NC}"
+else
+    echo -e "${YELLOW}Development mode installation (copy-first for reliability)${NC}"
+fi
 echo "  Source: $SCRIPT_DIR"
 echo "  Target: $CURSOR_SKILLS_DIR, $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
@@ -77,12 +84,22 @@ fi
 echo ""
 echo -e "${BLUE}Installing skills...${NC}"
 
-# Install skill copies (avoid symlink discovery issues)
+# Install skills: copy (default) or symlink when VIEPILOT_SYMLINK_SKILLS=1
 mkdir -p "$CURSOR_SKILLS_DIR"
 for skill in "$SCRIPT_DIR"/skills/vp-*/; do
     skill_name=$(basename "$skill")
-    cp -R "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
-    echo -e "  ${GREEN}✓${NC} $skill_name"
+    if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
+        if command -v realpath >/dev/null 2>&1; then
+            skill_abs=$(realpath "$skill")
+        else
+            skill_abs=$(cd "$skill" && pwd)
+        fi
+        ln -sfn "$skill_abs" "$CURSOR_SKILLS_DIR/$skill_name"
+        echo -e "  ${GREEN}✓${NC} $skill_name (symlink)"
+    else
+        cp -R "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
+        echo -e "  ${GREEN}✓${NC} $skill_name"
+    fi
 done
 
 echo ""
@@ -120,10 +137,14 @@ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━
 echo -e "${GREEN} DEV INSTALLATION COMPLETE ✓${NC}"
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
-echo "Installed (copy mode):"
+if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
+    echo "Installed (skills symlink mode):"
+    echo -e "${YELLOW}Skills point at repo — edits in $SCRIPT_DIR/skills/ are live.${NC}"
+else
+    echo "Installed (copy mode):"
+    echo -e "${YELLOW}Development mode enabled (reliable copy mode).${NC}"
+    echo "Re-run this script after local changes to refresh installed files."
+fi
 echo "  - Skills: $SKILL_COUNT"
 echo "  - Workflows: $WORKFLOW_COUNT"
 echo ""
-echo -e "${YELLOW}Development mode enabled (reliable copy mode).${NC}"
-echo "Re-run this script after local changes to refresh installed files."
-echo ""

package/docs/README.md

@@ -29,6 +29,8 @@
 | Feature | Document |
 |---------|----------|
 | Autonomous Mode | [autonomous-mode.md](user/features/autonomous-mode.md) (flags, `--fast`, lượt chat) |
+| Brainstorm & product horizon | [brainstorm.md](user/features/brainstorm.md) (MVP / Post-MVP tags, crystallize handoff) |
+| Product horizon end-to-end | [product-horizon.md](user/features/product-horizon.md) (brainstorm → ROADMAP / PROJECT-CONTEXT, AI load order) |
 | UI Direction Mode | [ui-direction.md](user/features/ui-direction.md) |
 | Checkpoint Recovery | [checkpoint-recovery.md](user/features/checkpoint-recovery.md) |
 | Debug Mode | [debug-mode.md](user/features/debug-mode.md) |
@@ -53,7 +55,7 @@
 |----------|-------------|
 | [Getting Started](getting-started.md) | Installation and first steps |
 | [Getting Started (dev entry)](dev/getting-started.md) | Short link into dev guide |
-| [CLI Reference](dev/cli-reference.md) | All 14 `vp-tools` commands with examples |
+| [CLI Reference](dev/cli-reference.md) | All `vp-tools` subcommands (incl. `info`, `update`) with examples |
 | [Architecture](dev/architecture.md) | System layers, data flow, design decisions |
 | [UI Components Library](dev/ui-components-library.md) | Curation taxonomy, storage contract, reuse flow |
 | [Contributing](dev/contributing.md) | How to add skills, workflows, CLI commands |
@@ -66,7 +68,7 @@
 
 | Document | Description |
 |----------|-------------|
-| [Skills Reference](skills-reference.md) | All 14 skills with flags and examples |
+| [Skills Reference](skills-reference.md) | All skills with flags and examples |
 | [Advanced Usage](advanced-usage.md) | Power user features and patterns |
 
 ---