viepilot 1.14.0 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-04-08
+
+### Added (FEAT-012 — Phase 54)
+- **Brainstorm staleness hook**: `lib/hooks/brainstorm-staleness.cjs` — Claude Code `Stop` event handler; fires after each AI response in a brainstorm session; detects stale architect HTML items via keyword matching; marks `data-arch-stale="true"` (amber badge, flag-only); non-blocking (exit 0 always)
+- `bin/vp-tools.cjs`: `hooks install [--adapter <id>]` subcommand — merges ViePilot hook entry into `~/.claude/settings.json`; idempotent (re-run safe)
+- `docs/user/features/hooks.md` — new user doc: install instructions, adapter table, troubleshooting
+- `workflows/brainstorm.md`: `architect_delta_sync` step now references automatic hook mode; `/hooks-install` command added
+
+### Tests
+- Added `tests/unit/brainstorm-staleness-hook.test.js` (20 tests, 4 groups) — session discovery, keyword detection, HTML patching, install command
+- Total: 578 tests (was 558)
+
+## [2.0.0] - 2026-04-08
+
+### Added (FEAT-013 — Phase 53)
+- **Dynamic agent adapter system**: `lib/adapters/` module with `claude-code.cjs`, `cursor.cjs`, `index.cjs` registry — each platform is a self-contained adapter (skillsDir, viepilotDir, executionContextBase, hooks config, installSubdirs, isAvailable, pathRewrite)
+- `lib/viepilot-install.cjs`: `buildInstallPlan()` now resolves all platform paths from adapter registry — no hardcoded `.cursor/` constants; single adapter loop replaces cursor + claude-code if-blocks
+- `bin/viepilot.cjs`: TARGETS sourced from adapter registry; default non-interactive target = `claude-code`
+- `dev-install.sh`: `VIEPILOT_ADAPTER` env var (default: `claude-code`); backward-compat `VIEPILOT_INSTALL_PROFILE` alias preserved
+- `bin/vp-tools.cjs`: `hooks scaffold [--adapter <id>]` subcommand — prints `~/.claude/settings.json` hook registration snippet for Claude Code; Cursor: prints explanation
+
+### BREAKING CHANGES
+- Default install target changes from `cursor-ide` → `claude-code` (`~/.claude/`)
+- Cursor users: set `VIEPILOT_ADAPTER=cursor-agent` (or `VIEPILOT_INSTALL_PROFILE=cursor-agent`) or pass `--target cursor-agent`
+- `normalizeInstallEnv({})` default profile is now `claude-code` (was `cursor-ide`)
+
+### Tests
+- Added `tests/unit/viepilot-adapters.test.js` (19 tests, 4 groups) — adapter interface, registry, install plan, dev-install.sh
+- Updated `tests/unit/viepilot-install.test.js` — 7 tests updated to reflect claude-code default; cursor-explicit tests use `VIEPILOT_INSTALL_PROFILE: 'cursor-ide'`
+- Total: 558 tests (was 539)
+
+## [1.19.0] - 2026-04-08
+
+### Added (ENH-034 — Phase 52)
+- **vp-brainstorm UI: Architect Delta Sync** — new `architect_delta_sync` step in `workflows/brainstorm.md`: bridges UI Direction Mode and Architect HTML workspace; when a UI session surfaces architect-related gaps, the step parses session for deltas, maps them to affected pages (using existing trigger keyword lists), updates `<tr>` / `<div class="card">` HTML content, marks changed items `data-updated="true"`, and records delta in `notes.md ## architect_sync`
+- `/sync-arch` command: manual trigger for architect delta sync at any point in a brainstorm session
+- `notes.md` YAML schema extended with `## architect_sync` section (synced_at, source_session, trigger, changes)
+- `templates/architect/style.css`: `.arch-gap-badge` (amber) + `[data-arch-stale="true"]` amber left-border indicator — visually distinct from `.updated` (yellow = changed); light-mode overrides included
+- `templates/architect/architect-actions.js`: `markStale(id, reason)` + `injectStaleBadges()` — auto-scans `[data-arch-stale="true"]` on DOMContentLoaded and injects amber "⚠ gap" badges; `window.vpMarkStale` exposed for browser console use
+
+### Tests
+- Added `tests/unit/vp-enh034-architect-delta-sync.test.js` (14 tests, 3 groups) — all pass (539 total)
+
+## [1.18.1] - 2026-04-07
+
+### Fixed (BUG-010 — Phase 51)
+- **Approve/Edit buttons missing on Mermaid diagram cards:** added `data-arch-id` + `data-arch-title` to all 9 diagram cards across 6 pages (architecture ARCH-DIAG1/2, data-flow DF-DIAG1/2, erd ERD-DIAG1, use-cases UC-DIAG1, sequence SEQ-DIAG1/2, deployment DEP-DIAG1)
+
+### Tests
+- Added Test Group 5 to `tests/unit/vp-enh033-architect-item-actions.test.js` (9 new tests) — 525 total
+
+## [1.18.0] - 2026-04-07
+
+### Added (ENH-033 — Phase 50)
+- **Architect HTML item actions:** stable `data-arch-id` IDs on every item across all 11 content pages (decisions D1–D2, architecture C1–C4, erd E1–E4, use-cases UC1–UC5, apis A1–A9, deployment DEP1–DEP7, data-flow DF1, sequence SEQ1–SEQ2, tech-stack TS1–TS6, tech-notes TN1, features F1–F3)
+- `templates/architect/architect-actions.js` — new shared vanilla JS: `approvePrompt()`, `editPrompt()`, `copyText()` with clipboard API + execCommand fallback, button injection on DOMContentLoaded
+- **✅ Approve button**: copies `[ARCH:{slug}:{id}] APPROVE — "{title}" on {slug} page. No changes needed.`
+- **✏️ Edit button**: copies `[ARCH:{slug}:{id}] EDIT — "{title}" on {slug} page. Current: "{excerpt}". What should I change?`
+- `templates/architect/style.css`: `.arch-id-badge`, `.arch-item-actions`, `.arch-btn`, `.arch-btn-approve`, `.arch-btn-edit`, `.arch-btn.copied`, `.arch-actions-cell` — hover-reveal pattern, light-mode overrides
+- `workflows/brainstorm.md`: **Architect Item Actions (ENH-033)** section — isolation rule, APPROVE/EDIT prompt handling spec, cross-page cascade prohibition
+
+### Tests
+- Added `tests/unit/vp-enh033-architect-item-actions.test.js` (50 tests, 4 groups) — all pass (516 total)
+
+## [1.17.0] - 2026-04-06
+
+### Added (ENH-032 — Phase 49)
+- **Language configuration system:** `~/.viepilot/config.json` stores `language.communication` and `language.document` (defaults: `en`/`en`)
+- `lib/viepilot-config.cjs` — new module: `readConfig`, `writeConfig`, `resetConfig`, `getConfigPath`; deep-merge with defaults; missing-file safe
+- `vp-tools config get/set/reset` — CLI commands to read and write language config
+- `lib/viepilot-install.cjs`: `language_config_prompt` step writes config at end of install; `--yes` uses defaults without prompting
+- `workflows/crystallize.md`: Step 0-A `load_language_config` — reads `DOCUMENT_LANG` + `COMMUNICATION_LANG` for file generation and session messages
+- `workflows/brainstorm.md`: Step 0 `detect_session_language` — reads `BRAINSTORM_LANG` for file storage; user session language overrides config
+- `workflows/autonomous.md`: `load_language_config` in Initialize — `COMMUNICATION_LANG` for banners and control-point messages
+- `skills/vp-crystallize/SKILL.md`, `skills/vp-brainstorm/SKILL.md`, `skills/vp-auto/SKILL.md`: ENH-032 language config notes
+
+### Tests
+- Added `tests/unit/vp-enh032-language-config.test.js` (18 tests) — all pass (466 total)
+
+## [1.16.0] - 2026-04-06
+
+### Changed (ENH-031 — Phase 48)
+- **Language standardization (English-primary):** all 12 workflows, all 16 skills, and `templates/project/AI-GUIDE.md` converted to English; Vietnamese retained only in `cursor_skill_adapter` invocation trigger keywords and UI scope signal detection patterns
+
+### Tests
+- Added `tests/unit/vp-enh031-language-standardization.test.js` (63 tests) — all pass (448 total)
+- Updated `vp-fe010-ui-walkthrough-contracts.test.js` + `vp-enh026-ui-extraction-contracts.test.js` to match translated English strings
+
+## [1.15.0] - 2026-04-06
+
+### Fixed (BUG-009 — Phase 47)
+- **Task path guard:** `workflows/evolve.md` now enforces repo-relative paths in task `## Paths` blocks (prevents generating `~/.claude/...` paths that would edit the live install instead of source)
+- **Preflight validation:** `workflows/autonomous.md` aborts task execution if `## Paths` contains `~/` or absolute path — error message names offending path and task file
+- `skills/vp-evolve/SKILL.md` + `skills/vp-auto/SKILL.md`: path convention documented in `<context>`
+
+### Tests
+- Added `tests/unit/vp-bug009-path-guard.test.js` (13 tests) — all pass (385 total)
+
 ## [1.14.0] - 2026-04-06
 
 ### Changed (ENH-030 — Phase 46)

