viepilot 1.8.1 → 1.9.2

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.4.0
+version: 0.5.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Tạo **artifact** trong `.viepilot/` (và template copy) từ brainstorm — **không** thay **`/vp-auto`** để implement mã ứng dụng / framework shipping. Backlog feature code: **`/vp-evolve`** + **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.
@@ -47,6 +53,9 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 - `LICENSE`
 - Updated `README.md`
 
+**ViePilot profile (FEAT-009):**
+- Đọc `.viepilot/META.md` → file `~/.viepilot/profiles/<slug>.md` (contract: `docs/dev/global-profiles.md`); pre-fill Step 0; merge vào **ARCHITECTURE** (`## ViePilot organization context`), **PROJECT-CONTEXT** (`## ViePilot active profile`), **AI-GUIDE** quick context.
+
 **Stack intelligence (global cache):**
 - `~/.viepilot/stacks/{stack}/SUMMARY.md`
 - `~/.viepilot/stacks/{stack}/BEST-PRACTICES.md`
@@ -68,7 +77,8 @@ Execute workflow from `@$HOME/.cursor/viepilot/workflows/crystallize.md`
 Key steps:
 
 ### Step 0: Collect Project Metadata
-Ask user for:
+- **FEAT-009:** Load `.viepilot/META.md` + global profile file first (`workflows/crystallize.md`); set `profile_resolved` or `none`; pre-fill org/website khi có profile.
+Ask user for (confirm proposals từ profile nếu có):
 - Project name, description
 - Organization name, website
 - Package Base ID (e.g., com.company.project)
@@ -110,6 +120,7 @@ Ask user for:
 - Quick lookup table
 - Context loading strategy
 - File relationships
+- **FEAT-009:** Quick context cho `profile_id` + path profile khi đã resolve
 
 ### Step 3: Generate PROJECT-META.md
 - Project info
@@ -117,9 +128,11 @@ Ask user for:
 - Package structure
 - Developer info
 - File headers template
+- **FEAT-009:** Align Organization với profile đã confirm (public only)
 
 ### Step 4: Generate ARCHITECTURE.md
 - System overview
+- **FEAT-009:** Section `## ViePilot organization context` khi có profile (hoặc dòng none)
 - Services definitions
 - Data flow
 - Technology decisions
@@ -132,6 +145,7 @@ Ask user for:
   - `N/A` => keep section heading + one-line rationale
 
 ### Step 5: Generate PROJECT-CONTEXT.md
+- **FEAT-009:** Block `## ViePilot active profile (FEAT-009)` khi có binding
 - Domain knowledge
 - Business rules
 - Conventions
@@ -192,4 +206,5 @@ Ask user for:
 - [ ] Project files created
 - [ ] Git committed
 - [ ] ARCHITECTURE diagram matrix is present and consistent (`required|optional|N/A`)
+- [ ] **FEAT-009:** Nếu có profile bound — ARCHITECTURE + PROJECT-CONTEXT ghi nguồn profile; nếu không — ghi rõ none / not configured
 </success_criteria>

