@shanyucoder/flowgrid 0.1.11 → 0.1.13

package/harness/docs/skills/risk-register/SKILL.md

@@ -4,26 +4,26 @@ description: /risk-register — Maintain architecture/11-risks/risk-register.md
 disable-model-invocation: true
 ---
 
-# /risk-register — Sổ rủi ro tổng hợp
+# /risk-register — Consolidated risk register
 
 **SSOT:** `architecture/11-risks/risk-register.md`  
 **Template:** `harness/docs/extracts/tpl-risk-register.md`
 
-**Khi dùng:** Rủi ro **không gắn một màn** — hạn mức email/SMS/API, license, SLA vendor, capacity cao điểm.
+**When to use:** Risks **not tied to a single screen** — email/SMS/API quotas, licenses, vendor SLA, peak capacity.
 
 ---
 
 ## Rule: Audit interlock
 
-- **[MANDATORY]** `flowgrid audit risks architecture/11-risks/risk-register.md` trước/sau sửa.
-- **[MANDATORY]** Mỗi dòng: so sánh **Hạn mức** vs **Nhu cầu** → **Chênh lệch** → **Ảnh hưởng** → **Phương án**.
-- **[STRICTLY FORBIDDEN]** Ghi `risks:` trên `*.bundle.yaml` — SSOT chỉ file này.
+- **[MANDATORY]** `flowgrid audit risks architecture/11-risks/risk-register.md` before/after edits.
+- **[MANDATORY]** Each row: compare **Limit** vs **Need** → **Gap** → **Impact** → **Mitigation**.
+- **[STRICTLY FORBIDDEN]** Put `risks:` on `*.bundle.yaml` — SSOT is this file only.
 
 ## Rule: AskQuestion (Law 2)
 
-Thiếu số (quota, peak): wizard ≥3 options (Recommended / Other / Tech debt → `qa/`).
+Missing numbers (quota, peak): wizard ≥3 options (Recommended / Other / Tech debt → `qa/`).
 
 ## Verification
 
-- [ ] Ít nhất một rủi ro thật (không chỉ RISK-EXAMPLE).
-- [ ] Audit `risks` trên register: gaps = 0 hoặc defer qa.
+- [ ] At least one real risk (not only RISK-EXAMPLE).
+- [ ] Audit `risks` on register: gaps = 0 or deferred via qa.

package/harness/docs/skills/spec/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: true
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. **STRICTLY FORBIDDEN** to rely on memory.
 > **[MANDATORY]** Read `.flowgrid/templates/feature.bundle.yaml` + `.flowgrid/templates/bundle-authoring.md` BEFORE generating any YAML. **Do NOT** use `design-spec.yaml` (deprecated).
 > If templates are missing → STOP: *"Template missing. Run `flowgrid init` to generate templates."*
-> **Extract:** `spec-ssot-prep.md`, `spec-prd-lite.md`, `db-audit-wizard.md`, `design-leaf-signoff.md`.
+> **Extract:** `spec-ssot-prep.md`, `spec-prd-lite.md`, `db-audit-wizard.md`, `design-leaf-signoff.md`, `agent-design-context.md`, `ir-read-only.md`.
 > Physical interlocks: `AGENTS.md` + `SSOT_AGENT_PROTOCOL.md` (Laws 1–7). Chat-only done = **FAILED**.
 
 # /spec — Function detail (design)
@@ -52,17 +52,17 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
 - **[MANDATORY]** Before first leaf on a **custom/maintain** project: confirm **custom-base** (`build-template-code`) or **standard** `registry:sync` — agent must map `#ui:` / `#shell:` from real `design.registry.json`, not invent `#needs-component`.
 - **[MANDATORY]** **Brownfield workspace:** `/adopt` + `audit legacy` on inventory **before** `/legacy /spec` on any `W-*` (see `/legacy` modifier below).
 - **[MANDATORY]** When `adoption-inventory.md` exists at workspace root: read **Section 5 (Common Catalog Candidates)** on every `/spec` and `/legacy /spec` — inherit `CMN-*`; **STRICTLY FORBIDDEN** copy-paste legacy files into new bundles.
-- **Greenfield hub mới (no legacy):** skip `/adopt`; prep = nhánh A/B only.
+- **New greenfield docs hub (no legacy):** skip `/adopt`; prep = branch A/B only.
 
 ---
 
 ## Rule: Audit Interlock
 
