@shanyucoder/flowgrid 0.1.10 → 0.1.12

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

@@ -1,16 +1,16 @@
 ---
 name: prototype
-description: /prototype — UI from FLOWGRID_DOCS_ROOT ir/design.yaml with mock API via bộ code.
+description: /prototype — UI from FLOWGRID_DOCS_ROOT ir/design.yaml with mock API via the FE code repo.
 disable-model-invocation: true
 ---
 
 # /prototype — UI Prototype (Mock API Boundary)
 
-**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs` | `dotnet-line`
+**Owner:** FE code repo (`--type=fe`) · Adapters: `nuxt4` | `nextjs` | `dotnet-line`
 
 ## Artifact & Target ID Resolution Rule
 
-- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-ADM-AUTH-01`, `login`).
 - Agent MUST use `--id` or resolve `surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml` via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (same leaf as the bundle; API trio is sibling `api/<seq>/`, not this file).
 - Shared UI (list shell, chips, delete flow, …) is **already in the FE base** — do not run `/gen-common` (deprecated).
 - `surfaces/…/common/` on the docs hub is **Markdown only** (`processes/FLOW-*.md`, `patterns/`) — read for context; never codegen from `common/yaml`.
@@ -18,11 +18,22 @@ disable-model-invocation: true
 
 ```text
 surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml
-# e.g. …/CMP-ADM-009/01/01/01/ir/design.yaml
+# e.g. …/CMP-ADM-DEMO-01/01/01/01/ir/design.yaml
 ```
 
 Read the **entire** `ir/design.yaml` (script + agent inspection). Do not filter keys from `*.bundle.yaml`. **`ir/spec.yaml`** is business prose only.
 
+## Agent context (ACP) before gen
+
+Per **`agent-design-context.md`** (resolve `W-*` via `flowgrid_docs_route` → `linkedFlows[]`):
+
+1. **`userFlows` / linked `FLOW-*.md`** — §6 sequence for journey context.
+2. **`bundle.nfr`** (from bundle or `ir/spec.yaml` mirror).
+3. **`ir/generated/design.md`** when `interactionCases.policy: required`.
+4. Then **`ir/design.yaml`**.
+
+Print checklist in chat: FLOW ids read · NFR · L2 design.md yes/no.
+
 **Docs hub is read-only for this skill.** Never Write/patch `*.bundle.yaml`, `ir/*`, or any file under `FLOWGRID_DOCS_ROOT`. Missing `ir/design.yaml`, empty `codegen.profile`, or `flowgrid gen` failure → **STOP**, quote the CLI error, hand off to docs-hub `/grill-dev` (or `/spec`). Do not invent SSOT to make gen pass. Login/forgot/reset must be `codegen.profile: auth` (not `create`) or gen writes `(dashboard)`.
 
 Do not invent sibling docs-hub paths. Pass `FLOWGRID_DOCS_ROOT` or `--docs-root`.
@@ -38,7 +49,7 @@ Do not invent sibling docs-hub paths. Pass `FLOWGRID_DOCS_ROOT` or `--docs-root`
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); IR/registry/gen →
+Architecture/C4 → docs hub (`FLOWGRID_DOCS_ROOT`); IR/registry/gen →
 `FLOWGRID_DOCS_ROOT`; symbols/call-graph for repo X → Platform DNA-wired
 `codegraph-<repo-key>`. Never workspace-parent graphs, sibling-path inference,
 or member-edited MCP. Local ArtifactGraph is allowlist/tag hints for this repo
@@ -47,12 +58,12 @@ only.
 ## Workflow
 
 ```bash
-npm run codegen:dry -- --id W-AD-AUTH-001
-npm run codegen -- --id W-AD-AUTH-001
+npm run codegen:dry -- --id W-ADM-AUTH-01
+npm run codegen -- --id W-ADM-AUTH-01
 
 # Fallback direct CLI if wrappers missing:
-flowgrid gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
-flowgrid gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
+flowgrid gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
 
 flowgrid gen:dry --adapter=nextjs -- --spec ir/design.yaml
 flowgrid gen --adapter=nextjs -- --spec ir/design.yaml
@@ -75,7 +86,7 @@ For each HANDOFF / `#needs-component: Mo…` after gen:
 4. Re-run `flowgrid gen` so slots bind to the new file.
 5. Dotnet-line / no `components.json`: skip this section; do not invent React/shadcn APIs.
 
