@shanyucoder/flowgrid 0.1.12 → 0.1.13

package/engines/spec/lib/audit-interaction-cases.mjs

@@ -1,5 +1,6 @@
 /**
- * Two-step audit for bundle interactionCases (see harness/docs/extracts/agent-design-context.md).
+ * Two-step audit for bundle interactionCases (invoked only from audit-bundle-gaps on *.bundle.yaml).
+ * See harness/docs/extracts/agent-design-context.md — do not run against ir/spec or ir/design.
  */
 
 function countMutationActions(design) {

package/harness/be/adapters/dotnet-integration/skills/framework-rules-be/SKILL.md

@@ -8,9 +8,9 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=dotnet-integration`)
 
-.NET integration host · bộ code grill/gen first when applicable.
+.NET integration host · code repo grill/gen first when applicable.
 
-## Gen trước (code)
+## Gen first (code)
 
 1. Prefer codegen / existing templates before free-form scaffolding
 2. AI fills gaps only — do not duplicate generated surfaces

package/harness/be/adapters/fastapi/skills/framework-rules-be/SKILL.md

@@ -8,11 +8,11 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=fastapi`)
 
-FastAPI · modular packages · bộ code grill/gen first.
+FastAPI · modular packages · code repo grill/gen first.
 
-## 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 `#needs-*` / gaps not yet in `registries/`
 3. Do not hand-write boilerplate codegen already covers
 

package/harness/be/adapters/laravel/skills/framework-rules-be/SKILL.md

@@ -8,11 +8,11 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=laravel`)
 
-Laravel · `nwidart/laravel-modules` (modules-v1) · bộ code grill/gen first.
+Laravel · `nwidart/laravel-modules` (modules-v1) · code repo grill/gen first.
 
-## 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 `#needs-*` / gaps not yet in registries
 3. Do not hand-write module scaffolding codegen already covers
 

package/harness/be/skills/api/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: api
-description: /api — backend API generation through bộ code BE adapters.
+description: /api — backend API generation through BE code repo adapters.
 disable-model-invocation: true
 ---
 
 # /api — Backend API
 
-**Owner:** bộ code (`--type=be`)  
+**Owner:** code repo (`--type=be`)  
 **Adapters:** `fastapi` · `laravel` · `dotnet-integration` · `nestjs`
 
 ## Generate
@@ -52,7 +52,7 @@ FE models (not this skill): `flowgrid contract-gen:dry -- --spec /path/to/ir/des
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); IR via explicit `--spec` /
+Architecture/C4 → docs hub (`FLOWGRID_DOCS_ROOT`); IR via explicit `--spec` /
 `FLOWGRID_DOCS_ROOT` when configured — never ArtifactGraph as the docs
 bridge. This-repo conventions → local CodeGraph if present; other repo X →
 only Platform DNA-wired `codegraph-<key>`. ArtifactGraph = local allowlist
@@ -87,7 +87,7 @@ warns and uses entity-local CRUD defaults.
 
 ```text
 if ArtifactGraph available: allowlist/recommend API generation
-else: execute bộ code adapter directly
+else: execute code repo adapter directly
 
 if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing module conventions/callers
 else: targeted repository search — never a workspace-parent graph

package/harness/be/skills/api-unit/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: api-unit
-description: /unit — backend API unit test generation via bộ code BE adapters.
+description: /unit — backend API unit test generation via BE code repo adapters.
 disable-model-invocation: true
 ---
 
 # /unit — Backend API Unit Tests
 
-**Owner:** bộ code (`--type=be`)
+**Owner:** code repo (`--type=be`)
 **Adapters:** `fastapi` · `laravel` · `nestjs`
 
 > `dotnet-integration` emits test source during its primary API pass; it has no
@@ -48,7 +48,7 @@ Requires a prior `01-backend-spec.yaml` under the docs hub API folder.
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); spec via explicit `--spec` /
+Architecture/C4 → docs hub (`FLOWGRID_DOCS_ROOT`); spec via explicit `--spec` /
 `FLOWGRID_DOCS_ROOT` when configured — never ArtifactGraph as the docs
 bridge. This-repo conventions → local CodeGraph if present; other repo X →
 only Platform DNA-wired `codegraph-<key>`. ArtifactGraph = local allowlist