-- **[MANDATORY]** If bundle file already exists: run `flowgrid audit spec <path-to-bundle.yaml> --type <pageType>` first.
-  - `<pageType>` = page type đã xác định ở bước trên (list | create | detail | admin-crud | auth | ...).
+- **[MANDATORY]** If bundle file already exists: run `flowgrid audit spec <path-to-bundle.yaml> --type <pageType>` first — **bundle path only** (includes `interactionCases`, `userFlows`, UX/DB confirms); never point audit at `ir/spec.yaml` or `ir/design.yaml`.
+  - `<pageType>` = page type determined in the step above (list | create | detail | admin-crud | auth | ...).
   - Script output:
     - `gaps[]` → required fields missing → Agent patches bundle directly.
-    - `warnings[]` → **quality hints** (`scopeIn`, `nonGoals`, `nfr`, `userFlows`, placeholders) — fix when info exists; **does not** block split. Rủi ro → `/risk-register` only (`WARN_BUNDLE_RISKS_FORBIDDEN` if `risks:` on bundle).
+    - `warnings[]` → **quality hints** (`scopeIn`, `nonGoals`, `nfr`, `userFlows`, placeholders) — fix when info exists; **does not** block split. Risks → `/risk-register` only (`WARN_BUNDLE_RISKS_FORBIDDEN` if `risks:` on bundle).
     - `confirms[]` → AskQuestion wizard (one question at a time, ≥3 options):
       - UX: `category: ux`, `UX_*`, `CONFIRM_UX_*` — `flowgrid-ux-common.mdc`
       - **DB:** `category: db`, `CONFIRM_DB_*` — `.cursor/extracts/db-audit-wizard.md` (entities, multi-table, `db` vs `01`, `#derived-data`)
@@ -96,9 +96,14 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
 
 ## Rule: Load Policy
 
-- **[MANDATORY]** Write the **entire** `*.bundle.yaml` (authoring SSOT).
-- **[MANDATORY]** After split exists: re-read **entire** `ir/design.yaml` + `ir/spec.yaml`; do not skim partial keys.
-- **[STRICTLY FORBIDDEN]** Do NOT read generated `*.md` files.
+See **`ir-read-only.md`**: **bundle → split → render**; IR and generated MD are **read-only**.
+
+- **[MANDATORY]** **Write** only `*.bundle.yaml` on the leaf (authoring SSOT).
+- **[MANDATORY]** `userFlows`, `nfr`, `interactionCases`, `design.stateMatrix` / `actions` → write on **`*.bundle.yaml`** only; `flowgrid split` projects them to `ir/*`.
+- **[OPTIONAL]** After split: re-read `ir/design.yaml` + `ir/spec.yaml` to **verify** projection — **never patch** IR to “fix” content.
+- **[STRICTLY FORBIDDEN]** Write or patch `ir/spec.yaml`, `ir/design.yaml`, or any `ir/generated/*`.
+- **[STRICTLY FORBIDDEN]** Use `spec:merge` / `flowgrid merge` instead of editing the bundle.
+- Member review of **`ir/generated/spec.md`** (VitePress) → hand off gaps to **`/update-spec`**, not to IR edits.
 
 ---
 
@@ -108,7 +113,7 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
 2. Detect page type from prompt or existing bundle's `codegen.profile`.
 3. Run audit: `flowgrid audit spec <bundle> --type <pageType>` (if bundle exists).
 4. Process audit output: fill `gaps[]` directly; **`confirms[]` (UX + DB)** → `AskQuestion` wizard per `db-audit-wizard.md` / `flowgrid-ux-common.mdc`.
-5. **Zone-based multi-turn authoring** (see rule below): chia page thành zones, phân tích từng zone trong turn riêng.
+5. **Zone-based multi-turn authoring** (see rule below): split the page into zones; analyze each zone in a separate turn.
 6. Write/update `*.bundle.yaml` with `specOrigin: requirement`.
 7. Apply **DSL/registry** + `flowgrid-ux-common.mdc` (FE base patterns — no `common/yaml` / gen-common).
 8. Run `pnpm docs:split -- <bundle>` → `pnpm docs:render` (design MD only).
