@shanyucoder/flowgrid 0.1.9 → 0.1.11

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

@@ -1,10 +1,10 @@
 ---
 id: SC-EXAMPLE
-module: CMP-01-auth
+module: CMP-ADM-AUTH-01
 surface: admin
-screen: W-AD-AUTH-001
+screen: W-ADM-AUTH-01
 screens:
-  - W-AD-AUTH-001
+  - W-ADM-AUTH-01
 rules:
   - RUL-00-example
 coverage_plan:
@@ -17,31 +17,31 @@ coverage_plan:
 
 # SC-EXAMPLE — Xác Thực & Khởi Tạo Hồ Sơ Khách Hàng
 
-Scenario thuộc **CMP-01-auth** · Tính năng năng lực **CAP-AUTH-001**.  
+Scenario thuộc **CMP-ADM-AUTH-01** · 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` |
+| **Module** | `CMP-ADM-AUTH-01` |
+| **Surface** | `admin` |
+| **Screen** | `W-ADM-AUTH-01` (`/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,12 +75,12 @@ 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 |
-|---|---|---|---|
-| `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/` |
-| `TC-EXAMPLE-CONCURRENCY` | interaction, double_submit | High | `cases/admin/CMP-01-auth/01/create/` |
-| `TC-EXAMPLE-OFFLINE` | reliability, offline_resilience | Medium | `cases/admin/CMP-01-auth/01/create/` |
+| Case ID | Facets | Priority | Tests hub path |
+| --- | --- | --- | --- |
+| `TC-EXAMPLE-VALID` | happy, boundary | Critical | `cases/admin/CMP-ADM-AUTH-01/01/create/` |
+| `TC-EXAMPLE-INVALID` | validation, boundary | High | `cases/admin/CMP-ADM-AUTH-01/01/create/` |
+| `TC-EXAMPLE-DUPLICATE` | concurrency, remote_unique | High | `cases/admin/CMP-ADM-AUTH-01/01/create/` |
+| `TC-EXAMPLE-CONCURRENCY` | interaction, double_submit | High | `cases/admin/CMP-ADM-AUTH-01/01/create/` |
+| `TC-EXAMPLE-OFFLINE` | reliability, offline_resilience | Medium | `cases/admin/CMP-ADM-AUTH-01/01/create/` |

package/harness/tests/templates/TC.example.yaml

@@ -10,11 +10,11 @@ story: |
   When thực hiện thao tác nhập liệu và nhấn lưu
   Then hệ thống tạo mới thành công và chuyển trạng thái
 refs:
-  module: CMP-01-auth
+  module: CMP-ADM-AUTH-01
   surface: admin
   scenario: SC-EXAMPLE
   example: EX-EXAMPLE-01
-  screen: W-AD-AUTH-001
+  screen: W-ADM-AUTH-01
 coverage: [happy, boundary, validation, concurrency, exception]
 priority: high
 automation: automated
@@ -123,7 +123,7 @@ testIds:
 
 # Fill when bundle is available (required for `flowgrid cases:gate --strict`).
 traceability:
-  bundleScreen: W-AD-AUTH-001
+  bundleScreen: W-ADM-AUTH-01
   bundleScenarios: []
   acceptanceRefs: []
   actionRefs:

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.9",
+  "version": "0.1.11",
   "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,22 +12,22 @@ 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:**
   | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
   | :--- | :--- | :--- |
-  | **Quản trị viên (Admin)** | Đăng nhập tài khoản | Nhập thông tin trên `[W-AD-AUTH-01]`, truy cập `[W-AD-DASH-01]` |
+  | **Quản trị viên (Admin)** | Đăng nhập tài khoản | Nhập thông tin trên `[W-ADM-AUTH-01]`, truy cập `[W-ADM-DASH-01]` |
 
 ---
 
