@shanyucoder/flowgrid 0.1.0

package/harness/fe/extracts/artifactgraph-hooks-fe.md

@@ -0,0 +1,15 @@
+# ArtifactGraph — frontend hooks
+
+- Resolve known shells, widgets, common components, and UI patterns from the
+  current FE repo's local index only.
+- Run FE dry generation before write generation when both keys exist.
+- **Code size discipline:** Enforce `platform-code-size.mdc` (~200 lines/file, ~20 lines/func). Automatically split pages/composables/components during bộ code generation.
+- Full product registry/IR remains in docs. bộ code reads it through the
+  member-selected `FLOWGRID_DOCS_ROOT`; ArtifactGraph does not follow that
+  pointer.
+- Architecture ID / C4 lookups go to bộ docs (`FLOWGRID_DOCS_ROOT`). Symbol /
+  call-graph lookups go to the target repo's `codegraph-<key>` MCP — Platform
+  DNA owns that auto-wire, not ArtifactGraph.
+- Promote canonical registry changes in docs; keep only FE-local
+  allowlists/templates in the FE repo.
+- Leave `/prototype`, `/wire`, `/unit`, and `/test` phase skills product-owned.

package/harness/fe/extracts/risk-classes.md

@@ -0,0 +1,69 @@
+# Risk classes checklist
+
+Use with [SKILL.md](SKILL.md). Tick each class against the vertical + horizontal maps.
+
+## AuthZ / IDOR
+
+- [ ] Resource by id checked against current tenant (`storeId` / `hotel_id` from trusted source)
+- [ ] Body/query `store_id` cannot switch store context for another hotel
+- [ ] Admin/batch skip of ownership is intentional and not reachable from store UI JWT
+- [ ] Report/filter/list-by-ids rejects foreign ids (404), not only empty data
+
+## Request bag / contract
+
+- [ ] ID lists use **named keys** (`ids`, `arrId`, `survey_ids`, `scenarioList`) — not bare `[1,2]` → `0=1`
+- [ ] `$request->all()` / `query()` not treated as “array of business ids”
+- [ ] Middleware `merge` fields (`store_id`, `storeId`, …) stripped or unused when parsing id lists
+- [ ] Allowlist vs denylist clear for context keys vs business keys
+
+**Context denylist (typical after ScenarioAuthentication):**  
+`store_id`, `storeId`, `service_id`, `serviceId`, `m_service_id`, `isAdmin`, `apiKey`, pagination/date noise if normalizing “all numbers”.
+
+**ID allowlist (prefer):**  
+`ids`, `arrId`, `survey_ids`, `scenario_ids`, `scenarioList`
+
+## Trust boundary / proxy
+
+- [ ] Upstream 404 stays 404 (or explicit not-found JSON), not 200 + empty Resource
+- [ ] FE `throwError` / `createError` aligned with real HTTP status
+- [ ] JWT/`attributes` preferred over client-supplied tenant ids
+
+## Over-broad parse
+
+- [ ] No “every positive int in the array is an id” unless array is already allowlisted
+- [ ] CSV/string explode paths do not swallow unrelated query params
+
+## Null / empty
+
+- [ ] Missing model → 404 vs empty collection semantics documented
+- [ ] `whereIn([], …)` / empty id list behavior safe (no accidental match-all)
+- [ ] Optional relations null-safe before property access
+
+## Error collapsing
+
+- [ ] Distinct failures keep distinct outcomes (authZ 404 ≠ relation-exists ≠ server error)
+- [ ] Controller does not always return one business message when helper returns `true` for multiple reasons
+
+## Hardcode / magic
+
+- [ ] No production hardcode of hotel/store/survey/scenario ids
+- [ ] Magic status/codes named or constanted when added
+
+## Async / Jobs / Events
+
+- [ ] Job payload carries needed tenant/service context (or reloads safely)
+- [ ] Job path does not assume HTTP middleware ran (`merge`, `attributes->storeId`)
+- [ ] Retries are idempotent for writes/deletes
+- [ ] Failed pre-check cannot leave partial side effects
+- [ ] `dispatch` callers listed in horizontal table
+
+## Business rules
+
+- [ ] Relation/existence gates: false positive and false negative both considered
+- [ ] Delete/update constraints still correct after ownership changes
+- [ ] Soft-deleted rows excluded/included as product intends
+
+## Data / transactions
+
+- [ ] Multi-step delete/update atomic where required
+- [ ] Soft delete vs force delete consistency with “exists” checks

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

