viepilot 1.0.0

package/docs/troubleshooting.md

@@ -0,0 +1,297 @@
+# ViePilot Troubleshooting Guide
+
+Common issues and solutions when using ViePilot.
+
+---
+
+## Installation Issues
+
+### `npx viepilot install` fails: "command not found" or "404"
+
+**Cause**: Package không có trong npm context hiện tại hoặc chưa publish phiên bản mới.
+
+```bash
+# Run from repository source as fallback
+cd /path/to/viepilot
+node bin/viepilot.cjs install --target all --yes
+```
+
+---
+
+### `npx viepilot install` asks too many prompts in CI
+
+**Cause**: Missing non-interactive flags.
+
+```bash
+npx viepilot install --target cursor-agent --yes --dry-run
+```
+
+Use `--yes` for no prompt and `--target` to avoid interactive selection.
+
+---
+
+### `./install.sh: Permission denied`
+
+**Cause**: Script not executable.
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+---
+
+### `vp-tools: command not found`
+
+**Cause**: ViePilot bin not in PATH.
+
+```bash
+# Check if symlink exists
+ls -la ~/.local/bin/vp-tools
+
+# If missing, re-run dev install
+cd /path/to/viepilot
+./dev-install.sh
+```
+
+---
+
+### Skills not showing in Cursor
+
+**Cause**: Skills not copied to the right directory.
+
+```bash
+ls ~/.cursor/skills/vp-*/SKILL.md
+```
+
+If empty:
+```bash
+cd /path/to/viepilot
+cp -r skills/vp-* ~/.cursor/skills/
+```
+
+Then restart Cursor.
+
+---
+
+## Project Initialization Issues
+
+### `/vp-brainstorm` doesn't produce a template
+
+**Cause**: AI model not following the skill structure.
+
+**Fix**: Ensure Cursor is using Claude (not GPT). Check Cursor settings → Model.
+
+---
+
+### `vp-tools init` fails: "No ViePilot project found"
+
+**Cause**: Running command outside a project with `.viepilot/` directory.
+
+```bash
+# Verify .viepilot/ exists
+ls .viepilot/
+
+# If missing, run crystallize first
+# In Cursor: /vp-crystallize
+```
+
+---
+
+### `HANDOFF.json` is corrupted
+
+**Cause**: Interrupted write during state save.
+
+```bash
+# Check the file
+cat .viepilot/HANDOFF.json
+
+# If invalid JSON, delete and let ViePilot recreate
+rm .viepilot/HANDOFF.json
+# In Cursor: /vp-auto  (will start from TRACKER.md state)
+```
+
+---
+
+## Autonomous Execution Issues
+
+### `/vp-auto` starts but stops immediately
+
+**Cause**: TRACKER.md says all phases complete.
+
+```bash
+cat .viepilot/TRACKER.md
+# Check "Current Phase" section
+
+# If ROADMAP.md has new phases not in TRACKER.md:
+# In Cursor: /vp-status
+# Then: /vp-auto --from N  (where N is the new phase)
+```
+
+---
+
+### `/vp-auto` runs one task then the AI ends the turn
+
+**Cause**: In chat (Cursor, etc.), one invocation often spans **one task** (implement → verify → update state). Spec does **not** require “no extra args ⇒ stop after every task”; that is typical **session** behavior, not `VP_ARGS` parsing.
+
+**Fix**:
+
+1. Send another message: continue the same phase/task from `HANDOFF.json` / `PHASE-STATE.md`, or run `/vp-auto` again.
+2. Use `/vp-auto --fast` to skip **optional** verification steps (fewer pauses).
+3. If the task file defines **manual** verification, you will be prompted — that is intentional.
+
+See: [Autonomous mode](user/features/autonomous-mode.md).
+
+---
+
+### Phase stuck at 0% for a long time
+
+**Cause**: AI model is not executing the task — just planning.
+
+**Fix**: Be more direct in the chat:
+
+> "Execute the task now. Create the files. Don't just describe what to do."
+
+Or use:
+```
+/vp-task start 1
+```
+
+---
+
+### Task marked done but code wasn't written
+
+**Cause**: AI confirmed acceptance criteria without verifying actual implementation.
+
+```bash
+# Check if files exist
+ls -la src/
+
+# Roll back to before the task
+/vp-rollback
+# Select the task's start checkpoint
+
+# Restart with explicit instruction
+/vp-task retry 1
+```
+
+---
+
+### Git tag creation fails: "tag already exists"
+
+**Cause**: Previous run created the tag.
+
+```bash
+# Delete the conflicting tag
+git tag -d vp-p2-t3
+
+# Resume
+/vp-auto --from 2
+```
+
+---
+
+## CLI Issues
+
+### `vp-tools progress` shows 0% even after tasks done
+
+**Cause**: PHASE-STATE.md uses different status format than expected.
+
+ViePilot's `progress` command looks for `✅ Done` pattern in PHASE-STATE.md.
+
+```bash
+# Check what's in the file
+grep -i "done\|complete" .viepilot/phases/*/PHASE-STATE.md
+
+# If status uses different emoji/text, manually update:
+# Change "✔ Complete" to "✅ Done"
+```
+
+---
+
+### `vp-tools version bump` shows wrong version
+
+**Cause**: TRACKER.md version block uses non-standard format.
+
+Expected format in TRACKER.md:
+```markdown
+### Current Version
+\`\`\`
+0.1.0
+\`\`\`
+```
+
+If your TRACKER.md uses a different format, `version bump` may not parse correctly.
+Edit TRACKER.md to match this exact format.
+
+---
+
+## State Recovery
+
+### How to fully reset ViePilot state
+
+```bash
+# Option 1: Reset to a checkpoint
+/vp-rollback
+# Select earliest checkpoint
+
+# Option 2: Manual reset (nuclear option)
+vp-tools reset all --force
+# WARNING: Resets all task statuses to not_started
+# Does NOT undo git commits
+
+# Option 3: Start fresh
+rm -rf .viepilot/
+# In Cursor: /vp-crystallize  (re-generates .viepilot/)
+```
+
+---
+
+### Resume after a crash
+
+```bash
+# Check last known state
+cat .viepilot/HANDOFF.json
+
+# Check git log for last checkpoint tag
+git log --oneline --tags
+
+# Resume from last complete phase
+/vp-resume
+# Or specify:
+/vp-auto --from 2
+```
+
+---
+
+## Performance Issues
+
+### `/vp-auto` is very slow
+
+**Common causes**:
+1. Large codebase being read every task → Use minimal context loading
+2. AI generating overly verbose responses → Not controllable, but `/vp-auto --fast` skips optional steps
+3. Many small tasks → Consider merging small tasks in ROADMAP.md
+
+---
+
+### Tests taking too long in CI
+
+**Cause**: Integration tests spawn subprocesses per test.
+
+```bash
+# Check test timing
+npx jest --verbose
+
+# Run only unit tests in CI for fast feedback
+npx jest tests/unit/ --no-coverage
+```
+
+---
+
+## Getting Help
+
+1. **Check the status**: `/vp-status` — shows blockers, current state
+2. **Debug mode**: `/vp-debug investigate: <your issue>`
+3. **GitHub Issues**: https://github.com/0-CODE/viepilot/issues
+4. **Review HANDOFF.json**: Contains full context of last session