package/skills/vp-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-debug
 description: "Systematic debugging with persistent state tracking across sessions"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Điều tra + log** session; **không** merge fix shipping mặc định cho đến khi user **explicit** (*sửa luôn*, *hotfix*) hoặc route **`/vp-request` → `/vp-evolve` → `/vp-auto`**. Patch nhỏ chỉ để **reproduce** OK nếu user đồng ý. Xem `workflows/debug.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Systematic debugging với persistent state tracking. Giúp track vấn đề qua nhiều sessions.

package/skills/vp-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-docs
 description: "Generate comprehensive documentation cho dự án"
-version: 0.1.0
+version: 0.2.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này sửa **`docs/`**, index, README liên quan doc — **không** implement **`lib/`**, **`tests/`**, logic product mặc định; việc đó là **`/vp-auto`**. Override explicit. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Generate comprehensive documentation từ code và artifacts.
@@ -54,6 +60,7 @@ CHANGELOG.md (updated)
 - GitHub owner/repo from `git remote get-url origin`
 - Skills count from `ls skills/*/SKILL.md | wc -l`
 - Workflows count from `ls workflows/*.md | wc -l`
+- **FEAT-009:** Optional ViePilot global profile từ `.viepilot/META.md` + `~/.viepilot/profiles/` cho attribution/tone (`workflows/documentation.md` §0A)
 </objective>
 
 <execution_context>
@@ -89,6 +96,10 @@ ACTUAL_WORKFLOWS=$(ls workflows/*.md 2>/dev/null | wc -l | tr -d ' ')
 > Use `$ACTUAL_SKILLS` and `$ACTUAL_WORKFLOWS` for counts.
 > **Never write** `your-org`, `YOUR_USERNAME`, `YOUR_ORG` into generated files.
 
+### Step 0A: ViePilot active profile (FEAT-009)
+
+Sau Step 0: resolve `.viepilot/META.md` → file profile global (cùng quy tắc `workflows/crystallize.md`). Giữ working notes (org, website, audience, branding) cho prose docs; **không** fail nếu thiếu. Chi tiết: `workflows/documentation.md` §0A.
+
 ### Step 1: Ask Documentation Scope
 ```
 Which documentation would you like to generate?
@@ -262,4 +273,5 @@ View at: docs/README.md
 - [ ] skills-reference.md has sections for all skills in skills/ directory
 - [ ] Root README.md Documentation table updated
 - [ ] Git committed
+- [ ] **FEAT-009:** Nếu có profile — dùng cho attribution khi phù hợp; nếu không — bỏ qua im lặng (không placeholder sai)
 </success_criteria>

package/skills/vp-evolve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-evolve
 description: "Nâng cấp, thêm features, hoặc bắt đầu milestone mới"
-version: 0.2.0
+version: 0.3.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,14 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này chỉ **planning**: ROADMAP, phase dir, SPEC/tasks, TRACKER, ghi chú version/CHANGELOG khi workflow quy định — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, sửa lớn `workflows/`/`skills/` ngoài plan artifact).
+- **Bước tiếp:** **`/vp-auto`**. Xem `workflows/evolve.md`.
+- **Ngoại lệ:** User **explicit** bypass — nêu rõ trong chat.
+</implementation_routing_guard>
+
 
 <objective>
 Nâng cấp hoặc mở rộng dự án sau khi hoàn thành milestone hoặc cần thêm features.

package/skills/vp-info/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-info
 description: "Hiển thị phiên bản ViePilot, npm latest, danh sách skills/workflows qua vp-tools"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Inventory / version info** — không implement shipping; implement qua **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chạy **`vp-tools info`** để lấy metadata bundle ViePilot (không cần `.viepilot/` trong project đích).

package/skills/vp-pause/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-pause
 description: "Pause work với context preservation để resume sau"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Handoff state** — không implement shipping; resume với **`/vp-resume`** rồi **`/vp-auto`** theo plan. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Save complete work state để có thể resume từ bất kỳ context nào.

package/skills/vp-request/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-request
 description: "Tạo request mới: feature, bug fix, enhancement, hoặc brainstorm tiếp"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,15 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này chỉ **tạo request**, **backlog**, **triage** (`.viepilot/requests/*`, `TRACKER`, đôi khi gợi ý ROADMAP) — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, `workflows/`, `skills/` của repo, v.v.).
+- **Sau request:** **`/vp-evolve`** (ROADMAP + phase + tasks + plan) → **`/vp-auto`** (thực thi). Xem `workflows/request.md`.
+- **Ngoại lệ:** User **explicit** (*hotfix ngay*, *sửa trong chat này*, *bypass planning*) — phải **nêu rõ** bypass trong chat.
+- **Không** đề xuất *“Start working now”* như implement trực tiếp trong thread này; thay bằng evolve → auto.
+</implementation_routing_guard>
+
 
 <objective>
 Tạo và quản lý requests cho dự án đang phát triển:
@@ -199,7 +208,7 @@ Options:
 1. Add to current milestone backlog
 2. Brainstorm in detail first
 3. Schedule for next milestone
-4. Start working now
+4. Plan then execute: `/vp-evolve` → `/vp-auto` (not direct implement here unless explicit override)
 ```
 
 **Tech Debt:**
@@ -242,7 +251,8 @@ Update `.viepilot/TRACKER.md`:
 
  Next:
  - /vp-request --list    View all requests
- - /vp-auto              Start working on it
+ - /vp-evolve            Plan phase/tasks + ROADMAP (before code)
+ - /vp-auto              Implement per task plan (after evolve)
  - /vp-request           Create another request
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```

package/skills/vp-resume/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-resume
 description: "Resume work từ previous session với full context restoration"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Khôi phục context** — không implement shipping mặc định; tiếp tục **`/vp-auto`** khi có task plan. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Restore complete project context và resume work seamlessly.

package/skills/vp-rollback/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-rollback
 description: "Rollback to any checkpoint safely with state preservation"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Checkpoint / revert** — không thay **`/vp-auto`** cho work mới; sau rollback dùng **`/vp-evolve`** / **`/vp-auto`** theo quy trình. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Rollback đến bất kỳ checkpoint nào một cách an toàn, với backup và state preservation.

package/skills/vp-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-status
 description: "Hiển thị progress dashboard và actionable insights"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Read-only / dashboard** — không implement shipping; **`/vp-evolve`** → **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Hiển thị visual progress dashboard với actionable insights.

package/skills/vp-task/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-task
 description: "Manual control over individual tasks"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này **chỉ** quản lý **state/tag/task** trong `.viepilot/` — **không** thay **`/vp-auto`** để implement shipping code. Implement: **`/vp-auto`** hoặc user **explicit** override. Chuỗi plan: **`/vp-evolve`** trước. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Manual control over tasks khi cần fine-grained management.

package/skills/vp-ui-components/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-ui-components
 description: "Quản lý workflow sưu tầm và tái sử dụng UI components"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Curation** `ui-components/` + metadata — không implement toàn bộ feature app / framework shipping mặc định; thay đổi lớn **`/vp-evolve`** → **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Thu thập, phân loại, và lưu trữ UI components để tái sử dụng:

package/skills/vp-update/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-update
 description: "Nâng cấp package viepilot qua npm (dry-run, --yes, --global) qua vp-tools"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Nâng cấp ViePilot package** (npm) — không implement feature product trong repo đang làm việc mặc định; feature code qua **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chạy **`vp-tools update`** để lên kế hoạch và (khi được xác nhận) thực thi `npm` nâng cấp `viepilot`.

package/templates/project/VIEPILOT-META.md

@@ -0,0 +1,30 @@
+---
+# ViePilot: links this repo to a global reusable profile (~/.viepilot/profiles/).
+# Created/updated by brainstorm meta intake or manual edit.
+viepilot_profile_id: "{{PROFILE_SLUG}}"
+# Optional absolute override (rare):
+# viepilot_profile_path: "/custom/path/profile.md"
+---
+
+# ViePilot project binding
+
+Operational metadata for ViePilot workflows (**not** full product metadata — see `PROJECT-META.md` if used).
+
+## Active profile
+
+| Field | Value |
+|-------|-------|
+| **profile_id** | `{{PROFILE_SLUG}}` |
+| **Global file** | `~/.viepilot/profiles/{{PROFILE_SLUG}}.md` |
+
+## Project-specific overrides
+
+_Add only non-secret lines that apply to this repo only (e.g. codename, release target). Full org context should live in the global profile file._
+
+- 
+
+## Intake notes
+
+_Short trail from meta intake (optional):_
+
+- 

package/workflows/autonomous.md

@@ -9,6 +9,10 @@ Pauses at control points cho user decisions.
 - External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
 - If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
 
+## Implementation entry (cross-skill)
+
+- **`/vp-auto`** + workflow này là **lane mặc định** để **implement** work đã có **phase/task plan** (và doc-first **BUG-001**). **`/vp-request`** và **`/vp-evolve`** **không** thay thế bước này trừ user explicit override — xem **Implementation routing guard** trong `workflows/request.md` và `workflows/evolve.md`.
+
 
 <process>
 

package/workflows/brainstorm.md

@@ -163,6 +163,61 @@ Khi thư mục `pages/` tồn tại hoặc bất kỳ `pages/*.html` nào đư
    - điều chỉnh theo mục tiêu sản phẩm
 4. Giữ prototype ở mức mô tả định hướng (directional), không ép build production-ready code ở bước brainstorm.
 
+### UI Direction — UX walkthrough & upgrade (FEAT-010)
+
+Khi đang trong **`/vp-brainstorm --ui`** hoặc đã có `.viepilot/ui-direction/{session-id}/` cho phiên hiện tại, user có thể gọi:
+
+- **`/research-ui`** — chạy đủ pipeline dưới đây
+- **`/research ui`** — **alias** của `/research-ui` (khoảng trắng sau `research`; không trùng `/research {chủ đề tự do}`)
+
+User có thể kèm ngữ cảnh một dòng (vd. tên sản phẩm **Trips**, persona, flow ưu tiên) — nhập vào cùng tin nhắn lệnh.
+
+Áp dụng **các phase tuần tự** (assistant không bỏ qua phase trừ khi user explicit “chỉ phase 1”):
+
+#### Phase 1 — Mô phỏng người dùng cuối
+
+1. Đóng vai **người dùng cuối** đang dùng prototype (lấy tên app / màn chính từ `notes.md`, HTML, hoặc prompt user).
+2. Liệt kê **3–8 scenario** cụ thể (vd. lần đầu mở app, hoàn tất task chính, lỗi edge case) — ưu tiên đúng page nếu multi-page (`pages/*.html`).
+3. Với từng scenario: mô tả **hành vi** (đọc/click tưởng tượng trên UI hiện tại) → ghi **pain**: mơ hồ, thiếu phản hồi, quá nhiều bước, không khớp mental model, khả năng mobile/a11y, v.v.
+4. Tổng hợp **Voice of pseudo-user** (bullet + mức độ **low / medium / high**).
+5. **Stress nội dung & tràn layout (content stress pass)** — *bắt buộc trong mỗi lần `/research-ui`*: sau happy/edge hành vi, mô phỏng **dữ liệu ở biên** trên từng màn/page quan trọng (hoặc toàn hub nếu single-screen). Tối thiểu xét **3–6 loại** sau (chọn đúng ngữ cảnh sản phẩm; bỏ qua mục không áp dụng nhưng **ghi rõ “N/A + lý do”**):
+   - **Copy dài**: tiêu đề, subtitle, CTA, placeholder ô nhập, tooltip, breadcrumb, tên địa điểm/người dài (Unicode), email/URL dài.
+   - **Khối lượng**: danh sách/grid **nhiều phần tử**, bảng nhiều cột/hàng, thẻ/tag/badge chồng, notification stack, lịch nhiều sự kiện.
+   - **Số & định dạng**: số tiền rất lớn/nhỏ, đơn vị dài, múi giờ/ngôn ngữ (nếu product có).
+   - **Trạng thái lỗi / validation**: message lỗi dài, nhiều lỗi cùng lúc, inline + banner.
+   - **Empty vs cực đầy**: không dữ liệu vs max items; skeleton vs flash of long content.
+   - **Viewport**: cùng stress trên **hẹp** (mobile) và **rộng** (desktop) nếu prototype nhắm đa kích thước.
+
+   **Stress recipes theo archetype (ENH-020)** — sau khi áp checklist trên, **chốt 1–2 archetype** khớp sản phẩm (từ `notes.md` / HTML / user) và áp **ít nhất hai recipe** trong mỗi hàng đã chọn (có thể diễn đạt lại bằng ngôn ngữ session; **ghi rõ archetype** trong Stress findings):
+
+   | Archetype | Ưu tiên stress (recipe gợi ý) | Ghi chú |
+   |-----------|------------------------------|---------|
+   | **Landing / marketing** | Hero **headline** cực ngắn vs cực dài; **pricing** 3–5 tier + feature list dài mỗi tier; **FAQ** 10–20 mục (accordion/stack); **logo / social proof** hàng 8–15 logo + tên dài | Sticky CTA vs nội dung dài; section order khi overflow |
+   | **App shell / SaaS admin** | **Bảng** nhiều cột + nhiều hàng; **filter bar** chip + dropdown tràn; **sidebar** nhiều cấp; **notification** stack / toast chồng | Trạng thái dense vs comfortable; frozen column |
+   | **Form-heavy / wizard** | **Label + hint** dài; **multi-step** 5–7 bước + breadcrumb dài; **lỗi** inline từng field + banner tổng; khối **optional fields** mở rộng | Tab order, submit disabled ambiguity |
+   | **Content / reader** | **Bài** cực dài; **code block** rộng; **TOC** 20–40 heading; **related** 8–15 thẻ | Max line length, sidenote, mobile đọc |
+   | **Commerce / booking / marketplace** | **Kết quả tìm** grid dày; **giá** + đơn vị + discount dài; **ngày giờ** + múi giờ + DST; **đặt chỗ** (ghế, phòng) + availability text dài | Giỏ / summary trên mobile |
+
+   Hybrid (vd. marketing + app): **gộp recipe** từ các hàng liên quan; tránh lặp cùng một stress vô nghĩa trên hai màn giống nhau.
+
+   Với prototype chỉ có nội dung mẫu ngắn: **không bắt buộc** sửa file ngay ở Phase 1 — hãy **mô tả giả định** (“nếu title 120 ký tự thì…”) và UI sẽ **tràn, ellipsis, scroll, overlap, wrap xấu** thế nào.
+6. Tổng hợp thêm **Stress findings** (bullet: loại stress → quan sát → severity **low/medium/high**) và merge vào tổng kết Phase 1 cho Phase 2.
+
+#### Phase 2 — UX designer + research
+
+1. Đổi vai: **UX/UI designer** nhận feedback từ Phase 1 (**gồm cả Stress findings**).
+2. Map pain → **nguyên nhân thiết kế** (heuristic ngắn, pattern thiếu/sai); **ưu tiên hóa** P0 / P1 / P2 — **ưu tiên P0** nếu stress nội dung gây **mất thông tin, click sai, hoặc không dùng được** (overflow che CTA, text cắt nghĩa, bảng tràn không đọc được).
+3. **Web research**: khi cần benchmark hoặc pattern chuẩn ngành, chạy **1–3 truy vấn** (search) → tóm tắt nguồn, takeaway, trade-off.
+4. **Đề xuất cải tiến** cụ thể (thành phần UI, copy, layout, luồng) gắn với file/page (`slug` nếu multi-page).
+
+#### Phase 3 — Cập nhật artifact
+
+1. Sửa **`index.html`**, **`pages/*.html`**, **`style.css`** theo P0 → P1 trong phạm vi phiên (prototype direction, không ép production).
+2. Trong **`notes.md`**, thêm hoặc append section **`## UX walkthrough log`** (một entry mỗi lần chạy lệnh): ngày/scenario đã mô phỏng, pain chính, **Stress findings** (tóm tắt), link research (nếu có), **diff ý định** (bullet), file đã đổi. *Tùy chọn:* chỉnh HTML với **placeholder/copy dài** hoặc thêm **demo row** để minh họa stress đã bàn (ghi trong log).
+3. **Multi-page**: sau chỉnh sửa page, giữ **`## Pages inventory`** và **hub** khớp 100% file trong `pages/*` (hook FEAT-007).
+
+**Quan hệ với `/research {topic}`**: lệnh **tự do** chỉ cần research ngắn và quay lại topic; **`/research-ui`** bắt buộc **3 phase** + **ghi log** + **chỉnh HTML/CSS khi có đề xuất hợp lý**.
+
 Tham chiếu user: `docs/user/features/ui-direction.md`.
 
 ### Kết thúc mỗi topic
@@ -172,8 +227,76 @@ Tham chiếu user: `docs/user/features/ui-direction.md`.
 - Nếu topic thêm/sửa capability: cập nhật **`## Product horizon`** trong bản nháp session (hoặc nhắc user lưu `/save`) với tag tier phù hợp
 </step>
 
+<step name="project_meta_intake">
+## 5. Project meta intake (FEAT-009)
+
+Normative contract: **`docs/dev/global-profiles.md`** (`~/.viepilot/profiles/`, `~/.viepilot/profile-map.md`, `.viepilot/META.md`).
+
+### 5.1 When this step runs
+
+Chạy **trước** khi ghi session ở trạng thái **`Completed`** hoặc khi user gõ **`/end`**, **nếu**:
+
+1. **Scope locked**: `## Product horizon` trong bản nháp session đã có nội dung thật (không chỉ placeholder) **hoặc** user vừa xác nhận bằng lời đã chốt scope MVP / horizon.
+2. **Binding thiếu**: không tồn tại `.viepilot/META.md` **hoặc** frontmatter thiếu `viepilot_profile_id` hợp lệ (slug `kebab-case` theo contract).
+
+**Bỏ qua mặc định** (skip intake) khi `.viepilot/META.md` đã có `viepilot_profile_id` hợp lệ — chỉ hỏi nhanh: *“Giữ profile `{id}`? Đổi profile?”*; nếu giữ → sang bước Save.
+
+### 5.2 Chuẩn bị registry
+
+1. `mkdir -p "$HOME/.viepilot/profiles"` nếu cần.
+2. Đọc `~/.viepilot/profile-map.md` nếu có để liệt kê profile hiện có (profile_id, display_name, org_tag).
+
+### 5.3 Disambiguation (nhiều profile / nhiều org)
+
+- Nếu brainstorm cho thấy **nhiều org/client** hoặc **≥2 dòng trong profile-map** khớp gợi ý (cùng `org_tag` hoặc tag): **bắt buộc** user chọn **một** `profile_id` **hoặc** chọn **Tạo profile mới** (slug mới, chưa tồn tại).
+
+### 5.4 Q&A tuần tự (một câu mỗi lượt)
+
+Với mỗi câu hỏi:
+
+1. Đưa **Proposal** ngắn (1–2 câu) suy ra từ session + Product horizon.
+2. User trả lời **Accept proposal** / **Edit** (ghi nhận bản user).
+3. Sang câu tiếp.
+
+**Tối thiểu** phải làm rõ trước khi ghi file (khớp body sections trong global contract):
+
+| Thứ tự | Câu hỏi (gợi ý) | Map tới |
+|--------|------------------|---------|
+| 1 | Tên hiển thị org/client hoặc “cá nhân”? | `display_name` |
+| 2 | `org_tag` ngắn (vd. `acme`, `personal`)? | `org_tag` |
+| 3 | Branding / giọng văn (audience, tone)? | body `## Branding & voice` |
+| 4 | Legal / attribution công khai (nếu có)? | body `## Legal & attribution` |
+| 5 | Website công khai (optional)? | frontmatter `website` |
+
+Sau đó: chốt **`profile_id`** = slug filename (`kebab-case`).
+
+### 5.5 Ghi artifact (machine + project)
+
+1. **`~/.viepilot/profiles/<slug>.md`**: YAML frontmatter đủ key bắt buộc (`profile_id`, `display_name`, `org_tag`, `tags`, `last_updated`) + body sections đã thu thập. **Không** ghi secrets.
+2. **`~/.viepilot/profile-map.md`**: thêm hoặc cập nhật dòng bảng (cột theo contract); cập nhật `last_used` = ngày hiện tại.
+3. **`.viepilot/META.md`**: tạo/cập nhật từ `templates/project/VIEPILOT-META.md` với `viepilot_profile_id: <slug>`.
+
+### 5.6 Ghi nhận trong session file
+
+Trong bản nháp / file session, thêm section:
+
+```markdown
+## Project meta intake (FEAT-009)
+- **status**: completed | skipped
+- **profile_id**: {slug}
+- **profile_path**: ~/.viepilot/profiles/{slug}.md
+- **binding**: .viepilot/META.md
+```
+
+Nếu skipped (hiếm): phải có **`## Meta intake waiver`** trong cùng file session kèm **lý do** do user cung cấp.
+
+### 5.7 Tiếp tục
+
+Sau khi intake **completed** hoặc **hợp lệ skip** (META đã có profile) → chuyển sang **bước 6 — Save Session**.
+</step>
+
 <step name="save_session">
-## 5. Save Session
+## 6. Save Session
 
 Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
@@ -209,6 +332,17 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 **Scope note (optional):** Nếu không có post-MVP: `Single-release product — no separate horizon epics.`
 
+## Project meta intake (FEAT-009)
+
+- **status**: not_started | completed | skipped
+- **profile_id**:
+- **profile_path**:
+- **binding** (.viepilot/META.md):
+
+_(Điền sau bước 5 — Project meta intake; xem `docs/dev/global-profiles.md`.)_
+
+<!-- Nếu skipped: ## Meta intake waiver + lý do -->
+
 ## Architecture diagram applicability inputs
 
 > Input contract for `/vp-crystallize` Step 4. Keep concise and explicit.
@@ -261,6 +395,9 @@ Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 - Preview focus:
   - {layout/flow summary; list each page slug if multi-page}
 
+**UX walkthrough log** (optional; FEAT-010 + ENH-019 + ENH-020 — khi đã chạy `/research-ui`):
+- {YYYY-MM-DD}: scenarios exercised → top pains → **Stress findings** (tóm tắt) → research links → HTML/CSS edits summary
+
 ---
 
 ## Summary
@@ -289,7 +426,7 @@ git push
 </step>
 
 <step name="suggest_next">
-## 6. Suggest Next Action
+## 7. Suggest Next Action
 
 ```
 ✓ Brainstorm session saved
@@ -315,9 +452,11 @@ User có thể dùng các lệnh trong phiên brainstorm:
 - `/topic {name}` - Chuyển sang topic mới
 - `/summary` - Xem tóm tắt phiên hiện tại
 - `/save` - Lưu tiến độ ngay
-- `/end` - Kết thúc và lưu phiên
+- `/end` - Kết thúc và lưu phiên (sau **bước 5 — Project meta intake** khi binding thiếu; xem workflow)
 - `/questions` - Xem danh sách open questions
 - `/research {topic}` - Research nhanh ngay trong phiên và quay lại topic hiện tại
+- `/research-ui` — UX walkthrough: mô phỏng user → designer + research → cập nhật UI direction + log (`notes.md`) — chỉ khi có UI session (FEAT-010)
+- `/research ui` — alias của `/research-ui`
 </commands>
 
 <success_criteria>
@@ -329,5 +468,8 @@ User có thể dùng các lệnh trong phiên brainstorm:
 - [ ] Landing page topics trigger layout follow-up questions
 - [ ] 21st.dev references được dùng khi thảo luận landing page
 - [ ] Research có thể chạy ngay trong brainstorm session khi user yêu cầu
+- [ ] **FEAT-010 + ENH-019 + ENH-020**: Trong UI Direction, `/research-ui` (hoặc `/research ui`) chạy đủ 3 phase, gồm **content stress pass** + **archetype stress recipes** + **`## UX walkthrough log`** (Stress findings) khi chỉnh prototype
 - [ ] Git committed
+- [ ] **FEAT-009**: Nếu binding thiếu và scope đã locked — đã chạy **Project meta intake** (bước 5) hoặc có **`## Meta intake waiver`** có lý do trước Completed
+- [ ] **`## Project meta intake (FEAT-009)`** trong session: `status` + `profile_id` khi completed (hoặc waiver nếu skipped)
 </success_criteria>