@@ -0,0 +1,24 @@
+---
+description: Route cross-repo evidence to the owning per-repo index
+alwaysApply: true
+---
+
+# Cross-repo index routing
+
+- Architecture IDs and Functions/W-* paths belong to bộ docs 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
+  `FLOWGRID_DOCS_ROOT`.
+- For symbols or call graphs in repo X, call the Platform DNA-wired
+  `codegraph-<repo-key>` MCP whose `--project-root` is checkout X. Never query
+  the index of the currently open repo for another repo.
+- Cross-index MCP entries come from Platform DNA using
+  `platform-repos.local.json` / `legacy-repos.local.json`. Do not ask members to
+  hand-edit `.cursor/mcp.json`, and never commit machine-local roots.
+- Only use a checkout-specific CodeGraph server when that checkout exists and
+  already has `.codegraph/`. If it is not indexed, report:
+  `cd <root> && codegraph init`.
+- Never initialize or scan a workspace parent. Keep one CodeGraph index per
+  repo. ArtifactGraph remains local to the current repo and is never a shared
+  docs or cross-repo index.

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

@@ -0,0 +1,21 @@
+---
+description: bộ test optional accelerator fallback and event contract
+alwaysApply: true
+---
+
+# bộ test 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
+stable `runId` per run and emit exactly one `flowgrid.missing-optional` event per
+`runId` + optional pair, after fallback completes; deduplicate all retries.
+
+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.
+
+Events must conform to
+`.cursor/schemas/flowgrid-test/missing-optional-event.schema.json`. Metrics count only
+successful file reads and exact raw bytes read into context as `fileReads` and
+`contextBytes`. Never estimate tokens, reads, bytes, or savings.

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

@@ -0,0 +1,43 @@
+---
+description: Platform — 200 lines/file hard cap, ~20 lines/function; split when exceeded
+globs: "{app,src,pages,components,composables,hooks,services,stores,models,validations,tests}/**/*.{vue,ts,tsx}"
+alwaysApply: false
+---
+
+# Code Size
+
+## Limits
+
+| Metric | Hard cap | Stretch max | Exempt |
+|--------|----------|-------------|--------|
+| Lines / file | 200 | 220–250 (edge case, <10% files) | `*.mock.ts` |
+| Lines / function | ~20 | — | — |
+
+Mock files (`*.mock.ts`) are exempt from both line limits and unit test coverage
+requirements — they are temporary and will be removed when wiring real APIs.
+
+## Proactive Component Splitting
+
+Do not wait until a file reaches 200 lines. Proactive component splitting MUST be decided during Spec review:
+
+- **Single Main Block** (e.g. 1 Table list): Use the standard page template without splitting.
+- **Multiple Blocks (≥2 blocks)** (e.g. 1 Card + 1 Tab, or 2 Tables): Scaffold a separate component for each block; the Page file acts solely as an orchestrating layout. Tag each block with `#needs-component: WidgetName`.
+- **Form Component Interlock**: Whenever a **Form** appears in the Spec (whether on a dedicated Create/Edit page or nested inside a Modal/Tab):
+  - **[MANDATORY]** Extract the Form into a fully self-contained component (UI component, logic hook/composable, Zod schema, and Service client).
+  - The component must be fully portable and reusable across contexts.
+  - The Page file acts strictly as a host container.
+
+Split in the same PR when exceeded line limits.
+
+## Next.js ↔ Nuxt4 split convention
+
+| Concern | Nuxt4 composable | Next.js hook |
+|---------|-----------------|--------------|
+| List data + pagination | `composables/xxx/useXxxList.ts` | `hooks/xxx/useXxxList.ts` |
+| Column definitions | `composables/xxx/useXxxColumns.ts` | `hooks/xxx/useXxxColumns.ts` |
+| Filter config + search/reset | `composables/xxx/useXxxFilters.ts` | `hooks/xxx/useXxxFilters.ts` |
+| Export logic | `composables/xxx/useXxxExport.ts` | `hooks/xxx/useXxxExport.ts` |
+| Form submit | `composables/xxx/useXxxForm.ts` | `hooks/xxx/useXxxForm.ts` |
+
+No padding files with blank lines. Detailed component-split conventions are
+product-owned because Nuxt and Next layouts differ.

package/harness/fe/rules/platform-design-vocabulary.mdc

