viepilot 1.14.0 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,197 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-04-10
+
+### Added (FEAT-015 — Phase 62)
+- **Codex adapter**: `lib/adapters/codex.cjs` — OpenAI Codex CLI is now a first-class install target; skills install to `~/.codex/skills/`, viepilot bundle to `~/.codex/viepilot/`
+- `lib/adapters/index.cjs`: `codex` registered; `listAdapters()` now returns 4 unique adapters
+- `bin/viepilot.cjs`: Codex added to interactive installer TARGETS list and help text
+- `docs/user/features/adapters.md`: Codex row added; `$skill-name` invocation note; removed stale `dev-install.sh` reference
+
+### Notes
+- Codex uses `$vp-status` syntax (not `/vp-status`) — SKILL.md format is fully compatible, invocation prefix differs
+
+### Tests
+- Added `tests/unit/vp-adapter-codex.test.js` (11 tests)
+- Updated `tests/unit/vp-adapter-antigravity.test.js`: `listAdapters()` now expects 4
+- Updated `tests/unit/viepilot-adapters.test.js`: count 3 → 4
+- Updated `tests/unit/guided-installer.test.js`: `normalizeTargets('all')` includes codex
+- Total: 607 tests (was 596)
+
+## [2.3.2] - 2026-04-10
+
+### Changed (ENH-037 — Phase 61)
+- Post-install "Next actions" block is now adapter-driven: each adapter carries a `postInstallHint` string; CLI prints one hint per unique installed target — Antigravity now appears when installed
+- `lib/adapters/claude-code.cjs`, `cursor.cjs`, `antigravity.cjs`: added `postInstallHint` field
+
+## [2.3.1] - 2026-04-10
+
+### Removed (ENH-036 — Phase 60)
+- `install.sh` — bash wrapper was redundant; `bin/viepilot.cjs install` covers all install functionality
+- `dev-install.sh` — bash adapter routing duplicated `lib/adapters/`; `bin/viepilot.cjs install --target <adapter>` is the canonical path
+- Removed 5 tests that only verified shell script content (viepilot-install.test.js, viepilot-adapters.test.js, vp-adapter-antigravity.test.js)
+
+## [2.3.0] - 2026-04-10
+
+### Added (FEAT-014 — Phase 59)
+- **Antigravity adapter**: `lib/adapters/antigravity.cjs` — Google Antigravity IDE is now a first-class install target; skills install to `~/.antigravity/skills/`, viepilot bundle to `~/.antigravity/viepilot/`
+- `lib/adapters/index.cjs`: `antigravity` registered; `listAdapters()` now returns 3 unique adapters
+- `dev-install.sh`: `VIEPILOT_ADAPTER=antigravity` supported
+- `bin/viepilot.cjs`: Antigravity added to interactive installer TARGETS list and help text
+- `docs/user/features/adapters.md`: new doc — supported platforms table, install examples, guide for adding new adapters
+
+### Tests
+- Added `tests/unit/vp-adapter-antigravity.test.js` (12 tests)
+- Updated `tests/unit/viepilot-adapters.test.js`: `listAdapters()` now expects 3
+- Updated `tests/unit/guided-installer.test.js`: `normalizeTargets('all')` includes antigravity
+- Total: 600 tests (was 588)
+
+## [2.2.0] - 2026-04-10
+
+### Changed (ENH-035 — Phase 58)
+- **{envToolDir} template variable**: all 14 `skills/*/SKILL.md` source files now use `$HOME/{envToolDir}/` instead of hardcoded `$HOME/.cursor/viepilot/` — skill sources are platform-neutral
+- **`lib/viepilot-install.cjs`**: path substitution now unconditionally replaces `{envToolDir}` → `adapter.executionContextBase` for every adapter (Cursor → `.cursor/viepilot`, Claude Code → `.claude/viepilot`, future adapters just set `executionContextBase`)
+- **`lib/adapters/claude-code.cjs`**: removed `pathRewrite` field — no longer needed
+- **`lib/adapters/cursor.cjs`**: removed `pathRewrite: null` field — no longer needed
+- Adding a new adapter now requires only `executionContextBase` — no `pathRewrite` definition
+
+### Tests
+- Updated `tests/unit/viepilot-adapters.test.js`: removed `pathRewrite` assertion; rewrite step tests now check `from: '{envToolDir}'`; added cursor-target substitution test
+- Updated `tests/unit/viepilot-install.test.js`: 2 tests updated for ENH-035 behavior
+- Total: 588 tests (was 587)
+
+## [2.1.3] - 2026-04-10
+
+### Fixed (BUG-011 — Phase 55)
+- **brainstorm.md dialogue path**: confirmation option 1 now shows `.viepilot/ui-direction/{session-id}/notes.md` instead of bare `ui-direction/notes.md` — eliminates ambiguity with user-managed `{root}/ui-direction/` folders
+- **crystallize.md PATH GUARD**: `consume_ui_direction` step now opens with `⛔ PATH GUARD (BUG-011)` — explicitly instructs LLM to ignore any `{root}/ui-direction/` folder and read only from `.viepilot/ui-direction/`
+
+### Tests
+- Added `tests/unit/vp-bug011-ui-direction-path-guard.test.js` (3 tests)
+- Total: 587 tests (was 584)
+
+## [2.1.2] - 2026-04-10
+
+### Fixed (BUG-013 — Phase 57)
+- **Untrack .viepilot/ from git**: `git rm -r --cached .viepilot/` — removes all 27 previously-tracked internal state files from the git index; `.viepilot/` now correctly treated as gitignored on disk only, never staged or pushed
+- **GITIGNORE-AWARE STAGING RULE**: `workflows/autonomous.md` commit block now has `⛔ GITIGNORE-AWARE STAGING RULE (BUG-013)` — instructs vp-auto to check `git check-ignore -q` before staging, and explicitly forbids `git add .viepilot/`
+- **Git persistence gate note**: porcelain check section clarified — `??` (untracked-only) lines are CLEAN, not dirty state; prevents false gate failures after BUG-013 fix
+
+### Tests
+- Added `tests/unit/vp-bug013-gitignore-staging-rule.test.js` (3 tests)
+- Total: 584 tests (was 581)
+- **ui-direction path disambiguation**: `workflows/brainstorm.md` confirmation dialogue option 1 now shows full unambiguous path `.viepilot/ui-direction/{session-id}/notes.md` (was bare `ui-direction/notes.md`)
+- **crystallize PATH GUARD**: `workflows/crystallize.md` `consume_ui_direction` step now opens with `⛔ PATH GUARD (BUG-011)` — explicitly instructs LLM to ignore any `{root}/ui-direction/` folder and read only from `.viepilot/ui-direction/`
+
+## [2.1.1] - 2026-04-10
+
+### Fixed (BUG-012 — Phase 56)
+- **PATH RESOLUTION RULE**: `workflows/autonomous.md` now has `⛔ PATH RESOLUTION RULE (BUG-012)` block — explicitly states all file reads/edits during task execution resolve from `{cwd}` (repo root), never from `~/.claude/` or `~/.cursor/` install directories
+- **evolve.md cwd note**: `workflows/evolve.md` TASK PATH RULE section now includes BUG-012 cwd-resolution clarification: repo-relative paths always anchor to `{cwd}`, not install paths
+
+### Tests
+- Added `tests/unit/vp-bug012-path-resolution-rule.test.js` (3 tests)
+- Total: 581 tests (was 578)
+
+## [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,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.9.5-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.4.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-607%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.
+**Versioning:** Shield **2.4.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**2.4.0**) is the Node package identifier for this repo; 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,13 +28,13 @@ 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 | **~39,668+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **308** (16 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + FEAT-001 Claude Code + ENH-022 crystallize architecture files + viepilot-info/update/install) |
-| ViePilot phases (local `.viepilot`) | **34** phase cycles — **M1.29** FEAT-001 (**v1.9.3** doc); patch **v1.9.4** (Claude installer); **M1.28** FEAT-010 (**v1.9.1**); **v1.9.2** (ENH-019~021); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
+| Tests | **607** (34 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009/010/011/012/013/015 + ENH-021~037 routing/language/architect/adapter + BUG-009~013 guards + viepilot-info/update/install/adapters) |
+| ViePilot phases (local `.viepilot`) | **62** phase cycles — **v2.4.0** FEAT-015 Codex adapter; **v2.3.x** ENH-036~037 installer cleanup; **v2.0.0** FEAT-013 dynamic adapters; **v1.x** M1.29 (FEAT-001~013); xem `CHANGELOG.md` |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
 > Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
