@shanyucoder/flowgrid 0.1.0

package/templates/shared/breadcrumb-flow.ejs

@@ -0,0 +1,45 @@
+# [Flow] <%= spec.title || spec.id %>
+
+<% if (context.testcases && context.testcases.length) { %>
+- **Testcase plans:** <%= context.testcases.map(tc => '`' + (tc.data.title || tc.data.id || tc.file) + '`').join(' · ') %> (hub: [base_test](https://github.com/raintr91/base_test))
+<% } else { %>
+- **Testcase plans:** [base_test](https://github.com/raintr91/base_test) (`pnpm cases:render` on tests hub) — see docs-hub TESTS-HUB
+<% } %>
+
+<% 
+  const route = spec.ui?.routes?.[0];
+  const path = route?.path || '';
+  const testId = route?.pageTestId || '';
+  let screenLine = '- **Screen:** None';
+  if (path) {
+    const screen = context.renderScreenLink ? context.renderScreenLink(path) : '`' + path + '`';
+    const suffix = testId ? ` · \`${testId}\`` : '';
+    screenLine = `- **Screen:** ${screen}${suffix}`;
+  }
+%>
+<%= screenLine %>
+
+> [!NOTE]
+> This document was rendered using the specialized **breadcrumb-flow** template.
+
+<% if (spec.summary) { %>
+<%= spec.summary %>
+<% } %>
+
+<% 
+  // Render other spec sections
+  const skipKeys = new Set(['id', 'title', 'summary', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template']);
+  Object.entries(spec).forEach(([key, value]) => {
+    if (skipKeys.has(key) || value == null) return;
+%>
+## <%= key %>
+
+<% if (typeof value === 'string') { %>
+<%= value %>
+<% } else { %>
+```yaml
+<%= context.stringify(value).trim() %>
+```
+<% } %>
+
+<% }); %>

package/templates/shared/bundle-authoring.md

@@ -0,0 +1,288 @@
+# portal-feature-bundle/v1 — authoring rules (PHASE 1)
+
+Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
+
+## Top-level
+
+| Key | Purpose |
+|-----|---------|
+| `page-id` | Screen identity (`cmp-adm-000-01`). Split copies this onto `ir/spec.yaml` as `page-id` (not `id`, so it does not collide with requirement/section ids). Legacy bundles may still use `id`. |
+| `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. |
+| `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. |
+| `spec` | Design v1 — actors, requirements, `ui.routes`, **`ui.list` / `ui.form` / `ui.detail`**, `acceptance`. **Không** author `spec.api` — API SSOT là `api/<seq>/01-backend-spec.yaml`. |
+| `gen` | **Bắt buộc trước flowgrid gen:** `codegen.profile` (`auth` login/forgot/reset; `change-password`; `public`; `not-found`/`error`; `list`/`create`/`admin-crud`) + entity/module, `tags`, derived `ui.*`. `/grill-dev` ghi. Endpoint `action` ghi trên **01**, không trên bundle. |
+| `legacy` | Legacy facts + evidence pointers |
+| `design` | Nested **`sections[]`** (card/container/form + `meaning` + `purpose` + `visual` + `interaction` + `validation` + `messages` + `states` + `bind`/`db`) · **`nav`** (`screenAccess` & `sidebar.hierarchy`) · `zones[]` fallback · `behavior` · **`actions[]`** (onSuccess, onSpecificError, backgroundTrigger) |
+| `review` | BA prose only — **không** split sang `ir/*` |
+
+## /spec authoring (complete when information exists)
+
+- Fill `userStories` chi tiết theo mẫu trong `feature.bundle.yaml`. Tuyệt đối không để trống hoặc chỉ ghi 1 câu qua loa.
+- **Quy tắc Khai báo Cách thức Truy cập Màn hình (screenAccess BẮT BUỘC):** Phải chọn đúng 1 trong 3 loại:
+  - `directRoute`: Dành cho trang truy cập trực tiếp bằng URL (Login, Register, Guest Page, Public Landing, 404). Khai báo `routePath`, `isPublic`.
+  - `sidebarMenu`: Dành cho Dashboard, Danh sách Admin CRUD. Khai báo `menuHierarchy` (mảng danh mục dropdown đa cấp `["Group", "Subgroup"]`), `menuLabel` (text nhãn menu), `icon`.
+  - `contextualAction`: Dành cho Trang chi tiết, Edit Modal, Settings. Khai báo `sourceScreen`, `triggerControl` (mô tả nút bấm kích hoạt từ màn hình A), `navigationType` (`pageRedirect`, `modalDialog`, `drawer`, `tabSwitch`).
+- **Quy tắc Meaning vs Purpose BẮT BUỘC:** Trên từng element (section, item, column, filter, action), BẮT BUỘC khai báo cả 2 trường:
+  - `meaning`: **Ý nghĩa nghiệp vụ** — Bản chất kinh doanh của trường dữ liệu/nút bấm trong thế giới thực, ảnh hưởng đến luồng tính toán hay quyết định nào.
+  - `purpose`: **Mục đích thao tác** — Người dùng thao tác gì với control này trên UI (nhập, tìm kiếm, bấm, xem).
+- **Thẩm định dữ liệu (Validation & Messages):** Mọi trường có `validation` (required, min/max, pattern, accept) PHẢI đi kèm trường `messages` chứa câu thông báo lỗi tiếng Việt tương ứng.
+- **Hành động & Tương tác (Actions):** Nút bấm nộp/lưu phải có đầy đủ: `validateFormBeforeSubmit`, `feedback` (loadingText, disableWhileSubmitting), `apiRefs`, `onSuccess` (toast, navigation handoff, backgroundTrigger), `onSpecificError` (map lỗi 422, 409 conflict, 403), `onCommonError`.
+- Fill `design.sections[]` as a **dynamic nested tree** for that page (any depth). Same node shape everywhere: `kind` + `meaning` + `purpose` + `visual` + `tags`/`extract` + `items[]` + nested `sections[]`. Do not assume login or any one layout.
+- When the page has app chrome: `design.nav.sidebar.levels` (đa cấp) + `design.nav.breadcrumb`. Full-bleed pages: `sidebar.enabled: false`.
+- Flat `design.zones[]` is only a fallback if there is no nested card tree.
+- Fill the matching profile: list → `spec.ui.list`; form → `spec.ui.form` (do not merge form into the page shell); detail → `spec.ui.detail`.
+- Do **not** dump the screen into `requirements` prose instead of inventory.
+- **UI Metrics Policy:** DO NOT declare basic CSS properties (e.g., `font-size`, `padding`, exact colors) in feature specs. These are governed by the global Design System (e.g., Shadcn/Tailwind). Only declare them if the feature requires a specific, exceptional override.
+- Missing hard facts → `#missing_info` on that field. Do not wait for grill to invent inventory.
+- `/grill-bqa`, `/grill-dev`, `/grill-docs` only re-check, fill gaps, or fix conflicts.
+
+## spec (design v1) — có
+
+- `actors`, `entities`, `relationships`
+- `requirements` (BẮT BUỘC chứa Edge Cases. CHÚ Ý: Field Validations, State Machine, UI Permissions phải được map vào từng item trong `design.sections`, KHÔNG liệt kê chung chung ở đây)
+- `ui.routes`, `ui.list`, `ui.form`, `ui.detail`, `ui.toolbar` (intent)
+- `acceptance`
+
+API: **chỉ** `…/api/<seq>/01-backend-spec.yaml` (`/api-spec`). Split **chiếu** `api.endpoints` (id/method/path/action) sang `ir/design.yaml` cho FE/bộ test — không author trên bundle.
+
+## spec — không (thuộc `gen`)
+
+- `codegen`, `tags`
+- root `ui.filters`, `ui.columns`, `ui.composition`, `ui.testIds` (derive after inventory exists)
+- Prose layout blob — dùng `design.sections[]` (nested) + `design.nav` + `review.layoutNotes`
+
+## Split output
+
+Split exists so agents **Read the entire `ir/design.yaml`** (tech) or **entire `ir/spec.yaml`** (prose). Do **not** instruct “only Read `design.sections` / `spec.ui` from the bundle” — that misses fields and is why IR is split.
+
+Authoring (`/spec`, grill-*) still **writes** `*.bundle.yaml`, then split.
+
+### UX affordance ↔ `userStories` (before `pnpm spec:split`)
+
+| Design / audit signal | Business layer (`userStories` → `ir/spec.yaml`) |
+|----------------------|--------------------------------------------------|
+| `design.nav.breadcrumb`, `CONFIRM_UX_BREADCRUMB_*` | Scenario **Initial Load** + scenario **Affordances UX**; AC deep link |
+| `spec.ui.list.filters`, `CONFIRM_UX_FILTER_*` | Scenario **Initial Load** / **Affordances UX**; AC empty “no results” |
+| `#pattern: delete-flow`, `UX_GAP_DELETE_*` | Scenario **Affordances UX** + **Exceptions**; AC delete confirm + result dialog |
+| `disabledReason`, `UX_GAP_DISABLED_REASON` | Scenario **Affordances UX**; AC disabled explanation |
+| Status column + chip, `CONFIRM_UX_STATUS_CHIP` | Scenario **Initial Load**; AC status readable |
+| `#needs-component` / `#needs-ui` | `primary.iWant` or scenario step naming the custom block in Vietnamese |
+| `flowgrid audit spec` `suggestedStoryPatch` on UX items | Apply verbatim to matching scenario step or AC |
+
+**Không** chỉ ghi tech vào `design.actions` — stakeholder đọc `ir/spec.yaml` / rendered MD phải thấy cùng hành vi.
+
+| Artifact | Đọc bởi | Nội dung |
+|----------|---------|----------|
+| `*.bundle.yaml` | **Ghi** `/spec`, grill-*; **đọc cả file** `/testcase`, `/grill-testcase` | Đầy đủ spec+gen+design+`userStories`; tests hub read-only |
+| `ir/design.yaml` | **Đọc cả file** — grill-*, FE `/prototype`, codegen | Tech sau split; `api` chiếu từ 01. |
+| `ir/spec.yaml` | VitePress + stakeholder | Business page + requirements/acceptance. Không id/tag/bind. `"Q&A"`. Không stub `legacy` rỗng. |
+| `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi:gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
+| `<slug>.md` | Người (BA/QA) | Render từ **`ir/spec.yaml`** (chưa split thì không có trang) |
+
+Không còn `ir/legacy.yaml`. `legacy:` trên `ir/spec.yaml` chỉ khi có evidence thật.
+
+Thiếu fact → `#missing_info` trên field đó. Grill không bịa CSS/API.
+
+## design.nav + nested sections (dynamic)
+
+Cùng một schema cho mọi page. Agent điền cây theo màn thực tế — không dùng một màn (login, list, …) làm mặc định.
+
+```yaml
+nav:
+  sidebar:
+    enabled: true   # false nếu không có menu trái
+    position: left
+    levels: []      # { id, label, href, active, children[] } lồng đa cấp
+  breadcrumb: []    # { label, href }
+
+**LƯU Ý ĐẶC BIỆT VỀ ĐA NGÔN NGỮ (i18n):**
+1. **Text hiển thị UI (cần i18n)**: Các thuộc tính như `label`, `value`, `copy.placeholder`, text của component lib... BẮT BUỘC dùng cho i18n (sẽ được map với file ngôn ngữ). Áp dụng cho các component lá như `input`, `text`, `button`, v.v.
+2. **Text ngữ cảnh (không i18n)**: Các thuộc tính giải thích/cấu trúc như `name`, `description`, `purpose` chỉ dùng cho BA/Dev, KHÔNG dùng để render UI, KHÔNG mang đi dịch. Tùy thuộc vào `kind` mà khai báo cho đúng bản chất, **tuyệt đối không dùng `label` để mô tả một node ẩn (như container)**.
+   - **BA**: `name`, `description`, `purpose`, `copy`, `position`, `color`, `visual` (width/height/max-*/scroll), `interaction`, `validation` (mặt UI), `db` (thông tin lưu trữ schema, field, enumMapping)
+   - **Tech**: `kind`/`widget`, `tags`, `extract`, `bind` (field/hidden/apiRef), `apiRefs`, `hidden`, `testId`, `states`
+
+```yaml
+sections:
+  # LOẠI 1: KHỐI STATS BANNER / HEADER KPI CARD (#ui: Card, #ui: Badge)
+  - id: sec_kpi_banner
+    name: "Khối Thống Kê Tổng Quan"
+    kind: card
+    primitive: "#ui: Card" # Gắn tag primitive Shadcn UI
+    meaning: "Cung cấp chỉ số hiệu suất tổng quan của tài khoản giúp nhân viên đưa ra quyết định xử lý nhanh"
+    purpose: "Hiển thị các thẻ KPI thống kê tổng số bản ghi và trạng thái"
+    visual:
+      colorToken: "#common:card-surface"
+      className: "grid grid-cols-1 md:grid-cols-3 gap-4 p-6 bg-card border rounded-xl shadow-xs"
+      typography: "text-card-foreground"
+    dynamicProps:
+      layoutMode: "responsive-grid"
+      columns: 3
+    items:
+      - id: kpi_total_records
+        kind: badge
+        primitive: "#ui: Badge"
+        label: "Tổng hồ sơ"
+        meaning: "Số lượng bản ghi đang quản lý trong hệ thống"
+        purpose: "Theo dõi số lượng hồ sơ hiện có"
+        colorToken: "#common:primary"
+        visual:
+          className: "text-2xl font-bold tracking-tight text-primary"
+
+  # LOẠI 2: KHỐI FORM NHẬP LIỆU ĐỘNG (#ui: Form, #ui: Select, #ui: Input)
+  - id: sec_main_info
+    name: "Khối Thông Tin Nhập Liệu Hồ Sơ"
+    kind: form_grid
+    primitive: "#ui: Form"
+    meaning: "Gom nhóm các thuộc tính nhận diện cốt lõi của bản ghi phục vụ tra cứu và kiểm toán"
+    purpose: "Khu vực nhập liệu thông tin chính của hồ sơ"
+    visual:
+      className: "space-y-6 border p-6 rounded-xl bg-background shadow-xs"
+      layoutMode: "two-column"
+    dynamicProps:
+      responsiveGrid: "grid grid-cols-1 lg:grid-cols-2 gap-6"
+    sections:
+      # Component nhập liệu có validation & messages & styling
+      - id: fld_record_name
+        name: "Record Name Field"
+        kind: input
+        primitive: "#ui: Input"
+        label: "Tên hồ sơ"
+        meaning: "Tên định danh giao dịch của khách hàng dùng làm tiêu đề hiển thị trên mọi báo cáo"
+        purpose: "Nhập tên hồ sơ hiển thị"
+        visual:
+          className: "w-full focus:ring-2 focus:ring-ring"
+        copy:
+          placeholder: "Nhập tên đầy đủ..."
+          helper: "Tối thiểu 3 ký tự, không chứa ký tự đặc biệt"
+        bind:
+          field: record_name
+        db:
+          schema: records
+          field: name
+        validation:
+          required: true
+          minLength: 3
+          maxLength: 100
+        messages:
+          required: "Vui lòng nhập tên hồ sơ."
+          minLength: "Tên hồ sơ phải có ít nhất 3 ký tự."
+
+      # Component chọn có điều kiện động (Dropdown + States)
+      - id: fld_service_level
+        name: "Service Level Select"
+        kind: select
+        primitive: "#ui: Select"
+        label: "Cấp độ dịch vụ"
+        meaning: "Xác định gói dịch vụ để áp dụng chính sách giá và kích hoạt tự động Zalo VIP"
+        purpose: "Chọn gói dịch vụ áp dụng"
+        visual:
+          className: "w-full border-input"
+        bind:
+          field: service_level
+        db:
+          schema: records
+          field: service_level
+          enumMapping:
+            "STANDARD": "Tiêu chuẩn"
+            "PREMIUM": "Cao cấp VIP"
+        validation:
+          required: true
+        messages:
+          required: "Vui lòng chọn cấp độ dịch vụ."
+
+      # Component hiển thị động theo trạng thái
+      - id: fld_vip_request
+        name: "VIP Special Request"
+        kind: textarea
+        primitive: "#ui: Textarea"
+        label: "Yêu cầu đặc biệt cho gói VIP"
+        meaning: "Chi tiết yêu cầu cá nhân hóa bổ sung"
+        purpose: "Nhập ghi chú yêu cầu riêng cho gói dịch vụ VIP"
+        visual:
+          className: "col-span-full border-muted bg-muted/20"
+        states:
+          visibleWhen: "service_level == 'PREMIUM'"
+```
+
+Minh họa lồng (không phải template cố định): container → card → form, hoặc sidebar → toolbar → table.
+
+## design.zones (flat fallback)
+
+```yaml
+zones:
+  - id: search
+    label: Khu vực tìm kiếm
+    kind: container
+    items:
+      - id: keyword
+        kind: search
+        widget: search
+        label: Ô tìm kiếm
+        purpose: "User tìm bản ghi theo tên hoặc mã"
+        copy:
+          placeholder: Search by name or code
+        bind: { field: keyword }
+```
+
+## design.behavior (CRUD table trong md render)
+
+```yaml
+behavior:
+  create: { enabled: true, surface: page }
+  delete: { enabled: true, mode: confirm_dialog }
+```
+
+## design.actions (API calls + UI error handling)
+
+Không còn `bundle.spec.api`. Màn gọi API nào = `design.actions` (và button/item trong `sections`/`zones`) trên **`ir/design.yaml`** sau split.
+
+- Unique API của màn: `apiRefs` (sau `/api-spec` ghi trio `api/<seq>/`).
+- API đã có (màn khác / common): `tags: ["#reuse-api"]` + `reuseFrom: …/01-backend-spec.yaml`. **Không** tạo trio mới.
+
+```yaml
+actions:
+  - id: submit_form
+    label: Submit Form
+    purpose: "Lưu form và báo kết quả cho user"
+    variant: primary
+    position: form_footer
+    trigger: button_click
+    apiRefs: [ feature.create ]
+    # tags: ["#reuse-api"]
+    # reuseFrom: surfaces/admin/CMP-01/auth/01/01/01/api/01/01-backend-spec.yaml
+    onSuccess:
+      - Navigate to list page
+      - Show success toast "Created successfully"
+    onCommonError:
+      override: false
+      notes: "Inherit #ui-common:error-handler (Global toast 500/401)"
+    onSpecificError:
+      - condition: "422 Validation"
+        notes: "Show inline field errors below inputs"
+      - condition: "403 IDOR"
+        notes: "Redirect to safety page, show warning"
+```
+
+## Agent output (/spec)
+
+YAML only per schema. No explanation. No markdown.
+
+## Questions: AskQuestion wizard or hub `qa/open/`
+
+Do **not** write `openQuestions` anywhere. Schema/render không còn field này.
+
+- Member trả lời **ngay:** AskQuestion (options + Recommended + **Other**) → **STOP** → ghi field thật.
+- Member chọn **Other** mà **chưa quyết:** `.cursor/extracts/qa-inbox.md` → `qa/open/QA-<bundle.id>-NNNN.yaml`. Đóng sau bằng **`/qa-resolve <id>` + giải pháp**.
+- `grillStatus` có thể `done` khi vẫn còn file QA.
+
+## YAML Syntax & Escaping Rules
+
+- **ALWAYS quote colons in strings:** Any string containing `:` (e.g., `summary: "Case 1: Token..."`, `label: "Hàng nút: [Secondary]"`) MUST be wrapped in double quotes `"..."`.
+- **Multiline text:** Use `|` block scalar for multiline strings or list items containing formatting symbols.
+
+## ir/spec.yaml vs ir/design.yaml
+
+`pnpm spec:split` ghi hai file. FlowGrid bộ docs grill **không** đọc `ir/*` khi author — chỉ bundle. Split ghi `"Q&A":` trên **`ir/spec.yaml`** (id `QA-<bundle.id>-NNNN` cách nhau bởi `, `) từ `qa/open/` — không nhét list vào bundle.
+
+Downstream (UI gen, API gen, testcase) đọc **chỉ `ir/design.yaml`**. Thiếu file = split/spec chưa xong. Story/copy chưa đủ thì **bổ sung design** (bundle.gen + split), không đọc `ir/spec.yaml`. `ir/spec.yaml` chỉ văn mô tả + `legacy` + `qa` (id treo).
+

package/templates/shared/clients-line.yaml

@@ -0,0 +1,18 @@
+# clients.line — append to ir/spec.yaml when feature has shop-floor UI
+
+clients:
+  line:
+    profile: kiosk   # kiosk | tablet
+    screens:
+      - id: check-in
+        route: workforce/check-in
+        automationIds:
+          page: {module}-page
+          submit-btn: {module}-submit-btn
+    devices:
+      - badgeReader
+    api:
+      endpoints:
+        checkIn:
+          method: POST
+          path: /workforce/check-in

package/templates/shared/default-layout.ejs

@@ -0,0 +1,234 @@
+# <%= spec.title || spec.id %>
+
+<% if (context.testcases && context.testcases.length) { %>
+- **Testcase plans:** <%= context.testcases.map(tc => '`' + (tc.data.title || tc.data.id || tc.file) + '`').join(' · ') %> (hub: [base_test](https://github.com/raintr91/base_test))
+<% } else { %>
+- **Testcase plans:** [base_test](https://github.com/raintr91/base_test) (`pnpm cases:render` on tests hub) — see docs-hub TESTS-HUB
+<% } %>
+
+<% 
+  const route = spec.ui?.routes?.[0];
+  const path = route?.path || '';
+  const testId = route?.pageTestId || '';
+  let screenLine = '- **Screen:** None';
+  if (path) {
+    const screen = context.renderScreenLink ? context.renderScreenLink(path) : '`' + path + '`';
+    const suffix = testId ? ` · \`${testId}\`` : '';
+    screenLine = `- **Screen:** ${screen}${suffix}`;
+  }
+%>
+<%= screenLine %>
+
+<% if (spec.summary) { %>
+<%= spec.summary %>
+<% } %>
+
+<% if (spec.userStories) { %>
+## User Stories & Screen Journey
+
+<% if (typeof spec.userStories === 'string') { %>
+<%= spec.userStories %>
+<% } else if (Array.isArray(spec.userStories)) { %>
+<% spec.userStories.forEach(story => { %>
+### <%= story.title || story.name || 'User Story' %>
+<% if (story.asA || story.role) { %>
+> **Là một** <%= story.asA || story.role %>,  
+> **Tôi muốn** <%= story.iWant || story.action %>,  
+> **Để** <%= story.soThat || story.benefit %>.
+<% } else if (story.story) { %>
+> <%= story.story %>
+<% } %>
+
+<% if (story.preConditions && story.preConditions.length) { %>
+**Điều kiện tiên quyết (Pre-conditions):**
+<% (Array.isArray(story.preConditions) ? story.preConditions : [story.preConditions]).forEach(p => { %>
+- <%= p %>
+<% }); %>
+<% } %>
+
+<% if (story.scenarios && story.scenarios.length) { %>
+**Kịch bản chi tiết trên màn hình (Scenarios):**
+<% story.scenarios.forEach(sc => { %>
+- **<%= sc.name || sc.title %>:** <%= sc.description || sc.steps || sc %>
+<% }); %>
+<% } %>
+
+<% if (story.acceptanceCriteria && story.acceptanceCriteria.length) { %>
+**Tiêu chí nghiệm thu (Acceptance Criteria):**
+<% (Array.isArray(story.acceptanceCriteria) ? story.acceptanceCriteria : [story.acceptanceCriteria]).forEach(ac => { %>
+- [ ] <%= ac %>
+<% }); %>
+<% } %>
+
+<% }); %>
+<% } else if (typeof spec.userStories === 'object') { %>
+<% if (spec.userStories.primary) { %>
+### User Story Chính
+> **Là một** <%= spec.userStories.primary.asA || spec.userStories.primary.role %>,  
+> **Tôi muốn** <%= spec.userStories.primary.iWant || spec.userStories.primary.action %>,  
+> **Để** <%= spec.userStories.primary.soThat || spec.userStories.primary.benefit %>.
+<% } %>
+
+<% if (spec.userStories.contextAndHandoff) { %>
+### Cách thức Truy cập & Chuyển giao Màn hình (Screen Access & Handoff)
+<% if (spec.userStories.contextAndHandoff.screenAccess) { %>
+<% const sa = spec.userStories.contextAndHandoff.screenAccess; %>
+- **Loại truy cập (Access Type):** `<%= sa.accessType || 'N/A' %>`
+<% if (sa.accessType === 'directRoute' && sa.directRoute) { %>
+  - **Đường dẫn URL (Path Router):** `<%= sa.directRoute.routePath || '' %>` <%= sa.directRoute.isPublic ? '(Công khai / Public)' : '(Cần đăng nhập / Authenticated)' %>
+<% } else if (sa.accessType === 'sidebarMenu' && sa.sidebarMenu) { %>
+  - **Menu Sidebar:** <%= sa.sidebarMenu.menuHierarchy ? sa.sidebarMenu.menuHierarchy.join(' > ') : '' %> > **<%= sa.sidebarMenu.menuLabel || '' %>**
+<% } else if (sa.accessType === 'contextualAction' && sa.contextualAction) { %>
+  - **Kích hoạt từ (Triggered By):** <%= sa.contextualAction.triggerControl || '' %> từ màn hình `<%= sa.contextualAction.sourceScreen || '' %>` (Loại: `<%= sa.contextualAction.navigationType || 'pageRedirect' %>`)
+<% } %>
+<% } %>
+- **Màn hình nguồn (Source Screen):** `<%= spec.userStories.contextAndHandoff.sourceScreen || 'Direct' %>`
+<% if (spec.userStories.contextAndHandoff.inputsReceived && spec.userStories.contextAndHandoff.inputsReceived.length) { %>
+- **Dữ liệu tiếp nhận (Inputs):** <%= Array.isArray(spec.userStories.contextAndHandoff.inputsReceived) ? spec.userStories.contextAndHandoff.inputsReceived.join(' · ') : spec.userStories.contextAndHandoff.inputsReceived %>
+<% } %>
+- **Điều hướng tiếp theo (Next Screen):** `<%= spec.userStories.contextAndHandoff.nextScreenOnSuccess || 'None' %>`
+<% } %>
+
+<% if (spec.userStories.scenarios && spec.userStories.scenarios.length) { %>
+### Kịch bản Chi tiết trên Màn hình (Scenarios)
+<% spec.userStories.scenarios.forEach(sc => { %>
+#### <%= sc.name || sc.title %>
+<% if (sc.steps && sc.steps.length) { %>
+<% (Array.isArray(sc.steps) ? sc.steps : [sc.steps]).forEach(step => { %>
+- <%= step %>
+<% }); %>
+<% } else if (sc.description) { %>
+<%= sc.description %>
+<% } %>
+<% }); %>
+<% } %>
+
+<% if (spec.userStories.acceptanceCriteria && spec.userStories.acceptanceCriteria.length) { %>
+### Tiêu chí Nghiệm thu (Acceptance Criteria)
+<% spec.userStories.acceptanceCriteria.forEach(ac => { %>
+- [ ] <%= ac %>
+<% }); %>
+<% } %>
+
+<% } %>
+<% } %>
+
+<%
+  // 1. Executive Summary & Screen Journey
+  const pageSections = spec.sections || spec.design?.sections || [];
+  const pageActions = spec.actions || spec.design?.actions || [];
+  const pageStateMatrix = spec.stateMatrix || spec.design?.stateMatrix;
+
+  const page = {
+    nav: spec.nav || spec.design?.nav,
+    sections: pageSections,
+    zones: spec.zones || spec.design?.zones,
+    behavior: spec.behavior || spec.design?.behavior,
+    actions: pageActions
+  }
+%>
+
+<% if (pageStateMatrix) { %>
+## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission Matrix)
+
+<%- context.renderStateMatrixTable(pageStateMatrix) %>
+
+<% } %>
+
+<% 
+  const validationTableMd = context.renderValidationDictionaryTable(pageSections);
+  if (validationTableMd) {
+%>
+## Danh Mục Trường Nhập Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary & Validation)
+
+<%- validationTableMd %>
+
+<% } %>
+
+<% 
+  const customWidgetMd = context.renderCustomWidgetSpecs(pageSections);
+  if (customWidgetMd) {
+%>
+<%- customWidgetMd %>
+
+<% } %>
+
+<% 
+  const actionFlowsMd = context.renderActionFlowsDetailed(pageActions);
+  if (actionFlowsMd) {
+%>
+## Đặc Tả Quy Trình Hành Động (Action Flows)
+
+<%- actionFlowsMd %>
+
+<% } else { %>
+<%- context.renderPageComposition(page, { businessOnly: true }) %>
+<% } %>
+
+<% 
+  const skipKeys = new Set([
+    'id', 'page-id', 'title', 'summary', 'userStories', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template',
+    'nav', 'sections', 'zones', 'behavior', 'actions', 'stateMatrix', 'grillStatus', 'specOrigin',
+    'status', 'owner', 'schema', 'qa', 'Q&A', 'pendingTechDebt', 'i18n', 'gen', '_meta'
+  ]);
+  Object.entries(spec).forEach(([key, value]) => {
+    if (skipKeys.has(key) || value == null) return;
+%>
+## <%= key %>
+
+<% if (typeof value === 'string') { %>
+<%= value %>
+<% } else { %>
+```yaml
+<%= context.stringify(value).trim() %>
+```
+<% } %>
+
+<% }); %>
+
+<% if (spec.pendingTechDebt && spec.pendingTechDebt.length) { %>
+## Pending tech debt
+
+| ID | Status | Summary |
+| --- | --- | --- |
+<% spec.pendingTechDebt.forEach(d => { %>
+| <%= d.id %> | <%= d.status %> | <%= d.summary || '' %> |
+<% }); %>
+
+<% } %>
+
+<% if (spec.review && (spec.review.layoutNotes || spec.review.summary)) { %>
+## Review — layout notes
+
+<% if (spec.review.layoutNotes) { %>
+<% if (Array.isArray(spec.review.layoutNotes)) { %>
+<%= spec.review.layoutNotes.map(n => `- ${n}`).join('\n') %>
+<% } else { %>
+- <%= spec.review.layoutNotes %>
+<% } %>
+<% } %>
+<% } %>
+
+<% if (spec.legacy && (spec.legacy.behaviors?.length || spec.legacy.fields?.length || spec.legacy.evidence?.length)) { %>
+## Legacy evidence
+
+<% if (spec.legacy.behaviors && spec.legacy.behaviors.length) { %>
+### Behaviors
+
+| ID | Fact | Confidence |
+| --- | --- | --- |
+<% spec.legacy.behaviors.forEach(b => { %>
+| <%= b.id || '' %> | `<%= JSON.stringify(b.fact || {}) %>` | <%= b.confidence || '' %> |
+<% }); %>
+<% } %>
+
+<% if (spec.legacy.fields && spec.legacy.fields.length) { %>
+### Fields
+
+| Name | Via | Confidence |
+| --- | --- | --- |
+<% spec.legacy.fields.forEach(f => { %>
+| <%= f.name || '' %> | <%= f.via || '' %> | <%= f.confidence || '' %> |
+<% }); %>
+<% } %>
+<% } %>

package/templates/shared/design-spec.yaml

@@ -0,0 +1,85 @@
+# Design spec v1 — /spec (round 1)
+# Do NOT add codegen, ui.filters, ui.columns, or portal-gen tags here.
+# After /grill-docs → see docs/templates/spec.yaml (portal-gen-ready).
+
+id: role-page-function
+title: Feature title
+status: draft
+owner: portal-team
+summary: Short business summary for BA, QA, dev, and AI.
+
+actors: []
+# - id: admin
+#   legacyRoleCode: master
+
+entities: []
+# - name: Entity
+#   table: entities
+#   importantFields: [id, name, created_at]
+
+relationships: []
+
+requirements:
+  - id: REQ-FEATURE-001
+    title: Main behavior
+    description: User can complete the main behavior.
+    priority: must
+
+ui:
+  routes:
+    - path: /feature-path
+      legacyPath: /legacy/path
+      pageTestId: feature-page
+  # Page profiles for design v1. Keep prose short; move validation/source/message details to form fields.
+  validationMessages:
+    required: This field is required
+    email: Email format is invalid
+    phone: Phone number format is invalid
+    minLength: Must be at least {n} characters
+    maxLength: Must be at most {n} characters
+    min: Must be at least {n}
+    max: Must be at most {n}
+    pattern: Invalid format
+  list:
+    columns: []
+    filters: []
+    rowActions: []
+    bulkActions: []
+    pagination:
+      defaultPageSize: 20
+      pageSizeOptions: [20, 50, 100]
+  form:
+    layout:
+      mode: single-column # single-column | two-column | custom
+    sections: []
+    fields:
+      # - key: name
+      #   label: Name
+      #   type: string
+      #   widget: text
+      #   purpose: "Tên hiển thị trên hồ sơ"
+      #   required: true
+      #   validation:
+      #     maxLength: 255
+      #   messages:
+      #     required: Name is required.
+  detail:
+    header:
+      titleField: name
+      subtitleField: code
+    sections: []
+    actions:
+      - id: edit
+        text: Edit
+      - id: delete
+        text: Delete
+
+# api.endpoints — not authored here. spec:split copies from …/api/<seq>/01-backend-spec.yaml
+
+acceptance:
+  - Main behavior is testable end to end.
+
+
+notes:
+  - YAML is source of truth. Render with pnpm docs:render.
+  - Portal-gen blocks added in /grill-docs — see .cursor/extracts/codegen/readiness.md