@@ -0,0 +1,33 @@
+---
+description: Registry-backed FE vocabulary for generated and handoff code
+globs: "{app,src,pages,components,composables,hooks,services,models,validations,registries}/**/*.{vue,ts,tsx,json}"
+alwaysApply: false
+---
+
+# Design vocabulary
+
+SSOT: `registries/design.registry.json` · validate with `flowgrid registry`.
+
+## Hashtags (grill → `tags:`)
+
+| Prefix | Example |
+|--------|---------|
+| `#shell:` | Registry-defined page/list shell |
+| `#pattern:` | `CRUD` |
+| `#ui:` | shadcn primitive |
+| `#widget:` | form field |
+| `#render:` | `text`, `chip` |
+| `#style:` | `compact`, `flat` |
+| `#needs-ui:` | planned widget — prototype implements |
+| `#split-hook:` | `columns`, `filters`, `export`, `form-sections` — hint codegen to split |
+
+Shell names and custom-template behavior are adapter/product registry data. Do
+not assume a Nuxt `.vue` shell in a Next.js target or vice versa.
+
+## Grill
+
+1. BA bullet → `lookupAlias()` in registry
+2. Low confidence → ask member
+3. `npm run codegen:dry -- --id …` must pass.
+
+Do not invent component names outside the selected adapter registry.

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

@@ -0,0 +1,32 @@
+---
+description: /prototype, /grill-prototype — UI prototype with mock API boundary
+globs: "{pages,components,composables,mocks,src/app,src/components,src/hooks}/**/*.{vue,ts,tsx}"
+alwaysApply: false
+---
+
+# Team Flow — Prototype
+
+Active: `/prototype` · `/grill-prototype` — **một** command / session.
+
+| Command | Skill |
+|---------|-------|
+| `/prototype` | `.cursor/skills/prototype/SKILL.md` |
+| `/grill-prototype` | `.cursor/skills/grill-prototype/SKILL.md` |
+
+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.
+
+## Thứ tự
+
+0. `/gen-common --surface=…` rồi `/gen-common --module=CMP-…` nếu hub có `common/` — gen molecule/shell dùng chung trước.
+1. Quét `#needs-component` / custom-render tags — chỉ tạo component còn thiếu.
+2. `npm run codegen -- --id W-…` (hoặc MCP `gen`) — đọc `…/code/{W-…}/generated/HANDOFF.md`.
+3. Vá slot · auth bypass · gap; **không** sửa YAML business trên hub khi prototype.
+
+- 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

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