-Do not copy the shadcn skill into bộ docs. Do not author `#ui:` tags from memory if `shadcn search` can name the registry item.
+Do not copy the shadcn skill into the docs hub. Do not author `#ui:` tags from memory if `shadcn search` can name the registry item.
 
 `dotnet-line` requires the .NET 8 SDK (`FLOWGRID_DOTNET`, then `dotnet`) and
 is limited to the pilot-specific `kiosk-check-in` profile. Its main pass also
@@ -88,14 +99,15 @@ if local ArtifactGraph available: recommend/check the FE repo's allowlisted gen
 else: run flowgrid gen:dry / gen directly
 
 Missing ArtifactGraph never blocks prototype generation. Complete the direct,
-deterministic bộ code fallback first, then follow
+deterministic FE-repo fallback first, then follow
 `.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.
 ```
 
-Docs render / `spec:split` remain flowgrid / bộ docs handoffs.
+Docs render / `spec:split` remain flowgrid / docs-hub handoffs.
 
 ## Translation Rule
-Luôn bọc text tĩnh bằng i18n helper native của framework. 
-- Đọc block `i18n` từ `ir/design.yaml`.
-- Tự động sinh/cập nhật file ngôn ngữ tương ứng (`.json` cho FE/NodeJS, hoặc `.resx` cho Dotnet). 
-- KHÔNG viết gộp ngôn ngữ lên giao diện (ví dụ không dùng `login / đăng nhập`).
+
+- Wrap all static UI copy with the framework’s native i18n helper.
+- Read the `i18n` block from `ir/design.yaml`.
+- Generate or update locale files (`.json` for FE/Node, `.resx` for dotnet-line).
+- Do **not** hard-code mixed languages in UI (e.g. avoid `login / đăng nhập` in one string).

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

@@ -9,12 +9,12 @@ disable-model-invocation: true
 **Owner:** bộ code (`--type=fe`)
 
 ```bash
-npm run codegen:unit:dry -- --id W-AD-AUTH-001
-npm run codegen:unit -- --id W-AD-AUTH-001
+npm run codegen:unit:dry -- --id W-ADM-AUTH-01
+npm run codegen:unit -- --id W-ADM-AUTH-01
 
 # Fallback direct CLI if wrappers missing:
-flowgrid unit-gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
-flowgrid unit-gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid unit-gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
+flowgrid unit-gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
 flowgrid unit-registry --adapter=nuxt4
 ```
 

package/harness/shared/SSOT_AGENT_PROTOCOL.md

@@ -4,7 +4,7 @@
 > These are **PHYSICAL INTERLOCKS**, not casual reminders.
 > Any violation of these laws → run **FAILED**. Chat-only "done" = **STRICTLY REJECTED**.
 >
-> Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).
+> Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). Product IDs: `product-id-convention.md` (`surfaceCode`, `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`).
 
 ---
 

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