package/docs/user/faq.md

@@ -0,0 +1,117 @@
+# Frequently Asked Questions
+
+## General
+
+### Q: ViePilot có yêu cầu AI provider cụ thể không?
+
+A: ViePilot hoạt động với bất kỳ AI assistant nào có thể đọc Markdown và thực thi code. Được test tốt nhất với **Cursor + Claude**. Cũng hoạt động với Claude CLI và các AI assistants khác.
+
+---
+
+### Q: ViePilot có thể dùng với VS Code không?
+
+A: Skills được thiết kế cho Cursor IDE. Tuy nhiên, workflows và CLI (`vp-tools`) hoạt động với bất kỳ editor nào. Bạn có thể dùng Claude CLI để chạy skills trong terminal.
+
+---
+
+### Q: Tôi có cần biết code để dùng ViePilot không?
+
+A: Không nhất thiết. ViePilot giúp AI code cho bạn. Tuy nhiên, để review code và approve control points, hiểu biết cơ bản về programming sẽ hữu ích.
+
+---
+
+### Q: ViePilot có tốn tiền không?
+
+A: ViePilot framework là **miễn phí và open source**. Bạn chỉ trả tiền cho AI provider (Cursor subscription hoặc Claude API).
+
+---
+
+## Technical
+
+### Q: `.viepilot/` directory là gì?
+
+A: Thư mục chứa toàn bộ project state của ViePilot:
+```
+.viepilot/
+├── AI-GUIDE.md       # Navigation guide cho AI
+├── TRACKER.md        # Progress tracking
+├── ROADMAP.md        # Phases và tasks
+├── HANDOFF.json      # Machine-readable state
+└── phases/           # Phase-specific files
+```
+
+Commit thư mục này vào git — nó là "memory" của dự án.
+
+---
+
+### Q: HANDOFF.json là gì?
+
+A: File JSON chứa machine-readable state: phase hiện tại, task, git HEAD, context. Được update sau mỗi task. Dùng để resume chính xác sau khi pause.
+
+---
+
+### Q: Tôi có thể edit `.viepilot/` files thủ công không?
+
+A: Có, nhưng cẩn thận:
+- `TRACKER.md`, `ROADMAP.md` — OK để edit
+- `HANDOFF.json` — Dùng `vp-tools save-state` thay vì edit trực tiếp
+- Phase PHASE-STATE.md — OK để edit status
+
+---
+
+### Q: Git tags `vp-p*` là gì?
+
+A: Checkpoint tags được tạo tự động bởi ViePilot:
+- `vp-p1-t1` — Bắt đầu task 1 của phase 1
+- `vp-p1-t1-done` — Hoàn thành task 1
+- `vp-p1-complete` — Hoàn thành phase 1
+
+Dùng để rollback an toàn. Xem: `vp-tools checkpoints`
+
+---
+
+### Q: Tại sao `vp-tools progress` hiển thị 0% dù đã làm xong tasks?
+
+A: `progress` command đọc `✅ Done` pattern trong PHASE-STATE.md. Nếu AI dùng format khác (ví dụ: `✔ Complete`), progress sẽ không tính đúng.
+
+Fix: Update PHASE-STATE.md để dùng `✅ Done` format.
+
+---
+
+### Q: Tôi có thể dùng ViePilot cho dự án đã có sẵn không?
+
+A: Có! Chạy `/vp-brainstorm` trong thư mục dự án hiện tại. ViePilot sẽ analyze existing code và tạo roadmap cho phần còn lại.
+
+---
+
+## Workflow
+
+### Q: Khác nhau giữa `/vp-pause` và đóng Cursor là gì?
+
+A: `/vp-pause` lưu full context vào `HANDOFF.json` và tạo `.continue-here.md` với instructions. Đóng Cursor không lưu context — bạn sẽ cần `/vp-resume` để restore state đúng cách.
+
+---
+
+### Q: Tôi có thể chạy nhiều phases song song không?
+
+A: Không — ViePilot chạy phases tuần tự theo dependency order. Tuy nhiên, trong một phase, các independent tasks có thể được execute song song (tùy AI implementation).
+
+---
+
+### Q: `/vp-auto` dừng giữa chừng — phải làm gì?
+
+A: Dùng `/vp-resume` để tiếp tục từ điểm dừng. Nếu có lỗi, dùng `/vp-debug` để investigate, sau đó `/vp-auto --from N` để restart từ phase N.
+
+---
+
+### Q: Làm sao thêm feature mới khi project đang chạy?
+
+A: Dùng `/vp-request --feature` — ViePilot sẽ insert phase mới vào roadmap mà không disrupt phases hiện tại.
+
+---
+
+### Q: Khi nào nên dùng `/vp-evolve` vs `/vp-request`?
+
+A: 
+- `/vp-request --feature` — Thêm feature nhỏ vào milestone hiện tại
+- `/vp-evolve` — Bắt đầu milestone mới (M2, M3) với scope lớn hơn

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