@@ -0,0 +1,27 @@
+---
+description: Unit Test — dev lane Vitest (/unit → /grill-unit)
+globs: "{src,composables,hooks,services,models,validations,utils,stores,tests/unit}/**/*.{ts,tsx,vue}"
+alwaysApply: false
+---
+
+# /unit · /grill-unit — Dev lane
+
+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
+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
+  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`

package/harness/fe/skills/build-template-code/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: build-template-code
+description: /build-template-code — Scaffolds custom codegen templates and registries based on platform-dna configuration.
+disable-model-invocation: true
+---
+
+# /build-template-code — Custom Template Scaffolding
+
+## Context - Action - Constraint (CAC)
+
+### Context
+Member wants to automatically generate or update frontend/backend codegen templates for a repository using `platform-dna` presets and source models.
+
+### Action
+```bash
+# Dry-run inspection
+flowgrid build-template-code --dry-run
+
+# Scaffolding templates and registry entries from Golden Sample
+flowgrid build-template-code --sample=src/pages/users/UserList.vue
+
+# Force overwrite existing custom templates
+flowgrid build-template-code --force
+```
+
+#### CLI Parameters
+- `--dry-run`: Preview files to be scaffolded/written without system mutation.
+- `--force`: Overwrite existing templates and registries.
+- `--merge`: Merge new registry entries into `registries/design.registry.json` (default).
+- `--output <dir>`: Target directory for generated templates (default: `adapters/<framework>/codegen/templates/custom`).
+
+#### Internal Pipeline
+1. **Scan Project**: `src/template-builder/scanProject.ts` reads `platform-dna` to identify source components/controllers.
+2. **Model Extraction**: Use AST/regex parsers to extract class names, routes, props, and build intermediate JSON models.
+3. **Template Generation**: `generateTemplate.ts` produces `.hbs` (FE) and `.scriban` (BE) files from extracted models.
+4. **Registry Update**: `writeRegistry.ts` creates or merges `custom.registry.json`.
+5. **Report**: Emit summary list of generated templates and registry entries.
+
+### Constraints
+- **[MANDATORY]** Validate `platform-dna` configuration prior to execution.
+- **[STRICTLY FORBIDDEN]** Do NOT overwrite modified custom templates without the `--force` flag.
+- **[MANDATORY]** Ensure generated template tags match the host framework's UI and routing patterns.

package/harness/fe/skills/gen-common/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: gen-common
+description: >-
+  /gen-common — generate shared UI from bộ docs common specs before
+  /prototype. Covers surface common (surfaces/<surface>/common) and
+  module common (surfaces/<surface>/CMP-*/common). Use when
+  bootstrapping DataListPage, MoStatusChip, or CMP-level shared widgets.
+disable-model-invocation: true
+---
+
+# /gen-common — Shared UI before /prototype
+
+**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs`  
+Not synced for `dotnet-line`.
+
+Skill is **`/gen-common`**, not `/common` — `common` is the docs folder name (and there are three of them).
+
+| Scope | Docs path | Flag |
+|-------|-----------|------|
+| Platform | `surfaces/common` | `--surface=common` |
+| Surface | `surfaces/<surface>/common` | `--surface=admin-web` |
+| Module | `surfaces/<surface>/<CMP-*>/common` | `--module=CMP-ADM-009` |
+
+Run **surface** first, then **module**, then `/prototype` for screens.
+
+## IR
+
+```text
+…/common/yaml/<slug>/ir/design.yaml   # tech — Read entire file
+…/common/yaml/<slug>/ir/spec.yaml     # prose only — do not gen from this
+```
+
+Read the **entire** `ir/design.yaml`. Missing design → STOP, hand off to docs `/common-spec` + `flowgrid split` (do not invent yaml). Prose-only `common/processes` (FLOW) is not `/gen-common` input. Thin design is OK for tokens; do not page-gen common IRs.
+
+**Docs hub is read-only.** Never Write common bundles/`ir/*` on the docs hub.
+
+Do **not** run `flowgrid gen --id common-list-page`. Page gen skips all three common trees.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating common IR (`ir/design.yaml`).
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+## Workflow
+
+```bash
+npm run codegen:common:dry -- --surface=admin-web --json
+npm run codegen:common -- --surface=admin-web
+npm run codegen:common:dry -- --module=CMP-ADM-009 --json
+npm run codegen:common -- --module=CMP-ADM-009
+
+# Fallback:
+flowgrid gen-common:dry --adapter=nextjs --docs-root=/path/to/docs -- --surface=admin-web --json
+flowgrid gen-common --adapter=nextjs --docs-root=/path/to/docs -- --module=CMP-ADM-009
+flowgrid gen-common:dry -- --id common-status-chip --surface=admin-web
+```
+
+`common-gen` is an alias of `gen-common`.
+
+1. Choose scope (`--surface` xor `--module`, or `--surface=… --all-modules`). Do not guess when several surfaces exist.
+2. Dry `--json`. Kinds: `tokens` / `policy` / `molecule` / `shell` / `flow`.
+3. Write stubs + upsert `registries/common.registry.json`. Keep existing files unless `--force`.
+4. Implement `action: implement` from **`ir/design.yaml`** (tokens/policy as constraints). shadcn compose when `components.json` exists.
+5. Surface emit → molecules/organisms. Module emit → `src/components/modules/<cmp-…>/` (namespaced, no overwrite of surface shells).
+6. Re-run dry until emit entries are `implemented`.
+7. `/prototype` for `CMP-*` screens.
+
+## Kind handling
+
+| Kind | Emit? | Agent |
+|------|-------|--------|
+| `tokens` / `policy` | no | Apply while implementing others |
+| `molecule` | yes | Compose primitive → molecule |
+| `shell` | yes | After `dependsOn` molecules |
+| `flow` | sometimes | delete-flow wires ConfirmDialog; import-csv emits `MoImportCsv` |
+| `skip` | no | Backend folders (`common-api`, `backend-core-services`) |
+
+## Do not
+
+- Page-gen common IRs or invent routes from them.
+- Copy platform `surfaces/common` over a surface overlay that already exists.
+- Emit module widgets onto surface paths (`DataListPage`, `MoStatusChip`).
+- Rewrite unrelated feature screens here.
+
+## 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`).

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

