viepilot 1.2.0 → 1.6.1

package/docs/skills-reference.md

@@ -26,6 +26,8 @@ Complete reference for all ViePilot skills.
 
 ### Output
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
+- **Product horizon:** session file giữ **`## Product horizon`** (MVP / Post-MVP / Future tags, deferred capabilities, hoặc single-release statement) để `/vp-crystallize` không bỏ sót post-MVP — xem `workflows/brainstorm.md`.
+- UI Direction (optional): `.viepilot/ui-direction/{session-id}/` — legacy (`index.html`) hoặc multi-page (`pages/*.html` + hub + `## Pages inventory` trong `notes.md`). Chi tiết: [UI Direction](user/features/ui-direction.md).
 
 ---
 
@@ -33,6 +35,14 @@ Complete reference for all ViePilot skills.
 
 **Purpose**: Chuyển đổi brainstorm thành executable artifacts
 
+### UI direction intake
+- Nếu có `.viepilot/ui-direction/{session-id}/` với `pages/*.html`: đọc `notes.md` (**Pages inventory**), từng file page, và hub `index.html` để architecture UI không bỏ sót màn hình.
+
+### Product horizon (brainstorm → ROADMAP / context)
+- Step 1: trích **`## Product horizon`** từ mọi session; **horizon inventory** + cổng single-release / thiếu section — `workflows/crystallize.md`.
+- `ROADMAP.md`: luôn có block **Post-MVP / Product horizon** (hoặc ghi rõ single-release); `PROJECT-CONTEXT.md`: khối **`<product_vision>`** từ `templates/project/PROJECT-CONTEXT.md`.
+- Hướng dẫn user tổng quan: [product-horizon.md](user/features/product-horizon.md). Thứ tự load cho AI: `templates/project/AI-GUIDE.md` (bản crystallize copy vào `.viepilot/AI-GUIDE.md`).
+
 ### Metadata Collection
 - Project name, description
 - Organization name, website
@@ -96,8 +106,9 @@ For each phase:
     2. Create git tag
     3. Execute implementation
     4. Verify results