@@ -0,0 +1,111 @@
+# Feature: Autonomous Mode (`/vp-auto`)
+
+Autonomous mode điều phối **toàn bộ** phase và task theo `workflows/autonomous.md`. Bạn **ít can thiệp** so với làm tay từng file, nhưng vẫn có **control points** và (trong chat) thường **phải tiếp tục** qua nhiều lượt nếu một lượt AI chỉ kịp một task.
+
+## Overview
+
+```
+/vp-auto
+  │
+  ├── Phase 1 → Task 1.1 → Task 1.2 → Task 1.3 → Phase 1 ✅
+  ├── Phase 2 → Task 2.1 → Task 2.2 → ...        → Phase 2 ✅
+  └── Phase N → ...                               → Done 🎉
+```
+
+Mỗi task:
+1. Tạo git checkpoint tag (`vp-p{N}-t{T}`)
+2. Implement theo acceptance criteria
+3. Verify (automated + manual nếu cần)
+4. Commit với conventional commit message
+5. Tạo done tag (`vp-p{N}-t{T}-done`)
+
+## Flags
+
+```bash
+/vp-auto                  # Bắt đầu từ phase chưa complete (không bật --fast)
+/vp-auto --from 3         # Bắt đầu từ phase 3
+/vp-auto --phase 2        # Chỉ chạy phase 2
+/vp-auto --fast           # Skip optional verifications
+/vp-auto --dry-run        # Preview, không execute
+```
+
+### Doc-first gate (v0.8.2 / BUG-001)
+
+Workflow `autonomous.md` yêu cầu **ghi nhận kế hoạch trong file task** và **`PHASE-STATE` → `in_progress`** trước khi chỉnh sửa deliverable. Xem `workflows/autonomous.md` — *Pre-execution documentation gate*.
+
+### `/vp-auto` không có thêm arg — hiểu đúng
+
+- **Không** có nghĩa “mỗi task bắt buộc dừng một lần” trong tài liệu workflow; đó không phải cờ ẩn.
+- Có nghĩa bạn không truyền `--fast`, `--from`, `--phase`, `--dry-run` — verify *tùy chọn* sẽ được xử lý đầy đủ hơn so với `--fast`.
+- Nếu **mọi phase** đã complete, workflow dừng ở banner “All phases complete” (không còn lặp task).
+
+### Tại sao vẫn thấy “dừng” sau mỗi task?
+
+1. **Chat / Cursor** — Một turn thường đủ cho một task (implement → verify → cập nhật state). Task tiếp theo: gọi lại `/vp-auto` hoặc nhắc tiếp trong cùng thread.
+2. **Control points** — Conflict, fail quality gate, blocker, hoặc menu retry/skip/rollback.
+3. **Manual verification** — Nếu `tasks/*.md` định nghĩa bước manual, AI được hướng dẫn hỏi bạn.
+4. **Task contract** — Task thiếu mục bắt buộc (ENH-010) thì phải refine task trước khi code (dừng có chủ đích).
+
+**Gợi ý:** Dùng `--fast` khi muốn giảm các bước verify *optional* (vẫn không bỏ gate bắt buộc đã mô tả trong task).
+
+## Control Points
+
+ViePilot tự động dừng và hỏi bạn khi:
+
+```
+⚠ Phase 2 (Database): Issue Encountered
+
+Conflicting migration files detected.
+
+Options:
+1. Fix and retry
+2. Skip task
+3. Rollback task
+4. Stop autonomous mode
+```
+
+**Khi nào xảy ra**:
+- Conflicts với existing code
+- Quality gate failures (tests fail, lint errors)
+- Task cần user decision
+- Blockers không thể tự resolve
+
+## Quality Gates
+
+Trước khi mark task done, ViePilot kiểm tra:
+
+```
+✅ acceptance_criteria_met
+✅ automated_tests_pass
+✅ no_lint_errors
+```
+
+Nếu bất kỳ gate nào fail → control point.
+
+## Checkpoints
+
+Mỗi task tạo 2 git tags:
+
+```bash
+vp-p2-t3        # Bắt đầu task 3 của phase 2
+vp-p2-t3-done   # Hoàn thành task 3 của phase 2
+```
+
+Khi phase complete:
+```bash
+vp-p2-complete  # Phase 2 hoàn thành
+```
+
+Xem tất cả checkpoints:
+```bash
+vp-tools checkpoints
+```
+
+## Tips
+
+- **Đừng interrupt** khi AI đang execute — đợi đến control point
+- **`/vp-auto` không arg** ≠ bắt buộc dừng từng task trong spec; **`--fast`** giúp ít dừng ở verify tùy chọn
+- **Sau mỗi task xong** — nếu AI kết thúc turn, chạy tiếp `/vp-auto` hoặc yêu cầu rõ task kế theo `PHASE-STATE.md`
+- **Dùng `--dry-run`** trước khi chạy phase mới để preview
+- **Mở terminal riêng** để chạy `vp-tools progress` theo dõi
+- **Commit thường xuyên** — mỗi task là một atomic commit