@@ -0,0 +1,41 @@
+---
+name: grill-prototype
+description: /grill-prototype — FE grill gate before /prototype generation.
+disable-model-invocation: true
+---
+
+# /grill-prototype
+
+**Owner:** bộ code · optional local ArtifactGraph allowlist check before dry-gen.
+
+## Target / ID Resolution Rule
+
+- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- **Read the entire `ir/design.yaml`** on the screen leaf (`…/CMP-*/<NN…>/ir/design.yaml`) before dry-gen. Do not skim keys from a feature bundle. Do **not** use `01-backend-spec.yaml` as FE input.
+- Docs hub is **read-only**. Dry-gen failure (missing design / `codegen.profile`) → STOP; do not patch docs.
+- After dry-gen, HANDOFF `#needs-component` is filled in `/prototype` using the FE shadcn skill when `components.json` exists (primitives via `shadcn add`, `Mo*` composed — see `/prototype`). Surface/module commons must already exist via `/gen-common`.
+- Do NOT demand full surface/module filesystem paths from the user if an ID is given.
+
+```text
+if local ArtifactGraph available: check the FE repo's allowlist for genDry
+else: npm run codegen:dry -- --id …
+```
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating `ir/design.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   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
+in other repos → `codegraph-<key>` only.
+
+Missing ArtifactGraph never blocks the grill. Complete the deterministic dry
+generation fallback first, then follow
+`.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.
+
+Do not execute flowgrid docs scripts from the FE repo.

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

@@ -0,0 +1,32 @@
+---
+name: grill-test
+description: /grill-test — FE grill gate before Playwright generation.
+disable-model-invocation: true
+---
+
+# /grill-test
+
+**Owner:** bộ test (`--type=fe`)
+
+After `/test`. Plan YAML remains on the tests hub (`/grill-testcase`).
+
+Route Functions/W-* evidence through bộ docs, plans/docs through
+`FLOWGRID_TESTS_DOC` / `FLOWGRID_DOCS_ROOT`, and repo-X symbols through its
+Platform DNA-wired `codegraph-<repo-key>` server. Never substitute the current
+repo index for another checkout or initialize a workspace-parent graph.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: recommend/check testcase gen (this repo)
+else: local deterministic search, then flowgrid testcase:gen:dry …
+```
+
+ArtifactGraph never follows `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC`; plan
+YAML and docs evidence flow only through those bộ test pointers.
+
+Use one stable `runId` per run. When ArtifactGraph is missing, finish the local
+fallback before emitting exactly one `flowgrid.missing-optional` event for that
+`runId` + `artifactgraph`; retries must not emit again. Conform to
+`.cursor/schemas/flowgrid-test/missing-optional-event.schema.json` and include only
+actual successful `fileReads` and exact raw `contextBytes`, never estimates.

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

@@ -0,0 +1,31 @@
+---
+name: grill-unit
+description: /grill-unit — FE grill gate before /unit generation.
+disable-model-invocation: true
+---
+
+# /grill-unit
+
+**Owner:** bộ code · optional local ArtifactGraph allowlist check before unit dry-gen.
+
+```text
+if local ArtifactGraph available: check the FE repo's allowlist for unitGenDry
+else: npm run codegen:unit:dry -- --id …
+```
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating codegen manifests.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   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
+in other repos → `codegraph-<key>` only.
+
+Missing ArtifactGraph never blocks the grill. Complete the deterministic dry
+generation fallback first, then follow
+`.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.

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

@@ -0,0 +1,48 @@
+---
+name: model
+description: /model — Zod models and TS types in models/ / validations/ (bộ code FE).
+disable-model-invocation: true
+---
+
+# /model — FE contract models
+
+**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs`  
+Not synced for `dotnet-line` (WinForms contracts live outside Zod `models/`).
+
+## Scope
+
+Write/update **Zod schemas + TS types** under `models/` and `validations/` from
+Docs hub (`FLOWGRID_DOCS_ROOT`): **Read the entire `ir/design.yaml`**. Do not cherry-pick `entities`/`api` keys from the bundle or from `ir/spec.yaml` prose.
+
+| Load | Do not load |
+|------|-------------|
+| Entire feature `ir/design.yaml` | `ir/spec.yaml` prose, generated `*.md`, `*.bundle.yaml` |
+| Target files under `models/`, `validations/` | Trace, full `bundle.legacy` unless gap |
+| Progressive path resolve only if FE↔BE needed | Full `legacy-api-migration` dumps |
+
+## Workflow
+
+1. Resolve feature via `--id` / `--spec` through `FLOWGRID_DOCS_ROOT`
+   (never CodeGraph or ArtifactGraph for architecture/registry).
+   (same docs-root rules as `/prototype`; never sibling inference)
+   - If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+     configuration (`platform-dna`) to resolve the docs hub path.
+     Platform DNA discovery is slower and more error-prone, so always prefer
+     an explicit `FLOWGRID_DOCS_ROOT` when available.
+2. Align `models/` + `validations/` with entities/api in the IR
+3. Do not rewrite unrelated UI or API server code here
+
+## Handoff
+
+→ `/wire` when forms/services need the updated schemas  
+→ `/api` (bộ code BE) when the backend contract must catch up
+
+## Accelerators (optional)
+
+```text
+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,
+not through ArtifactGraph.

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

