@shanyucoder/flowgrid 0.1.0

package/harness/common/extracts/docs-mark.md

@@ -0,0 +1,62 @@
+# Docs-mark — member annotation
+
+> Skill: `/docs-mark` · Registries: `registries/common.registry.json` + `registries/design.registry.json`
+
+## When to use
+
+Member (or agent after grill prompt) marks **spec** and/or **code** — **not** during round-1 `/spec` or bulk `/dev-grill-docs`.
+
+Grill lanes ask first; member confirms → apply mark in same session.
+
+## Mark kinds — logic (`registries/common.registry.json`)
+
+| kind | Tag | Spec block |
+|------|-----|------------|
+| common | `#common:{id}` | `marks[]` + optional `commonRefs[]` on routes/endpoints |
+| needs-common | `#needs-common:{id}` | `marks[]` — registry `status: planned` |
+| call-external | `#call-external` | `technicalMarks[]` + `externalCalls[]` |
+| cross-entity-service | `#cross-entity-service` | `technicalMarks[]` + `services[]` |
+| cross-service | `#cross-service` | `technicalMarks[]` + `services[]` (alias for cross-entity-service) |
+| derived-data | `#derived-data` | `technicalMarks[]` + `derivedData` |
+| reuse-api | `#reuse-api` | `tags:` — signals route reuse from common/sibling; suppresses DUPLICATE_API_ROUTE |
+
+## Mark kinds — UI (`registries/design.registry.json`)
+
+| kind | Tag | Spec / gen |
+|------|-----|------------|
+| needs-component | `#needs-component: {slot}:MoXxx[:prop]` | `tags:` — bộ code HANDOFF until Mo* exists |
+| needs-ui | `#needs-ui: {Widget}` | `tags:` — widget `planned` in design registry |
+| common-ui | Mo* in design registry `implemented` | promote after `/prototype`; re-run flowgrid gen |
+
+## Spec block — `marks[]` (`ir/spec.yaml`)
+
+```yaml
+marks:
+  - id: MK-STATUS-CHIP-001
+    kind: needs-component
+    tag: "#needs-component: cell-status:MoStatusChip:label"
+    registryId: MoStatusChip
+    reason: "Cột status render custom"
+    source: docs-mark
+```
+
+## Registry — common / design
+
+- `status`: `planned` | `implemented`
+- Validate via bộ code FE / product registry scripts (not docs-hub shell)
+
+## Workflow (each `/docs-mark` session)
+
+1. Resolve scope: function id `W-*`/`API-*` under `surfaces/.../CMP-*/<slug>/code/` (legacy `.../modules/CMP-*/` also accepted), `ir/spec.yaml`, optional code paths. Tag business gaps `#missing_info` — do not invent fills.
+2. Read `tags:`, `marks[]`, `technicalMarks[]`, both registries
+3. Apply member intent — one concern per mark
+4. Update spec YAML (`tags:` and/or `marks[]`)
+5. Upsert correct registry entry
+6. If `planned` → HANDOFF / `openQuestions`
+7. Optional: `artifactgraph_remember` after confirm B
+
+## Do not
+
+- Rewrite full contract like `/spec`
+- Auto-mark without member confirmation
+- Treat `artifactgraph_gen` as required

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

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "bundles": {
+    "core": [
+      ".cursor/extracts/core/agent-discipline.md"
+    ],
+    "platform-ai": [
+      ".cursor/extracts/artifact-graph.md",
+      ".cursor/extracts/extract-registry.json"
+    ],
+    "platform-mark": [
+      ".cursor/extracts/core/agent-discipline.md",
+      ".cursor/extracts/platform-mark.md",
+      ".cursor/extracts/platform-mark-detect.md"
+    ],
+    "artifactgraph": [
+      ".cursor/extracts/core/agent-discipline.md",
+      ".cursor/extracts/artifactgraph-hooks-core.md"
+    ],
+    "docs-mark": [
+      ".cursor/extracts/core/agent-discipline.md",
+      ".cursor/extracts/docs-mark.md",
+      ".cursor/extracts/docs-mark-detect.md"
+    ],
+    "ux-common": [
+      ".cursor/extracts/ux-common-patterns.md"
+    ]
+  }
+}

package/harness/common/extracts/ux-common-patterns.md