package/docs/user/features/checkpoint-recovery.md

@@ -0,0 +1,76 @@
+# Feature: Checkpoint Recovery (`/vp-rollback`)
+
+ViePilot tạo git checkpoint tags tại mỗi task — cho phép rollback an toàn đến bất kỳ điểm nào.
+
+## Overview
+
+```
+vp-p1-t1 ──► vp-p1-t1-done ──► vp-p1-t2 ──► vp-p1-t2-done ──► vp-p1-complete
+                                                    ↑
+                                              Rollback đến đây
+```
+
+## How to Rollback
+
+```
+/vp-rollback
+```
+
+ViePilot hiển thị danh sách checkpoints:
+
+```
+Select checkpoint to restore:
+
+1. vp-p2-t3-done  (Phase 2 Task 3 complete)   2026-03-30 14:30
+2. vp-p2-t2-done  (Phase 2 Task 2 complete)   2026-03-30 13:45
+3. vp-p2-t1-done  (Phase 2 Task 1 complete)   2026-03-30 12:00
+4. vp-p2-complete (Phase 2 complete)           2026-03-30 11:00
+5. vp-p1-complete (Phase 1 complete)           2026-03-29 18:00
+```
+
+Chọn số → ViePilot rollback về checkpoint đó.
+
+## Safety
+
+Rollback dùng `git revert` — **không phải** `git reset`:
+- Lịch sử git được giữ nguyên
+- Có thể undo rollback nếu cần
+- Không mất commits
+
+## Listing Checkpoints
+
+```bash
+vp-tools checkpoints
+```
+
+Output:
+```
+ViePilot Checkpoints
+
+  TAG                         COMMIT    DATE
+  ─────────────────────────────────────────────────────
+  ✅ vp-p2-complete           a1b2c3d   2026-03-30 14:00
+  ✔️  vp-p2-t3-done            b2c3d4e   2026-03-30 13:45
+  📌 vp-p2-t3                  c3d4e5f   2026-03-30 12:00
+
+  Total: 8 checkpoints
+```
+
+**Icons**:
+- ✅ Phase complete
+- ✔️ Task done
+- 📌 Task start
+
+## Manual Rollback (Advanced)
+
+```bash
+# Rollback đến specific tag
+git revert --no-commit $(git rev-list vp-p2-t3..HEAD)
+git commit -m "revert: rollback to vp-p2-t3"
+```
+
+## When to Use
+
+- Task tạo ra code không đúng → rollback về task start
+- Phase có vấn đề → rollback về phase start
+- Muốn thử approach khác → rollback và retry

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