@@ -21,7 +21,7 @@ query a workspace-parent graph.
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a screen ID, module ID, or short slug (e.g. `W-AD-AUTH-001`, `CMP-ADM-000`, `login`).
+- User prompt MAY specify a screen ID, module ID, or short slug (e.g. `W-ADM-AUTH-01`, `CMP-ADM-AUTH-01`, `login`).
 - **[MANDATORY]** Agent MUST use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob search under `FLOWGRID_DOCS_ROOT` / `surfaces/...`) to resolve target paths.
 - **[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.

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

@@ -49,8 +49,8 @@ Mirror the FLOW file path onto the tests hub. Strip **only** these prefixes:
 
 Examples:
 
-- 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`
+- Docs `surfaces/admin/CMP-ADM-ORD-01/02/common/user-flows/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-ORD-01/02/common/user-flows/FLOW-checkout/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-ORD-01/common/user-flows/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-ORD-01/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

@@ -49,7 +49,7 @@ disable-model-invocation: true
 ## Rule: Directory Mirroring (Docs SSOT)
 
 - **[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`
+  - ✅ `surfaces/admin/CMP-ADM-ORD-01/02/01/login/` → `cases/admin/CMP-ADM-ORD-01/02/01/login/TC-*.yaml`
   - ❌ `cases/admin/auth/W-…` — invented path not matching docs structure.
 - Cross-flow plans → `/scenario` (mirror `common/user-flows/FLOW-*` or `architecture/03-user-flows/FLOW-*`).
 

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,15 +17,15 @@ 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`).
 
 | Attribute | Value |
 | --- | --- |
 | **Scenario ID** | `SC-EXAMPLE` |
-| **Module** | `CMP-01-auth` |
+| **Module** | `CMP-ADM-AUTH-01` |
 | **Surface** | `admin` |
-| **Screen** | `W-AD-AUTH-001` (`/admin/records/create`) |
+| **Screen** | `W-ADM-AUTH-01` (`/admin/records/create`) |
 | **Priority** | `High` |
 
 ## 1. Business context & risk analysis
@@ -79,8 +79,8 @@ stateDiagram-v2
 
 | 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/` |
-| `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/` |
+| `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/package.json

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

package/templates/project-skeleton/architecture/03-user-flows/FLOW-login.md

@@ -18,7 +18,7 @@ status: "approved"
 * **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]` |
 
 ---
 
@@ -26,8 +26,8 @@ status: "approved"
 
 ### 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,  
@@ -55,11 +55,11 @@ status: "approved"
 
 ## 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.
 
 ---
@@ -68,9 +68,9 @@ status: "approved"
 
 | 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 |
 
 ---
 
@@ -80,10 +80,10 @@ status: "approved"
 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/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/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 |

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

@@ -1,11 +1,11 @@
 ---
-id: CMP-NN-slug
+id: CMP-ADM-DOMAIN-01
 title: "Module name"
 status: draft
 contentLocale: vi
 ---
 
-# CMP-{NN} — [Name]
+# CMP-ADM-DOMAIN-01 — [Name]
 
 > Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
 

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

@@ -1,5 +1,6 @@
 ---
 id: SURFACE-TEMPLATE
+surfaceCode: ADM
 title: "Surface channel name"
 status: draft
 contentLocale: vi

package/templates/shared/bundle-authoring.md

@@ -10,7 +10,8 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 | `summary` | Phải trình bày dạng bullet. Bắt buộc có các tiêu đề (chuẩn Arc42 business): **mục tiêu nghiệp vụ** (business_goals), **các bên liên quan** (stakeholders), **kịch bản người dùng** (user_journey), **bối cảnh** (description, input liên kết cross-page/module, output) và **cách giải quyết** (tùy chọn). Mục đích để 100% Non-tech Stakeholder hiểu và duyệt. |
 | `scopeIn` | **Khuyến nghị** — trong phạm vi màn/phase (PRD). Audit `WARN_NO_SCOPE_IN`. |
 | `nonGoals` | **Khuyến nghị** — ngoài phạm vi màn/phase (PRD). Audit `WARN_NO_NON_GOALS`. |
-| `userFlows` | **Khuyến nghị** — link `FLOW-*` (`03-user-flows` / `common/user-flows`) hoặc journey ngắn. Audit `WARN_NO_USER_FLOWS` khi multi-screen. |
+| `userFlows` | **Recommended** — `FLOW-* — role: … — screens: W-* (this leaf)`; agents read linked `FLOW-*.md` §6 before codegen (`agent-design-context.md`). |
+| `interactionCases` | **Optional L2** — `policy` + `items[]` (`IC-*`, `description`, `sequenceDiagram`); split → `spec.md` + `ir/generated/design.md`. Audit `CONFIRM_INTERACTION_CASES_POLICY`. |
 | `nfr` | **Khuyến nghị** — hiệu năng, bảo mật. Audit `WARN_NO_NFR`. |
 | _(rủi ro)_ | **Không** khai báo trên bundle. SSOT: `architecture/11-risks/risk-register.md` — `/risk-register`. Key `risks:` → audit `WARN_BUNDLE_RISKS_FORBIDDEN`. |
 | `userStories` | **Khối User Stories chuyên sâu cho màn hình:** `primary`, `contextAndHandoff` (+ `screenAccess`), `scenarios` (5 kịch bản chuẩn + **scenario thứ 6 “Affordances UX”** khi màn có delete/filter/breadcrumb/disabled/import — xem `feature.bundle.yaml`), `acceptanceCriteria` (kèm checkbox UX khi áp dụng). **Split:** `pnpm spec:split` copy nguyên khối sang `ir/spec.yaml` (business prose); **không** tự sinh từ `design` — Agent phải cập nhật `userStories` khi bổ sung DSL/`#needs-component`/audit `UX_*`. Render → `## User Stories & Screen Journey` trong Markdown. |
