@shanyucoder/flowgrid 0.1.8 → 0.1.10

package/harness/fe/skills/wire/SKILL.md

@@ -56,7 +56,7 @@ flowgrid audit e2e --e2e-root <playwright-dir> --tests-docs "$FLOWGRID_TESTS_DOC
 Optional: pass explicit `cases/**/TC-*.yaml` paths instead of `--tests-docs`.
 
 - Parse JSON: `missingInPlaywright`, `matrixRowsUncovered`, `orphanTestCases`, `orphanSpecs`, `gaps[]`.
-- **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa/open` if team policy allows.
+- **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa` if team policy allows.
 - **[MANDATORY]** Portal leaf with `apiRef`: `flowgrid audit fe-be <bundle.yaml>`.
 - **[MANDATORY]** When `SC-*` covers screen: `flowgrid audit scenario <SC.yaml> --tests-docs "$FLOWGRID_TESTS_DOC"`.
 

package/harness/tests/extracts/grill-scenario-flow.md

@@ -4,7 +4,7 @@ Hub SSOT: `docs/workflows/test.md#grill-scenario-flow`.
 
 ## Scope
 
-- Docs **`FLOW-*.md`** exists (Phase 0 / business-process) — **no SC without FLOW**
+- Docs **`FLOW-*.md`** exists (Phase 0 / user-flow) — **no SC without FLOW**
 - Tests: `scenarios/<mirror>/FLOW-<name>/SC-*.yaml` with `screens: [W-*, W-*, …]`
 - **Per screen touched:** at least one `cases/…/TC-*.yaml` OR documented defer (`coverage_deferred` + `QA-*` on docs)
 
@@ -36,4 +36,4 @@ Hub SSOT: `docs/workflows/test.md#grill-scenario-flow`.
 - [ ] Each screen's TC passed `cases:gate --strict` traceability
 - [ ] SC `screens[]` matches docs FLOW touchpoints (spot vs `FLOW-*.md`)
 
-Handoff thin FLOW → `/docs-hub /business-process` or `/update-spec` — not tests hub.
+Handoff thin FLOW → `/docs-hub /user-flow` or `/update-spec` — not tests hub.

package/harness/tests/skills/grill-testcase/SKILL.md

@@ -26,7 +26,7 @@ query a workspace-parent graph.
 - **[MANDATORY]** Read the entire function **`*.bundle.yaml`** (sibling of `ir/`). Cross-reference plans against bundle `userStories`, `acceptanceCriteria`, `spec.ui`, and `design.*` — not split IR files.
 - If scenarios/acceptance are thin or missing → hand off docs-hub `/update-spec` or `/spec` (paste-ready prompt). Do not patch bundle from tests hub.
 - **[STRICTLY FORBIDDEN]** Do NOT read generated `*.md`.
-- If auditing **SC-***, the YAML/MD path MUST mirror the docs `FLOW-*.md` (cluster/module/surface `common/processes/` or `architecture/03-business-process/`). Flag `scenarios/auth/…` or `common/` leftovers.
+- If auditing **SC-***, the YAML/MD path MUST mirror the docs `FLOW-*.md` (cluster/module/surface `common/user-flows/` or `architecture/03-user-flows/`). Flag `scenarios/auth/…` or `common/` leftovers.
 
 ## Audit Rules
 

package/harness/tests/skills/scenario/SKILL.md

@@ -13,7 +13,7 @@ disable-model-invocation: true
 
 Author cross-flow scenarios (SC) on the current tests hub. Design rules stay on the docs hub.
 
-Scenarios test a **business process** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
+Scenarios test a **user flow** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
 
 ## Output Rules
 