-## 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,  
-> **Tôi muốn** nhập tên đăng nhập và mật khẩu hợp lệ trên màn hình đăng nhập `[W-AD-AUTH-01]`,  
-> **Để** hệ thống xác thực danh tính và cấp quyền truy cập vào trang tổng quan `[W-AD-DASH-01]`.
+> **Tôi muốn** nhập tên đăng nhập và mật khẩu hợp lệ trên màn hình đăng nhập `[W-ADM-AUTH-01]`,  
+> **Để** hệ thống xác thực danh tính và cấp quyền truy cập vào trang tổng quan `[W-ADM-DASH-01]`.
 
 ### Story 2: Xử lý Sai Thông tin & Khóa Tài khoản (Security Fallback 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,37 +53,37 @@ 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]`
+### Chặng 1: Nhập thông tin trên `[W-ADM-AUTH-01]`
 1. **Thao tác:** Quản trị viên mở trang đăng nhập, điền `username` và `password`.
 2. **Bấm "Đăng nhập":**
    * Hệ thống kiểm tra xác thực thông tin đối soát với cơ sở dữ liệu tài khoản.
-   * **Nếu hợp lệ:** Khởi tạo phiên làm việc an toàn, điều hướng sang `[W-AD-DASH-01] Dashboard`.
+   * **Nếu hợp lệ:** Khởi tạo phiên làm việc an toàn, điều hướng sang `[W-ADM-DASH-01] Dashboard`.
    * **Nếu sai thông tin:** Giữ nguyên màn hình đăng nhập, xóa trắng trường mật khẩu và hiển thị cảnh báo đỏ theo BR-03.
 
 ---
 
-## 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 |
 | :--- | :--- | :--- | :--- |
-| **Story 1 (Đăng nhập)** | `[W-AD-AUTH-01]` | `Admin ->> W_Auth ->> Core: Xác thực` | Auth Service, User Table |
-| **Story 1 (Điều hướng)** | `[W-AD-DASH-01]` | `W_Auth -->> W_Dash: Mở Dashboard` | Router & Session Storage |
-| **Story 2 (Sai mật khẩu)** | `[W-AD-AUTH-01]` | `W_Auth -->> Admin: Báo lỗi` | Form State & Error Alert |
+| **Story 1 (Đăng nhập)** | `[W-ADM-AUTH-01]` | `Admin ->> W_Auth ->> Core: Xác thực` | Auth Service, User Table |
+| **Story 1 (Điều hướng)** | `[W-ADM-DASH-01]` | `W_Auth -->> W_Dash: Mở Dashboard` | Router & Session Storage |
+| **Story 2 (Sai mật khẩu)** | `[W-ADM-AUTH-01]` | `W_Auth -->> Admin: Báo lỗi` | Form State & Error Alert |
 
 ---
 
-## 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
     autonumber
     actor Admin as Quản trị viên
-    participant W_Auth as [W-AD-AUTH-01] Màn hình Đăng nhập
+    participant W_Auth as [W-ADM-AUTH-01] Màn hình Đăng nhập
     participant Core as Dịch vụ Xác thực (Auth Service)
     participant Storage as Cơ sở dữ liệu Người dùng
-    participant W_Dash as [W-AD-DASH-01] Bàn làm việc (Dashboard)
+    participant W_Dash as [W-ADM-DASH-01] Bàn làm việc (Dashboard)
 
     Admin->>W_Auth: 1. Mở trang đăng nhập
     Admin->>W_Auth: 2. Nhập tên tài khoản, mật khẩu & bấm "Đăng nhập"

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/04-solution-strategy/index.md