@@ -0,0 +1,77 @@
+# Feature: Debug Mode (`/vp-debug`)
+
+`/vp-debug` giúp bạn track và resolve issues một cách có hệ thống, với state được lưu lại qua các sessions.
+
+## Overview
+
+Thay vì debug theo kiểu "thử cái này, thử cái kia", `/vp-debug` tổ chức:
+- **Problem statement** rõ ràng
+- **Hypotheses** được track
+- **Attempts** với kết quả
+- **Resolution** khi tìm ra
+
+## Starting a Debug Session
+
+```
+/vp-debug investigate: API returns 500 after adding auth middleware
+```
+
+ViePilot tạo `DEBUG-001.md`:
+
+```markdown
+# Debug Session: API returns 500 after adding auth middleware
+
+## Problem
+API returns 500 after adding auth middleware
+
+## Hypotheses
+- [ ] Middleware order incorrect
+- [ ] JWT secret not loaded from env
+- [ ] Token format mismatch
+
+## Attempts
+### Attempt 1: Check middleware order
+...
+
+## Resolution
+_Pending_
+```
+
+## Continuing Across Sessions
+
+Debug state được lưu — có thể tiếp tục sau khi close Cursor:
+
+```
+/vp-debug continue
+```
+
+ViePilot load lại debug session và tiếp tục từ hypothesis chưa test.
+
+## Closing a Session
+
+```
+/vp-debug close: Fixed by moving auth middleware before route handlers
+```
+
+ViePilot:
+- Mark session resolved
+- Log fix vào CHANGELOG.md
+- Archive debug file
+
+## Multiple Sessions
+
+```
+/vp-debug list
+```
+
+```
+Active debug sessions:
+1. DEBUG-001 — API 500 error (in progress)
+2. DEBUG-002 — Test flakiness (open)
+```
+
+## Tips
+
+- Mô tả problem cụ thể: "X happens when Y" thay vì "something is broken"
+- Một session per issue — không mix nhiều bugs
+- Dùng `/vp-debug continue` sau context reset để không mất progress

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

@@ -0,0 +1,29 @@
+# UI Direction Mode
+
+`/vp-brainstorm --ui` bật flow thiết kế trực quan ngay trong phiên brainstorm.
+
+## 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`
+
+## Artifacts
+Mỗi session UI tạo/cập nhật:
+
+```text
+.viepilot/ui-direction/{session-id}/
+  index.html
+  style.css
+  notes.md
+```
+
+`notes.md` là nguồn sự thật cho:
+- rationale
+- assumptions
+- references (bao gồm 21st.dev links/prompts)
+
+## 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