viepilot 1.8.1 → 1.9.1

package/CHANGELOG.md

@@ -9,11 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Planned
 
- - None.
+- None.
 
 ### Added
 
- - None yet.
+- None yet.
+
+## [1.9.1] - 2026-04-02
+
+### Added
+
+- **M1.28 / Phase 32 (FEAT-010)** — UI Direction **UX walkthrough**: slash **`/research-ui`** and **`/research ui`** in `workflows/brainstorm.md` (3 phases: end-user simulation → designer + web research → update `notes.md` **`## UX walkthrough log`** and HTML/CSS); `skills/vp-brainstorm` **0.6.0**; `docs/user/features/ui-direction.md`, `docs/skills-reference.md`; `tests/unit/vp-fe010-ui-walkthrough-contracts.test.js`.
+
+## [1.9.0] - 2026-04-01
+
+### Added
+
+- **M1.27 / Phase 31 (FEAT-009) completed** — reusable global org context: `~/.viepilot/profiles/<slug>.md` + `~/.viepilot/profile-map.md`; project binding `.viepilot/META.md`; brainstorm **Project meta intake** after scope lock; Node installer seeds dirs/map; **crystallize** + **vp-docs** consume active profile for pre-fill and attribution.
+- `docs/dev/global-profiles.md` — normative contract (paths, schema, resolution).
+- `templates/project/VIEPILOT-META.md` — template for `.viepilot/META.md`.
+- `workflows/brainstorm.md` + `skills/vp-brainstorm/SKILL.md` (0.5.0) — meta intake step 5 + session sections.
+- `lib/viepilot-install.cjs` — `mkdir` `~/.viepilot/profiles` + `write_file_if_missing` for `profile-map.md`; plan paths `viepilotProfilesDir` / `viepilotProfileMapPath`.
+- `workflows/crystallize.md` + `skills/vp-crystallize/SKILL.md` (0.5.0) — Step 0 profile load; ARCHITECTURE / PROJECT-CONTEXT / AI-GUIDE merge rules.
+- `workflows/documentation.md` + `skills/vp-docs/SKILL.md` (0.2.0) — §0A profile resolution for generated docs.
+- `docs/user/quick-start.md`, `docs/user/features/brainstorm.md`, `docs/skills-reference.md` — user-facing FEAT-009 notes.
+- `tests/unit/vp-fe009-global-profiles-contracts.test.js` — regression tests for workflow/skill/installer/template contracts.
 
 ## [1.8.1] - 2026-04-01
 