@@ -64,7 +64,7 @@ hints only.
 
 ```text
 if ArtifactGraph available: allowlist/recommend API unit generation
-else: execute bộ code adapter directly
+else: execute code repo adapter directly
 
 if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing test conventions
 else: targeted repository search — never a workspace-parent graph

package/harness/be/skills/audit-api/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implementation.
 
-**Owner:** bộ code (`--type=be`). Docs hub is **read-only**.
+**Owner:** code repo (`--type=be`). Docs hub is **read-only**.
 
 ## Target / ID Resolution Rule
 
@@ -36,7 +36,7 @@ Check:
 - Writes are transaction-safe; async retries are idempotent.
 - Generated placeholders are replaced before ship.
 
-**CLI (lượng):** `flowgrid audit api` on `01`; when portal bundle exists → `flowgrid audit fe-be` on sibling `*.bundle.yaml`.
+**CLI (quantitative):** `flowgrid audit api` on `01`; when portal bundle exists → `flowgrid audit fe-be` on sibling `*.bundle.yaml`.
 
 ## Accelerators (optional)
 
@@ -47,7 +47,7 @@ else: scoped contract-to-code comparison
 if codegraph-<repo-key> for this checkout: callers/routes/jobs/listeners
 else: targeted repository search
 
-architecture IDs / C4 → bộ docs (FLOWGRID_DOCS_ROOT), never CodeGraph
+architecture IDs / C4 → docs hub (FLOWGRID_DOCS_ROOT), never CodeGraph
 ```
 
 Missing accelerators never block the audit. Complete each scoped model or

package/harness/be/skills/grill-api-unit/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /grill-unit
 
-**Owner:** bộ code · audit gate before BE unit test generation.
+**Owner:** code repo · audit gate before BE unit test generation.
 
 Run after `npm run codegen:api:unit:dry` / `flowgrid api-unit-gen:dry` and
 before committing generated test code.
@@ -50,7 +50,7 @@ else: scoped spec-to-test comparison
 if codegraph-<repo-key> for this checkout: callers/routes/existing test patterns
 else: targeted repository search
 
-architecture IDs / C4 → bộ docs (FLOWGRID_DOCS_ROOT), never CodeGraph
+architecture IDs / C4 → docs hub (FLOWGRID_DOCS_ROOT), never CodeGraph
 ```
 
 Missing accelerators never block the grill. Complete each scoped model or

package/harness/common/rules/artifactgraph.mdc

@@ -14,9 +14,9 @@ alwaysApply: false
 
 ## Cross-repo routing
 
-- Architecture ID / C4 → bộ docs (`FLOWGRID_DOCS_ROOT`), not CodeGraph and not
+- Architecture ID / C4 → docs hub (`FLOWGRID_DOCS_ROOT`), not CodeGraph and not
   ArtifactGraph.
-- IR / registry / generation → bộ code / bộ test pointers
+- IR / registry / generation → code repo / tests hub pointers
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
 - Symbol / call-graph of repo X → `codegraph-<key>` MCP for checkout X.
 - ArtifactGraph is local-only: never follow those pointers, never read repo

package/harness/common/rules/cross-repo-index.mdc

@@ -9,13 +9,13 @@ Do not merge every repository into a single workspace graph (the parent folder
 must never be indexed). "Cross-repo" means a skill/rule knows how to reach the
 **correct per-repo index**, one repository at a time.
 
-**Owner:** Platform DNA. FlowGrid harness rules (bộ docs, bộ process, …) install this same
+**Owner:** Platform DNA. FlowGrid harness rules (docs hub, process hub, …) install this same
 filename only when DNA is absent, so a destination never carries duplicate
 `alwaysApply` routing rules under different names.
 
 Route by intent:
 
-- Need an architecture ID or C4 path -> bộ docs MCP (`FLOWGRID_DOCS_ROOT`). Never
+- Need an architecture ID or C4 path -> docs hub MCP (`FLOWGRID_DOCS_ROOT`). Never
   CodeGraph for architecture Markdown.
 - Need IR / registry / generation -> the pointer kit
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).

package/harness/common/rules/platform-code-size.mdc

@@ -8,17 +8,17 @@ alwaysApply: false
 
 Soft limits — split in the same PR when exceeded.
 
-| Vượt ~200 dòng/file | Tách | Gợi ý Tag DSL (`/docs-mark`) |
+| Exceeds ~200 lines/file | Split | Suggest Tag DSL (`/docs-mark`) |
 |---------------------|------|------------------------------|
-| Page `.vue` | Composable + sub-component | `#needs-component: sub-{name}:MoXxx` hoặc `#common-ui` |
+| Page `.vue` | Composable + sub-component | `#needs-component: sub-{name}:MoXxx` or `#common-ui` |
 | Composable | `useXxxForm`, `useXxxList`, … | `#common-ui` / `#needs-ui` |