@@ -288,7 +289,7 @@ actions:
     trigger: button_click
     apiRefs: [ feature.create ]
     # tags: ["#reuse-api"]
-    # reuseFrom: surfaces/admin/CMP-01/auth/01/01/01/api/01/01-backend-spec.yaml
+    # reuseFrom: surfaces/admin/CMP-ADM-AUTH-01/01/01/01/api/01/01-backend-spec.yaml
     onSuccess:
       - Navigate to list page
       - Show success toast "Created successfully"

package/templates/shared/default-layout.ejs

@@ -7,6 +7,13 @@
   const hasStories = !!spec.userStories;
   const hasNfr = spec.nfr && String(spec.nfr).trim();
   const hasUserFlows = spec.userFlows && String(spec.userFlows).trim();
+  const icBlock = spec.interactionCases;
+  const icItems = icBlock && Array.isArray(icBlock.items) ? icBlock.items : [];
+  const hasInteractionCases =
+    icBlock &&
+    (icBlock.policy === 'skip' ||
+      icItems.length > 0 ||
+      (icBlock.policy === 'required' && icItems.length === 0));
   const qaOpen = spec['Q&A'] && String(spec['Q&A']).trim();
   const hasEntities = spec.entities && (Array.isArray(spec.entities) ? spec.entities.length : true);
   const pageSections = spec.sections || spec.design?.sections || [];
@@ -34,8 +41,9 @@
   if (hasNonGoals) addToc('Out of scope', 'scope-out');
   if (hasStories) addToc('User stories & requirements', 'user-stories--screen-journey');
   addToc('Data & integrations / API', 'data-integrations');
-  if (hasUserFlows) addToc('User flows', 'user-flows');
+  if (hasUserFlows) addToc('Linked user flows (FLOW)', 'user-flows');
   if (hasNfr) addToc('Non-functional (NFR)', 'nfr');
+  if (hasInteractionCases) addToc('Interaction cases', 'interaction-cases');
   if (hasState) addToc('State & permissions matrix', 'state--permission-matrix');
   if (hasListColumns) addToc('List columns', 'list-columns');
   if (hasListExtras) addToc('Filters & pagination', 'list-filters-pagination');
@@ -213,7 +221,11 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 <% } %>
 
 <% if (hasUserFlows) { %>
-## User flows {#user-flows}
+## Linked user flows (FLOW) {#user-flows}
+
+Use product journey docs (`FLOW-*.md`) — include §6 sequence. Convention per line:
+
+`FLOW-<id> — role: entry|step-N-*|exit — screens: W-* … (this leaf)`
 
 <%= spec.userFlows %>
 
@@ -226,6 +238,39 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 
 <% } %>
 