@@ -149,11 +154,14 @@ Each zone turn — **in order**:
 - **[MANDATORY]** List columns: `key` consistent with `bind.field`; computed-only columns → document `#derived-data` (see `common/data-model/derived-data.md`), no fake `db`.
 - **[STRICTLY FORBIDDEN]** Empty `entities: []` while form/list has multiple persisted `db.field` without QA defer.
 - **Authoring detail:** [bundle-authoring.md § Data model](../../../templates/shared/bundle-authoring.md#data-model--phase-0-erd-vs-screen-detail) · [tpl-screen-data-model.md](../../../templates/shared/tpl-screen-data-model.md) (multi-table).
-- **Sau split:** `ir/generated/data-model.md` cho review. **Audit:** `CONFIRM_DB_*` → member wizard; sau chốt → re-audit. BE SSOT: `01` khớp `db` (drift → `/api-update`).
+- **After split:** `ir/generated/data-model.md` for review. **Audit:** `CONFIRM_DB_*` → member wizard; re-audit after confirm. BE SSOT: `01` must match `db` (drift → `/api-update`).
 
 ### Rule: Summary extensions (PRD lite)
 - **[MANDATORY]** `summary` bullets: business_goals, stakeholders, user_journey, context (input/output), optional solution.
-- **[RECOMMENDED]** Fill `scopeIn`, `nonGoals`, `userFlows`, `nfr` when PO/BA có thông tin. Rủi ro dự án → **`/risk-register`** (`architecture/11-risks/risk-register.md`), never `risks:` on bundle.
+- **[RECOMMENDED]** Fill `scopeIn`, `nonGoals`, `userFlows`, `nfr` when PO/BA provide facts. Complex single-screen flows → `interactionCases` (L2) or resolve audit `CONFIRM_INTERACTION_CASES_POLICY`. Project risks → **`/risk-register`**, never `risks:` on bundle.
+- **[MANDATORY]** `userFlows:` bullets link **`FLOW-*`** (`FLOW-id — role: … — screens: W-* (this leaf)`). Journey sequence lives in **`FLOW-*.md` §6** — not in bundle.
+- **[RECOMMENDED]** Multi-state / multi-case on **one screen:** optional top-level **`interactionCases`** (`policy`, `items[]` with `IC-*`, `description`, `sequenceDiagram`) — see `agent-design-context.md`. After split: prose → `spec.md`, diagrams → `design.md`.
+- **[MANDATORY]** Consume `confirms[]` **`CONFIRM_INTERACTION_CASES_POLICY`** from audit — set `policy: required` or `policy: skip` + `skipReason`.
 - **[MANDATORY]** Replace template `[placeholder]` brackets in `summary` / metrics / non-goals before handoff grill.
 
 ### Rule: User Stories (`userStories`)
@@ -269,6 +277,6 @@ Each zone turn — **in order**:
 - [ ] UX gap questions used checklist-backed `(Recommended)` options (`flowgrid-ux-common.mdc`), not open brainstorming.
 - [ ] `userStories` scenarios/AC reflect UX affordances patched in `design` (incl. audit `suggestedStoryPatch`).
 - [ ] YAML strings with `:` or `[]` are double-quoted. No `.md` written by hand.
-- [ ] PRD fields (`scopeIn`, `nonGoals`, `userFlows`, `nfr`) filled or deferred via `qa/` (no template brackets). Rủi ro không trên bundle.
+- [ ] PRD fields (`scopeIn`, `nonGoals`, `userFlows`, `nfr`) filled or deferred via `qa/` (no template brackets). No project risks on bundle (`/risk-register` only).
 - [ ] `pnpm docs:split` + `pnpm docs:render` run with zero errors; `ir/generated/spec.md` has TOC + overview sections.
 - [ ] Handoff → `/testcase` created.

package/harness/docs/skills/update-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: update-spec
 extractBundle: update-spec
-description: /update-spec — delta update bundle/spec.
+description: /update-spec — patch bundle after VitePress review; split+render (never edit ir/*).
 disable-model-invocation: true
 ---
 
@@ -17,10 +17,20 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 
 ## Rule: Load Policy
 
-| Read (whole file) | Write | NEVER |
+See **`ir-read-only.md`**. One write path: **bundle → split → render**.
+
+| Read (for gap analysis) | Write | NEVER |
 |---|---|---|
-| **`ir/design.yaml`** — current tech/UI | Patch `*.bundle.yaml` → then split | Write generated `*.md`; write to `ir/*` directly |
-| **`ir/spec.yaml`** — ONLY when delta involves requirements/acceptance prose | | Read only `design.sections` / `spec.ui` partial slices |
+| **`ir/generated/spec.md`** — primary review surface (VitePress) | **`*.bundle.yaml`** only | **`ir/spec.yaml`**, **`ir/design.yaml`**, any **`ir/generated/*`** |
+| **`ir/design.yaml`** + **`ir/spec.yaml`** — whole file when delta touches tech vs prose | Then `flowgrid split` + `flowgrid render` | `spec:merge` / `flowgrid merge` for review fixes |
+
+---
+
+## Rule: Review → delta (member loop)
+
+- **[MANDATORY]** Assume the member found gaps while reading **`ir/generated/spec.md`** (and `design.md` / `api.md` when relevant) — **read-only** artifacts.
+- **[MANDATORY]** Translate every fix into a **minimal bundle patch**, then audit → split → render.
+- **[STRICTLY FORBIDDEN]** Patch `ir/*` or `ir/generated/*` to “save time”.
 
 ---
 
@@ -28,7 +38,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 
 - **[MANDATORY]** Scope: patch bundle (delta only); emit `#update:*` tags; bump `specRevision`; run `flowgrid split/check`.
 - **[STRICTLY FORBIDDEN]** Full rewrite → `/spec`. Close `qa` item → `/qa-resolve`. Production code → NOT this skill.
-- **[MANDATORY]** Legacy re-mine / trace lại từ code cũ: dùng **`/legacy /spec`** (adopt lại) hoặc **`/update-spec`** với delta `legacy` / `legacyEvidence` + `#update:*` — **không** skill riêng.
+- **[MANDATORY]** Legacy re-mine / re-trace from old code: use **`/legacy /spec`** (re-adopt) or **`/update-spec`** with delta `legacy` / `legacyEvidence` + `#update:*` — not a separate skill.
 
 ---
 
@@ -48,7 +58,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 - **[MANDATORY]** Patch minimal YAML sections in **bundle** only (not `ir/*`).
 - **[MANDATORY]** When the delta touches scope or acceptance: update `summary`, `successMetrics`, or `nonGoals` if PO changed goals/out-of-scope; sync `userStories` / AC.
 - **[MANDATORY]** When the delta touches `design.actions`, `design.sections`, or `spec.ui` (list/form/detail, filters, row actions): run the **UX ↔ userStories** checklist in `templates/shared/bundle-authoring.md` — sync `userStories.scenarios` / `acceptanceCriteria` prose when behavior or affordances change (do not leave business story stale).
-- **[MANDATORY]** Before split/merge: run `flowgrid audit spec <bundle.yaml> --type <pageType>` and resolve or explicitly defer `UX_*` / gap codes; do not hand off FE/tests with a fresh structural delta and no re-audit.
+- **[MANDATORY]** Before split: run `flowgrid audit spec <bundle.yaml> --type <pageType>` and resolve or explicitly defer `UX_*` / gap codes; do not hand off FE/tests with a fresh structural delta and no re-audit.
 - **[MANDATORY]** Preserve error matrices: when patching actions/API endpoints, ensure `onSuccess`, `onCommonError`, `onSpecificError` + `#err:*` tags are preserved and updated accordingly.
   - ✅ Add new `onSpecificError.409` entry alongside existing `onSuccess` block.
   - ❌ Overwrite or delete existing error handling blocks that are unrelated to this delta.
@@ -71,7 +81,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 8. `flowgrid_docs_bundle_check` / `flowgrid split --check -- <bundle>` (fallback: `pnpm docs:check`).
 9. User runs `docs_render` / `flowgrid render` (fallback: `pnpm docs:render`).
 10. Follow-up per patch type: handoff FE `/prototype` or `/grill-dev` / `/grill-bqa`; if API contract changed → `/api-update` before `openapi:gen`.
-11. When delta originated from wire/`audit fe-be` on FE: read `.cursor/extracts/wire-spec-feedback.md`; after merge handoff tests-hub `/grill-testcase` then FE `/wire` or `/grill-wire`.
+11. When delta originated from wire/`audit fe-be` on FE: read `.cursor/extracts/wire-spec-feedback.md`; after bundle patch + split handoff tests-hub `/grill-testcase` then FE `/wire` or `/grill-wire`.
 
 ---
 

package/harness/docs/skills/user-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-flow
-description: /user-flow — Luồng người dùng (FLOW-*) trên surfaces.
+description: /user-flow — Author cross-surface user journeys (FLOW-*.md) on the docs hub.
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -12,7 +12,9 @@ extractBundle: architecture-core
 
 **Mindset:** Model the process by **business actions on surfaces**, not by repository or service topology.
 
-**Template:** `architecture/03-user-flows/FLOW-template.md` (or `**/common/user-flows/FLOW-*.md`) — **Non-goals** in §1 when information exists (KPI ngoài hub).
+**Template:** `architecture/03-user-flows/FLOW-template.md` (or `**/common/user-flows/FLOW-*.md`) — **Non-goals** in §1 when information exists (out-of-hub KPIs).
+
+**Leaf link:** Bundles reference this file via `userFlows:` (`FLOW-* — role — screens`). Agents read FLOW **before** codegen (`agent-design-context.md`). **Do not** put single-screen multi-state cases here — use bundle `interactionCases` (L2).
 
 ---
 

package/harness/fe/adapters/dotnet-line/skills/framework-rules/SKILL.md

@@ -8,10 +8,10 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=fe|monolith --fe-adapter=dotnet-line`)
 
-WinForms Line client · bộ code grill/gen first when applicable.  
+WinForms Line client · code repo grill/gen first when applicable.  
 Not Nuxt/Next — do not apply web FE layer rules here.
 
-## Gen trước (code)
+## Gen first (code)
 
 1. Prefer codegen / existing Line templates before free-form UI scaffolding
 2. AI fills gaps only — do not duplicate generated surfaces

package/harness/fe/adapters/nextjs/skills/framework-rules/SKILL.md

@@ -12,9 +12,9 @@ Auth-first Next.js · App Router · shadcn · Playwright. Code under `src/`.
 
 **Rules (FE globs):** `platform-invariants.mdc` · contract-naming · `framework-rules-*` · size/split/import · design-vocab (product repo).
 
-## Gen trước (code)
+## Gen first (code)
 
-1. bộ code `gen` / repo shim from IR already grilled
+1. code repo `gen` / repo shim from IR already grilled
 2. AI only fills gaps: Mo* / `#needs-*` not yet in registries
 3. Do not write boilerplate when codegen already covers it
 

package/harness/fe/adapters/nuxt4/skills/framework-rules/SKILL.md

@@ -12,9 +12,9 @@ Auth-first Nuxt 4 · Pinia · vee-validate+Zod · shadcn · Playwright.
 
 **Rules (FE globs):** `platform-invariants.mdc` · `platform-contract-naming.mdc` · `framework-rules-*` · size/split/import · design-vocab (product repo).
 
-## Gen trước (code)
+## Gen first (code)
 
-1. bộ code `gen` / repo shim from IR already grilled
+1. code repo `gen` / repo shim from IR already grilled
 2. AI only fills gaps: Mo* / `#needs-*` not yet in `registries/`
 3. Do not write layer boilerplate when codegen already covers it
 

package/harness/fe/rules/cross-repo-index-routing.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # Cross-repo index routing
 
-- Architecture IDs and Functions/W-* paths belong to bộ docs through `FLOWGRID_DOCS_ROOT`.
+- Architecture IDs and Functions/W-* paths belong to docs hub through `FLOWGRID_DOCS_ROOT`.
   Never use CodeGraph as the architecture index.
 - Test plans use `FLOWGRID_TESTS_DOC`; docs evidence uses
   `FLOWGRID_DOCS_ROOT`; IR/registry/generation follows its owning pointer such as

package/harness/fe/rules/flowgrid-test-optional-accelerators.mdc

@@ -1,9 +1,9 @@
 ---
-description: bộ test optional accelerator fallback and event contract
+description: tests hub optional accelerator fallback and event contract
 alwaysApply: true
 ---
 
-# bộ test optional accelerators
+# tests hub optional accelerators
 
 ArtifactGraph accelerates coverage and search but is never required. When it is
 missing or fails, continue with deterministic local coverage/search. Assign one
@@ -13,7 +13,7 @@ stable `runId` per run and emit exactly one `flowgrid.missing-optional` event pe
 ArtifactGraph is local-only: in this repo it indexes this repo's own data
 (taxonomy/coverage hints) and never follows `FLOWGRID_DOCS_ROOT` or
 `FLOWGRID_TESTS_DOC`. Canonical docs/tests-hub evidence always flows through
-those bộ test pointers, never through ArtifactGraph.
+those tests hub pointers, never through ArtifactGraph.
 
 Events must conform to
 `.cursor/schemas/flowgrid-test/missing-optional-event.schema.json`. Metrics count only

package/harness/fe/rules/team-flow-prototype.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Team Flow — Prototype
 
-Active: `/prototype` và `/grill-prototype` — **hai** session (prototype trước, grill-prototype sau).
+Active: `/prototype` and `/grill-prototype` — **two** sessions (prototype first, then grill-prototype).
 
 | Command | Skill |
 |---------|-------|
@@ -16,21 +16,21 @@ Active: `/prototype` và `/grill-prototype` — **hai** session (prototype trư
 Prerequisite: member-configured `FLOWGRID_DOCS_ROOT` points to the grilled
 docs registry hub → `npm run codegen:dry -- --id …` OK. Never infer a sibling docs
 checkout; local ArtifactGraph is not the docs bridge. Architecture IDs →
-bộ docs (`FLOWGRID_DOCS_ROOT`); never CodeGraph for C4/architecture.
+docs hub (`FLOWGRID_DOCS_ROOT`); never CodeGraph for C4/architecture.
 
-## Thứ tự
+## Order
 
-0. Docs hub `common/` = `processes/` + `patterns/` (Markdown) — tham chiếu nghiệp vụ; **không** gen-common.
-1. `npm run codegen:dry` rồi `npm run codegen -- --id W-…` (hoặc MCP `gen`) — đọc `…/code/{W-…}/generated/HANDOFF.md`.
-2. Quét `#needs-component` — implement từ FE base + shadcn; template/registry mới → `docs/workflows/custom-base.md` (toolkit SSOT).
-3. Vá slot · auth bypass · gap; **không** sửa YAML business trên hub khi prototype.
+0. Docs hub `common/` = `processes/` + `patterns/` (Markdown) — business reference; **no** gen-common.
+1. `npm run codegen:dry` then `npm run codegen -- --id W-…` (or MCP `gen`) — read `…/code/{W-…}/generated/HANDOFF.md`.
+2. Scan `#needs-component` — implement from FE base + shadcn; new template/registry → `docs/workflows/custom-base.md` (toolkit SSOT).
+3. Fill slots · auth bypass · gaps; **do not** edit business YAML on the hub during prototype.
 
-## Sau prototype
+## After prototype
 
-4. Session mới: `/grill-prototype` — checklist UI (design.md bước 6); không chạy `gen:dry` lại trừ khi đổi IR.
+4. New session: `/grill-prototype` — UI checklist (design.md step 6); do not re-run `gen:dry` unless IR changed.
 
 - Source: grill-approved hub `ir/design.yaml`
-- Real UI; mock chỉ API boundary
-- **Không** backend thật — `/wire` thay mock
-- `data-testid` sớm (`E2E-TESTIDS.md` trên hub)
-- **Không** viết lại scaffold đã gen
+- Real UI; mock API boundary only
+- **No** real backend — `/wire` replaces mocks
+- Early `data-testid` (`E2E-TESTIDS.md` on hub)
+- **Do not** rewrite generated scaffold

package/harness/fe/rules/team-flow-unit.mdc

@@ -9,19 +9,19 @@ alwaysApply: false
 Skills: `.cursor/skills/unit/SKILL.md` · `.cursor/skills/grill-unit/SKILL.md`  
 Extract: `.cursor/extracts/portal-unit-workflow.md`, `portal-unit-test-tags.md`, `verify-gate.md`
 
-Canonical IR via `FLOWGRID_DOCS_ROOT`; architecture → bộ docs; cross-repo
+Canonical IR via `FLOWGRID_DOCS_ROOT`; architecture → docs hub; cross-repo
 symbols → Platform DNA-wired `codegraph-<key>`; ArtifactGraph local-only.
 
 ## `/unit`
 
 - Manifest-first: `unit.manifest.json` + `UNIT-HANDOFF.md`
-- Gọi `npm run codegen:unit` khi thiếu smoke; xử lý `needsUnit[]` / `#needs-unit-test:*`
-- Tách file test thiếu theo registry (1 source logic → 1 test file)
-- Logic only — **không** mount page/component; mock the selected adapter's
+- Run `npm run codegen:unit` when smoke is missing; handle `needsUnit[]` / `#needs-unit-test:*`
+- Split missing test files per registry (1 logic source → 1 test file)
+- Logic only — **do not** mount page/component; mock the selected adapter's
   transport and framework globals at the unit boundary.
 - Done: `needsUnit` clear, vitest scoped green → **`/grill-unit`**
 
 ## `/grill-unit`
 
-- Sau `/unit` — coverage scoped + map `reqIds`; **không** gọi `portal:unit-gen`
-- Thiếu file test → báo quay `/unit`
+- After `/unit` — scoped coverage + map `reqIds`; **do not** call `portal:unit-gen`
+- Missing test file → report and return to `/unit`

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /grill-prototype — UI checklist (post-prototype)
 
-**Owner:** bộ code FE · **When:** After `/prototype` session has run `gen:dry` → `gen` and filled HANDOFF slots — **before** demo, `/test`, or `/wire`.
+**Owner:** FE code repo · **When:** After `/prototype` session has run `gen:dry` → `gen` and filled HANDOFF slots — **before** demo, `/test`, or `/wire`.
 
 **Not this skill:** `flowgrid gen:dry` gate — that runs at the **start** of `/prototype` ([team-flow-prototype.mdc](../rules/team-flow-prototype.mdc)). This skill audits the **built** UI against docs IR.
 
@@ -45,7 +45,7 @@ Work through in order; fix **only** in FE repo when issue is clear. Otherwise li
 1. `FLOWGRID_DOCS_ROOT` (non-empty) → canonical pointer for `ir/design.yaml`.
 2. Else Platform DNA (`platform-dna`) — slower; prefer explicit env.
 
-Architecture IDs → bộ docs; symbols in other repos → `codegraph-<key>` only.
+Architecture IDs → docs hub; symbols in other repos → `codegraph-<key>` only.
 
 Optional: local ArtifactGraph allowlist hint — never blocks checklist. Telemetry: `flowgrid-code-optional-integrations.mdc` once per run.
 

package/harness/fe/skills/grill-test/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # /grill-test — E2E Traceability Audit (FE repo)
 
-**Owner:** bộ test (`--type=fe`). Plan SSOT stays on tests-docs hub — grill plans with `/grill-testcase`, not here.
+**Owner:** tests hub (`--type=fe`). Plan SSOT stays on tests-docs hub — grill plans with `/grill-testcase`, not here.
 
 **Mindset:** Audit only — **no** fixing production code like `/test`, **no** bulk `testcase:gen` regen.
 

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /grill-unit
 
-**Owner:** bộ code · optional local ArtifactGraph allowlist check before unit dry-gen.
+**Owner:** code repo · optional local ArtifactGraph allowlist check before unit dry-gen.
 
 ```text
 if local ArtifactGraph available: check the FE repo's allowlist for unitGenDry
@@ -23,7 +23,7 @@ else: npm run codegen:unit:dry -- --id …
    an explicit `FLOWGRID_DOCS_ROOT` when available.
 
 Canonical IR/registries come from `FLOWGRID_DOCS_ROOT`; ArtifactGraph does
-not follow that pointer. Architecture IDs → bộ docs (`FLOWGRID_DOCS_ROOT`); symbols
+not follow that pointer. Architecture IDs → docs hub (`FLOWGRID_DOCS_ROOT`); symbols
 in other repos → `codegraph-<key>` only.
 
 Missing ArtifactGraph never blocks the grill. Complete the deterministic dry

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

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # /grill-wire — Wire Convergence Audit (FE repo)
 
-**Owner:** bộ code (`--type=fe`)
+**Owner:** code repo (`--type=fe`)
 
 **Mindset:** Audit and gap routing only — **no** bulk `/wire` implementation, **no** `/test` fixes inline unless member explicitly runs `/test` in same session.
 

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

@@ -1,12 +1,12 @@
 ---
 name: model
-description: /model — Zod models and TS types in models/ / validations/ (bộ code FE).
+description: /model — Zod models and TS types in models/ / validations/ (FE code repo).
 disable-model-invocation: true
 ---
 
 # /model — FE contract models
 
-**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs`  
+**Owner:** code repo (`--type=fe`) · Adapters: `nuxt4` | `nextjs`  
 Not synced for `dotnet-line` (WinForms contracts live outside Zod `models/`).
 
 ## Scope
@@ -35,7 +35,7 @@ Docs hub (`FLOWGRID_DOCS_ROOT`): **Read the entire `ir/design.yaml`**. Do not ch
 ## Handoff
 
 → `/wire` when forms/services need the updated schemas  
-→ `/api` (bộ code BE) when the backend contract must catch up
+→ `/api` (BE code repo) when the backend contract must catch up
 
 ## Accelerators (optional)
 
@@ -44,5 +44,5 @@ if local ArtifactGraph available: local FE tag/allowlist hints only
 else: scoped IR + registry evidence only
 ```
 
-Canonical IR/registry evidence always comes through the bộ code docs pointer,
+Canonical IR/registry evidence always comes through the code repo docs pointer,
 not through ArtifactGraph.

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

@@ -1,12 +1,12 @@
 ---
 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
 
@@ -23,7 +23,18 @@ surfaces/<surface>/CMP-*/<NN…>/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.
 
-**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)`.
+## 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 any file under `FLOWGRID_DOCS_ROOT` (including `*.bundle.yaml`, `ir/*`, `ir/generated/*`). Hub fixes → `/update-spec` on bundle in a docs session. 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
@@ -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/test/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /test
 
-**Owner:** bộ test (`--type=fe`)
+**Owner:** tests hub (`--type=fe`)
 
 ```bash
 flowgrid testcase:gen:dry --tests-docs=/path/to/tests-hub --docs-root=/path/to/docs-hub -- --id TC-…
@@ -15,7 +15,7 @@ flowgrid testcase:gen --tests-docs=/path/to/tests-hub --docs-root=/path/to/docs-
 
 Use `FLOWGRID_TESTS_DOC` (or `--tests-docs`) when the tests hub is not local.
 Use `FLOWGRID_DOCS_ROOT` for docs evidence. Route Functions/W-* evidence through
-bộ docs, and symbols or call graphs for repo X through the Platform DNA-wired
+docs hub, and symbols or call graphs for repo X through the Platform DNA-wired
 `codegraph-<repo-key>` server for checkout X. Never use a workspace-parent
 graph or ask the member to hand-edit MCP configuration.
 
@@ -27,7 +27,7 @@ else: local deterministic search, then run flowgrid testcase:gen directly
 ```
 
 ArtifactGraph never follows `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC`; plan
-YAML and docs evidence flow only through those bộ test pointers.
+YAML and docs evidence flow only through those tests hub pointers.
 
 Assign one stable `runId` at run start. If ArtifactGraph is missing, complete
 the local fallback, count successful file reads and exact raw bytes read into

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

@@ -1,12 +1,12 @@
 ---
 name: unit
-description: /unit — unit test generation from codegen manifests via bộ code.
+description: /unit — unit test generation from codegen manifests via code repo.
 disable-model-invocation: true
 ---
 
 # /unit
 
-**Owner:** bộ code (`--type=fe`)
+**Owner:** code repo (`--type=fe`)
 
 ```bash
 npm run codegen:unit:dry -- --id W-ADM-AUTH-01
@@ -35,7 +35,7 @@ local ArtifactGraph never replaces it.
 
 ## 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 or member-edited MCP.
 Local ArtifactGraph is allowlist/tag hints for this repo only.
@@ -51,5 +51,5 @@ else: run flowgrid unit-gen directly
 ```
 
 Missing ArtifactGraph never blocks unit generation. Complete the direct,
-deterministic bộ code fallback first, then follow
+deterministic code repo fallback first, then follow
 `.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.

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

@@ -1,17 +1,17 @@
 ---
 name: wire
-description: /wire — replace prototype mocks with real API wiring (bộ code FE lane).
+description: /wire — replace prototype mocks with real API wiring (FE code repo lane).
 disable-model-invocation: true
 ---
 
 # /wire
 
-**Owner:** bộ code (`--type=fe`)
+**Owner:** code repo (`--type=fe`)
 
 > **[MANDATORY]** Read `.cursor/extracts/wire-phase.md`, `.cursor/extracts/wire-audit-loop.md`, and hub `docs/workflows/wire.md` (wire cycle) before wiring.
 
 Use after `/prototype` when tags/handoff mark `#wire-only` or real API integration is required.
-Keep generation through bộ code adapters; resolve canonical docs evidence
+Keep generation through code repo adapters; resolve canonical docs evidence
 through `FLOWGRID_DOCS_ROOT` and do not invent sibling layout.
 
 ## Docs Root Resolution
@@ -25,7 +25,7 @@ through `FLOWGRID_DOCS_ROOT` and do not invent sibling layout.
 
 ## Route
 
-IR/handoff via `FLOWGRID_DOCS_ROOT`; architecture IDs via bộ docs
+IR/handoff via `FLOWGRID_DOCS_ROOT`; architecture IDs via docs hub
 (`FLOWGRID_DOCS_ROOT`); BE/FE symbols via per-repo `codegraph-<key>`; ArtifactGraph
 local tags only. Never workspace-parent graphs or member-edited MCP.
 
@@ -45,7 +45,7 @@ once-per-run telemetry with observed metrics only.
 - **[MANDATORY]** Resolve **tests-docs** (`FLOWGRID_TESTS_DOC`) and **e2e-root** (FE `tests/e2e` or project convention).
 - **[MANDATORY]** `flowgrid cases:gate --strict` on TC YAML for the screen being wired (when gate is enabled for the team).
 
-## Post-wire (audit đầu ra)
+## Post-wire (output audit)
 
 - **[MANDATORY]** After mocks are removed and real API is connected, run: