viepilot 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -9,10 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Planned
 
-- **M1.25 / Phase 29 (ENH-018)** — **Crystallize + ARCHITECTURE**: Mermaid diagrams **complexity-gated** from brainstorm; six diagram kinds with required/optional/N/A; vp-audit / vp-auto / vp-debug alignment; target **1.8.0** on complete.
+- None.
 
 ### Added
 
+- 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
+
+### Fixed
+
+- **M1.26 / Phase 30 (BUG-004) completed** — enforced vp-only namespace behavior across the framework: all `vp-*` skills include scope guard rules, core workflows default to `vp-*` routing only, and external skills are allowed only via explicit user opt-in.
+
+### Added
+
+- `tests/unit/vp-scope-policy-contracts.test.js` — regression tests to ensure all bundled skills/workflows retain the BUG-004 scope policy contract.
+
+### Documentation
+
+- `docs/skills-reference.md`, `docs/user/features/autonomous-mode.md`, `docs/user/features/debug-mode.md`, `docs/user/quick-start.md` — clarified default `vp-*` scope and added explicit opt-in examples for external skills.
+
 ## [1.8.0] - 2026-04-01
 
 ### Added
@@ -274,7 +310,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.8.0...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
 [0.9.0]: https://github.com/0-CODE/viepilot/compare/v0.8.2...v0.9.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

@@ -2,6 +2,14 @@
 
 Complete reference for all ViePilot skills.
 
+## ViePilot Scope Policy
+
+- **Default behavior**: ViePilot workflows and responses only use skills under `vp-*`.
+- **Out-of-scope by default**: skills outside the ViePilot namespace are ignored, even if present in the runtime environment.
+- **Explicit opt-in**: external skills are considered only when the user explicitly asks to expand beyond ViePilot scope.
+- **Routing fallback**: if an external skill is mentioned accidentally, prefer the closest built-in `vp-*` command instead.
+- **Opt-in example**: "Trong bước này, cho phép dùng thêm external skills ngoài ViePilot để tham khảo."
+
 ---
 
 ## /vp-brainstorm
@@ -21,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).
 
@@ -43,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
@@ -221,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/autonomous-mode.md

@@ -30,6 +30,12 @@ Mỗi task:
 /vp-auto --dry-run        # Preview, không execute
 ```
 
+## ViePilot Scope Policy (BUG-004)
+
+- Mặc định, `/vp-auto` chỉ route/gợi ý các skill thuộc namespace `vp-*`.
+- Nếu môi trường runtime có skills ngoài framework, workflow sẽ bỏ qua và ưu tiên skill ViePilot tương đương.
+- Chỉ khi bạn ghi rõ yêu cầu mở rộng (explicit opt-in), agent mới được phép dùng external skills.
+
 ### 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*.

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/debug-mode.md

@@ -75,3 +75,4 @@ Active debug sessions:
 - 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
+- Theo policy BUG-004, `/vp-debug` mặc định chỉ dùng hệ skill `vp-*`; external skills chỉ dùng khi bạn explicit opt-in.

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
@@ -182,6 +184,14 @@ Hiển thị:
 
 ---
 
+## Skill Scope (BUG-004)
+
+- Theo mặc định, ViePilot chỉ dùng hệ lệnh/skill `vp-*` trong toàn bộ workflow.
+- Nếu bạn thấy đề cập skill ngoài framework, hãy coi đó là out-of-scope trừ khi bạn đã explicit opt-in.
+- Ví dụ opt-in hợp lệ: "Cho phép dùng thêm external skills ngoài ViePilot trong bước research này."
+
+---
+
 ## Next Steps
 
 - [Skills Reference](../skills-reference.md) — Chi tiết tất cả commands

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.0",
+  "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-audit/SKILL.md

@@ -15,6 +15,13 @@ Display audit results clearly with actionable suggestions grouped by tier.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Audit ViePilot project state và documentation để phát hiện drift.

package/skills/vp-auto/SKILL.md

@@ -18,6 +18,13 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 ## D. Subagent Spawning
 Use `Task(subagent_type="generalPurpose", ...)` for parallel execution.
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Autonomous execution của project phases. Cho mỗi phase: analyze → plan → execute → verify → iterate.

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>
@@ -15,6 +15,13 @@ Prompt user conversationally với numbered list options.
 ## C. Tool Usage
 Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
 </cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
 
 <objective>
 Thu thập ý tưởng, requirements, quyết định kiến trúc cho dự án thông qua interactive Q&A.
@@ -27,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`
@@ -58,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>
@@ -74,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>