-    5. Handle outcome (pass/fail)
-    6. Update state
+    5. Enforce git persistence gate (`vp-tools git-persistence --strict`)
+    6. Handle outcome (pass/fail)
+    7. Update state
   Mark phase complete
 ```
 
@@ -189,6 +200,23 @@ AI pauses for user input when:
 
 ---
 
+## /vp-info
+
+**Purpose**: Xem metadata bundle ViePilot — version đã cài, npm latest, danh sách skills/workflows (FEAT-008).
+
+### CLI
+| Invocation | Description |
+|------------|-------------|
+| `vp-tools info` | Bảng human-readable |
+| `vp-tools info --json` | JSON parse được: `packageRoot`, `packageName`, `installedVersion`, `latestNpm`, `gitHead`, `skills[]`, `workflows[]` |
+| `node node_modules/viepilot/bin/vp-tools.cjs info` | Từ project có dependency `viepilot` |
+
+### JSON fields (tóm tắt)
+- **`skills[]`**: `id`, `version`, `relativePath`
+- **`workflows[]`**: `id`, `relativePath`, `semverInFile`, `note`
+
+---
+
 ## /vp-docs
 
 **Purpose**: Generate documentation
@@ -398,3 +426,20 @@ CHANGELOG.md (updated)
 | `skip N --reason "..."` | Skip task N |
 | `retry N` | Retry failed task N |
 | `rollback N` | Rollback task N changes |
+
+---
+
+## /vp-update
+
+**Purpose**: Nâng cấp package `viepilot` qua npm — có dry-run và xác nhận non-interactive (FEAT-008).
+
+### Flags
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | In planned npm command, không chạy |
+| `--yes` | Bỏ qua prompt; **bắt buộc** trong non-interactive khi apply |
+| `--global` | Ép `npm install -g viepilot@latest` |
+
+### Lưu ý
+- Trong repo **application** có `node_modules/viepilot`, update mặc định có thể target **local** — dùng **`--global`** nếu chỉ muốn global.
+- Luồng an toàn: `vp-tools update --dry-run` → sau đó `vp-tools update --yes` (hoặc `--global --yes`).

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

@@ -18,6 +18,7 @@ Mỗi task:
 3. Verify (automated + manual nếu cần)
 4. Commit với conventional commit message
 5. Tạo done tag (`{project}-vp-p{N}-t{T}-done`)
+6. Pass Git persistence gate (clean + pushed) trước khi mark done
 
 ## Flags
 
@@ -82,6 +83,21 @@ Trước khi mark task done, ViePilot kiểm tra:
 
 Nếu bất kỳ gate nào fail → control point.
 
+## Git Persistence Gate (BUG-003)
+
+Trước khi `/vp-auto` được phép mark task/phase là PASS:
+
+```bash
+node bin/vp-tools.cjs git-persistence --strict
+```
+
+Gate chỉ PASS khi:
+- Working tree sạch (không còn thay đổi chưa commit)
+- Nhánh hiện tại có upstream
+- Không còn commit local chưa push (`ahead_count = 0`)
+
+Nếu fail, workflow phải vào control point và **không được** cập nhật state sang `done/complete`.
+
 ## Checkpoints
 
 Mỗi task tạo 2 git tags:

package/docs/user/features/brainstorm.md

@@ -0,0 +1,28 @@
+# Brainstorm sessions — product horizon (MVP / Post-MVP / Future)
+
+ViePilot brainstorm lưu session tại `docs/brainstorm/session-*.md`. Để **không mất** ý tưởng sau MVP khi chạy `/vp-crystallize`, mỗi session nên có section **`## Product horizon`** (workflow tự gợi ý cấu trúc khi lưu).
+
+## Tag trên từng bullet
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `(MVP)` | Ship trong bản đầu tiên |
+| `(Post-MVP)` | Đã thống nhất nhưng sau release đầu |
+| `(Future)` | Hướng thử nghiệm / chưa cam kết |
+
+## Các subsection khuyến nghị
+
+- **Non-goals for MVP** — Cố tình không làm ở bản đầu (tránh bị hiểu là “quên”).
+- **Deferred capabilities** — Tính năng rõ ràng bị lùi khỏi MVP để crystallize map vào roadmap horizon.
+
+## Single-release (không có post-MVP)
+
+Ghi một dòng explicit trong `## Product horizon`, ví dụ: **Single-release product — no separate horizon epics.**
+
+## Tiếp tục session cũ
+
+Khi **Continue** session, giữ và cập nhật `## Product horizon`; không xóa section này trừ khi bạn chủ động đổi scope.
+
+## Bước tiếp
+
+Sau brainstorm: `/vp-crystallize` — horizon trong session được dùng để bổ sung roadmap và project context (xem workflow crystallize). Tổng quan end-to-end: [Product horizon](product-horizon.md).

package/docs/user/features/product-horizon.md

@@ -0,0 +1,18 @@
+# Product horizon — từ brainstorm tới roadmap (không để post-MVP “chết” trong session)
+
+Ý tưởng **sau MVP** dễ chỉ nằm trong file brainstorm rồi bị AI bỏ qua khi code. ViePilot chuẩn hóa **horizon** để mọi người (và AI) luôn thấy nó ở chỗ đúng.
+
+## Quy tắc ngắn
+
+1. Trong brainstorm: luôn có section **`## Product horizon`** với tag `(MVP)` / `(Post-MVP)` / `(Future)` — xem [Brainstorm & product horizon](brainstorm.md).
+2. Sau **`/vp-crystallize`**: horizon phải xuất hiện trong **`ROADMAP.md`** (Post-MVP / Future) và **vision theo pha** trong **`PROJECT-CONTEXT.md`** — không được “chỉ để trong `docs/brainstorm/`”.
+3. Khi AI bắt đầu task implementation sâu: đọc **vision + horizon trước**, rồi mới khóa kiến trúc chi tiết — xem thứ tự trong `AI-GUIDE.md` (file được crystallize tạo dưới `.viepilot/AI-GUIDE.md`).
+
+## Single-release
+
+Nếu không có lộ trình sau MVP, ghi rõ một dòng trong horizon (ví dụ *Single-release — no separate horizon epics*) để crystallize không bịa thêm epic.
+
+## Liên kết
+
+- Workflow brainstorm: `workflows/brainstorm.md` (trong repo ViePilot).
+- Workflow crystallize: `workflows/crystallize.md` — bước trích horizon và gate “không được lặng lẽ bỏ sót”.