package/README.md

@@ -2,12 +2,12 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-1.9.5-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.16.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-308%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-448%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
 **Versioning:** Shield **1.9.5** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.5**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
@@ -28,7 +28,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~27,991+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~34,308+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |

package/bin/viepilot.cjs

@@ -14,11 +14,13 @@ const { buildInstallPlan, applyInstallPlan, resolveViepilotPackageRoot } = requi
   'lib',
   'viepilot-install.cjs',
 ));
+const { adapters: adapterMap } = require(path.join(__dirname, '..', 'lib', 'adapters', 'index.cjs'));
 
+// UI target list — keep cursor-agent and cursor-ide as distinct choices for users.
 const TARGETS = [
-  { id: 'claude-code', label: 'Claude Code' },
+  { id: 'claude-code',  label: adapterMap['claude-code'].name + ' (default)' },
   { id: 'cursor-agent', label: 'Cursor Agent' },
-  { id: 'cursor-ide', label: 'Cursor IDE' },
+  { id: 'cursor-ide',   label: 'Cursor IDE' },
 ];
 
 function printHelp() {
@@ -254,7 +256,7 @@ async function interactiveTargetSelection() {
 function runInstallViaNode(selectedTargets, dryRun) {
   const fallbackRoot = path.join(__dirname, '..');
   const pkgRoot = resolveViepilotPackageRoot(fallbackRoot) || fallbackRoot;
-  const profile = selectedTargets[0] || 'cursor-ide';
+  const profile = selectedTargets[0] || 'claude-code';
   const env = {
     ...process.env,
     VIEPILOT_AUTO_YES: '1',
@@ -307,8 +309,8 @@ async function installCommand(rawArgs) {
 
   if (!selectedTargets) {
     if (options.yes) {
-      selectedTargets = TARGETS.map((t) => t.id);
-      console.log('No --target provided with --yes; defaulting to all targets.');
+      selectedTargets = ['claude-code'];
+      console.log('No --target provided with --yes; defaulting to claude-code.');
     } else {
       selectedTargets = await interactiveTargetSelection();
       if (selectedTargets.length === 0) {

package/bin/vp-tools.cjs

@@ -13,6 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const os = require('os');
 
 const {
   validators,
@@ -25,6 +26,7 @@ const {
 
 const viepilotInfo = require(path.join(__dirname, '../lib/viepilot-info.cjs'));
 const viepilotUpdate = require(path.join(__dirname, '../lib/viepilot-update.cjs'));
+const viepilotConfig = require(path.join(__dirname, '../lib/viepilot-config.cjs'));
 
 // ============================================================================
 // Output Formatting (TTY-aware)
@@ -946,6 +948,195 @@ const commands = {
     }, null, 2));
   },
 
+  /**
+   * Hooks scaffold + install — FEAT-013/FEAT-012 adapter hook management
+   * Usage: vp-tools hooks <scaffold|install> [--adapter <id>]
+   */
+  hooks: (args) => {
+    const sub = args[0];
+    if (!sub || sub === 'help') {
+      console.log(`${colors.cyan}Usage:${colors.reset}
+  vp-tools hooks scaffold [--adapter <id>]
+  vp-tools hooks install  [--adapter <id>]
+
+${colors.cyan}Subcommands:${colors.reset}
+  scaffold   Print hook config snippet for the target adapter (default: claude-code)
+  install    Install ViePilot staleness hook into adapter config file (idempotent)
+
+${colors.cyan}Options:${colors.reset}
+  --adapter <id>   Adapter ID: claude-code (default), cursor-agent, cursor-ide
+
+${colors.cyan}Examples:${colors.reset}
+  ${colors.gray}$${colors.reset} vp-tools hooks scaffold
+  ${colors.gray}$${colors.reset} vp-tools hooks scaffold --adapter cursor-agent
+  ${colors.gray}$${colors.reset} vp-tools hooks install
+  ${colors.gray}$${colors.reset} vp-tools hooks install --adapter claude-code`);
+      return;
+    }
+
+    // ── shared adapter resolution ──────────────────────────────────────────
+    const adapterArgIdx = args.indexOf('--adapter');
+    const adapterId = adapterArgIdx !== -1 ? args[adapterArgIdx + 1] : 'claude-code';
+    if (adapterArgIdx !== -1 && !adapterId) {
+      console.error(formatError('--adapter requires a value (e.g. claude-code, cursor-agent)'));
+      process.exit(1);
+    }
+    const { getAdapter } = require(path.join(__dirname, '../lib/adapters/index.cjs'));
+    let adapter;
+    try {
+      adapter = getAdapter(adapterId);
+    } catch (e) {
+      console.error(formatError(e.message));
+      process.exit(1);
+    }
+
+    if (sub === 'scaffold') {
+      if (!adapter.hooks || !adapter.hooks.configFile) {
+        console.log(`Adapter "${adapterId}" (${adapter.name}) does not use a settings.json hook config.`);
+        console.log(`For Cursor, hooks are configured via .cursorrules or project MDC files.`);
+        process.exit(0);
+      }
+      const home = os.homedir();
+      const configPath = adapter.hooks.configFile(home);
+      console.log(`\nViePilot hooks scaffold for: ${adapter.name}`);
+      console.log(`Config file: ${configPath}\n`);
+      console.log(`Add the following to your ${configPath}:\n`);
+      console.log(JSON.stringify({
+        hooks: {
+          Stop: [{
+            matcher: {},
+            hooks: [{
+              type: 'command',
+              command: `node ${path.join(home, '.viepilot', 'hooks', 'brainstorm-staleness.cjs')}`
+            }]
+          }]
+        }
+      }, null, 2));
+      console.log(`\nRun 'vp-tools hooks install' to register this hook automatically.`);
+      process.exit(0);
+    }
+
+    if (sub === 'install') {
+      if (!adapter.hooks || !adapter.hooks.configFile) {
+        console.log(`Adapter "${adapterId}" (${adapter.name}) does not support settings.json hooks.`);
+        console.log(`For Cursor, add hooks via .cursorrules or project MDC files.`);
+        process.exit(0);
+      }
+      const home = os.homedir();
+      const configPath = adapter.hooks.configFile(home);
+      const hookCommand = `node ${path.join(home, '.viepilot', 'hooks', 'brainstorm-staleness.cjs')}`;
+
+      // Read existing settings.json (create if missing)
+      let settings = {};
+      if (fs.existsSync(configPath)) {
+        try { settings = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch (_e) { settings = {}; }
+      }
+
+      // Merge hook entry — idempotent check
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.Stop) settings.hooks.Stop = [];
+
+      const alreadyInstalled = settings.hooks.Stop.some((entry) =>
+        Array.isArray(entry.hooks) &&
+        entry.hooks.some((h) => h.type === 'command' && h.command === hookCommand)
+      );
+
+      if (alreadyInstalled) {
+        console.log(formatSuccess('ViePilot staleness hook already installed.'));
+        console.log(`  Config: ${configPath}`);
+        process.exit(0);
+      }
+
+      settings.hooks.Stop.push({
+        matcher: {},
+        hooks: [{ type: 'command', command: hookCommand }],
+      });
+
+      try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+      } catch (e) {
+        console.error(formatError(`Failed to write ${configPath}: ${e.message}`));
+        process.exit(1);
+      }
+
+      console.log(formatSuccess('ViePilot staleness hook installed.'));
+      console.log(`  Config:  ${configPath}`);
+      console.log(`  Command: ${hookCommand}`);
+      process.exit(0);
+    }
+
+    console.error(formatError(`Unknown hooks subcommand: ${sub}`, 'Use: scaffold, install'));
+    process.exit(1);
+  },
+
+  /**
+   * Config get/set/reset — ENH-032 language configuration
+   */
+  config: (args) => {
+    const sub = args[0];
+    if (!sub || sub === 'help') {
+      console.log(`${colors.cyan}Usage:${colors.reset}
+  vp-tools config get <key>
+  vp-tools config set <key> <value>
+  vp-tools config reset
+
+${colors.cyan}Keys:${colors.reset}
+  language.communication   Language for AI communication/banners (e.g. en, vi)
+  language.document        Language for generated project files (e.g. en, vi)
+
+${colors.cyan}Examples:${colors.reset}
+  ${colors.gray}$${colors.reset} vp-tools config get language.communication
+  ${colors.gray}$${colors.reset} vp-tools config set language.communication vi
+  ${colors.gray}$${colors.reset} vp-tools config reset`);
+      return;
+    }
+    if (sub === 'get') {
+      const key = args[1];
+      if (!key) {
+        console.error(formatError('Missing key', 'Usage: vp-tools config get <key>'));
+        process.exit(1);
+      }
+      const cfg = viepilotConfig.readConfig();
+      const parts = key.split('.');
+      let val = cfg;
+      for (const p of parts) {
+        if (val == null || typeof val !== 'object') { val = undefined; break; }
+        val = val[p];
+      }
+      if (val === undefined) {
+        console.error(formatError(`Unknown config key: ${key}`));
+        process.exit(1);
+      }
+      console.log(val);
+      return;
+    }
+    if (sub === 'set') {
+      const key = args[1];
+      const value = args[2];
+      if (!key || value === undefined) {
+        console.error(formatError('Usage: vp-tools config set <key> <value>'));
+        process.exit(1);
+      }
+      const parts = key.split('.');
+      if (parts.length !== 2) {
+        console.error(formatError('Key must be in format <section>.<field> (e.g. language.communication)'));
+        process.exit(1);
+      }
+      const [section, field] = parts;
+      viepilotConfig.writeConfig({ [section]: { [field]: value } });
+      console.log(formatSuccess(`Set ${key} = ${value}`));
+      return;
+    }
+    if (sub === 'reset') {
+      viepilotConfig.resetConfig();
+      console.log(formatSuccess('Config reset to defaults (communication=en, document=en)'));
+      return;
+    }
+    console.error(formatError(`Unknown config subcommand: ${sub}`, 'Use get, set, or reset'));
+    process.exit(1);
+  },
+
   /**
    * Help
    */
@@ -1088,6 +1279,8 @@ ${colors.cyan}Commands:${colors.reset}
   ${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}hooks${colors.reset} scaffold|install [--adapter] scaffold: print snippet; install: write to settings.json
+  ${colors.bold}config${colors.reset} <get|set|reset>    Read/write language config (~/.viepilot/config.json)
   ${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

@@ -3,8 +3,11 @@
 # 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)
+# Optional env vars:
+#   VIEPILOT_ADAPTER      — target platform: claude-code (default), cursor, cursor-agent, cursor-ide
+#   VIEPILOT_INSTALL_PROFILE — backward-compat alias for VIEPILOT_ADAPTER
+#   VIEPILOT_AUTO_YES     — skip confirmation prompt (set to 1)
+#   VIEPILOT_SYMLINK_SKILLS=1 — symlink each skills/vp-* instead of copy
 
 set -e
 
@@ -17,10 +20,27 @@ NC='\033[0m'
 
 # Get script directory (project root)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
-VIEPILOT_DIR="$HOME/.cursor/viepilot"
 AUTO_YES="${VIEPILOT_AUTO_YES:-0}"
-INSTALL_PROFILE="${VIEPILOT_INSTALL_PROFILE:-cursor-agent}"
+
+# Backward compat: VIEPILOT_INSTALL_PROFILE accepted as alias for VIEPILOT_ADAPTER
+ADAPTER="${VIEPILOT_ADAPTER:-${VIEPILOT_INSTALL_PROFILE:-claude-code}}"
+
+case "$ADAPTER" in
+  claude-code)
+    SKILLS_DIR="$HOME/.claude/skills"
+    VIEPILOT_DIR="$HOME/.claude/viepilot"
+    PROFILE_LABEL="Claude Code"
+    ;;
+  cursor|cursor-agent|cursor-ide)
+    SKILLS_DIR="$HOME/.cursor/skills"
+    VIEPILOT_DIR="$HOME/.cursor/viepilot"
+    PROFILE_LABEL="Cursor"
+    ;;
+  *)
+    echo "Unknown adapter: $ADAPTER. Use: claude-code (default), cursor-agent, cursor-ide"
+    exit 1
+    ;;
+esac
 
 echo -e "${BLUE}"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -33,9 +53,10 @@ if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
 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"
+echo "  Source:  $SCRIPT_DIR"
+echo "  Skills:  $SKILLS_DIR"
+echo "  Viepilot: $VIEPILOT_DIR"
+echo "  Adapter: $ADAPTER ($PROFILE_LABEL)"
 echo ""
 
 check_cloc_dependency() {
@@ -68,7 +89,7 @@ echo ""
 echo -e "${BLUE}Removing old installations...${NC}"
 
 # Remove old skill installations
-for skill in "$CURSOR_SKILLS_DIR"/vp-*/; do
+for skill in "$SKILLS_DIR"/vp-*/; do
     if [ -d "$skill" ] || [ -L "$skill" ]; then
         rm -rf "$skill"
         echo "  Removed: $(basename "$skill")"
@@ -85,7 +106,7 @@ echo ""
 echo -e "${BLUE}Installing skills...${NC}"
 
 # Install skills: copy (default) or symlink when VIEPILOT_SYMLINK_SKILLS=1
-mkdir -p "$CURSOR_SKILLS_DIR"
+mkdir -p "$SKILLS_DIR"
 for skill in "$SCRIPT_DIR"/skills/vp-*/; do
     skill_name=$(basename "$skill")
     if [ "${VIEPILOT_SYMLINK_SKILLS:-0}" = "1" ]; then
@@ -94,10 +115,10 @@ for skill in "$SCRIPT_DIR"/skills/vp-*/; do
         else
             skill_abs=$(cd "$skill" && pwd)
         fi
-        ln -sfn "$skill_abs" "$CURSOR_SKILLS_DIR/$skill_name"
+        ln -sfn "$skill_abs" "$SKILLS_DIR/$skill_name"
         echo -e "  ${GREEN}✓${NC} $skill_name (symlink)"
     else
-        cp -R "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
+        cp -R "$skill" "$SKILLS_DIR/$skill_name"
         echo -e "  ${GREEN}✓${NC} $skill_name"
     fi
 done
@@ -129,7 +150,7 @@ echo -e "  ${GREEN}✓${NC} ui-components"
 check_cloc_dependency
 
 # Count installed
-SKILL_COUNT=$(ls -d "$CURSOR_SKILLS_DIR"/vp-*/ 2>/dev/null | wc -l | tr -d ' ')
+SKILL_COUNT=$(ls -d "$SKILLS_DIR"/vp-*/ 2>/dev/null | wc -l | tr -d ' ')
 WORKFLOW_COUNT=$(ls "$SCRIPT_DIR"/workflows/*.md 2>/dev/null | wc -l | tr -d ' ')
 
 echo ""

package/docs/user/features/hooks.md

@@ -0,0 +1,93 @@
+# ViePilot Hooks
+
+ViePilot integrates with Claude Code's hook system to automate actions after each AI response. Hooks are shell commands that fire at specific Claude Code events — no manual typing required.
+
+## Brainstorm Staleness Hook
+
+**Event**: `Stop` (fires after each Claude response)  
+**Script**: `~/.viepilot/hooks/brainstorm-staleness.cjs`  
+**Config**: `~/.claude/settings.json`
+
+### What it does
+
+After each exchange in a `vp-brainstorm` session, the hook automatically:
+
+1. Finds the most recently modified brainstorm session file (`notes.md` or `session-*.md`)
+2. Scans session content for keywords that match architect HTML pages
+3. Marks relevant architect items with `data-arch-stale="true"` — rendered as an amber "⚠ gap" badge in the browser
+4. Exits cleanly — if it fails or finds nothing, your session continues normally
+
+This is **flag-only** (Option A) — the hook does not rewrite architect HTML content, only marks items for review. Use `/sync-arch` to perform a full content sync.
+
+### Install
+
+Run once per machine:
+
+```bash
+node bin/vp-tools.cjs hooks install
+# or if installed globally:
+vp-tools hooks install
+```
+
+This writes the hook entry into `~/.claude/settings.json`. Running it again is safe (idempotent).
+
+To verify the install:
+
+```bash
+cat ~/.claude/settings.json | grep brainstorm-staleness
+```
+
+### Preview (scaffold)
+
+To see what will be written without installing:
+
+```bash
+node bin/vp-tools.cjs hooks scaffold
+```
+
+### Cursor users
+
+Cursor does not support `settings.json` hook events. Use `/sync-arch` manually within the brainstorm session to trigger architect delta sync (ENH-034).
+
+---
+
+## Adapter support
+
+Hook behavior is adapter-dependent:
+
+| Adapter | Config file | Programmatic events |
+|---------|-------------|---------------------|
+| `claude-code` | `~/.claude/settings.json` | Stop, PreToolUse, PostToolUse, UserPromptSubmit, … |
+| `cursor` | `.cursorrules` / MDC | None (no programmatic hook events) |
+
+Check your adapter's supported events:
+
+```bash
+node bin/vp-tools.cjs hooks scaffold --adapter claude-code
+```
+
+---
+
+## Adding custom hooks
+
+1. Create your hook script in `~/.viepilot/hooks/` (or anywhere accessible)
+2. Get the config format: `vp-tools hooks scaffold`
+3. Add your command to the relevant event array in `~/.claude/settings.json`
+
+Claude Code passes a JSON payload on stdin with `session_id`, `cwd`, `transcript_path`, and event-specific data. Your hook script should read from stdin and always exit 0.
+
+---
+
+## Troubleshooting
+
+**Hook not firing**  
+- Confirm `~/.claude/settings.json` has a `Stop` entry: `vp-tools hooks install` (idempotent)
+- Restart your Claude Code session after modifying `settings.json`
+
+**No stale badges appearing**  
+- The hook only marks stale if session content matches architect keyword triggers
+- Check that the brainstorm session notes file exists in `.viepilot/ui-direction/` or `docs/brainstorm/`
+- The architect HTML files must exist at `templates/architect/` (repo) or `~/.claude/viepilot/templates/architect/` (installed)
+
+**Hook error messages**  
+Hook errors appear on stderr (not in Claude's response). Check terminal output or Claude Code logs.

package/lib/adapters/claude-code.cjs

@@ -0,0 +1,42 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'claude-code',
+  name: 'Claude Code',
+  // Paths (home-relative; resolved at install time)
+  skillsDir:   (home) => path.join(home, '.claude', 'skills'),
+  viepilotDir: (home) => path.join(home, '.claude', 'viepilot'),
+  // execution_context base for skill .md files
+  executionContextBase: '.claude/viepilot',
+  // Path rewrite rule: when mirroring skills, rewrite from → to in *.md files
+  pathRewrite: { from: '.cursor/viepilot', to: '.claude/viepilot' },
+  // Hooks configuration (Claude Code settings.json)
+  hooks: {
+    configFile: (home) => path.join(home, '.claude', 'settings.json'),
+    schema: 'claude-code',
+    supportedEvents: [
+      'SessionStart', 'SessionEnd', 'Stop', 'StopFailure',
+      'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
+      'FileChanged', 'SubagentStart', 'SubagentStop',
+      'TaskCreated', 'TaskCompleted', 'PreCompact', 'PostCompact'
+    ]
+  },
+  // Files/dirs to install into viepilotDir
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  // Detection: is this platform available on the current machine?
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.claude'));
+  }
+};

package/lib/adapters/cursor.cjs

@@ -0,0 +1,31 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'cursor',          // maps to cursor-agent and cursor-ide (same paths)
+  name: 'Cursor',
+  skillsDir:   (home) => path.join(home, '.cursor', 'skills'),
+  viepilotDir: (home) => path.join(home, '.cursor', 'viepilot'),
+  executionContextBase: '.cursor/viepilot',
+  pathRewrite: null,     // no rewrite needed (source is cursor-first)
+  hooks: {
+    configFile: null,    // Cursor uses .cursorrules/MDC, not settings.json hooks
+    schema: 'cursor',
+    supportedEvents: []  // no programmatic hook events
+  },
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.cursor'));
+  }
+};