@@ -48,14 +48,14 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
 | CLI Tools | 2 | vp-tools.cjs (**17** subcommands) + viepilot.cjs (guided installer) |
-| Test Files | 15 | Jest: 14 unit + 1 integration (contracts, installer + Claude paths, info/update, FEAT-009, FEAT-010, FEAT-001, ENH-021, scope policy, …) |
+| Test Files | 34 | Jest: 33 unit + 1 integration (contracts, installer + Claude paths, info/update, FEAT-009/010/011~015, ENH-021~037, BUG-009~013 guards, adapter tests, scope policy, …) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.4** (Claude Code **installer** ~/.claude/skills); **v1.9.3** FEAT-001 doc; **v1.9.2** (ENH-019~021); **v1.9.1** FEAT-010; **v1.9.0** FEAT-009
+Tổng thể / Overall:  ████████████████████  ~99% ✅ Latest **v2.4.0** FEAT-015 Codex adapter; **v2.3.x** ENH-036~037 installer cleanup; **v2.1.x** BUG-009~013; **v2.0.0** FEAT-013 dynamic adapters
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
@@ -65,11 +65,11 @@ Tổng thể / Overall:  ██████████████████
 | Project Templates (12) | ✅ Hoàn thiện | Placeholders cho customization (+ `VIEPILOT-META` FEAT-009) |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
 | CLI Tools (18) | ✅ Hoàn thiện | vp-tools 17 subcommands + viepilot installer; bundle `info` / `update` |