@@ -30,12 +30,12 @@ Scenarios test a **business process** (`FLOW-*`) that spans multiple screens (`W
 
 - **[MANDATORY]** Agent MUST locate the **`FLOW-*.md`** file on the docs hub (`FLOWGRID_DOCS_ROOT`) via `flowgrid_docs_route` / `flowgrid_docs_get_element` / glob. Filenames are `FLOW-…md`, not `flow-*`.
 - Search in this order (same LCA as bộ docs `common-scope.md`):
-  1. `surfaces/<surface>/<CMP-id>/<NN>/common/processes/FLOW-*.md` (cluster)
-  2. `surfaces/<surface>/<CMP-id>/common/processes/FLOW-*.md` (module)
-  3. `surfaces/<surface>/common/processes/FLOW-*.md` (surface)
-  4. `surfaces/common/processes/FLOW-*.md` (cross-surface product common)
-  5. `architecture/03-business-process/FLOW-*.md` (org catalog only)
-- **Strict:** Only author a scenario if that `FLOW-*.md` exists. Missing FLOW or thin business rules → hand off to docs-hub `/business-process` or `/update-spec`, do not invent SC. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report (formatted as a complete, ready-to-use prompt starting with `/docs-hub`) detailing exactly what flows or business rules are missing, so the user can copy-paste it directly to run the docs-hub skill.
+  1. `surfaces/<surface>/<CMP-id>/<NN>/common/user-flows/FLOW-*.md` (cluster)
+  2. `surfaces/<surface>/<CMP-id>/common/user-flows/FLOW-*.md` (module)
+  3. `surfaces/<surface>/common/user-flows/FLOW-*.md` (surface)
+  4. `surfaces/common/user-flows/FLOW-*.md` (cross-surface product common)
+  5. `architecture/03-user-flows/FLOW-*.md` (org catalog only)
+- **Strict:** Only author a scenario if that `FLOW-*.md` exists. Missing FLOW or thin business rules → hand off to docs-hub `/user-flow` or `/update-spec`, do not invent SC. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report (formatted as a complete, ready-to-use prompt starting with `/docs-hub`) detailing exactly what flows or business rules are missing, so the user can copy-paste it directly to run the docs-hub skill.
 - **[STRICTLY FORBIDDEN]** Do not treat `common/yaml/` or `common/patterns/` as scenario sources.
 
 ## Directory Mirroring Rule (Docs SSOT)
@@ -44,13 +44,13 @@ Mirror the FLOW file path onto the tests hub. Strip **only** these prefixes:
 
 | Docs FLOW path | Tests hub |
 |----------------|-----------|
-| `surfaces/<rest>/common/processes/FLOW-checkout.md` | `scenarios/<rest>/common/processes/FLOW-checkout/SC-*.yaml` |
-| `architecture/03-business-process/FLOW-checkout.md` | `scenarios/architecture/03-business-process/FLOW-checkout/SC-*.yaml` |
+| `surfaces/<rest>/common/user-flows/FLOW-checkout.md` | `scenarios/<rest>/common/user-flows/FLOW-checkout/SC-*.yaml` |
+| `architecture/03-user-flows/FLOW-checkout.md` | `scenarios/architecture/03-user-flows/FLOW-checkout/SC-*.yaml` |
 
 Examples:
 
-- Docs `surfaces/admin/CMP-ADM-002/02/common/processes/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-002/02/common/processes/FLOW-checkout/SC-*.yaml`
-- Docs `surfaces/admin/CMP-ADM-002/common/processes/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-002/common/processes/FLOW-onboard/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-002/02/common/user-flows/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-002/02/common/user-flows/FLOW-checkout/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-002/common/user-flows/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-002/common/user-flows/FLOW-onboard/SC-*.yaml`
 
 Do **not** flatten to `scenarios/auth/…`. Do **not** use `common/` (legacy). Keep numeric cluster folders (`02/`) in the tests path.
 

package/harness/tests/skills/testcase/SKILL.md

@@ -51,7 +51,7 @@ disable-model-invocation: true
 - **[MANDATORY]** Mirror function folder: `cases/<relative-path>/TC-*.yaml`.
   - ✅ `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
   - ❌ `cases/admin/auth/W-…` — invented path not matching docs structure.
-- Cross-flow plans → `/scenario` (mirror `common/processes/FLOW-*` or `architecture/03-business-process/FLOW-*`).
+- Cross-flow plans → `/scenario` (mirror `common/user-flows/FLOW-*` or `architecture/03-user-flows/FLOW-*`).
 
 ---
 

package/harness/tests/templates/SC.example.md

@@ -20,28 +20,28 @@ coverage_plan:
 Scenario thuộc **CMP-01-auth** · Tính năng năng lực **CAP-AUTH-001**.  
 Quy tắc chi tiết và schema cơ sở dữ liệu tham chiếu tại **Docs Hub** (cite ID: `spec.yaml`).
 
-| Thuộc tính | Giá trị |
-|---|---|
+| Attribute | Value |
+| --- | --- |
 | **Scenario ID** | `SC-EXAMPLE` |
 | **Module** | `CMP-01-auth` |
-| **Bề mặt (Surface)** | `admin` |
-| **Màn hình (Screen)** | `W-AD-AUTH-001` (`/admin/records/create`) |
-| **Mức độ ưu tiên** | `High` |
+| **Surface** | `admin` |
+| **Screen** | `W-AD-AUTH-001` (`/admin/records/create`) |
+| **Priority** | `High` |
 
-## 1. Bối Cảnh Nghiệp Vụ & Phân Tích Rủi Ro (Business Context & Risk Analysis)
+## 1. Business context & risk analysis
 
 Màn hình khởi tạo hồ sơ là cửa ngõ dữ liệu tài chính của khách hàng. Nếu bỏ sót kiểm tra trùng mã hoặc không xử lý chặn click đúp (double-submit), hệ thống sẽ tạo các bản ghi rác gây xung đột số liệu doanh thu và vi phạm tính toàn vẹn dữ liệu kế toán.
 
-## 2. Hành Vi Chuẩn BDD (Behavior: Given / When / Then)
+## 2. BDD behavior (Given / When / Then)
 
 - **Given (Tiền điều kiện):** Người dùng đăng nhập thành công với vai trò Quản trị viên (`ADMIN`), tài khoản có quyền `records.create`, và chưa tồn tại bản ghi nào có mã `REC-2026-001` trong cơ sở dữ liệu.
 - **When (Thao tác):** Người dùng nhập đầy đủ các trường thông tin hợp lệ (mã hồ sơ, tên hồ sơ, chọn gói dịch vụ) và nhấn nút "Lưu & Xác Nhận".
 - **Then (Hậu điều kiện):** Hệ thống khóa nút để tránh gửi trùng lặp, gửi request kèm header `X-Idempotency-Key`, tạo mới bản ghi thành công trong bảng `records`, hiển thị Toast thông báo màu xanh và điều hướng sang màn hình chi tiết `W-ADM-DETAIL-01`.
 
-## 3. Ma Trận Test Phân Hoạch Tương Đương & Phân Tích Giá Trị Biên (Equivalence Partitioning & Boundary Test Matrix - IEEE 29119)
+## 3. Equivalence & boundary test matrix
 
-| Mã Case (Case ID) | Khía Cạnh Kiểm Thử (Facet) | Dữ Liệu Đầu Vào (Input Data) | Kết Quả Mong Đợi (Expected Outcome) | HTTP Status & UI State | Tự Động Hóa (Automation Case) |
-|---|---|---|---|---|---|
+| Case ID | Facet | Input | Expected outcome | HTTP & UI | Automation case |
+| --- | --- | --- | --- | --- | --- |
 | **TC-VAL-01** | `positive_boundary` (Biên tối thiểu) | `code: "REC01"` (5 chars), `name: "Hồ sơ A"` | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
 | **TC-VAL-02** | `positive_boundary` (Biên tối đa) | `code: "REC-2026-MAXIMUM-001"` (20 chars) | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
 | **TC-VAL-03** | `negative_length` (Dưới độ dài min) | `code: "REC"` (3 chars) | Chặn submit, báo lỗi inline dưới ô nhập | `Client Error` · "Độ dài từ 5 đến 20 ký tự" | `TC-EXAMPLE-INVALID` |
@@ -50,10 +50,10 @@ Màn hình khởi tạo hồ sơ là cửa ngõ dữ liệu tài chính của kh
 | **TC-ACT-06** | `concurrency_double_submit` | Click nút "Lưu" liên tục 2 lần trong 100ms | Nút khóa disabled tức thì, chỉ 1 request gửi đi | `UI Locked` · Không tạo 2 bản ghi trùng | `TC-EXAMPLE-CONCURRENCY` |
 | **TC-SYS-07** | `network_interruption` (Mất mạng) | Ngắt kết nối mạng ngay khi gửi request | Hiện banner cảnh báo mất kết nối, giữ nguyên dữ liệu form | `Network Banner` · Form state preserved | `TC-EXAMPLE-OFFLINE` |
 
-## 4. Bao Phủ Rủi Ro & Khía Cạnh Chất Lượng (Quality Dimensions Coverage)
+## 4. Quality dimensions coverage
 
-| Khía Cạnh (Dimension) | Mức Độ Bao Phủ | Ghi Chú Đảm Bảo Chất Lượng |
-|---|---|---|
+| Dimension | Coverage | Notes |
+| --- | --- | --- |
 | **Happy Path & Workflow** | 100% | Toàn bộ luồng khởi tạo đến xem chi tiết hoàn tất |
 | **Boundary Value Analysis** | 100% | Kiểm thử đầy đủ tại ngưỡng min-1, min, max, max+1 |
 | **Data Integrity & Concurrency** | 100% | Kiểm tra unique mã hồ sơ qua async DB & chặn double-click |
@@ -75,10 +75,10 @@ stateDiagram-v2
   ChuyenTrangChiTiet --> [*]
 ```
 
-## 5. Danh Sách Test Cases Chi Tiết (Test Cases Mapping)
+## 5. Test case mapping
 
-| Mã Case (ID) | Khía Cạnh | Mức Độ Ưu Tiên | Thư Mục Test Hub |
-|---|---|---|---|
+| Case ID | Facets | Priority | Tests hub path |
+| --- | --- | --- | --- |
 | `TC-EXAMPLE-VALID` | happy, boundary | Critical | `cases/admin/CMP-01-auth/01/create/` |
 | `TC-EXAMPLE-INVALID` | validation, boundary | High | `cases/admin/CMP-01-auth/01/create/` |
 | `TC-EXAMPLE-DUPLICATE` | concurrency, remote_unique | High | `cases/admin/CMP-01-auth/01/create/` |

package/lexicon/registry-tags.en.txt

@@ -127,7 +127,7 @@ PII / Sensitive / Masked
 K. Business architecture — process hierarchy & synonyms
 ================================================================================
 Business Capability
-Business Process
+User flow
 End-to-End Flow / E2E Flow
 Use Case
 Scenario
@@ -138,7 +138,7 @@ Cross-Service Flow / Service Orchestration / Service Choreography
 Saga Flow / Distributed Transaction
 Domain Workflow / Event Flow / Command Flow
 #process: business-capability
-#process: business-process
+#process: user-flow
 #process: e2e-flow
 #process: use-case
 #process: scenario

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
   "type": "module",
   "main": "./dist/index.js",

package/templates/project-skeleton/architecture/03-business-process/index.md

@@ -0,0 +1,3 @@
+# Deprecated path
+
+Use [`../03-user-flows/`](../03-user-flows/) for new hubs. Files here are legacy copies only.

package/templates/project-skeleton/architecture/{03-business-process → 03-user-flows}/FLOW-login.md

@@ -12,7 +12,7 @@ status: "approved"
 
 ---
 
-## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ
+## 1. Context & role matrix
 
 * **Bối cảnh kích hoạt:** Quản trị viên truy cập vào cổng quản trị để quản lý hệ thống. Phiên đăng nhập hiện tại chưa có hoặc đã hết hạn.
 * **Ma trận Vai trò & Quyền hạn:**
@@ -22,7 +22,7 @@ status: "approved"
 
 ---
 
-## 2. Chuỗi User Stories Đa Tầng
+## 2. User stories (multi-tier)
 
 ### Story 1: Xác thực & Truy cập Hệ thống (Primary Action Story)
 > **Là một** Quản trị viên hệ thống,  
@@ -38,7 +38,7 @@ status: "approved"
 
 ---
 
-## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+## 3. Business rules & state lifecycle
 
 ### Danh mục Quy tắc Nghiệp vụ
 * **BR-01 (Giới hạn thử lại):** Cho phép nhập sai tối đa 5 lần liên tiếp. Nếu vượt quá, khóa tài khoản tạm thời trong 15 phút.
@@ -53,7 +53,7 @@ status: "approved"
 
 ---
 
-## 4. Đặc tả Chi tiết Hành trình Từng Chặng
+## 4. Step-by-step journey
 
 ### Chặng 1: Nhập thông tin trên `[W-AD-AUTH-01]`
 1. **Thao tác:** Quản trị viên mở trang đăng nhập, điền `username` và `password`.
@@ -64,7 +64,7 @@ status: "approved"
 
 ---
 
-## 5. Ma trận Đối chiếu (Traceability Matrix)
+## 5. Traceability matrix
 
 | Bước trong User Story | Màn hình liên quan | Hành động trên Sequence Diagram | Thành phần kỹ thuật đảm nhiệm |
 | :--- | :--- | :--- | :--- |
@@ -74,7 +74,7 @@ status: "approved"
 
 ---
 
-## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Sequence Diagram)
+## 6. Screen-to-screen sequence diagram
 
 ```mermaid
 sequenceDiagram

package/templates/project-skeleton/architecture/{03-business-process → 03-user-flows}/FLOW-template.md

@@ -11,11 +11,10 @@ status: "draft"
 
 ---
 
-## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ (Context & Role Matrix)
+## 1. Context & role matrix
 
 * **Bối cảnh kích hoạt (Trigger Context):** [Mô tả hoàn cảnh hoặc sự kiện nào khiến quy trình này diễn ra. Ví dụ: Khách hàng yêu cầu đặt hàng, hoặc quản trị viên khởi tạo chiến dịch khuyến mãi...]
 * **Mục tiêu kinh doanh (Business Goal):** [Giá trị kinh doanh hoặc bài toán mà quy trình này giải quyết...]
-* **Chỉ số thành công (Success metrics):** [Đo được nếu có — VD: thời gian xử lý, tỷ lệ lỗi, SLA phản hồi]
 * **Phạm vi không làm (Non-goals):** [Quy trình/phase này cố ý không bao gồm — tránh trùng FLOW khác]
 * **Ma trận Vai trò & Quyền hạn (Role & Permission Matrix):**
   | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
@@ -28,7 +27,7 @@ status: "draft"
 
 ---
 
-## 2. Chuỗi User Stories Đa Tầng (Multi-tiered User Stories)
+## 2. User stories (multi-tier)
 
 ### Story 1: Thao tác Chuẩn bị / Cấu hình (Setup Story - Tùy chọn)
 > **Là một** [Vai trò chuẩn bị, vd: Quản trị viên],  
@@ -52,7 +51,7 @@ status: "draft"
 
 ---
 
-## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+## 3. Business rules & state lifecycle
 
 ### Danh mục Quy tắc Nghiệp vụ (Business Rules)
 * **BR-01 (Quy tắc thẩm định dữ liệu):** [Mô tả điều kiện hợp lệ để cho phép đi tiếp sang bước kế tiếp...]
@@ -70,7 +69,7 @@ status: "draft"
 
 ---
 
-## 4. Đặc tả Chi tiết Hành trình Từng Chặng (Step-by-step Journey)
+## 4. Step-by-step journey
 
 ### Chặng 1: Thao tác & Nhập liệu trên Màn hình `[W-ACTION-01]`
 1. **Thao tác người dùng:** Người dùng truy cập form, điền các thông tin bắt buộc.
@@ -96,7 +95,7 @@ status: "draft"
 
 ---
 
-## 5. Ma trận Đối chiếu (Traceability Matrix)
+## 5. Traceability matrix
 
 | Bước trong User Story | Màn hình liên quan | Hành động trên Sequence Diagram | Thành phần kỹ thuật đảm nhiệm |
 | :--- | :--- | :--- | :--- |
@@ -107,7 +106,7 @@ status: "draft"
 
 ---
 
-## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Business Sequence Diagram)
+## 6. Screen-to-screen sequence diagram
 
 ```mermaid
 sequenceDiagram

package/templates/project-skeleton/architecture/11-risks/index.md

@@ -2,24 +2,14 @@
 
 status: active
 
-Risks and mitigations for the docs hub migration and for relying on curated architecture docs.
+Risks live **only** in the central register — not on feature bundles.
 
-## Docs hub
+## Register (member-facing)
 
-| Risk | Mitigation |
-|------|------------|
-| Stale paths after arc42 migrate | Redirect stubs on old flat paths; skills + start-now / SYSTEM-DOC-STRUCTURE |
-| Orphan / wrong IDs in MD | FlowGrid bộ docs MCP orphans + validate_links; add FLOW-* only with lead IDs |
-| “Full sequence every story” pressure | Principle: curated ~10–20%; skill `/journey` refusal |
-| Mermaid render confusion | Reader = VitePress only; no Mermaid MCP; Structurizr only if C4 hierarchy pain |
-| Invented deployment topology | §07 stub-first; `/deployment` refuses fiction |
+**[risk-register.md](./risk-register.md)** — bảng `RISK-*`, hạn mức vs nhu cầu peak.
 
-## Product / domain (stub)
+```bash
+flowgrid audit risks architecture/11-risks/risk-register.md
+```
 
-New MES / IoT / ERP journeys only when lead assigns real `CTR-*`/`API-*` ownership — do not invent draft FLOW SSOT.
-
-## See also
-
-- [10 Quality](/architecture/10-quality/)
-- [Start now](/platform/guide/start-now)
-- [Doc structure](/platform/guide/SYSTEM-DOC-STRUCTURE)
+Skill: `/risk-register`

package/templates/project-skeleton/architecture/11-risks/risk-register.md

@@ -0,0 +1,34 @@
+---
+status: draft
+owner: product-team
+contentLocale: vi
+---
+
+# Risk register
+
+**SSOT** for project risks — members edit this file only. **Do not** use `risks:` on `*.bundle.yaml`.
+
+Add a row when **limit** (quota, SLA, license) differs from **need** (peak, campaign).
+
+## Summary
+
+| Metric | Value |
+| --- | --- |
+| Open risks | 0 |
+| Quota / capacity gaps | 0 |
+| With mitigation | 0 |
+
+## Risk table
+
+| ID | Type | Description | Limit | Need | Gap | Impact | Mitigation | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| RISK-QUOTA-EMAIL-001 | Quota / infra | System notification email | 500 emails/day (SMTP) | ~700 emails/day (month start, reminders) | +200 (~40%) | Users miss timely email | (1) Spread queue (2) Upgrade plan (3) SMS for critical | Open |
+
+### Suggested types
+
+Quota / infra · Vendor · Data / compliance · Operations capacity · Product / scope
+
+## Links
+
+- Open questions: `qa/index.md`
+- Skill: `/risk-register` · `flowgrid audit risks architecture/11-risks/risk-register.md`

package/templates/project-skeleton/architecture/12-glossary/index.md

@@ -21,7 +21,8 @@ status: active
 
 | Term | Meaning |
 |------|---------|
-| Journey | Curated product runtime flow `FLOW-*` under §06 |
+| Journey / Luồng người dùng | `FLOW-*` under `architecture/03-user-flows` or `common/user-flows` |
+| `/user-flow` | Docs skill to author product `FLOW-*` |
 | business-process-trace | Brownfield process-through-code skill — **not** product journey `FLOW-*` |
 | flow-trace | Deprecated alias of business-process-trace |
 | `_legacy.dynamics*` | Extract/artifact name for old dynamics — keep filename; wording → FLOW/journey |

package/templates/project-skeleton/overview/index.md

@@ -1,68 +1,46 @@
 ---
 status: draft
 owner: product-team
+contentLocale: vi
 ---
 
-# Product overview (arc42 §1 — Introduction & Goals)
+# Product overview
 
-Tài liệu **sản phẩm** cho toàn docs hub: *vì sao* hệ thống tồn tại, *ai* dùng, *phạm vi* operational area. Chi tiết màn/API → `surfaces/`; kiến trúc kỹ thuật → `architecture/`.
+Product-level docs for this hub. Screen detail → `surfaces/` · technical architecture → `architecture/`.
 
-## Mục tiêu (Goals)
+> Section titles are **English** (global keys). Prose uses `contentLocale` in frontmatter / `docs-hub.locale.yaml`.
 
-1. **Giá trị nghiệp vụ** — [Một đoạn: bài toán chính product giải quyết.]
-2. **Đối tượng phục vụ** — [Vai trò / operational area chính.]
-3. **Nguyên tắc sản phẩm** — [VD: một SSOT docs, trace `W-*` / `API-*`, grill trước codegen.]
+## Goals {#goals}
 
-## Stakeholders
+1. **Business value** — [Main problem this product solves.]
+2. **Primary audience** — [Roles / channels — one line.]
+3. **Product principles** — [e.g. single SSOT, trace `W-*` / `API-*`.]
 
-| Vai trò | Mục đích đọc overview |
-| --- | --- |
-| PO / BA | Phạm vi, persona, operational area |
-| Dev / QA | Boundary module, link `CMP-*` |
-| Leadership | Goals + success metrics cấp product |
-
-## Top quality goals (arc42)
-
-| # | Thuộc tính | Mục tiêu (đo được nếu có) |
-| --- | --- | --- |
-| 1 | Khả dụng | [VD: uptime SLA nội bộ] |
-| 2 | Bảo mật | [VD: RBAC trên admin portal] |
-| 3 | Khả năng mở rộng | [VD: multi-tenant / module mới không phá SSOT] |
-| 4 | Khả năng bảo trì | [VD: spec bundle + split + audit] |
-| 5 | Trải nghiệm | [VD: affordance UX portal chuẩn] |
-
-## Personas (tóm tắt)
-
-- **[Persona A]** — [Một câu: nhu cầu chính trên surface nào.]
-- **[Persona B]** — […]
-
-Leaf `userStories.primary.asA` **tham chiếu** persona ở đây (không copy persona dài trên từng màn).
-
-## Phạm vi & không làm (product-level)
+## Background {#background}
 
-**In scope (overview):**
+[Short paragraph: current situation, why this product/phase exists. No infra deep-dive.]
 
-- [Operational area / surface được document trong hub này]
+## Scope {#scope}
 
-**Non-goals (product-level):**
+**In scope:**
 
-- [VD: không mô tả hạ tầng chi tiết — xem `architecture/`]
-- [VD: không thay quy trình UAT Excel deliverable — xem tests-docs]
+- [Operational areas / surfaces documented in this hub]
 
-## Success metrics (product-level)
+**Out of scope:**
 
-- [Chỉ số đo được cấp product — VD: thời gian onboard member đọc SSOT, % leaf có audit sạch trước test lane]
+- [e.g. deployment detail → `architecture/07-deployment/`]
+- [personas / KPIs managed outside the hub]
 
 ## Operational areas
 
-Mỗi area một file dưới `overview/operational-areas/` — dùng [`_template.md`](./operational-areas/_template.md).
+One file per area under `overview/operational-areas/` — see [`_template.md`](./operational-areas/_template.md).
 
 | Area | File |
 | --- | --- |
-| [Tên area] | `operational-areas/<slug>.md` |
+| [Area name] | `operational-areas/<slug>.md` |
 
 ## See also
 
-- Surfaces SSOT: `surfaces/`
-- Architecture: `architecture/01-introduction/`
-- Workflow Design: `platform` hoặc `docs/workflows/design.md` (khi publish site)
+- Surfaces: `surfaces/`
+- User flows catalog: `architecture/03-user-flows/`
+- Risk register: `architecture/11-risks/risk-register.md`

package/templates/project-skeleton/overview/operational-areas/_template.md

@@ -1,37 +1,30 @@
 ---
 id: OA-TEMPLATE
-title: "Tên operational area"
+title: "Operational area name"
 status: draft
 surfaces: ["admin-web"]
+contentLocale: vi
 ---
 
-# Operational area: [Tên]
+# Operational area: [Name]
 
-**Mục đích:** [Một đoạn — bối cảnh vận hành: ai làm việc gì, trên kênh nào.]
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
 
-## Personas trong area
+**Purpose:** [One paragraph — who does what, on which channel.]
 
-| Persona | Mô tả ngắn | Surface chính |
-| --- | --- | --- |
-| [VD: Nhân viên vận hành] | [Nhu cầu] | `admin-web` |
+## Scope {#scope}
 
-## Phạm vi nghiệp vụ
+- **In scope:** [Processes / modules in this area]
+- **Out of scope:** [Other area or later phase]
 
-- **In scope:** [Quy trình / module thuộc area]
-- **Out of scope:** [Chuyển sang area khác hoặc phase sau]
+## Module links
 
-## Success metrics (area)
-
-- [Metric 1 — đo được]
-- [Metric 2]
-
-## Liên kết module
-
-| CMP | Mô tả |
+| CMP | Summary |
 | --- | --- |
-| `CMP-XX-…` | [Boundary một dòng] |
+| `CMP-XX-…` | [One-line boundary] |
 
-## Non-goals
+## Related user flows
 
-- [Không document chi tiết deployment — `architecture/07-deployment/`]
-- [Không duplicate FLOW kỹ thuật — `architecture/03-business-process/`]
+| FLOW | Summary |
+| --- | --- |
+| `FLOW-…` | [Link under `architecture/03-user-flows/` or `common/user-flows/`] |

package/templates/project-skeleton/qa/README.md

@@ -1,11 +1,7 @@
-# QA inbox (docs hub)
+# QA inbox
 
-Open customer / choice / tech-debt questions live here — **not** in `*.bundle.yaml`.
+One file per case: `qa/<SHORT>_0001.yaml`.
 
-- One file per open issue: `qa/open/QA-<bundle.id>-NNNN.yaml`
-- `bundle.id` is the screen leaf id from `/spec` (e.g. `cmp-adm-002-02-01-02`)
-- Sequence is **per screen** (`0001`, `0002`, …). Different screens never share a counter.
-- Close with **`/qa-resolve QA-<bundle.id>-NNNN`** plus the decision (skill deletes the file).
+After `flowgrid init`, copy from `.flowgrid/templates/qa-item.yaml` and follow `.flowgrid/templates/qa-authoring.md`.
 
-Template: `.flowgrid/templates/qa-item.yaml`  
-Rules: `.cursor/extracts/qa-inbox.md`
+Append-only `updates[]` · `flowgrid render` refreshes `index.md`.

package/templates/project-skeleton/surfaces/_module-index.template.md

@@ -0,0 +1,40 @@
+---
+id: CMP-NN-slug
+title: "Module name"
+status: draft
+contentLocale: vi
+---
+
+# CMP-{NN} — [Name]
+
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
+
+## Goals {#goals}
+
+[Module value — one paragraph.]
+
+## Scope {#scope}
+
+- **In scope:** [Capabilities owned by this CMP on this surface.]
+- **Out of scope:** [Other CMP / phase / channel.]
+
+## Features overview {#features-overview}
+
+| Function | Screen / API | Notes |
+| --- | --- | --- |
+| `<slug>` | `W-…` / `API-…` | Leaf: `ir/generated/spec.md` |
+
+## Depends on {#depends-on}
+
+| ID / artifact | Reason |
+| --- | --- |
+| `CMP-…` / `FLOW-…` | [Upstream dependency] |
+
+## Module metadata
+
+| Field | Value |
+| --- | --- |
+| **ID** | `CMP-{NN}` |
+| **User flows** | `…/common/user-flows/FLOW-…` · [`architecture/03-user-flows/`](../../architecture/03-user-flows/) |
+| **Functions** | `<function-slug>`, … |
+| **Screens** | `W-…` |

package/templates/project-skeleton/surfaces/_surface-index.template.md

@@ -0,0 +1,43 @@
+---
+id: SURFACE-TEMPLATE
+title: "Surface channel name"
+status: draft
+contentLocale: vi
+---
+
+# Surface: [Channel name]
+
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
+
+## Goals {#goals}
+
+[Value of this channel — one paragraph.]
+
+## Background {#background}
+
+[Who uses this channel and in what context.]
+
+## Scope {#scope}
+
+**In scope:**
+
+- [CMP modules on this surface]
+
+**Out of scope:**
+
+- [Other surface or integration-only scope]
+
+## Modules (CMP)
+
+| CMP | Summary | Primary flow |
+| --- | --- | --- |
+| `CMP-…` | […] | `FLOW-…` (if any) |
+
+## User flows on this surface
+
+- Catalog: [`architecture/03-user-flows/`](/architecture/03-user-flows/)
+- Shared on surface: `common/user-flows/FLOW-*.md` (when ≥2 modules share)
+
+## Features overview
+
+[1–2 paragraphs: how to read the hub — detail per screen in bundles and `ir/generated/spec.md`.]