-| Service / store | File theo aggregate; action phức tạp → service | `#cross-service` / `#cross-entity-service` / `#needs-service` |
+| Service / store | File per aggregate; complex action → service | `#cross-service` / `#cross-entity-service` / `#needs-service` |
 | E2E spec | Page Object + helper | `#e2e-test` bundle split |
 
-| Vượt ~20 dòng/function | Tách | Gợi ý Tag DSL (`/docs-mark`) |
+| Exceeds ~20 lines/function | Split | Suggest Tag DSL (`/docs-mark`) |
 |------------------------|------|------------------------------|
 | Submit handler | `buildPayload`, `validateBeforeSubmit`, `handleApiError` | `#needs-service` / local helper |
 | Map/transform | Pure helpers / computed | `#derived-data` |
 
 No padding files with blank lines. Component split: `platform-component-split.mdc`.
-Khi file/function chạm ngưỡng vượt giới hạn, AI Agent cần chủ động đề xuất gán tag tương ứng (thông qua `/docs-mark`) và cập nhật registry (`registries/design.registry.json` hoặc `registries/common.registry.json`) để tái sử dụng sau này.
+When a file or function hits an exceed threshold, the agent should proactively propose the matching tag (via `/docs-mark`) and update the registry (`registries/design.registry.json` or `registries/common.registry.json`) for reuse later.

package/harness/common/rules/team-flow-harness-state.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Harness State
 
-- `feature_list.json` — scope, không tự đánh done khi chưa verify
-- `progress.md` — handoff session tiếp theo
-- `registries/page-lifecycle.registry.json` + `base-docs/platform/toolchain/PAGE-LIFECYCLE.md` — stage cao nhất từng route; `portal:gen` / `portal:remove` / `portal:lifecycle sync` tự cập nhật
-- Khi command public cập nhật phase, ghi rõ: command, file đã đổi, verify đã chạy/chưa chạy, blocker còn lại.
+- `feature_list.json` — scope; do not mark done without verification
+- `progress.md` — handoff for the next session
+- `registries/page-lifecycle.registry.json` + `base-docs/platform/toolchain/PAGE-LIFECYCLE.md` — highest stage per route; `portal:gen` / `portal:remove` / `portal:lifecycle sync` update automatically
+- When a public command updates phase, record clearly: command, files changed, verify run or not, remaining blockers.

package/harness/common/skills/business-impact-review/SKILL.md

@@ -90,7 +90,7 @@ if CodeGraph available: changed symbols + callers + call graph — for repo X us
   open repo's index; unindexed repo → report `cd <root> && codegraph init`
 else: targeted repository search/read
 
-if bộ docs available: map process steps to CMP/CTR/FLOW docs via FLOWGRID_DOCS_ROOT
+if docs hub available: map process steps to CMP/CTR/FLOW docs via FLOWGRID_DOCS_ROOT
   (never CodeGraph for architecture Markdown)
 else: repository conventions/search
 

package/harness/common/skills/configure-repo-maps/SKILL.md

@@ -55,6 +55,6 @@ legacy ERP at D:\legacy\erp, key legacy-erp
 ## After Write
 
 1. Compare with `.flowgrid/config.json` (init SSOT): `flowgrid repo-maps check`.
-2. If paths conflict with init/harness MCP: `flowgrid repo-maps align` (member chốt từng hub `docs` / `tests`).
+2. If paths conflict with init/harness MCP: `flowgrid repo-maps align` (member confirms each hub `docs` / `tests`).
 3. One-way refresh from config: `flowgrid repo-maps sync --from-config` then `flowgrid harness sync`.
 4. Optional CodeGraph: `platform-dna codegraph:wire` · `codegraph init` per checkout.

package/harness/common/skills/docs-mark/SKILL.md

@@ -31,13 +31,13 @@ fallbacks.
 | UI | `registries/design.registry.json` | `#needs-component:` `#needs-ui:` `#shell:` |
 | Logic | `registries/common.registry.json` | `#common:*` `#needs-common:*` |
 
-Executable registry validation is **bộ code FE** (or product scripts on the
+Executable registry validation is **FE code repo** (or product scripts on the
 FE checkout). On docs hub:
 
 ```text
 if ArtifactGraph available:
   artifactgraph_allowlist_check(registryValidate|commonRegistry)
-  artifactgraph_recommend_command → hand off to bộ code FE
+  artifactgraph_recommend_command → hand off to FE code repo
 else:
   note pending FE registry validate; do not invent local shell fallbacks
 ```
@@ -58,8 +58,8 @@ else:
 
 ## Handoff
 
-bộ code FE / product: `flowgrid gen:dry` (or repo shim) after marks change,
-when that lane is available. Missing bộ code is a pending handoff, not a
+FE code repo / product: `flowgrid gen:dry` (or repo shim) after marks change,
+when that lane is available. Missing code repo is a pending handoff, not a
 docs failure.
 
 ## Compatibility

package/harness/docs/extracts/agent-design-context.md

@@ -26,8 +26,8 @@ Agents often read only `*.bundle.yaml` + `ir/design.yaml` and miss three indepen
 | --- | --- | --- | --- |
 | **L1** | `FLOW-*` · `common/user-flows/` | MD + **§6 `sequenceDiagram`** | Where the user goes across screens |
 | **L2** | `interactionCases` on bundle (optional) | YAML → split | One `W-*`: cases + per-case sequence |
-| **L3** | `design.stateMatrix` | YAML | Machine state/button matrix |
-| **L4** | bundle + `ir/design.yaml` + `01` | YAML | Fields, actions, apiRef, outcomes |
+| **L3** | `bundle.design.stateMatrix` | YAML on bundle → split | Machine state/button matrix |
+| **L4** | `bundle.design` + `01` | YAML on bundle → `ir/design.yaml` | Fields, actions, apiRef, outcomes |
 | **NFR** | `bundle.nfr` | MD bullets | Constraints on all cases |
 
 **Do not** put L2 single-screen branches into FLOW MD. **Do not** require L2 on trivial list-only GET screens.
@@ -70,9 +70,14 @@ interactionCases:
           ...
 ```
 
-**Split:** prose → `ir/spec.yaml` → `ir/generated/spec.md` (§ Interaction cases); diagrams only → `ir/design.yaml` → `ir/generated/design.md`.
+**Author here only** — on `feature.bundle.yaml`. **`flowgrid split`** partitions:
 
-**Codegen read order for L2:** `spec.md` prose + `design.md` mermaid + `stateMatrix` / `actions` — not FLOW.
+- prose (`description`, `policy`, …) → `ir/spec.yaml` → render `spec.md`
+- `sequenceDiagram` per item → `ir/design.yaml` → render `design.md`
+
+**Codegen read order for L2:** read split/render output (`design.md` + `stateMatrix` / `actions` on `ir/design.yaml`) — do not author L2 on IR.
+
+**Not FLOW** for L2 timelines.
 
 ---
 
@@ -94,7 +99,11 @@ For target leaf `W-*`:
 
 ## Audit (`flowgrid audit spec`)
 
-**Step 1 — policy confirm** when screen is complex and `interactionCases` missing:
+**Target file:** always **`*.bundle.yaml`** on the function leaf — **not** `ir/spec.yaml`, `ir/design.yaml`, or `ir/generated/*`.
+
+`engines/spec/lib/audit-bundle-gaps.mjs` parses the **bundle** and runs `auditInteractionCases(bundle)` (plus UX/DB/userFlows warnings). Patch findings on the **bundle**, then `split` → `render`.
+
+**Step 1 — policy confirm** when screen is complex and `interactionCases` missing on the **bundle**:
 
 - Emit `CONFIRM_INTERACTION_CASES_POLICY` in `confirms[]`.
 - Options: **(Recommended) required** — set `policy: required` + `items[]`; **skip** — `policy: skip` + `skipReason`; **Other** (free text).
@@ -117,8 +126,11 @@ Skip step 1 when `interactionCases.policy: skip` is already declared.
 | Design sequences | `ir/generated/design.md` |
 | API | `ir/generated/api.md` |
 
+**SSOT loop:** Review **`ir/generated/spec.md`** (read-only) → gaps → **`/update-spec`** patches **`*.bundle.yaml`** → `split` → `render`. Never edit `ir/spec.yaml`, `ir/design.yaml`, or generated MD. See **`ir-read-only.md`**. No routine `spec:merge`.
+
 ---
 
+
 ## One-line summary
 
 **L1:** `/user-flow` → `FLOW-*.md` + §6; leaf links via **`userFlows`**. **NFR:** mandatory read before design/API. **L2:** **`interactionCases`** on bundle → `spec.md` + `design.md`; never in FLOW.

package/harness/docs/extracts/extract-registry.docs.json

@@ -29,13 +29,15 @@
       ".cursor/extracts/agent-execution-protocol.md",
       ".cursor/extracts/common-scope.md",
       ".cursor/extracts/product-id-convention.md",
-      ".cursor/extracts/agent-design-context.md"
+      ".cursor/extracts/agent-design-context.md",
+      ".cursor/extracts/ir-read-only.md"
     ],
     "spec-core": [
       ".cursor/extracts/spec-core.md",
       ".cursor/extracts/common-scope.md",
       ".cursor/extracts/product-id-convention.md",
-      ".cursor/extracts/agent-design-context.md"
+      ".cursor/extracts/agent-design-context.md",
+      ".cursor/extracts/ir-read-only.md"
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",
@@ -54,6 +56,7 @@
     ],
     "update-spec": [
       ".cursor/extracts/update-spec-delta.md",
+      ".cursor/extracts/ir-read-only.md",
       ".cursor/extracts/wire-spec-feedback.md",
       ".cursor/extracts/qa-inbox.md"
     ]

package/harness/docs/extracts/ir-read-only.md

@@ -0,0 +1,42 @@
+# IR & generated markdown — read-only (SSOT = bundle)
+
+## Authoring SSOT (incl. L1/L2 added for agents)
+
+**Write on `*.bundle.yaml` only** — then `split` materializes IR:
+
+| Field | On bundle | After `split` (read-only) |
+| --- | --- | --- |
+| `userFlows`, `nfr`, `interactionCases` (full block) | top-level on bundle | partitioned → `ir/spec.yaml` + `ir/design.yaml` |
+| `design.stateMatrix`, `design.actions`, sections | `design:` on bundle | `ir/design.yaml` |
+
+**Never** create or edit `interactionCases` / `userFlows` first on `ir/spec.yaml` or `ir/design.yaml`. There is no separate IR authoring path for those fields.
+
+## Write path (single loop)
+
+1. **Author / patch** `*.bundle.yaml` on the function leaf (`/spec`, `/grill-*`, `/update-spec`, `/api-spec` for `01` only).
+2. **`flowgrid audit spec <bundle.yaml>`** — UX, DB, `userFlows`, **`interactionCases`** (`CONFIRM_INTERACTION_CASES_POLICY`), state/action checks all run on the **bundle file**, never on `ir/*`.
+3. **`flowgrid split`** → regenerates `ir/spec.yaml` + `ir/design.yaml` from bundle.
+4. **`flowgrid render`** → regenerates `ir/generated/*.md` for VitePress.
+
+**Do not** use `spec:merge` / `flowgrid merge` to “fix” review findings — patch the **bundle**, then split (+ render).
+
+## Read-only (agents and members)
+
+| Path | Role |
+| --- | --- |
+| `ir/spec.yaml` | Split output — business prose mirror. **Read only.** |
+| `ir/design.yaml` | Split output — tech IR. **Read only.** |
+| `ir/generated/spec.md` | **Primary human review** (VitePress). **Read only.** |
+| `ir/generated/design.md` | L2 sequence diagrams (render). **Read only.** |
+| `ir/generated/data-model.md`, `api.md` | Review helpers. **Read only.** |
+
+**[STRICTLY FORBIDDEN]** `Write` / patch on any `ir/*` or `ir/generated/*` file.
+
+## Review → fix loop
+
+1. Member runs docs site build (VitePress) and reads **`ir/generated/spec.md`** (and linked `design.md` / `api.md` when relevant).
+2. Gaps, typos, scope, stories, `interactionCases`, NFR → **`/update-spec`** (or `/spec` if greenfield rewrite).
+3. Agent patches **`*.bundle.yaml` only** → audit → split → render.
+4. Re-open VitePress page to confirm.
+
+Downstream codegen (`/prototype`, `/grill-dev`) **reads** `ir/design.yaml` (and ACP reads `ir/generated/design.md` for L2) — still **never writes** IR.

package/harness/docs/rules/agent-compliance.mdc

@@ -1,5 +1,5 @@
 ---
-description: Enforce physical interlocks for all bộ docs skills
+description: Enforce physical interlocks for all docs hub skills
 alwaysApply: true
 ---
 
@@ -24,3 +24,7 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 7. **ISOLATION:** Execute strictly within the invoked skill scope. **[STRICTLY FORBIDDEN]** to merge sibling features or output fake Markdown reports when YAML contracts are required.
 
 **Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). **IDs:** `product-id-convention.md` (`surfaceCode` + `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).
+
+**Harness language:** Agent instructions in `harness/**/skills` and `harness/**/rules` are **English**. Member-facing product prose (bundle summaries, UI copy) follows `docs-hub.locale.yaml` / `/spec` — not the skill language.
+
+**Docs hub IR:** SSOT write = **`*.bundle.yaml`** → `flowgrid split` → `flowgrid render`. **`ir/spec.yaml`**, **`ir/design.yaml`**, and **`ir/generated/*`** are **read-only** for agents and members; review fixes → **`/update-spec`** on the bundle (`ir-read-only.md`).

package/harness/docs/rules/docs-hub.mdc

@@ -1,12 +1,12 @@
 ---
-description: bộ docs MCP — arc42/C4 docs index; opt-in skill use
+description: docs hub MCP — arc42/C4 docs index; opt-in skill use
 alwaysApply: false
 ---
-# docs-hub (bộ docs)
+# docs-hub (docs hub)
 
 Use `/docs-hub` for targeted ID, dependency, link, journey, and chapter queries.
 
-The docs repo owns architecture/product Markdown. bộ docs indexes and validates
+The docs repo owns architecture/product Markdown. docs hub indexes and validates
 only.
 
 - In docs: `FLOWGRID_DOCS_ROOT` points to the current docs repo.
@@ -21,14 +21,14 @@ only.
 4. Run `flowgrid_docs_orphans` and `flowgrid_docs_validate_links` before claiming completeness.
 5. Use `flowgrid_docs_user_flows` before reading all journey files.
 
-Do not require bộ docs for architecture work: if the MCP is unavailable, inspect
+Do not require docs hub for architecture work: if the MCP is unavailable, inspect
 the repository Markdown directly or explain how to run project-local setup.
 
 ## Index routing
 
 Cross-repo index is per-repo, never one giant parent-workspace graph:
 
-- Architecture ID / C4 path → bộ docs (`FLOWGRID_DOCS_ROOT`). Never CodeGraph for
+- Architecture ID / C4 path → docs hub (`FLOWGRID_DOCS_ROOT`). Never CodeGraph for
   architecture Markdown.
 - IR / registry / generation → pointer kits when present
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
@@ -40,7 +40,7 @@ Cross-repo index is per-repo, never one giant parent-workspace graph:
 - ArtifactGraph stays local-only; it is never a shared index for other repos.
 
 ArtifactGraph is optional. If `@platform/artifactgraph` is not configured,
-unavailable, or fails, bộ docs must continue with targeted local search and
+unavailable, or fails, docs hub must continue with targeted local search and
 scoped Markdown reads; the missing optional must never abort the run. Assign one
 stable `runId` per run. Count each successful fallback file read and its exact
 raw byte length. After the fallback completes, emit exactly one

package/harness/docs/rules/flowgrid-process.mdc

@@ -1,9 +1,9 @@
 ---
-description: FlowGrid bộ process — business-process-trace (brownfield) and impact review (opt-in)
+description: FlowGrid process hub — business-process-trace (brownfield) and impact review (opt-in)
 alwaysApply: false
 ---
 
-# FlowGrid bộ process
+# FlowGrid process hub
 
 - `/business-process-trace`: observed brownfield process through code/evidence.
 - `/business-impact-review`: read-only vertical × horizontal blast-radius review.
@@ -14,11 +14,11 @@ alwaysApply: false
 Checkout routing (`cross-repo-index.mdc`): `legacy-*` →
 `legacy-repos.local.json`; other system ids → `platform-repos.local.json`.
 Ambiguous or missing keys → ask / Gaps + `/configure-repo-maps` — never invent
-paths. FlowGrid bộ process does not write cross-repo CodeGraph MCP entries.
+paths. FlowGrid process hub does not write cross-repo CodeGraph MCP entries.
 
-CodeGraph, bộ docs and ArtifactGraph are optional accelerators; route them per
+CodeGraph, docs hub and ArtifactGraph are optional accelerators; route them per
 repo/intent as defined in `cross-repo-index.mdc` (architecture →
-bộ docs, IR/registry → pointer kits, symbols of repo X → `codegraph-<key>` for
+docs hub, IR/registry → pointer kits, symbols of repo X → `codegraph-<key>` for
 X). Missing tools must fall back to targeted local search/model analysis and
 explicit residual gaps. Per run/optional pair, count actual successful file reads and raw context
 bytes, then emit exactly one `flowgrid.missing-optional` event conforming to

package/harness/docs/rules/team-flow-grill.mdc

@@ -1,5 +1,5 @@
 ---
-description: bộ docs grill metadata — list/form/detail profiles
+description: docs hub grill metadata — list/form/detail profiles
 globs: surfaces/**
 alwaysApply: false
 ---

package/harness/docs/rules/team-flow-spec.mdc

@@ -1,5 +1,5 @@
 ---
-description: bộ docs docs spec/grill/update workflow
+description: docs hub docs spec/grill/update workflow
 globs: surfaces/**, legacy-dynamics/**
 alwaysApply: false
 ---
@@ -24,12 +24,12 @@ Shared: resolve skill `extractBundle` → `.cursor/extracts/extract-registry.doc
 
 ## Pipeline
 
-1. **`/spec`** — `*.bundle.yaml` only (`feature.bundle.yaml` template; not `design-spec.yaml`). Include `successMetrics` / `nonGoals` when known. Per-zone: DSL/registry → bundle; `audit spec` `gaps[]` + non-blocking `warnings[]`. BA deliverable: `ir/generated/spec.md` after split+render. No `gen` / `codegen` in first pass.
+1. **`/spec`** — **write** `*.bundle.yaml` only → `split` → `render`. **Read-only:** `ir/spec.yaml`, `ir/design.yaml`, `ir/generated/*` (see `ir-read-only.md`). BA reviews **`ir/generated/spec.md`** on VitePress; gaps → **`/update-spec`** (not direct IR edits, not `spec:merge`). No `gen` / `codegen` in first pass.
 2. **`/grill-bqa`** — UI, acceptance, breadcrumb, delete rules.
-3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit bộ code FE dry-run handoff.
+3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit FE code repo dry-run handoff.
 4. **`/grill-docs`** — optional reconcile when BQA↔Dev contradict.
-5. **`/update-spec`** — controlled delta + `#update:*` (legacy trace → `/legacy /spec` hoặc delta legacy trong cùng skill; not full rewrite).
-6. **`/prototype`** — FE-lane handoff only after bộ code dry-run passes.
+5. **`/update-spec`** — controlled delta + `#update:*` (legacy trace → `/legacy /spec` or legacy delta in the same skill; not full rewrite).
+6. **`/prototype`** — FE-lane handoff only after code repo dry-run passes.
 
 - Render: `docs_render` / `flowgrid render` (pnpm fallback during transition)
 - **[STRICTLY FORBIDDEN]** Do NOT build UI prototypes, backend implementations, live APIs, or full E2E/unit tests during the spec/grill phase.

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

@@ -12,7 +12,7 @@ extractBundle: architecture-core
 
 **Audit Interlock:** Run `flowgrid audit legacy <target-id>`. Consume JSON gap report to verify mapping or prompt member if index is missing.
 
-**Handoff SSOT spec:** Sau adopt, member drill [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (không nhảy thẳng bundle không có ID trong inventory).
+**Handoff SSOT spec:** After adopt, member drills [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (do not jump straight to a bundle whose ID is not in the inventory).
 
 **Inventory template:** `.cursor/extracts/tpl-adoption-inventory.md` — section layout + **user-flow placement tiers** (cross-surface → `architecture/03-user-flows/`).
 

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

@@ -22,7 +22,7 @@ disable-model-invocation: true
   | Portal specs changed / merge deferred child functions | `/api-update` |
   | BE-only requirement (no FE contract change) | `/api-update --be-only` |
   | Spec exists but not codegen-ready / `approval.status` not `approved` | `/grill-api-spec` |
-  | `approval.status: approved` + explicit implement request | bộ code BE `/api` (switch to BE repo skill — NOT this skill) |
+  | `approval.status: approved` + explicit implement request | BE code repo `/api` (switch to BE repo skill — NOT this skill) |
 
 - **[MANDATORY]** Locate `01-backend-spec.yaml` under: `…/api/<seq>/` (screen leaf), `…/common/yaml/<slug>/`, or any surface leaf dedicated to external-channel APIs.
 - **[STRICTLY FORBIDDEN]** Do NOT skip `/grill-api-spec` for new features, cross-portal, or legacy-derived contracts.
@@ -35,5 +35,5 @@ Doc: `docs/operational/TEAM-AI-BACKEND-WORKFLOW.md`
 ## Verification Checklist
 
 - [ ] Checked `01-backend-spec.yaml` presence, `approval.status`, and `feature.source.kind`.
-- [ ] Correctly routed to contract skills vs bộ code BE `/api`.
+- [ ] Correctly routed to contract skills vs BE code repo `/api`.
 - [ ] Did NOT generate any content from this routing skill.

package/harness/docs/skills/build-templates/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: true
 
 # /build-templates — Codebase Scanning & Template Scaffolding
 
-**Purpose:** Synchronize Docs Hub (bộ docs) with actual FE/BE codebase reality by scanning code and scaffolding customized `.ejs` templates.
+**Purpose:** Synchronize Docs Hub (docs hub) with actual FE/BE codebase reality by scanning code and scaffolding customized `.ejs` templates.
 
 ---
 

package/harness/docs/skills/call-external/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # #call-external — Third-Party Integration Tag
 
-Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+Used from: `/api-spec`, `/grill-api-spec`, and BE code repo `/api` when this hashtag is present.
 
 ---
 

package/harness/docs/skills/cross-entity-service/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # #cross-entity-service — Cross-Aggregate Orchestration Tag
 
-Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+Used from: `/api-spec`, `/grill-api-spec`, and BE code repo `/api` when this hashtag is present.
 
 ---
 

package/harness/docs/skills/db-erd/SKILL.md

@@ -10,14 +10,14 @@ extractBundle: architecture-core
 
 # /db-erd — Business Data Model (ERD)
 
-**Phase:** **0 Architecture** — sau `/overview`, `/module`, `/user-flow` khi có entity/bảng mới. **Trước** `/spec` leaf.
+**Phase:** **0 Architecture** — after `/overview`, `/module`, `/user-flow` when new entities/tables appear. **Before** any `/spec` leaf.
 
 **Hub SSOT:** [architecture-data.md](../../../docs/workflows/architecture-data.md)
 
 **Target Path:** `<LCA>/common/db-erd.md` — LCA resolved from `.cursor/extracts/common-scope.md`.
 VitePress/publish menu label: **`db-erd`** (not the H1 heading).
 
-**Handoff:** Design `/spec` đọc file này; chi tiết cột → `design.sections[].db` + `spec.entities` — **không** duplicate full ER trên bundle.
+**Handoff:** Design `/spec` reads this file; column detail → `design.sections[].db` + `spec.entities` — do **not** duplicate the full ER on the bundle.
 
 ---
 

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

@@ -22,7 +22,7 @@ SSOT flow: `docs/workflows/grill-and-human-review.md` · close checklist: `docs/
   | Gap context | Route to |
   | --- | --- |
   | Overview / surface / CMP `index.md` PRD sections | `/grill-hub-prd` |
-  | Sổ rủi ro quota / hạn mức / peak | `/risk-register` |
+  | Consolidated risk register (quota / limits / peak) | `/risk-register` |
   | UI acceptance, copy, validation, UX affordance | `/grill-bqa` |
   | `bundle.gen`, codegen profile, `#gen:*`, endpoint `action` on `01` | `/grill-dev` |
   | BQA ↔ Dev contradiction on same bundle | `/grill-docs` |