-| Tests (304) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010/001, ENH-021, info/update |
+| Tests (607) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009~015, ENH-021~037, BUG-009~013, adapter tests, info/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 |
-| Installation | ✅ Hoàn thiện | install.sh + dev-install.sh |
+| Installation | ✅ Hoàn thiện | `bin/viepilot.cjs install` (Node-based, all adapters) |
 
 ---
 
@@ -205,10 +205,13 @@ Chọn target profile trong wizard (phím mũi tên + space + enter):
 - Claude Code
 - Cursor Agent
 - Cursor IDE
+- Antigravity
+- Codex
 
 Non-interactive:
 ```bash
 npx viepilot install --target cursor-agent --yes
+npx viepilot install --target codex --yes
 ```
 
 Gỡ cài đặt:
@@ -353,7 +356,7 @@ viepilot/
 │   ├── vp-rollback/               # Checkpoint recovery
 │   └── vp-audit/                  # Documentation sync
 │
-├── workflows/                     # 11 Workflow definitions
+├── workflows/                     # 12 Workflow definitions
 │   ├── brainstorm.md              # Brainstorm session flow
 │   ├── crystallize.md             # Artifact generation flow
 │   ├── autonomous.md              # Execution loop
@@ -388,17 +391,25 @@ viepilot/
 │       └── SUMMARY.md
 │
 ├── lib/                           # Shared CLI logic (coverage target for Jest)
-│   └── cli-shared.cjs             # Validators, project root, Levenshtein helpers
+│   ├── cli-shared.cjs             # Validators, project root, Levenshtein helpers
+│   └── adapters/                  # Dynamic adapter system (FEAT-013)
+│       ├── index.cjs              # Registry: listAdapters(), getAdapter()
+│       ├── claude-code.cjs        # Claude Code adapter (~/.claude/)
+│       ├── cursor.cjs             # Cursor adapter (~/.cursor/)
+│       ├── antigravity.cjs        # Antigravity adapter (~/.antigravity/)
+│       └── codex.cjs              # Codex CLI adapter (~/.codex/)
 │
 ├── bin/                           # CLI tools
 │   └── vp-tools.cjs               # 17 subcommands; uses ../lib/cli-shared.cjs, viepilot-info/update.cjs
 │
-├── tests/                         # Test suite (308 tests)
-│   ├── unit/                      # Unit tests
+├── tests/                         # Test suite (607 tests, 34 suites)
+│   ├── unit/                      # 33 unit test files
 │   │   ├── validators.test.js     # CLI subprocess + in-process coverage tests
-│   │   └── ai-provider-compat.test.js  # 142 AI compat tests
+│   │   ├── ai-provider-compat.test.js  # AI compat tests
+│   │   ├── viepilot-adapters.test.js   # Adapter registry tests
+│   │   └── vp-adapter-codex.test.js    # Codex adapter tests
 │   └── integration/               # Integration tests
-│       └── workflow.test.js       # 22 E2E tests
+│       └── workflow.test.js       # E2E tests
 │
 ├── .github/workflows/             # CI/CD
 │   └── ci.yml                     # Node 18/20/22 matrix
@@ -419,7 +430,6 @@ viepilot/
 │   ├── api-service/               # Express + JWT example
 │   └── cli-tool/                  # Node.js CLI example
 │
-├── install.sh                     # Installation script
 ├── Makefile                       # Developer commands
 ├── CHANGELOG.md                   # Version history
 ├── CONTRIBUTING.md                # Contribution guide

package/bin/viepilot.cjs

@@ -14,11 +14,15 @@ 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' },
+  { id: 'antigravity',  label: adapterMap['antigravity'].name },
+  { id: 'codex',        label: adapterMap['codex'].name },
 ];
 
 function printHelp() {
@@ -32,14 +36,14 @@ Usage:
   viepilot --list-targets
 
 Install options:
-  --target <id|id,id|all>   Target profile(s): claude-code (mirrors vp-* to ~/.claude/skills), cursor-agent, cursor-ide
+  --target <id|id,id|all>   Target profile(s): claude-code (mirrors vp-* to ~/.claude/skills), cursor-agent, cursor-ide, antigravity, codex
   --yes                      Non-interactive mode (skip confirmations)
   --dry-run                  Print actions only (Node installer; no bash)
   --list-targets             Print supported targets and exit
   --help                     Show help
 
 Uninstall options:
-  --target <id|id,id|all>   Remove assets (claude-code: ~/.claude/skills/vp-*; cursor-*: ~/.cursor/skills/vp-*; shared: ~/.cursor/viepilot)
+  --target <id|id,id|all>   Remove assets (claude-code: ~/.claude/skills/vp-*; cursor-*: ~/.cursor/skills/vp-*; antigravity: ~/.antigravity/skills/vp-*; codex: ~/.codex/skills/vp-*)
   --yes                     Non-interactive mode (skip confirmations)
   --dry-run                 Print actions only, do not remove files
 `);
@@ -254,7 +258,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 +311,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) {
@@ -335,8 +339,14 @@ async function installCommand(rawArgs) {
     else console.log(`- ${r.target}: failed (exit ${r.code})`);
   }
   console.log('\nNext actions:');
-  console.log('- Cursor: open project and run /vp-status');
-  console.log('- Claude Code: restart session if needed so ~/.claude/skills/vp-* is picked up; then /vp-status');
+  const seenAdapters = new Set();
+  for (const target of selectedTargets) {
+    const a = adapterMap[target];
+    if (a && !seenAdapters.has(a.id)) {
+      seenAdapters.add(a.id);
+      console.log(`- ${a.name}: ${a.postInstallHint || 'run /vp-status'}`);
+    }
+  }
   console.log('- If needed, run /vp-brainstorm then /vp-crystallize');
 
   return failed.length === 0 ? 0 : 1;

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)