package/docs/user/features/ui-direction.md

@@ -5,25 +5,76 @@
 ## Mục tiêu
 - Chốt hướng UI/UX sớm bằng prototype định hướng
 - Ghi quyết định thiết kế cùng ngữ cảnh nghiệp vụ
-- Tạo đầu vào rõ ràng cho `/vp-crystallize`
+- Tạo đầu vào rõ ràng cho `/vp-crystallize`, kể cả khi sản phẩm có **nhiều page** (FEAT-007)
 
-## Artifacts
-Mỗi session UI tạo/cập nhật:
+## Hai layout được hỗ trợ
+
+### A) Legacy — một file chính (FEAT-002)
+Dùng khi chỉ có một màn hình / một luồng prototype đơn.
 
 ```text
 .viepilot/ui-direction/{session-id}/
-  index.html
+  index.html    # toàn bộ direction
   style.css
-  notes.md
+  notes.md      # rationale, assumptions, references
+```
+
+### B) Multi-page — mỗi page một HTML (khuyến nghị khi ≥2 màn)
+Dễ diff, dễ review, dễ map sang routing thật sau này.
+
+```text
+.viepilot/ui-direction/{session-id}/
+  index.html           # hub: liên kết tới mọi page (nav / danh sách)
+  style.css            # shared styles (tránh copy lớn giữa các file)
+  pages/
+    landing.html
+    dashboard.html
+    ...
+  notes.md             # rationale + bảng inventory (bắt buộc khi có pages/)
 ```
 
-`notes.md` là nguồn sự thật cho:
-- rationale
-- assumptions
-- references (bao gồm 21st.dev links/prompts)
+- **`index.html`**: không bắt buộc trùng nội dung với một page cụ thể; nên là **mục lục + link** tới `pages/*.html` để mở nhanh từng màn.
+- **`pages/{slug}.html`**: một file cho một page/screen; đặt `slug` ổn định (trùng tên route dự kiến nếu đã biết).
+
+## `notes.md` — nguồn sự thật
+
+Luôn ghi:
+- rationale, assumptions, references (21st.dev, v.v.)
+
+### Hook bắt buộc khi thư mục `pages/` tồn tại
+
+Sau **mỗi** lần thêm / đổi tên / xóa file trong `pages/`, assistant **phải** cập nhật:
+
+1. Liên kết trong `index.html` (hub).
+2. Section **`## Pages inventory`** trong `notes.md` (bảng đầy đủ mọi page hiện có).
+
+Mẫu bảng (copy-paste và điền):
+
+```markdown
+## Pages inventory
+
+| Slug | File | Title | Purpose | Key sections | Nav to |
+|------|------|-------|---------|--------------|--------|
+| landing | pages/landing.html | Marketing home | Acquire signups | hero, features, CTA | signup, login |
+| dashboard | pages/dashboard.html | App shell | Overview metrics | sidebar, charts, alerts | settings |
+```
+
+- **Slug**: định danh ngắn, ổn định.
+- **File**: đường dẫn tương đối từ thư mục session.
+- **Nav to**: slug hoặc tên page đích (comma-separated).
+
+Nếu **không** có thư mục `pages/`, không cần section `## Pages inventory` (layout legacy).
 
 ## Flow khuyến nghị
 1. `/vp-brainstorm --ui`
-2. Cập nhật yêu cầu/điều chỉnh layout trong chat
-3. Assistant cập nhật artifacts theo từng quyết định
-4. `/vp-crystallize` đọc artifacts để map sang tech stack thật
+2. Chọn legacy hoặc multi-page theo số màn hình.
+3. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
+4. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+
+## Kiểm tra nhanh (optional)
+
+```bash
+node scripts/verify-ui-direction-pages.cjs
+```
+
+Script báo lỗi nếu có session có `pages/*.html` nhưng thiếu `## Pages inventory` hoặc thiếu tên file page trong `notes.md`.

package/docs/user/quick-start.md

@@ -54,6 +54,25 @@ npm run readme:sync
 # refresh README Total LOC metrics via cloc
 ```
 
+### Version check & update
+
+Sau khi có `vp-tools` trên PATH (ví dụ `npm i -g viepilot` hoặc cài qua `npx viepilot install` copy bundle):
+
+```bash
+vp-tools info
+vp-tools info --json
+```
+
+Cập nhật ViePilot qua npm — nên xem trước bằng dry-run; trong script/CI thêm `--yes` khi apply:
+
+```bash
+vp-tools update --dry-run
+vp-tools update --yes
+vp-tools update --global --yes
+```
+
+Trong project có dependency `viepilot`, có thể chạy: `node node_modules/viepilot/bin/vp-tools.cjs info`.
+
 ---
 
 ## Step 2: Create a New Project
@@ -103,6 +122,9 @@ ViePilot tạo `.viepilot/` directory với:
 - `TRACKER.md` — Progress tracking
 - `ARCHITECTURE.md` — System design
 - `SYSTEM-RULES.md` — Coding standards
+- `AI-GUIDE.md` — Thứ tự đọc context (kể cả **vision / horizon** trước khi khóa kiến trúc sâu)
+
+**Post-MVP không chỉ nằm trong brainstorm:** sau crystallize, horizon phải vào `ROADMAP.md` + vision theo pha trong `PROJECT-CONTEXT.md`. Tóm tắt cho user: [Product horizon end-to-end](features/product-horizon.md).
 
 ---
 

package/install.sh

@@ -2,6 +2,8 @@
 
 # ViePilot Installation Script
 # Installs ViePilot skills and tools to Cursor/Claude environment
+#
+# Optional: VIEPILOT_SYMLINK_SKILLS=1 — symlink skills/* into ~/.cursor/skills/ (absolute paths)
 
 set -e
 
@@ -109,13 +111,23 @@ mkdir -p "$VIEPILOT_DIR/bin"
 mkdir -p "$VIEPILOT_DIR/lib"
 mkdir -p "$VIEPILOT_DIR/ui-components"
 
-# Install skills
+# 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")
-        cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
-        echo "    ✓ $skill_name"
+        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
 

package/lib/viepilot-info.cjs

@@ -0,0 +1,196 @@
+/**
+ * ViePilot bundle metadata for `vp-tools info` (FEAT-008).
+ * Resolves the viepilot package root from the CLI location — no `.viepilot/` project required.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Walk upward from startDir (and optionally cwd) for package.json with name "viepilot".
+ * @param {string} startDir - e.g. path.join(__dirname, '..') from bin/vp-tools.cjs
+ * @returns {string|null} absolute package root or null
+ */
+function resolveViepilotPackageRoot(startDir) {
+  const tryRoots = [path.resolve(startDir), path.resolve(process.cwd())];
+  const seen = new Set();
+  for (const base of tryRoots) {
+    if (seen.has(base)) continue;
+    seen.add(base);
+    let dir = base;
+    while (dir && dir !== path.dirname(dir)) {
+      const pkgPath = path.join(dir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          if (pkg && pkg.name === 'viepilot') {
+            return dir;
+          }
+        } catch (_e) {
+          /* ignore */
+        }
+      }
+      dir = path.dirname(dir);
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {string|null}
+ */
+function readInstalledVersion(root) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.version || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Query npm registry for latest published version (requires network + npm on PATH).
+ * @returns {{ ok: true, version: string } | { ok: false, error: string }}
+ */
+function fetchLatestNpmVersion() {
+  try {
+    const out = execFileSync('npm', ['view', 'viepilot', 'version', '--json'], {
+      encoding: 'utf8',
+      timeout: 15000,
+      windowsHide: true,
+    }).trim();
+    const parsed = JSON.parse(out);
+    const version = typeof parsed === 'string' ? parsed : String(parsed);
+    return { ok: true, version };
+  } catch (e) {
+    return { ok: false, error: e.message || String(e) };
+  }
+}
+
+/**
+ * Parse `version:` from YAML-like frontmatter (first --- block).
+ * @param {string} content
+ * @returns {string}
+ */
+function parseSkillFileVersion(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) {
+    return 'unspecified';
+  }
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) {
+    return 'unspecified';
+  }
+  const block = content.slice(3, end);
+  const m = block.match(/^version:\s*["']?([^"'\r\n]+)["']?/m);
+  return m ? m[1].trim() : 'unspecified';
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {Array<{ id: string, version: string, relativePath: string }>}
+ */
+function listSkillsWithVersions(root) {
+  const skillsDir = path.join(root, 'skills');
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, ent.name, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+    const content = fs.readFileSync(skillFile, 'utf8');
+    out.push({
+      id: ent.name,
+      version: parseSkillFileVersion(content),
+      relativePath: path.join('skills', ent.name, 'SKILL.md').replace(/\\/g, '/'),
+    });
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+const WORKFLOW_SEMVER_NOTE = 'no semver in workflow markdown';
+
+/**
+ * @param {string} root
+ * @returns {Array<{ id: string, relativePath: string, semverInFile: null, note: string }>}
+ */
+function listWorkflows(root) {
+  const wfDir = path.join(root, 'workflows');
+  if (!fs.existsSync(wfDir)) {
+    return [];
+  }
+  const files = fs
+    .readdirSync(wfDir)
+    .filter((f) => f.endsWith('.md'))
+    .sort((a, b) => a.localeCompare(b));
+  return files.map((f) => ({
+    id: f.replace(/\.md$/i, ''),
+    relativePath: path.join('workflows', f).replace(/\\/g, '/'),
+    semverInFile: null,
+    note: WORKFLOW_SEMVER_NOTE,
+  }));
+}
+
+/**
+ * @param {string} root
+ * @returns {string|null}
+ */
+function tryGitHead(root) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 8000,
+      windowsHide: true,
+    }).trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ includeLatestNpm?: boolean }} [options]
+ */
+function buildInfoReport(root, options = {}) {
+  const includeLatestNpm = options.includeLatestNpm !== false;
+  const installedVersion = readInstalledVersion(root);
+  let pkgName = 'viepilot';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name) pkgName = pkg.name;
+  } catch (_e) {
+    /* keep default */
+  }
+
+  const report = {
+    packageRoot: root,
+    packageName: pkgName,
+    installedVersion: installedVersion || 'unknown',
+    latestNpm: includeLatestNpm ? fetchLatestNpmVersion() : { ok: false, error: 'skipped' },
+    gitHead: tryGitHead(root),
+    skills: listSkillsWithVersions(root),
+    workflows: listWorkflows(root),
+  };
+
+  return report;
+}
+
+module.exports = {
+  resolveViepilotPackageRoot,
+  readInstalledVersion,
+  fetchLatestNpmVersion,
+  parseSkillFileVersion,
+  listSkillsWithVersions,
+  listWorkflows,
+  tryGitHead,
+  buildInfoReport,
+  WORKFLOW_SEMVER_NOTE,
+};

package/lib/viepilot-update.cjs

@@ -0,0 +1,156 @@
+/**
+ * Plan and run `npm` upgrade for the viepilot package (FEAT-008 / vp-tools update).
+ */
+
+const path = require('path');
+const { spawnSync, execFileSync } = require('child_process');
+const viepilotInfo = require('./viepilot-info.cjs');
+
+/**
+ * @returns {string|null} absolute path to global .../node_modules/viepilot
+ */
+function tryGetNpmGlobalViepilotPath() {
+  try {
+    const root = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+    }).trim();
+    if (!root) return null;
+    return path.resolve(root, 'viepilot');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} viepilotPackageRoot
+ * @param {boolean} forceGlobal
+ * @param {string|null} globalViepilotPath
+ */
+function classifyInstall(viepilotPackageRoot, forceGlobal, globalViepilotPath) {
+  if (forceGlobal) {
+    return {
+      mode: 'global',
+      cwd: undefined,
+      npmArgs: ['install', '-g', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  const r = path.resolve(viepilotPackageRoot);
+  if (globalViepilotPath) {
+    const g = path.resolve(globalViepilotPath);
+    if (r === g) {
+      return {
+        mode: 'global',
+        cwd: undefined,
+        npmArgs: ['install', '-g', 'viepilot@latest'],
+        ambiguous: false,
+      };
+    }
+  }
+  const localSuffix = path.join('node_modules', 'viepilot');
+  if (r.endsWith(localSuffix)) {
+    const projectRoot = path.resolve(viepilotPackageRoot, '..', '..');
+    return {
+      mode: 'local',
+      cwd: projectRoot,
+      npmArgs: ['install', 'viepilot@latest'],
+      ambiguous: false,
+    };
+  }
+  return {
+    mode: 'global',
+    cwd: undefined,
+    npmArgs: ['install', '-g', 'viepilot@latest'],
+    ambiguous: true,
+  };
+}
+
+/**
+ * Rough semver compare for x.y.z (numeric segments only).
+ * @returns {-1|0|1|null} null if either side empty
+ */
+function compareSemver(a, b) {
+  if (a == null || b == null || a === '' || b === '') return null;
+  const pa = String(a).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.+]/).map((x) => parseInt(x, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {{ startDir: string, forceGlobal?: boolean }} opts
+ */
+function buildUpdatePlan(opts) {
+  const startDir = opts.startDir;
+  const forceGlobal = Boolean(opts.forceGlobal);
+  const root = viepilotInfo.resolveViepilotPackageRoot(startDir);
+  if (!root) {
+    return { ok: false, error: 'Could not locate viepilot package root' };
+  }
+
+  const installed = viepilotInfo.readInstalledVersion(root);
+  const latestResult = viepilotInfo.fetchLatestNpmVersion();
+
+  if (latestResult.ok && installed && compareSemver(installed, latestResult.version) >= 0) {
+    return {
+      ok: true,
+      alreadyLatest: true,
+      installedVersion: installed,
+      latestVersion: latestResult.version,
+      viepilotRoot: root,
+    };
+  }
+
+  const globalViepilotPath = tryGetNpmGlobalViepilotPath();
+  const layout = classifyInstall(root, forceGlobal, globalViepilotPath);
+  const displayCommand = layout.cwd
+    ? `(cwd ${layout.cwd}) npm ${layout.npmArgs.join(' ')}`
+    : `npm ${layout.npmArgs.join(' ')}`;
+
+  return {
+    ok: true,
+    alreadyLatest: false,
+    installedVersion: installed,
+    latestVersion: latestResult.ok ? latestResult.version : null,
+    latestNpmError: latestResult.ok ? null : latestResult.error,
+    viepilotRoot: root,
+    mode: layout.mode,
+    cwd: layout.cwd,
+    npmArgs: layout.npmArgs,
+    ambiguous: layout.ambiguous,
+    displayCommand,
+  };
+}
+
+/**
+ * @param {object} plan - from buildUpdatePlan (not alreadyLatest)
+ * @returns {{ ok: boolean, code?: number }}
+ */
+function runNpmUpdate(plan) {
+  const r = spawnSync('npm', plan.npmArgs, {
+    cwd: plan.cwd,
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+  if (r.status === 0) {
+    return { ok: true };
+  }
+  return { ok: false, code: r.status == null ? 1 : r.status };
+}
+
+module.exports = {
+  tryGetNpmGlobalViepilotPath,
+  classifyInstall,
+  compareSemver,
+  buildUpdatePlan,
+  runNpmUpdate,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.2.0",
+  "version": "1.6.1",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "test:watch": "jest --watch",
     "readme:sync": "node scripts/sync-readme-metrics.cjs",
     "lint:cli": "node --check bin/vp-tools.cjs && node --check bin/viepilot.cjs",
+    "verify:ui-direction": "node scripts/verify-ui-direction-pages.cjs",
     "verify:release": "npm run lint:cli && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run verify:release",
     "smoke:published": "node scripts/smoke-published.cjs",