@@ -0,0 +1,172 @@
+# UX gap checklists (extract only — policy in `flowgrid-ux-common.mdc`)
+
+## 1. Flat design (shadcn admin)
+
+**Recognize:** Flat portal chrome — borders, muted surfaces, clear typography.
+
+**Propose when missing or off-pattern:**
+
+- [ ] No heavy gradients/shadows on buttons, cards, table chrome.
+- [ ] One clear primary per section; destructive only for dangerous actions.
+- [ ] No stacked modals — prefer page, step, or inline over dialog stacks.
+- [ ] Semantic colors; inline state near context instead of alert dialogs for read-only hints.
+
+---
+
+## 2. List page & toolbar
+
+**Recognize:** Title + primary (create) + secondary; bulk/export on list.
+
+**Propose when missing:**
+
+- [ ] List shell: title + main action; bulk actions on toolbar, not scattered per row.
+- [ ] One primary intent; outline/ghost for secondary.
+
+---
+
+## 3. Breadcrumb
+
+**Recognize:** `A > B > C`, or list → detail/edit hierarchy even if not labeled “breadcrumb”.
+
+**Propose when missing:**
+
+- [ ] Trail or back + title reflecting module/record.
+- [ ] Multiple entry paths (deep links) — vague Back alone is insufficient.
+- [ ] Breadcrumb shell slot unwired → `#needs-ui:breadcrumb` or registry update.
+
+---
+
+## 4. Search & filter
+
+**Recognize:** Search box, filter dropdowns, active filter chips, reset.
+
+**Propose when missing or unmapped:**
+
+- [ ] Large lists or server pagination → search and/or filters (name fields).
+- [ ] State: URL query **or** store — state choice in proposal.
+- [ ] “No results” empty state distinct from empty list.
+- [ ] If `#split-hook: filters` exists in design → use DSL; no duplicate filter YAML.
+
+---
+
+## 5. Pagination
+
+**Recognize:** Prev/next, page numbers, server total count.
+
+**Propose when missing:**
+
+- [ ] Standard paginator (no infinite scroll unless member explicitly chose it).
+- [ ] Stay in sync with search/filter when present.
+
+---
+
+## 6. Data table
+
+**Recognize:** Column grid, sort, selection, action column — often covered by list shell DSL.
+
+**Propose when under-specified:**
+
+- [ ] Horizontal scroll; compact density; muted header.
+- [ ] Status column → chip; action column → fixed width, nowrap; numbers → right-align.
+- [ ] Long text: truncate + tooltip (default).
+
+---
+
+## 7. Table action column & disabled affordance
+
+**Recognize:** Per-row icons/buttons; disabled by status, RBAC, or business rules.
+
+**Propose when missing (common gap):**
+
+- [ ] Row actions **icon-only** in table; outside table use icon + text when discoverability matters.
+- [ ] Non-obvious disabled → **badge/chip/tooltip** with reason (“Locked”, “No permission”, …).
+- [ ] Document `disabledReason` / preconditions in handoff.
+
+---
+
+## 8. Buttons
+
+**Recognize:** Primary/destructive/outline on forms, dialogs, toolbars.
+
+**Propose when missing:**
+
+- [ ] Submit/delete: `disabledReason` when blocked — not bare `disabled`.
+- [ ] Confirm dialogs: correct primary/secondary/destructive roles.
+
+---
+
+## 9. Status chip (lifecycle)
+
+**Recognize:** Status column, detail tags, post-job badges.
+
+**Propose when missing:**
+
+- [ ] Text label + semantic color; consistent tone map (pending/warning, failed/danger, …).
+- [ ] No plain text for states that need quick scanning.
+
+---
+
+## 10. Confirm dialog (non-delete)
+
+**Recognize:** Destructive actions, overwrite, cancel with side effects.
+
+**Propose when missing:**
+
+- [ ] Centered modal; never use confirm for form validation (use inline field errors).
+
+---
+
+## 11. Delete flow
+
+**Recognize:** Row delete, bulk delete, soft-delete with confirm.
+
+**Propose when DSL/handler missing or under-specified:**
+
+- [ ] Blocking **confirm** (AlertDialog) before delete — clear cancel/confirm.
+- [ ] After API: **result dialog** for success/error — user must acknowledge; **no** toast-only delete.
+- [ ] Bulk: copy includes **count**; batch/endpoint explicit.
+- [ ] API not ready → `#wire-only` / handoff — no fake success UI.
+
+---
+
+## 12. Feedback (inline / toast / dialog)
+
+**Recognize:** After save, delete, import, async jobs.
+
+**Propose when missing:**
+
+- [ ] Inline alert under title when still visible on light scroll.
+- [ ] Toast ~5s for non-blocking notices — **does not** replace delete result dialog.
+- [ ] One primary channel per action (inline OR dialog OR toast).
+
+---
+
+## 13. Form validation
+
+**Recognize:** Create/edit, wizards, modal forms.
+
+**Propose when missing:**
+
+- [ ] Field-level inline errors; block submit while invalid.
+- [ ] Submit/delete preconditions in handoff.
+
+---
+
+## 14. Navigation (menu / sidebar)
+
+**Recognize:** Module menu, active route, nested nav.
+
+**Propose when missing:**
+
+- [ ] Clear active state; no duplicate entries without routes.
+
+---
+
+## 15. Import CSV
+
+**Recognize:** Upload, column mapping, preview, import result.
+
+**Propose when missing:**
+
+- [ ] Flow: pick file → validate → confirm → result (row errors downloadable).
+- [ ] No silent failure; feedback per section 12.