@@ -0,0 +1,100 @@
+---
+name: prototype
+description: /prototype — UI from FLOWGRID_DOCS_ROOT ir/design.yaml with mock API via bộ code.
+disable-model-invocation: true
+---
+
+# /prototype — UI Prototype (Mock API Boundary)
+
+**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs` | `dotnet-line`
+
+## Artifact & Target ID Resolution Rule
+
+- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- Agent MUST use `--id` or resolve `surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml` via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (same leaf as the bundle; API trio is sibling `api/<seq>/`, not this file).
+- Prerequisite: `/gen-common` when `surfaces/<surface>/common` (or `CMP-*/common`) exists — generate shared molecules/shells **before** this skill.
+- Do NOT demand full filesystem paths from the user if an ID is given.
+
+```text
+surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml
+# e.g. …/CMP-ADM-009/01/01/01/ir/design.yaml
+```
+
+Read the **entire** `ir/design.yaml` (script + agent inspection). Do not filter keys from `*.bundle.yaml`. **`ir/spec.yaml`** is business prose only.
+
+**Docs hub is read-only for this skill.** Never Write/patch `*.bundle.yaml`, `ir/*`, or any file under `FLOWGRID_DOCS_ROOT`. Missing `ir/design.yaml`, empty `codegen.profile`, or `flowgrid gen` failure → **STOP**, quote the CLI error, hand off to docs-hub `/grill-dev` (or `/spec`). Do not invent SSOT to make gen pass. Login/forgot/reset must be `codegen.profile: auth` (not `create`) or gen writes `(dashboard)`.
+
+Do not invent sibling docs-hub paths. Pass `FLOWGRID_DOCS_ROOT` or `--docs-root`.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   registry/IR pointer for locating `ir/design.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+## Route
+
+Architecture/C4 → bộ docs (`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
+only.
+
+## Workflow
+
+```bash
+npm run codegen:dry -- --id W-AD-AUTH-001
+npm run codegen -- --id W-AD-AUTH-001
+
+# Fallback direct CLI if wrappers missing:
+flowgrid gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+
+flowgrid gen:dry --adapter=nextjs -- --spec ir/design.yaml
+flowgrid gen --adapter=nextjs -- --spec ir/design.yaml
+flowgrid gen:dry --adapter=dotnet-line -- --spec ir/design.yaml
+flowgrid gen --adapter=dotnet-line -- --spec ir/design.yaml
+flowgrid registry --adapter=dotnet-line
+```
+
+You MUST run `/gen-common` for this surface (then `--module=CMP-…` if the module has `common/yaml`) when those trees exist, then run the codegen script (`npm run codegen` or `flowgrid gen`) FIRST to generate the skeleton from **design IR**, before filling gaps **in the FE repo only**.
+
+## Shadcn/ui skill (FE repo only)
+
+When the FE checkout has `components.json`, the member should have installed [shadcn/ui skills](https://ui.shadcn.com/docs/skills) (`pnpm dlx skills add shadcn/ui`). That skill owns **primitives, theming, `shadcn add/search/info`**. This skill owns **IR → gen → slots**.
+
+For each HANDOFF / `#needs-component: Mo…` after gen:
+
+1. Run or read `shadcn info --json` (framework, aliases, installed set, base `radix|aria`).
+2. `shadcn search` / docs: if the gap is a missing **primitive**, `shadcn add` it — do **not** hand-roll Button/Dialog/Table.
+3. Implement `Mo*` as **composition** of those primitives (FieldGroup for forms, semantic tokens). Match `components.json` aliases.
+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.
+
+`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
+emits generated test source.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: recommend/check the FE repo's allowlisted gen command
+else: run flowgrid gen:dry / gen directly
+
+Missing ArtifactGraph never blocks prototype generation. Complete the direct,
+deterministic bộ code 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.
+
+## 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`).