@@ -12,7 +12,7 @@ High-level approach: docs hub as arc42 TOC + C4 views; product Code under `CMP-*
 |-------|----------|
 | Docs structure | [ADR-001](../09-decisions/ADR-001-arc42-toc) — arc42 TOC over flat C4 folders |
 | Admin runtime | Admin Web + Admin API ([§07](../07-deployment/)) |
-| Auth entry | [CMP-01](/surfaces/CMP-01-auth/) · [FLOW-login](../06-runtime/journeys/FLOW-login) |
+| Auth entry | [CMP-ADM-AUTH-01](/surfaces/admin/CMP-ADM-AUTH-01/) · [FLOW-login](../03-user-flows/FLOW-login) |
 
 Further ADRs land in [§09](../09-decisions/).
 

package/templates/project-skeleton/architecture/08-cross-cutting/security.md

@@ -11,7 +11,7 @@ Authenticate admin operators and protect Admin API (session/token). Details evol
 
 ## Approach
 
-TBD — link ADR / CMP-01 / FLOW-login when expanded.
+TBD — link ADR / CMP-ADM-AUTH-01 / FLOW-login when expanded.
 
 ## Out of scope
 

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

@@ -9,8 +9,9 @@ status: active
 | `LND-*` | Landscape |
 | `DEP-*` | Deployment node |
 | `CTR-*` | Container |
-| `CMP-*` | Component (product) |
-| `W-*` / `API-*` | Screen / API Code |
+| `surfaceCode` | 2–4 letter token on `surfaces/*/index.md` — embedded in all product IDs on that channel |
+| `CMP-*` | Component (product) — folder name = id, pattern `CMP-{SURF}-{DOMAIN}-{NN}` |
+| `W-*` / `API-*` | Screen / API — `W-{SURF}-{DOMAIN}-{NN}` (globally unique) |
 | `FLOW-*` | Product journey (runtime) |
 | `DEP-*` | Deployment (optional) |
 | `ADR-*` | Architecture decision |
@@ -21,7 +22,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/architecture/model/workspace.dsl

@@ -1,7 +1,7 @@
 /*
  * Structurizr DSL — pilot skeleton (Phase B).
  * SSOT for prose/IDs remains MD under architecture/ + surfaces/ (see MODEL.md).
- * IDs mirror docs hub: admin, web, CMP-01.
+ * IDs mirror docs hub: admin, CMP-ADM-AUTH-01, W-ADM-AUTH-01.
  */
 workspace "base-docs platform" "arc42 × C4 pilot model" {
 
@@ -12,10 +12,10 @@ workspace "base-docs platform" "arc42 × C4 pilot model" {
 
         admin = softwareSystem "Admin Product" "Admin product boundary" {
             web = container "Admin Web" "Admin SPA / FE" "Nuxt/Next" {
-                auth = component "CMP-01 Auth" "Authentication module" "Vue/React"
+                auth = component "CMP-ADM-AUTH-01" "Authentication module" "Vue/React"
             }
             api = container "Admin API" "Admin HTTP API" "Nest/FastAPI" {
-                authApi = component "CMP-01 Auth API" "Auth endpoints" "Node"
+                authApi = component "API-ADM-AUTH-01" "Auth endpoints" "Node"
             }
             db = container "Admin DB" "Storage" "PostgreSQL" "Database"
         }
@@ -46,19 +46,19 @@ workspace "base-docs platform" "arc42 × C4 pilot model" {
             autoLayout tb
         }
 
-        component web "CMP-01-web" {
+        component web "CMP-ADM-AUTH-01-web" {
             include *
             autoLayout lr
         }
 
-        component api "CMP-01-api" {
+        component api "API-ADM-AUTH-01-api" {
             include *
             autoLayout lr
         }
 
         dynamic admin "FLOW-login" {
-            op -> web "Open login W-AD-AUTH-001"
-            web -> api "POST login API-AD-AUTH-001"
+            op -> web "Open login W-ADM-AUTH-01"
+            web -> api "POST login API-ADM-AUTH-01"
             api -> idp "Validate credentials"
             api -> web "session / token"
             web -> op "Authenticated shell"

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/surfaces/_module-index.template.md

@@ -0,0 +1,40 @@
+---
+id: CMP-ADM-DOMAIN-01
+title: "Module name"
+status: draft
+contentLocale: vi
+---
+
+# CMP-ADM-DOMAIN-01 — [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-…` |