viepilot 1.2.0 → 1.6.1

package/CHANGELOG.md

@@ -7,8 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
@@ -16,11 +43,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **M1.19 / Phase 23 (BUG-003) completed** — enforced deterministic git persistence gates for `/vp-auto`: PASS transitions now require clean worktree, configured upstream, and zero unpushed commits (via `vp-tools git-persistence --strict` in workflow).
 - **M1.18 / Phase 22 (BUG-002) completed** — introduced project-scoped checkpoint tags (`{project}-vp-p...`) and kept backward compatibility with legacy `vp-p...` tags for list/rollback flows.
 - **CI coverage** — Jest chỉ instrument process hiện tại; test CLI qua `spawnSync` khiến `bin/vp-tools.cjs` báo **0%**. Đã tách `lib/cli-shared.cjs` (validators, `findProjectRoot`, Levenshtein) và đặt `collectCoverageFrom` trên file đó; bổ sung test in-process + `require.main === module` gate cho CLI; `install.sh` / `dev-install.sh` cài kèm `lib/`.
 
 ### Documentation
 
+- `README.md`, `docs/README.md` — refreshed framework version, skills/commands/test counts, and index notes after M1.18 checkpoint-tag rollout.
+- `workflows/autonomous.md`, `skills/vp-auto/SKILL.md`, `docs/user/features/autonomous-mode.md`, `docs/skills-reference.md` — documented and standardized git persistence gate behavior for `/vp-auto`.
 - `README.md`, `docs/user/quick-start.md` — updated install wizard controls and uninstall command examples.
 - `README.md`, `docs/troubleshooting.md`, `docs/user/quick-start.md` — documented README metric sync flow, `cloc` fallback/install guidance, and maintainer usage.
 - `docs/troubleshooting.md` — added selector TTY fallback guidance and uninstall/reinstall recovery flow for legacy symlink installs.

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-0.10.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 **0.10.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.0.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 | 3 | Jest unit, integration, AI compatibility (202 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.14 roadmap phases ✅ (v0.10.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               # 13 commands (requires ../lib/cli-shared.cjs)
+│   └── vp-tools.cjs               # 17 subcommands; uses ../lib/cli-shared.cjs, viepilot-info/update.cjs
 │
-├── tests/                         # Test suite (202 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 13 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/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)
 // ============================================================================
@@ -634,6 +637,193 @@ const commands = {
     console.log(JSON.stringify({ prefix }));
   },
 
+  /**
+   * Validate git persistence readiness for PASS transitions
+   */
+  'git-persistence': (args) => {
+    const projectCheck = validators.requireProjectRoot();
+    validateArgs([projectCheck]);
+    const projectRoot = projectCheck.value;
+    const strict = args.includes('--strict');
+    const { execSync } = require('child_process');
+
+    let cleanWorktree = false;
+    let upstreamConfigured = false;
+    let aheadCount = null;
+    let branch = '';
+
+    try {
+      branch = execSync('git branch --show-current', { cwd: projectRoot, encoding: 'utf8' }).trim();
+    } catch (_e) {
+      branch = '';
+    }
+
+    try {
+      const status = execSync('git status --porcelain', { cwd: projectRoot, encoding: 'utf8' }).trim();
+      cleanWorktree = status.length === 0;
+    } catch (_e) {
+      cleanWorktree = false;
+    }
+
+    try {
+      execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', { cwd: projectRoot, encoding: 'utf8' });
+      upstreamConfigured = true;
+    } catch (_e) {
+      upstreamConfigured = false;
+    }
+
+    if (upstreamConfigured) {
+      try {
+        const output = execSync('git rev-list --count @{u}..HEAD', { cwd: projectRoot, encoding: 'utf8' }).trim();
+        aheadCount = parseInt(output, 10);
+      } catch (_e) {
+        aheadCount = null;
+      }
+    }
+
+    const readyForPersistedPass = cleanWorktree && upstreamConfigured && aheadCount === 0;
+    const result = {
+      branch,
+      clean_worktree: cleanWorktree,
+      upstream_configured: upstreamConfigured,
+      ahead_count: aheadCount,
+      ready_for_persisted_pass: readyForPersistedPass,
+    };
+
+    console.log(JSON.stringify(result, null, 2));
+
+    if (strict && !readyForPersistedPass) {
+      process.exit(1);
+    }
+  },
+
+  /**
+   * 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
    */
@@ -829,6 +1019,34 @@ const commands = {
           'vp-tools tag-prefix --raw',
         ],
       },
+      'git-persistence': {
+        usage: 'vp-tools git-persistence [--strict]',
+        description: 'Check if commit/push persistence gate is satisfied',
+        examples: [
+          'vp-tools git-persistence',
+          '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]) {
@@ -866,6 +1084,9 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}clean${colors.reset} [-f] [--dry-run]   Clean generated files (interactive)
   ${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 13 `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 13 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 |
 
 ---
@@ -122,4 +124,4 @@
 
 ---
 
-*Last updated: 2026-03-31 — ViePilot framework v0.10.0 (see `.viepilot/TRACKER.md`); guided NPX installer flow added.*
+*Last updated: 2026-03-31 — ViePilot framework v1.2.0 (see `.viepilot/TRACKER.md`); project-scoped checkpoint tags delivered.*

package/docs/dev/cli-reference.md

@@ -5,10 +5,12 @@
 ## Installation
 
 ```bash
-# Sau khi install ViePilot
+# Sau khi install ViePilot (global: npm i -g viepilot — có `vp-tools` trên PATH)
 vp-tools help
 ```
 
+Sau `npm i -g viepilot`, lệnh `vp-tools` (cùng bundle với `npx viepilot`) có sẵn để gọi `info` / `update` mà không cần clone repo.
+
 ---
 
 ## Commands
@@ -291,6 +293,73 @@ vp-tools help version
 
 ---
 
+### `info [--json]`
+
+Hiển thị metadata bundle ViePilot: thư mục gốc package đã resolve, version đã cài, (nếu có mạng) version mới nhất trên npm, optional `git HEAD`, danh sách **skills** và **workflows** kèm semver trong frontmatter (skills).
+
+**Không cần** project có `.viepilot/` — CLI resolve gói `viepilot` từ vị trí `vp-tools.cjs` hoặc từ `process.cwd()`.
+
+```bash
+vp-tools info
+vp-tools info --json
+```
+
+**Flags**:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | In một object JSON duy nhất (parse-friendly) |
+
+**JSON shape** (`vp-tools info --json`, rút gọn):
+
+```json
+{
+  "packageRoot": "/path/to/viepilot",
+  "packageName": "viepilot",
+  "installedVersion": "1.5.1",
+  "latestNpm": { "ok": true, "version": "1.5.1" },
+  "gitHead": "abc1234…",
+  "skills": [
+    { "id": "vp-auto", "version": "0.1.0", "relativePath": "skills/vp-auto/SKILL.md" }
+  ],
+  "workflows": [
+    { "id": "autonomous", "relativePath": "workflows/autonomous.md", "semverInFile": null, "note": "no semver in workflow markdown" }
+  ]
+}
+```
+
+**Errors**:
+- `Could not locate viepilot package root` — Cài global, thêm dependency `viepilot`, hoặc chạy `node path/to/viepilot/bin/vp-tools.cjs info` từ clone.
+
+---
+
+### `update [--dry-run] [--yes] [--global]`
+
+Nâng cấp package `viepilot` qua **npm** (local `node_modules`, global install, hoặc ép global).
+
+```bash
+vp-tools update --dry-run
+vp-tools update --yes
+vp-tools update --global --dry-run
+vp-tools update --global --yes
+```
+
+**Flags**:
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Chỉ in lệnh npm dự kiến và hướng dẫn rollback, **không** chạy npm |
+| `--yes` | Bỏ qua prompt; **bắt buộc** trong môi trường non-interactive khi thực sự apply |
+| `--global` | Ép `npm install -g viepilot@latest` |
+
+**Lưu ý**:
+- Trong repo **ứng dụng** có `node_modules/viepilot`, bản mặc định có thể cập nhật **dependency local** — dùng `--global` nếu chỉ muốn nâng bản global.
+- Non-interactive: dùng `vp-tools update --dry-run` trước, sau đó `vp-tools update --yes` (hoặc `--global --yes`).
+
+**Success**: Thông báo `npm update completed` hoặc `already up to date` (no-op).
+
+---
+
 ## Exit Codes
 
 | Code | Meaning |

package/docs/dev/contributing.md

@@ -14,6 +14,10 @@ Hướng dẫn đóng góp cho ViePilot framework.
    ```bash
    ./dev-install.sh
    ```
+   Để **symlink** toàn bộ `skills/vp-*` về repo (sửa skill là Cursor thấy ngay), dùng:
+   ```bash
+   VIEPILOT_SYMLINK_SKILLS=1 ./dev-install.sh
+   ```
 4. Tạo branch cho feature/fix:
    ```bash
    git checkout -b feat/my-new-skill