+<% if (hasInteractionCases) { %>
+## Interaction cases {#interaction-cases}
+
+<% if (icBlock.policy === 'skip') { %>
+_Screen interaction sequences skipped:_ <%= icBlock.skipReason || '(no reason given)' %>
+
+<% } else { %>
+> Sequence diagrams: [design.md](./design.md) (generated). Authoring: `interactionCases` on `*.bundle.yaml`.
+
+<% for (const item of icItems) { %>
+### <%= item.id || 'IC-?' %> {#<%= String(item.id || 'ic').toLowerCase() %>}
+
+<% if (item.title) { %>**<%= item.title %>**
+
+<% } %>
+<% if (item.description) { %>
+<%= item.description %>
+
+<% } %>
+<% if (item.links && typeof item.links === 'object') { %>
+| Link | Value |
+| --- | --- |
+<% for (const [k, v] of Object.entries(item.links)) { %>
+| `<%= k %>` | <%= v %> |
+<% } %>
+
+<% } %>
+[View sequence diagram](./design.md#<%= String(item.id || 'ic').toLowerCase() %>)
+
+<% } %>
+<% } %>
+<% } %>
+
 <%
   const page = {
     nav: spec.nav || spec.design?.nav,

package/templates/shared/feature.bundle.yaml

@@ -26,7 +26,35 @@ nonGoals: |
   - [VD: không export Excel tại màn list — defer QA/debt]
 
 userFlows: |
-  - [Luồng người dùng — link FLOW-* trong architecture/03-user-flows hoặc common/user-flows]
+  - FLOW-checkout — role: step-3-ops — screens: W-ADM-ORD-01 (this leaf)
+  # Journey SSOT: FLOW-*.md (§6 sequenceDiagram) — read via userFlows before codegen
+
+# Optional — màn nhiều state / case trên một W-* (L2). Không thay FLOW-*.md.
+# interactionCases:
+#   policy: required
+#   items:
+#     - id: IC-SUBMIT-HAPPY
+#       title: "Lưu từ DRAFT"
+#       description: |
+#         User bấm Lưu; form hợp lệ; chuyển trạng thái.
+#       links:
+#         actionId: btn_save_record
+#         recordStatus: DRAFT
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           actor U as User
+#           participant W as [W-ADM-ORD-01]
+#           U->>W: Submit
+#     - id: IC-SUBMIT-409
+#       title: "Conflict"
+#       description: |
+#         Optimistic lock conflict — giữ form, reload.
+#       links:
+#         actionId: btn_save_record
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           U->>W: Submit
+#           W-->>U: 409 message
 
 nfr: |
   - **Hiệu năng:** [VD: danh sách < 2s với 10k bản ghi — phân trang server]

package/templates/shared/tpl-runtime-sequence.md

@@ -0,0 +1,56 @@
+---
+page-id: W-XXX-DOMAIN-01
+title: "Runtime sequence — <feature title>"
+status: draft
+---
+
+# Runtime sequence — `<page-id>`
+
+> SSOT for **tech review** (BE/FE). Journey context: link `FLOW-*` from bundle `userFlows`.  
+> Authoring: `ir/runtime-sequence.md` or `api/<seq>/02-runtime-sequence.md` — not this generated copy.
+
+## Scope
+
+- **In this diagram:** …
+- **Out of scope:** …
+
+## Preconditions & state
+
+| State / gate | Rule |
+| --- | --- |
+| e.g. `DRAFT` | User may edit until submit |
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as User
+    participant W as [W-XXX-DOMAIN-01]
+    participant API as [API-XXX-DOMAIN-01]
+    participant Svc as DomainService
+    participant DB as Database
+
+    U->>W: Open screen
+    W->>API: Load (GET …)
+    API->>Svc: fetch
+    Svc->>DB: query
+    DB-->>Svc: rows
+    Svc-->>API: DTO
+    API-->>W: 200 + body
+    W-->>U: Render
+
+    alt Validation error
+        API-->>W: 422 field errors
+        W-->>U: Inline messages
+    else Conflict
+        API-->>W: 409
+        W-->>U: Toast + stay
+    end
+```
+
+## Traceability
+
+| Step | Endpoint / action | Tables / events |
+| --- | --- | --- |
+| 1 | `endpoints[].id` … | … |

package/templates/tests-skeleton/cases/README.md

@@ -2,7 +2,7 @@
 
 Đặt `TC-*.yaml` mirror path function trên docs-hub (bỏ prefix `surfaces/`).
 
-Ví dụ docs: `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
+Ví dụ docs: `surfaces/admin/CMP-ADM-ORD-01/02/01/login/` → `cases/admin/CMP-ADM-ORD-01/02/01/login/TC-*.yaml`
 
 - SSOT ghi: `TC-*.yaml` (`schemaVersion: 2`) — copy mẫu từ `../_templates/TC.example.yaml` (init từ harness).
 - SSOT đọc QA/Dev: `pnpm cases:render` → `TC-*.md` cùng thư mục — **không sửa tay** MD.