package/harness/common/rules/artifactgraph.mdc

@@ -0,0 +1,26 @@
+---
+description: ArtifactGraph local-first MCP protocol
+alwaysApply: false
+---
+
+# ArtifactGraph
+
+- Product registries, templates, lexicons, and config are repository-local SSOT.
+- Use local analyze/grill/parity/suggest before requesting cloud work.
+- Never dump full registries or lexicons into `cloudPromptSlice`.
+- Run only generation keys allowlisted by the current repo.
+- Promote reviewed artifacts in the product repo, then rebuild the local index.
+- Do not depend on `platform-repos.json`, `base-docs`, or `base-tests`.
+
+## Cross-repo routing
+
+- Architecture ID / C4 → bộ docs (`FLOWGRID_DOCS_ROOT`), not CodeGraph and not
+  ArtifactGraph.
+- IR / registry / generation → bộ code / bộ test 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
+  maps, never scan a workspace parent, never wire CodeGraph MCP itself.
+- Platform DNA owns map-based CodeGraph auto-wire and missing-index hints.
+
+Hooks: `.cursor/extracts/artifactgraph-hooks-core.md`

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

@@ -0,0 +1,47 @@
+---
+description: Cross-repo index routing — call the correct per-repo index, never one giant workspace graph.
+alwaysApply: true
+---
+
+# Cross-repo index routing (SSOT)
+
+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
+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
+  CodeGraph for architecture Markdown.
+- Need IR / registry / generation -> the pointer kit
+  (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
+- Need a symbol or call-graph for repo `X` -> the CodeGraph MCP server for repo
+  `X` (`codegraph-<key>`, whose `--project-root` is `X`'s checkout). Do not use
+  the index of the repository currently open.
+
+Checkout maps (machine-local only):
+
+| System id / intent | Map |
+|--------------------|-----|
+| Prefix `legacy-` or clear legacy archaeology | `legacy-repos.local.json` |
+| Platform skills / step `[system]` without `legacy-` | `platform-repos.local.json` |
+
+Rules:
+
+- One `.codegraph/` per repository, created locally with `codegraph init` inside
+  that repo. Never run `codegraph init` in a workspace parent.
+- A repo without an index is reported, not auto-indexed; run the printed
+  `cd <root> && codegraph init` first.
+- ArtifactGraph stays local-only; it is never a shared index for FE, tests, or
+  legacy repositories.
+- Ambiguous keys → ask or Gaps; never invent sibling paths.
+- Missing / empty `.local.json` or missing key → Gaps + `/configure-repo-maps`
+  (NL); do not hand-edit JSON or guess absolute paths.
+- Platform DNA wires `codegraph-<key>` from both machine-local maps. Re-run
+  `platform-dna codegraph:wire` to refresh; never commit machine paths. Key
+  collision: **platform map wins**; prefer `legacy-*` keys for legacy-only
+  checkouts.

package/harness/common/rules/flowgrid-ux-common.mdc

@@ -0,0 +1,39 @@
+---
+description: UX gap analysis and proposals after DSL/spec policy (always-on)
+alwaysApply: true
+---
+
+# UX proposals (global)
+
+**DSL and bundle SSOT:** `/spec`, `/update-spec`, `design.registry.json`, `gen-common`. Do not replace spec authoring with the checklist extract.
+
+## When this applies
+
+Prompt analysis, UI proposals, affordance review. **Primary:** `/spec` per-zone pipeline (DSL → `#needs-component` / `#needs-ui` → checklist gaps → `AskQuestion`). Also `/grill-bqa` Step B. Explicit: `/ui-proposal`.
+
+## Flow
+
+1. Map DSL/registry first (`#shell:`, `#pattern:`, `#ui:`, `#widget:`, generated CMN).
+2. On match → codegen/wire only; no redundant YAML/spec.
+3. Unmapped, missing DSL, or UI not recognized as a pattern → read **`.cursor/extracts/ux-common-patterns.md`**; apply matching **Recognize** / **Propose** sections.
+4. **`flowgrid audit spec`** — patch `UX_*` gaps in bundle; `CONFIRM_UX_*` → `AskQuestion` using audit `(Recommended)` options.
+5. Stable cross-project pattern → `gen-common`; never hand-duplicate common IR.
+
+| Situation | Action |
+|-----------|--------|
+| Already in DSL/registry | Skip matching checklist section |
+| Looks like list/table/breadcrumb/delete but untagged | Recognize → propose tag or CMN |
+| Thin spec/code (silent disabled, toast-only delete, …) | Propose affordance |
+
+## Proposal output (required format)
+
+```text
+DSL: [mapped | unmapped] — registry id / #tag
+Gap: [pattern-id or checklist section] — [1–2 sentences]
+Propose: [#needs-ui:… | tag | handoff field]
+Avoid: [redundant YAML/spec when DSL is sufficient]
+```
+
+## CMN pattern IDs (after DSL gap confirmed)
+
+`common-flat-design`, `common-list-page`, `common-list-toolbar`, `common-breadcrumb-flow`, `common-search-filter`, `common-pagination`, `common-data-table`, `common-table-action-column`, `common-buttons`, `common-status-chip`, `common-confirm-dialog`, `common-delete-flow`, `common-feedback`, `common-form-validation`, `common-navigation`, `common-import-csv`.

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

@@ -0,0 +1,24 @@
+---
+description: Platform — ~200 lines/file, ~20 lines/function; split when exceeded
+globs: "{pages,components,composables,services,stores,models,validations,tests}/**/*.{vue,ts}"
+alwaysApply: false
+---
+
+# Code Size
+
+Soft limits — split in the same PR when exceeded.
+
+| Vượt ~200 dòng/file | Tách | Gợi ý Tag DSL (`/docs-mark`) |
+|---------------------|------|------------------------------|
+| Page `.vue` | Composable + sub-component | `#needs-component: sub-{name}:MoXxx` hoặc `#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` |
+| E2E spec | Page Object + helper | `#e2e-test` bundle split |
+
+| Vượt ~20 dòng/function | Tách | Gợi ý 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.

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

@@ -0,0 +1,12 @@
+---
+description: Harness state files — progress handoff between sessions
+globs: .harness/**/*
+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.

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

@@ -0,0 +1,106 @@
+---
+name: business-impact-review
+description: Comprehensive blast-radius evaluation across repositories (Cross-repo) and functional surfaces (Cross-surface).
+disable-model-invocation: true
+---
+
+# /business-impact-review
+
+Read-only analysis by default. Do not implement fixes unless explicitly asked.
+
+**Owner:** Common Hub (Cross-Boundary Inspector). Optional rule: `flowgrid-process.mdc`.
+
+## Checkout resolution
+
+Cross-repo callers/callees:
+
+| System id | Map |
+|-----------|-----|
+| `legacy-*` | `legacy-repos.local.json` |
+| Otherwise | `platform-repos.local.json` |
+
+Missing/empty map or missing key → **Gaps** + **`/configure-repo-maps`**; never
+guess paths. Then remind `platform-dna codegraph:wire` if needed. Ambiguous
+matches → ask or Gaps.
+
+## Context - Action - Constraint Model (CAC)
+
+### Context
+Execution triggered by `/business-impact-review` against uncommitted diffs, PR branches, or specified modified files/routes spanning cross-repo (FE ↔ BE) or cross-surface boundaries.
+
+### Action (2-Stage Phased Protocol)
+
+#### Stage 1: Candidate Indexing & Blast-Radius Manifest
+1. **Symbol & Route Scoping:** Extract all modified public/protected methods, API routes, Jobs, Events, Listeners, Commands, and DB schemas from diff.
+2. **Candidate Index Generation:** Perform targeted symbol/caller indexing (using `codegraph-<key>` or caller search across repos listed in `platform-repos.local.json`/`legacy-repos.local.json`).
+3. **Compile Candidate Manifest:** Produce an indexed list of potential blast-radius targets categorized into:
+   - Callers (FE/Mobile consumers, cross-repo API clients)
+   - Vertical process paths (Controller → Service → Repository → DB)
+   - Cross-surface listeners (Shared Events, Queue consumers, DB triggers)
+4. **Workload Threshold Interlock (Law 2):**
+   - **If total candidates ≤ 5:** Execute Stage 2 deep inspection directly in the current session.
+   - **If total candidates > 5 (or spanning > 1 repository):**
+     - **[MANDATORY HARD STOP IN CHAT]**
+     - Author an implementation plan / Plan Mode document (brain dir / `plan.md`).
+     - Partition candidate inspection into sequential **Phases** (each phase capped at 3–5 candidate call-sites/paths).
+     - **Phase Boundary Context Pruning:** At the end of each phase, persist analysis findings into the output report on disk. For each subsequent phase, load fresh state from disk instead of maintaining full AST/diff context in conversational RAM.
+
+#### Stage 2: Phased Deep-Dive Inspection
+Inspect each candidate path sequentially across the vertical stack:
+```text
+Client/FE or Scheduler/Webhook
+  → route/command/job
+  → auth/middleware/context rewrite
+  → controller/handler
+  → service/domain
+  → repository/model/database
+  → event/listener/job/external API
+  → response/error/status mapping
+  → FE/consumer/next async hop
+```
+Apply `risk-classes.md`: authZ/IDOR, request bag, trust boundary, over-broad parse, null/empty, error collapsing, hardcode/magic, async context/idempotency, business rules, transactions, and contract compatibility.
+
+### Constraints
+- **[STRICTLY FORBIDDEN]** to rely solely on naive single-pass grep scripts that produce false negatives when member code is non-compliant or uses dynamic routing.
+- **[STRICTLY FORBIDDEN]** to dump > 5 candidate analyses in a single chat turn.
+- **[MANDATORY]** Write analysis findings directly to disk at each phase boundary.
+- **[MANDATORY]** Maintain read-only analysis; do not generate or modify application code unless explicitly requested.
+
+## Required Report
+
+```text
+Summary / ship recommendation
+Changed symbols & Candidate Index
+Horizontal callers
+Vertical process paths
+Cross-Boundary Impact (FE/BE & Surfaces)  <-- MANDATORY EXPLICIT SECTION
+Findings: severity · class · evidence · impact · verify
+Unsearched repos / residual risks
+Targeted test plan
+```
+
+## Accelerators (optional)
+
+Route per intent (rule `cross-repo-index.mdc`): never one merged
+workspace graph — always the correct per-repo index.
+
+```text
+if CodeGraph available: changed symbols + callers + call graph — for repo X use
+  its own server `codegraph-<key>` (--project-root = X's checkout), never the
+  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
+  (never CodeGraph for architecture Markdown)
+else: repository conventions/search
+
+IR / registry / generation questions → pointer kits
+  (FLOWGRID_DOCS_ROOT, FLOWGRID_DOCS_ROOT, FLOWGRID_TESTS_DOC)
+
+if ArtifactGraph available: affected tags/registries/parity
+  (local-only — never a shared index for other repos)
+else: model review from scoped evidence
+```
+
+Missing accelerators never block the review. Assign one stable `runId` at run
+start. Report only actual `fileReads` and `contextBytes`, never invented token claims.

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

@@ -0,0 +1,58 @@
+---
+name: configure-repo-maps
+description: /configure-repo-maps — Merge NL checkout paths into platform-repos.local.json / legacy-repos.local.json (no git clone).
+disable-model-invocation: true
+---
+
+<!-- platform-dna:configure-repo-maps-ssot -->
+
+# /configure-repo-maps
+
+**Purpose:** Populate local checkout directory paths into machine-local mapping files — do not clone repositories, do not alter portable catalogs.
+
+## Hard Rules
+
+1. **[MANDATORY]** Write ONLY to `platform-repos.local.json` and/or `legacy-repos.local.json` (merge-by-key).
+2. **[STRICTLY FORBIDDEN]** Do NOT execute `git clone` / `git fetch` / connect remotes / download source archives.
+3. **[STRICTLY FORBIDDEN]** Do NOT edit `platform-repos.json` / `legacy-repos.json` (portable catalogs where `root` remains `"."`).
+4. **[STRICTLY FORBIDDEN]** Do NOT hand-edit entire JSON files on behalf of the member by pasting full files — accept natural language (NL) input and prompt for missing keys or paths.
+5. **[MANDATORY]** Normalize absolute paths (including `~` or Windows drives) and write to `projects.<key>.root`.
+
+## Routing
+
+| Intent | File |
+|--------|------|
+| Current platform / hub (docs, portal, api, tests, …) | `platform-repos.local.json` |
+| Prefix / concept `legacy-*`, legacy archaeology | `legacy-repos.local.json` |
+
+## Example Prompts (NL input from user)
+
+**Platform-only**
+
+```text
+docs = base-docs at ~/ws/base-docs, portal admin at ~/ws/portal, api core at ~/ws/api
+```
+
+→ Merge `base-docs`, `portal`, `api` into `platform-repos.local.json` (prompt if keys or roles are ambiguous).
+
+**Multi portal / API**
+
+```text
+2 portals: admin at ~/ws/portal, line at ~/ws/line; 2 APIs: core at ~/ws/api-core,
+scenario at ~/ws/api-scenario; docs = ~/ws/base-docs; tests = ~/ws/base-tests
+```
+
+→ Map one key per checkout; prompt for any missing paths.
+
+**Legacy**
+
+```text
+legacy ERP at D:\legacy\erp, key legacy-erp
+```
+
+→ Target strictly `legacy-repos.local.json`.
+
+## After Write
+
+1. Run `platform-dna codegraph:wire` (when utilizing Cursor + CodeGraph).
+2. For checkouts lacking `.codegraph/`: `cd <root> && codegraph init`.

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

@@ -0,0 +1,67 @@
+---
+name: docs-mark
+extractBundle: docs-mark
+description: /docs-mark — member marks tags/registries after grill confirm.
+disable-model-invocation: true
+---
+
+# /docs-mark
+
+**Owner:** ArtifactGraph (common harness)  
+Member annotation following grill A/B/C confirmation — NOT for bulk `/spec` / `/dev-grill-docs`.
+
+Hub policy (docs hub): `platform/toolchain/PLATFORM-MARK.md` (alias: docs-mark).  
+Technical marks SSOT on the docs hub: `surfaces/common/integrations/*`,
+`surfaces/common/data-model/derived-data.md`.
+
+## Accelerators (optional)
+
+When ArtifactGraph tools are available: `artifactgraph_analyze`,
+`artifactgraph_suggest_tags`, `artifactgraph_remember`,
+`artifactgraph_allowlist_check`, `artifactgraph_recommend_command`,
+`artifactgraph_api_reuse_check` (confirm route reuse before applying `#reuse-api`),
+`artifactgraph_grill_check` (re-scan for `duplicate-api-route` / missing tags after mark).  
+Missing AG tools → continue with local registry/spec edits; do not invent shell
+fallbacks.
+
+## Registries (on the product / FE repo)
+
+| Layer | File | Tags |
+|-------|------|------|
+| 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
+FE checkout). On docs hub:
+
+```text
+if ArtifactGraph available:
+  artifactgraph_allowlist_check(registryValidate|commonRegistry)
+  artifactgraph_recommend_command → hand off to bộ code FE
+else:
+  note pending FE registry validate; do not invent local shell fallbacks
+```
+
+## Workflow
+
+1. Feature `ir/spec.yaml` + registries (optional `artifactgraph_analyze`)
+2. One mark / concern; member already confirmed at grill
+3. Upsert registry · planned → HANDOFF · implemented → promote path
+4. `artifactgraph_remember` subject after confirm B
+
+## Do not
+
+- Auto-tag without asking the member
+- Put Mo* into `common.registry` (design registry only)
+- Full contract rewrite
+- Treat `artifactgraph_gen` as required (deprecated shim)
+
+## 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
+docs failure.
+
+## Compatibility
+
+`/platform-mark` is a deprecated alias for this skill (one compatibility cycle).