@@ -290,7 +310,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.1...HEAD
+[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.9.1...HEAD
+[1.9.1]: https://github.com/0-CODE/viepilot/compare/v1.9.0...v1.9.1
+[1.9.0]: https://github.com/0-CODE/viepilot/compare/v1.8.1...v1.9.0
 [1.8.1]: https://github.com/0-CODE/viepilot/compare/v1.8.0...v1.8.1
 [1.8.0]: https://github.com/0-CODE/viepilot/compare/v1.7.0...v1.8.0
 [0.10.0]: https://github.com/0-CODE/viepilot/compare/v0.9.0...v0.10.0

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.6.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.9.1-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-16-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-267%20passing-brightgreen.svg)](tests/)
+[![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
+[![Tests](https://img.shields.io/badge/tests-294%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.6.1** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.6.1**) is the Node package identifier for this repo and may differ; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.9.1** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.1**) 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 | **~25,050+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~27,113+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
-| Templates | **16** (Project: 11, Phase: 5) |
+| Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **267** (9 suites: unit + integration + AI compat + README metrics + UI direction verify + ENH workflow contracts + viepilot-info + viepilot-update) |
-| ViePilot phases (repo) | **15** hoàn thành (xem `.viepilot/TRACKER.md`) |
+| Tests | **294** (13 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + viepilot-info/update/install) |
+| ViePilot phases (local `.viepilot`) | **32** phase cycles — **M1.28** (**v1.9.1** FEAT-010); **M1.27** (**v1.9.0** FEAT-009); 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).
@@ -45,27 +45,27 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 |------------------------|------------------|---------------------|
 | Skill Definitions | **16** | SKILL.md files với trigger, process, success criteria |
 | Workflow Files | **12** | Step-by-step execution guides |
-| Project Templates | 11 | AI-GUIDE, ARCHITECTURE, README, SYSTEM-RULES, etc. |
+| 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 | 6 | Jest unit + integration + AI compatibility + README metrics + ENH backlog + viepilot-info/update |
+| Test Files | 13 | Jest: 12 unit + 1 integration (contracts, installer, info/update, FEAT-009, FEAT-010, scope policy, …) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.6.1** (ENH-015 symlink skills opt-in); M1.23 FEAT-008 (v1.6.0); M1.22 (v1.5.1)
+Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.1** (M1.28 FEAT-010 — `/research-ui`); prior **v1.9.0** FEAT-009; **v1.8.1** BUG-004
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
 | Core Skills (16) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components |
 | Workflows (12) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
-| Project Templates (11) | ✅ Hoàn thiện | Placeholders cho customization |
+| 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 (267) | ✅ Hoàn thiện | Unit, integration, AI provider compatibility, workflow contracts, viepilot-info, viepilot-update |
+| Tests (294) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010, 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 |
@@ -150,11 +150,12 @@ Tổng thể / Overall:  ██████████████████
 
 ## Templates
 
-### Project Templates (11)
+### Project Templates (12)
 
 | Template | Mô tả / Description |
 |----------|---------------------|
 | `AI-GUIDE.md` | Navigation cho AI - quick lookup, context loading strategy |
+| `VIEPILOT-META.md` | Binding profile active: `viepilot_profile_id` / path (FEAT-009) |
 | `PROJECT-META.md` | Metadata: org, package, developer, headers |
 | `ARCHITECTURE.md` | System design, services, data flow, tech decisions |
 | `PROJECT-CONTEXT.md` | Domain knowledge, business rules, constraints |
@@ -365,8 +366,8 @@ viepilot/
 │   ├── rollback.md                # Rollback workflow
 │   └── audit.md                   # Audit workflow
 │
-├── templates/                     # 16 Templates
-│   ├── project/                   # 11 Project-level templates
+├── templates/                     # 17 Templates
+│   ├── project/                   # 12 Project-level templates
 │   │   ├── AI-GUIDE.md
 │   │   ├── PROJECT-META.md
 │   │   ├── ARCHITECTURE.md

package/docs/README.md

@@ -29,7 +29,7 @@
 | Feature | Document |
 |---------|----------|
 | Autonomous Mode | [autonomous-mode.md](user/features/autonomous-mode.md) (flags, `--fast`, lượt chat) |
-| Brainstorm & product horizon | [brainstorm.md](user/features/brainstorm.md) (MVP / Post-MVP tags, crystallize handoff) |
+| Brainstorm & product horizon | [brainstorm.md](user/features/brainstorm.md) (MVP / Post-MVP, **meta intake** + global profiles) |
 | Product horizon end-to-end | [product-horizon.md](user/features/product-horizon.md) (brainstorm → ROADMAP / PROJECT-CONTEXT, AI load order) |
 | UI Direction Mode | [ui-direction.md](user/features/ui-direction.md) |
 | Checkpoint Recovery | [checkpoint-recovery.md](user/features/checkpoint-recovery.md) |
@@ -57,6 +57,7 @@
 | [Getting Started (dev entry)](dev/getting-started.md) | Short link into dev guide |
 | [CLI Reference](dev/cli-reference.md) | All `vp-tools` subcommands (incl. `info`, `update`) with examples |
 | [Architecture](dev/architecture.md) | System layers, data flow, design decisions |
+| [Global profiles (FEAT-009)](dev/global-profiles.md) | `~/.viepilot/profiles`, `profile-map.md`, `.viepilot/META.md` binding |
 | [UI Components Library](dev/ui-components-library.md) | Curation taxonomy, storage contract, reuse flow |
 | [Contributing](dev/contributing.md) | How to add skills, workflows, CLI commands |
 | [Testing](dev/testing.md) | Test structure, running tests, writing new tests |
@@ -113,6 +114,8 @@
 | `/vp-pause` | "pause", "dừng" | Save state and pause |
 | `/vp-resume` | "resume", "tiếp tục" | Restore and continue |
 | `/vp-status` | "status", "tiến độ" | Progress dashboard |
+| `/vp-info` | "version", "phiên bản" | Bundle version, npm latest, inventory |
+| `/vp-update` | "upgrade viepilot", "npm" | Upgrade ViePilot via npm |
 | `/vp-request` | "request", "feature", "bug" | Add feature/bug |
 | `/vp-ui-components` | "ui components", "21st.dev" | Curate and reuse UI component library |
 | `/vp-evolve` | "evolve", "milestone mới" | New milestone |
@@ -124,4 +127,4 @@
 
 ---
 
-*Last updated: 2026-03-31 — ViePilot framework v1.2.0 (see `.viepilot/TRACKER.md`); project-scoped checkpoint tags delivered.*
+*Last updated: 2026-04-01 — ViePilot framework **v1.9.0** (M1.27 FEAT-009: global profiles + docs workflow §0A); see `CHANGELOG.md` and `docs/dev/global-profiles.md`.*

package/docs/dev/global-profiles.md

@@ -0,0 +1,115 @@
+# Global profiles & project meta binding (FEAT-009)
+
+Normative contract for machine-level **reusable org/context** (`~/.viepilot/`) and **per-repo binding** (`.viepilot/META.md`). Implementations (installer, brainstorm intake, crystallize, vp-docs) MUST follow this doc unless a phase explicitly supersedes it.
+
+## Layout (machine-level)
+
+Same home as stack cache and UI components:
+
+| Path | Purpose |
+|------|---------|
+| `~/.viepilot/profiles/` | One markdown file per reusable profile |
+| `~/.viepilot/profiles/<slug>.md` | Profile body + YAML frontmatter |
+| `~/.viepilot/profile-map.md` | Registry for lookup / disambiguation (human-editable) |
+
+`npx viepilot install` (Node installer) creates `profiles/` and seeds `profile-map.md` when missing — see `lib/viepilot-install.cjs`. Manual equivalent:
+
+```bash
+mkdir -p "$HOME/.viepilot/profiles"
+```
+
+## Profile slug & filename
+
+- **Slug**: `kebab-case`, characters `[a-z0-9-]` only, length 1–64.
+- **File**: `~/.viepilot/profiles/<slug>.md` where `<slug>` matches basename without `.md`.
+- **profile_id**: MUST equal `<slug>` (stable id for maps and binding). Future UUID optional in later revisions; v1 uses slug only.
+
+## Profile file schema (`*.md`)
+
+YAML frontmatter (required keys):
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `profile_id` | string | Same as slug |
+| `display_name` | string | Human label |
+| `org_tag` | string | Short org / client tag (e.g. `acme`, `personal`) |
+| `tags` | string[] | Freeform tags for filtering |
+| `last_updated` | string | ISO 8601 date `YYYY-MM-DD` |
+
+Optional frontmatter:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `locale` | string | BCP 47 or free text (e.g. `vi-VN`) |
+| `website` | string | Public URL only |
+
+Recommended markdown body sections (headings):
+
+- `## Organization`
+- `## Branding & voice`
+- `## Audience`
+- `## Legal & attribution` (public-facing lines only)
+- `## Contact (public)`
+- `## Notes`
+
+### Forbidden content
+
+Do **not** store secrets in profiles: API keys, passwords, tokens, private PEMs, session cookies, or any credential used for auth. Use a secrets manager; profiles are **non-sensitive** context only.
+
+## Registry: `~/.viepilot/profile-map.md`
+
+Purpose: **quick lookup** without opening every `profiles/*.md`.
+
+### File shape
+
+1. Title + short intro (1–3 lines).
+2. One markdown **table** with fixed columns (header row literal):
+
+| profile_id | display_name | org_tag | profile_path | tags | last_used |
+
+- **profile_path**: Prefer absolute path `~/.viepilot/profiles/<slug>.md` or `$HOME/.viepilot/profiles/<slug>.md` for clarity.
+- **tags**: Comma-separated in cell.
+- **last_used**: ISO `YYYY-MM-DD` or empty; tooling SHOULD update when user selects profile for a project.
+
+### Rules
+
+- **Add** a row when a new profile is created.
+- **Do not** delete rows silently; deprecate with a tag or note if needed.
+- Implementations SHOULD sort or filter by `org_tag` / `tags` when offering disambiguation (multiple companies).
+
+## Project binding (repo-local)
+
+### Source of truth: `.viepilot/META.md`
+
+Small file (see template `templates/project/VIEPILOT-META.md`). Minimum YAML frontmatter:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `viepilot_profile_id` | string | Active profile slug / `profile_id` |
+
+Optional:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `viepilot_profile_path` | string | Override path to profile file (advanced; default derived from id) |
+
+Crystallize / vp-docs / automation **MUST** resolve active profile by:
+
+1. Read `.viepilot/META.md` frontmatter `viepilot_profile_id`.
+2. If missing → intake or explicit user choice (Phase 31.2+).
+3. Load `~/.viepilot/profiles/<viepilot_profile_id>.md` unless `viepilot_profile_path` set.
+4. If file missing → error or re-prompt (implementation-defined in later tasks).
+
+### Optional mirror
+
+`HANDOFF.json` MAY duplicate `viepilot_profile_id` for session continuity. If both exist, **META.md wins**; tooling SHOULD keep them in sync when updating binding.
+
+## Relation to `PROJECT-META.md`
+
+`templates/project/PROJECT-META.md` is a **large product metadata** template (attribution, headers, etc.). **Do not merge** with ViePilot binding. Keep **VIEPILOT-META.md** (or `.viepilot/META.md`) separate and small.
+
+## References
+
+- UI component store pattern: `workflows/ui-components.md` (`~/.viepilot/ui-components/`)
+- Stack cache: `~/.viepilot/stacks/{stack}/`
+- Request: `.viepilot/requests/FEAT-009.md` (local)

package/docs/skills-reference.md

@@ -29,11 +29,15 @@ Complete reference for all ViePilot skills.
 | `/topic {name}` | Chuyển sang topic mới |
 | `/summary` | Xem tóm tắt hiện tại |
 | `/save` | Lưu tiến độ |
-| `/end` | Kết thúc và lưu |
+| `/end` | Kết thúc và lưu (sau **Project meta intake** nếu thiếu `.viepilot/META.md` / `viepilot_profile_id` — FEAT-009) |
 | `/questions` | Xem open questions |
+| `/research {topic}` | Research nhanh trong phiên, quay lại topic hiện tại |
+| `/research-ui` | **UI Direction (FEAT-010)**: mô phỏng user → designer + web research → cập nhật HTML/CSS + **`## UX walkthrough log`** trong `notes.md` |
+| `/research ui` | Alias của `/research-ui` |
 
 ### Output
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
+- **Project meta intake (FEAT-009):** khi scope đã chốt và chưa bind profile — Q&A tuần tự; ghi `~/.viepilot/profiles/<slug>.md`, cập nhật `~/.viepilot/profile-map.md`, tạo `.viepilot/META.md` — normative: `docs/dev/global-profiles.md`.
 - **Product horizon:** session file giữ **`## Product horizon`** (MVP / Post-MVP / Future tags, deferred capabilities, hoặc single-release statement) để `/vp-crystallize` không bỏ sót post-MVP — xem `workflows/brainstorm.md`.
 - UI Direction (optional): `.viepilot/ui-direction/{session-id}/` — legacy (`index.html`) hoặc multi-page (`pages/*.html` + hub + `## Pages inventory` trong `notes.md`). Chi tiết: [UI Direction](user/features/ui-direction.md).
 
@@ -51,6 +55,9 @@ Complete reference for all ViePilot skills.
 - `ROADMAP.md`: luôn có block **Post-MVP / Product horizon** (hoặc ghi rõ single-release); `PROJECT-CONTEXT.md`: khối **`<product_vision>`** từ `templates/project/PROJECT-CONTEXT.md`.
 - Hướng dẫn user tổng quan: [product-horizon.md](user/features/product-horizon.md). Thứ tự load cho AI: `templates/project/AI-GUIDE.md` (bản crystallize copy vào `.viepilot/AI-GUIDE.md`).
 
+### ViePilot global profile (FEAT-009)
+- Step 0: đọc `.viepilot/META.md` → `~/.viepilot/profiles/<slug>.md` (contract: `docs/dev/global-profiles.md`); pre-fill metadata; merge vào **ARCHITECTURE** (`## ViePilot organization context`) và **PROJECT-CONTEXT** (`## ViePilot active profile`).
+
 ### Metadata Collection
 - Project name, description
 - Organization name, website
@@ -229,6 +236,9 @@ AI pauses for user input when:
 
 **Purpose**: Generate documentation
 
+### ViePilot global profile (FEAT-009)
+- Sau resolve git/repo context: nếu có binding `.viepilot/META.md`, dùng profile global cho attribution/tone trong prose (không fail khi thiếu) — `workflows/documentation.md` §0A.
+
 ### Flags
 | Flag | Description |
 |------|-------------|

package/docs/user/features/brainstorm.md

@@ -23,6 +23,15 @@ Ghi một dòng explicit trong `## Product horizon`, ví dụ: **Single-release
 
 Khi **Continue** session, giữ và cập nhật `## Product horizon`; không xóa section này trừ khi bạn chủ động đổi scope.
 
+## Project meta intake & global profile (FEAT-009)
+
+Sau khi **chốt scope** (`## Product horizon` có nội dung thật hoặc bạn xác nhận đã lock) và **trước** khi kết thúc phiên (`/end` / `Completed`), nếu repo **chưa** có `.viepilot/META.md` với `viepilot_profile_id`, workflow bắt buộc chạy **Project meta intake**: hỏi **tuần tự** (có proposal), ghi `~/.viepilot/profiles/<slug>.md`, cập nhật `~/.viepilot/profile-map.md`, tạo binding **`.viepilot/META.md`**.
+
+- Đã có profile bound → có thể bỏ qua intake mặc định (chỉ hỏi đổi profile nếu cần).
+- Waiver hiếm: ghi `## Meta intake waiver` + lý do trong session.
+- Hợp đồng đầy đủ: [Global profiles (dev)](../../dev/global-profiles.md).
+- `npx viepilot install` tạo sẵn thư mục `~/.viepilot/profiles/` và file mẫu `profile-map.md` nếu thiếu.
+
 ## Bước tiếp
 
-Sau brainstorm: `/vp-crystallize` — horizon trong session được dùng để bổ sung roadmap và project context (xem workflow crystallize). Tổng quan end-to-end: [Product horizon](product-horizon.md).
+Sau brainstorm: `/vp-crystallize` — horizon trong session được dùng để bổ sung roadmap và project context; **crystallize** đọc `.viepilot/META.md` để pre-fill org/branding từ profile global khi có. Tổng quan end-to-end: [Product horizon](product-horizon.md).

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

@@ -65,11 +65,31 @@ Mẫu bảng (copy-paste và điền):
 
 Nếu **không** có thư mục `pages/`, không cần section `## Pages inventory` (layout legacy).
 
+## UX walkthrough — `/research-ui` (FEAT-010)
+
+Sau khi có prototype trong `.viepilot/ui-direction/{session-id}/`, bạn có thể **đánh giá và nâng cấp** bằng lệnh trong phiên brainstorm UI:
+
+| Lệnh | Ý nghĩa |
+|------|---------|
+| `/research-ui` | Pipeline đầy đủ (xem dưới) |
+| `/research ui` | Cùng nội dung (alias; có khoảng trắng sau `research`) |
+
+**Pipeline (3 phase)** — normative: `workflows/brainstorm.md` (mục *UI Direction — UX walkthrough & upgrade*):
+
+1. **End-user simulation** — AI đóng vai người dùng cuối: đi qua 3–8 scenario trên UI hiện tại, ghi pain (mơ hồ, thiếu feedback, quá nhiều bước, …) và mức độ.
+2. **Designer + research** — Đổi vai UX/UI designer: ưu tiên P0/P1/P2, **web search** khi cần benchmark/pattern, đề xuất cải tiến theo từng page/slug.
+3. **Cập nhật artifact** — Sửa HTML/CSS, và trong **`notes.md`** thêm section **`## UX walkthrough log`** (entry: ngày, scenario, pain, link research, tóm tắt thay đổi). Multi-page: vẫn giữ **hub** + **`## Pages inventory`** khớp `pages/*`.
+
+Gợi ý: kèm tên sản phẩm hoặc ngữ cảnh trong cùng tin nhắn (vd. “Trips — ưu tiên luồng đặt chuyến”).
+
+**Khác `/research {chủ đề}`**: lệnh tự do chỉ cần research ngắn và quay lại topic; **`/research-ui`** bắt buộc 3 phase + log + chỉnh prototype khi phù hợp.
+
 ## Flow khuyến nghị
 1. `/vp-brainstorm --ui`
 2. Chọn legacy hoặc multi-page theo số màn hình.
-3. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
-4. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+3. (Optional) `/research-ui` để chạy walkthrough và nâng cấp prototype + `notes.md`.
+4. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
+5. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
 
 ## Kiểm tra nhanh (optional)
 

package/docs/user/quick-start.md

@@ -48,6 +48,8 @@ vp-tools help
 # Hiển thị targets + ViePilot CLI Tools
 ```
 
+Sau khi cài, ViePilot tạo (nếu chưa có) **`~/.viepilot/profiles/`** và file mẫu **`~/.viepilot/profile-map.md`** để đăng ký profile tái sử dụng (brainstorm meta intake — xem `docs/dev/global-profiles.md`).
+
 Optional (maintainers):
 ```bash
 npm run readme:sync

package/lib/viepilot-install.cjs

@@ -8,6 +8,15 @@ const path = require('path');
 const os = require('os');
 const { resolveViepilotPackageRoot } = require('./viepilot-info.cjs');
 
+/** @see docs/dev/global-profiles.md (FEAT-009) */
+const VIEPILOT_PROFILE_MAP_SEED = `# ViePilot profile map
+
+Machine-level registry for reusable org/client profiles. Add rows when you create files under \`profiles/\`. Normative contract: bundled \`docs/dev/global-profiles.md\`.
+
+| profile_id | display_name | org_tag | profile_path | tags | last_used |
+|------------|--------------|---------|--------------|------|-----------|
+`;
+
 /**
  * @param {Record<string, string | undefined>} [envSource]
  * @returns {{ autoYes: boolean, profile: string, addPath: boolean, symlinkSkills: boolean }}
@@ -78,6 +87,9 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     opts.overrideHomedir != null ? path.resolve(opts.overrideHomedir) : os.homedir();
   const cursorSkillsDir = path.join(home, '.cursor', 'skills');
   const viepilotDir = path.join(home, '.cursor', 'viepilot');
+  const viepilotUserDataDir = path.join(home, '.viepilot');
+  const viepilotProfilesDir = path.join(viepilotUserDataDir, 'profiles');
+  const viepilotProfileMapPath = path.join(viepilotUserDataDir, 'profile-map.md');
 
   let wantPathShim = opts.wantPathShim;
   if (wantPathShim === undefined) {
@@ -100,6 +112,13 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     steps.push({ kind: 'mkdir', path: dir });
   }
 
+  steps.push({ kind: 'mkdir', path: viepilotProfilesDir });
+  steps.push({
+    kind: 'write_file_if_missing',
+    path: viepilotProfileMapPath,
+    content: VIEPILOT_PROFILE_MAP_SEED,
+  });
+
   for (const name of listSkillDirNames(root)) {
     const src = path.join(root, 'skills', name);
     const dest = path.join(cursorSkillsDir, name);
@@ -205,6 +224,9 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     paths: {
       cursorSkillsDir,
       viepilotDir,
+      viepilotUserDataDir,
+      viepilotProfilesDir,
+      viepilotProfileMapPath,
     },
     steps,
   };
@@ -222,6 +244,9 @@ function formatPlanLines(plan) {
   lines.push(`  profile: ${plan.env.profile} (informational; same file set as install.sh)`);
   lines.push(`  skills: ${plan.paths.cursorSkillsDir}`);
   lines.push(`  viepilot: ${plan.paths.viepilotDir}`);
+  if (plan.paths.viepilotUserDataDir) {
+    lines.push(`  userData (~/.viepilot): ${plan.paths.viepilotUserDataDir}`);
+  }
   lines.push('');
   for (let i = 0; i < plan.steps.length; i++) {
     const s = plan.steps[i];
@@ -230,6 +255,9 @@ function formatPlanLines(plan) {
       case 'mkdir':
         lines.push(`${n}. mkdir -p ${s.path}`);
         break;
+      case 'write_file_if_missing':
+        lines.push(`${n}. writeFileIfMissing ${s.path}`);
+        break;
       case 'copy_file':
         lines.push(`${n}. copy ${s.from} -> ${s.to}`);
         break;
@@ -340,6 +368,15 @@ function applyInstallPlan(plan, options = {}) {
           if (dryRun) logs.push(`[dry-run] mkdir -p ${step.path}`);
           else fs.mkdirSync(step.path, { recursive: true });
           break;
+        case 'write_file_if_missing':
+          if (dryRun) logs.push(`[dry-run] writeFileIfMissing ${step.path}`);
+          else {
+            fs.mkdirSync(path.dirname(step.path), { recursive: true });
+            if (!fs.existsSync(step.path)) {
+              fs.writeFileSync(step.path, step.content, 'utf8');
+            }
+          }
+          break;
         case 'copy_file':
           if (dryRun) logs.push(`[dry-run] copy ${step.from} -> ${step.to}`);
           else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-brainstorm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-brainstorm
 description: "Brainstorm session để thu thập ý tưởng, quyết định cho dự án"
-version: 0.4.0
+version: 0.6.0
 ---
 
 <cursor_skill_adapter>
@@ -34,6 +34,8 @@ Hỗ trợ:
 - In-session research (research ngay trong phiên brainstorm theo yêu cầu)
 - UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/` — hỗ trợ **multi-page** (`pages/{slug}.html` + hub `index.html`) và hook **`## Pages inventory`** trong `notes.md` khi có `pages/` (FEAT-007)
 - **Product horizon (ENH-014):** mọi session phải duy trì **`## Product horizon`** khi thảo luận capability/milestone — tier tags `(MVP)` / `(Post-MVP)` / `(Future)`, non-goals, deferred capabilities; hoặc ghi rõ **single-release / no deferred epics** (contract: `workflows/brainstorm.md`)
+- **Project meta intake (FEAT-009):** sau khi **scope locked**, **trước** `Completed` / `/end`, nếu thiếu `.viepilot/META.md` (`viepilot_profile_id`) — chạy Q&A **tuần tự** có proposal; đọc/ghi `~/.viepilot/profile-map.md`; tạo `~/.viepilot/profiles/<slug>.md` + binding theo **`docs/dev/global-profiles.md`**. Nếu đã có profile bound — skip intake mặc định (hỏi đổi nếu cần).
+- **UX walkthrough (FEAT-010):** trong **`--ui`**, lệnh **`/research-ui`** hoặc **`/research ui`** chạy 3 phase — mô phỏng **end-user** → **UX designer + web research** → chỉnh `index.html` / `pages/*.html` / `style.css` và ghi **`## UX walkthrough log`** trong `notes.md` (đồng bộ hub + **Pages inventory** khi multi-page).
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -65,10 +67,12 @@ Key steps:
 4. Run interactive Q&A với topic-based structure
 5. Nếu topic là landing page: hỏi thêm bố cục + tham khảo `21st.dev` để đề xuất section/components
 6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts trong `.viepilot/ui-direction/{session-id}/` — legacy: `index.html` + `style.css` + `notes.md`; multi-page: thêm `pages/*.html`, `index.html` làm hub, và sau mỗi thay đổi page cập nhật **`## Pages inventory`** trong `notes.md` (xem `docs/user/features/ui-direction.md`)
+6b. Khi user gõ **`/research-ui`** hoặc **`/research ui`** trong phiên UI: làm đúng **`workflows/brainstorm.md`** (FEAT-010) — không gộp vào bước research ngắn thường lệ
 7. Nếu user yêu cầu research hoặc cần làm rõ quyết định: research ngay trong session và quay lại topic
 8. Khi topic thêm/sửa capability hoặc release scope: cập nhật **`## Product horizon`** trong session (merge, không xóa tier tags im lặng) theo `workflows/brainstorm.md`
-9. Save session with structured format (bao gồm research notes + UI direction references + **Product horizon** khi có)
-10. Suggest next action: `/vp-crystallize`
+9. Trước khi hoàn tất phiên: **bước 5 — Project meta intake (FEAT-009)** trong `workflows/brainstorm.md` khi binding thiếu; sequential Q&A + profile-map disambiguation + ghi global profile + `.viepilot/META.md`
+10. Save session with structured format (bao gồm **`## Project meta intake (FEAT-009)`**, research notes + UI direction references + **Product horizon** khi có)
+11. Suggest next action: `/vp-crystallize`
 </process>
 
 <success_criteria>
@@ -81,6 +85,8 @@ Key steps:
 - [ ] Research can be executed inside the same brainstorm session
 - [ ] UI Direction artifacts created/updated when UI mode is active
 - [ ] Multi-page sessions: hub links + `## Pages inventory` stay in sync with `pages/*.html`
+- [ ] **FEAT-010**: `/research-ui` (khi `--ui`) chạy đủ 3 phase + **`## UX walkthrough log`** khi có chỉnh prototype
 - [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement) khi scope được thảo luận
+- [ ] **FEAT-009**: intake hoàn tất hoặc binding đã có **hoặc** waiver có lý do trước Completed; session ghi **`## Project meta intake (FEAT-009)`**
 - [ ] Next steps suggested
 </success_criteria>

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.0
 ---
 
 <cursor_skill_adapter>
@@ -47,6 +47,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 +71,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 +114,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 +122,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 +139,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 +200,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-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-docs
 description: "Generate comprehensive documentation cho dự án"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -54,6 +54,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 +90,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 +267,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/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/brainstorm.md

@@ -163,6 +163,39 @@ 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**).
+
+#### Phase 2 — UX designer + research
+
+1. Đổi vai: **UX/UI designer** nhận feedback từ Phase 1.
+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.
+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, link research (nếu có), **diff ý định** (bullet), file đã đổi.
+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 +205,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 +310,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 +373,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 — khi đã chạy `/research-ui`):
+- {YYYY-MM-DD}: scenarios exercised → top pains → research links → HTML/CSS edits summary
+
 ---
 
 ## Summary
@@ -289,7 +404,7 @@ git push
 </step>
 
 <step name="suggest_next">
-## 6. Suggest Next Action
+## 7. Suggest Next Action
 
 ```
 ✓ Brainstorm session saved
@@ -315,9 +430,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 +446,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**: Trong UI Direction, `/research-ui` (hoặc `/research ui`) chạy đủ 3 phase và ghi **`## UX walkthrough log`** 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>

package/workflows/crystallize.md

@@ -14,6 +14,23 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 <step name="collect_metadata">
 ## Step 0: Collect Project Metadata
 
+### ViePilot active profile (FEAT-009)
+
+Normative: **`docs/dev/global-profiles.md`**. Binding: **`.viepilot/META.md`** (`viepilot_profile_id`, optional `viepilot_profile_path`).
+
+**Trước** block câu hỏi Basic Info:
+
+1. Nếu có `.viepilot/META.md`, parse YAML frontmatter lấy `viepilot_profile_id` và tùy chọn `viepilot_profile_path`.
+2. **Resolve** file profile markdown:
+   - Nếu `viepilot_profile_path` có và file tồn tại (expand `~` / `$HOME`) → dùng path đó.
+   - Else nếu có `viepilot_profile_id` hợp lệ → `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`.
+3. **Khi đọc được file profile:**
+   - Đọc frontmatter (`display_name`, `org_tag`, `website`, `tags`, …) và body (`## Organization`, `## Branding & voice`, `## Audience`, `## Legal & attribution`, `## Contact (public)`).
+   - **Pre-fill** các câu hỏi Step 0 (org, website, mô tả ngắn nếu khớp) dưới dạng **proposal**; user **confirm** hoặc **sửa**.
+   - Ghi working note **`profile_resolved`**: `{ profile_id, absolute_path }` cho các bước sau.
+4. **Khi không có META, thiếu id, hoặc file không tồn tại:**
+   - Ghi **`profile_resolved: none`** và tiếp tục Step 0 như cũ — **không** fail crystallize.
+
 Hỏi user các thông tin dự án:
 
 ### Basic Info
@@ -202,6 +219,7 @@ Create `.viepilot/AI-GUIDE.md` using template:
 
 Customize with:
 - Project-specific file references
+- **ViePilot profile (FEAT-009):** Nếu Step 0 đặt `profile_resolved` thành đường dẫn hợp lệ, thêm mục **Quick context** ghi `profile_id`, đường dẫn file profile, và nhắc đọc file đó cho **tone/branding** khi viết user-facing text. Nếu `profile_resolved: none`, ghi một dòng: chưa bind profile global.
 - Context loading strategy based on project size — **preserve template ordering** where `PROJECT-CONTEXT.md` **`<product_vision>`** and **`ROADMAP.md` horizon** (Post-MVP / Future) are read **before** deep implementation / architecture lock; state this explicitly in the generated `AI-GUIDE.md` if you trim sections
 - Quick lookup for project-specific terms
 - Fast stack lookup section:
@@ -222,6 +240,7 @@ Fill with collected metadata:
 - Package structure (generate from base ID)
 - Developer info
 - File headers (generate from metadata)
+- **FEAT-009:** Nếu profile đã resolve ở Step 0 và user đã confirm pre-fill, **ưu tiên** khớp bảng Organization / attribution trong template với nội dung profile (chỉ dữ liệu công khai; không secrets).
 </step>
 
 <step name="generate_architecture">
@@ -237,6 +256,21 @@ Extract from brainstorm:
 - Technology decisions with rationale
 - Integration points
 
+### ViePilot organization context (FEAT-009)
+
+- Nếu Step 0 ghi **`profile_resolved`** với đường dẫn hợp lệ: ngay sau phần **overview** đầu tiên của `.viepilot/ARCHITECTURE.md`, thêm section:
+
+```markdown
+## ViePilot organization context
+
+> **Active profile**: `{profile_id}` — `{absolute path to profile file}` — binding `.viepilot/META.md`.
+
+```
+
+Sau đó **2–8 bullet** tóm tắt (không secrets) từ **Organization**, **Branding & voice**, **Audience** trong file profile.
+
+- Nếu **`profile_resolved: none`**: một dòng dưới overview: *No ViePilot global profile bound — organization context comes from Step 0 only.*
+
 Before writing diagrams, create a **diagram applicability matrix** from brainstorm signals (complexity, service boundaries, event usage, deployment shape, user-flow complexity, integration surface):
 
 | Diagram type | Status | Rule |
@@ -267,6 +301,23 @@ Extract:
 - Business rules
 - Naming conventions
 - Constraints
+
+**FEAT-009 — ViePilot active profile block:** Nếu profile đã resolve ở Step 0, chèn **trước** `<domain_knowledge>` (hoặc ngay sau title file) section:
+
+```markdown
+## ViePilot active profile (FEAT-009)
+
+| Field | Value |
+|-------|-------|
+| profile_id | … |
+| profile file | … |
+| org_tag | … |
+
+**Summary (non-secret):** …
+
+```
+
+Nếu không có profile: một dòng *Profile binding not configured (`META.md` or global profile file missing).*
 </step>
 
 <step name="generate_rules">

package/workflows/documentation.md

@@ -58,6 +58,14 @@ Use `$GITHUB_OWNER`, `$GITHUB_REPO` throughout all generated files.
 For viepilot framework repos, also use `$ACTUAL_SKILLS`, `$ACTUAL_WORKFLOWS`.
 **Never hardcode** `your-org`, `YOUR_USERNAME`, `YOUR_ORG`, or static skill/workflow counts.
 
+### 0A. ViePilot active profile (FEAT-009)
+
+Normative: **`docs/dev/global-profiles.md`**. Cùng **resolution** như `workflows/crystallize.md` Step 0 (đọc `.viepilot/META.md` → `viepilot_profile_path` hoặc `$HOME/.viepilot/profiles/<viepilot_profile_id>.md`).
+
+1. Nếu đọc được file profile, giữ **working notes** (display_name, org_tag, website, audience, branding) để dùng khi sinh README / contributing / bất kỳ prose **attribution** — chỉ nội dung **công khai**, không secrets.
+2. Nếu không có binding hoặc file thiếu → tiếp tục; **không** fail `/vp-docs`.
+3. Khi có profile, nhắc trong output (vd. footer README hoặc `docs/dev/architecture.md`) một dòng trích **profile_id** nếu phù hợp policy dự án.
+
 Post-generation validation (run after all files generated):
 ```bash
 PLACEHOLDERS=$(grep -r "your-org\|YOUR_USERNAME\|YOUR_ORG\|your-username" docs/ --include="*.md" -l 2>/dev/null)