@shanyucoder/flowgrid 0.1.0

package/harness/docs/skills/background-logic/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: background-logic
+description: /background-logic — Manage, enrich, and update background processing logic, async jobs, cron triggers, and message dispatchers for business flows (FLOW-*).
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /background-logic — Background Processing Logic
+
+**Purpose:** Specialize in managing, auditing, enriching, and updating background processing tasks (Async Jobs, Workers, Event Triggers, Scheduled Cronjobs, Message Dispatchers) for `FLOW-*` processes or screen clusters `W-*`.
+
+**Principle:** Maintain strict separation between the stable UI presentation layer and automated background logic — adjust background operations without disrupting UI screen specifications.
+
+---
+
+## Rule: When to Use /background-logic
+
+- **[MANDATORY]** Use this skill when:
+  1. A `FLOW-*` business process has established UI steps but requires background automation (e.g. dispatching Zalo/SMS notifications upon booking creation, auto-cancelling orders after 15 minutes of non-payment).
+  2. Existing background logic needs updating (changing dispatch channels, modifying filtering conditions, adjusting retry policies, updating storage buckets).
+  3. Auditing background tasks for comprehensive error scenarios, retry strategies, and idempotency guarantees.
+- **[STRICTLY FORBIDDEN]** Do NOT use this skill to edit UI screen specifications (use `/update-spec`) or author new APIs (use `/api-spec`).
+
+---
+
+## Rule: Missing Information Handling
+
+- **[MANDATORY]** Prior to authoring background logic, clarify the following 5 dimensions via `AskQuestion` wizard (one question at a time, ≥3 options):
+  1. **Trigger:** When does activation occur? (Immediately post-save / cron schedule / event message).
+  2. **Matching:** What are the exact evaluation criteria?
+  3. **Action:** What operation does the worker execute? (Dispatch notifications, synchronize ERP, generate PDF assets, etc.).
+  4. **Idempotency & Retry:** How is duplicate processing prevented? What is the retry count and backoff schedule?
+  5. **Feedback:** How is the outcome reflected on user screens? (Status badge / retry action trigger).
+- **[STRICTLY FORBIDDEN]** Do NOT invent triggers, matching rules, or retry policies — always confirm with user.
+
+---
+
+## Rule: 4 Mandatory Sections in `FLOW-*.md`
+
+### Section 1 — System Story (`## 2. Multi-tier User Stories`)
+- **[MANDATORY]** Add `### System Story: Automated Background Processing & Deduplication`:
+  ```markdown
+  ### System Story: Automated Background Processing & Deduplication
+  > **As an** Automated System (Background Job Worker),
+  > **I want to** capture [Event Name] and validate data against [Rule Name],
+  > **So that** [Action] is executed towards [Destination Channel] with guaranteed idempotency.
+  ```
+
+### Section 2 — Business Rules (`## 3. Business Rules`)
+- **[MANDATORY]** Specify 3 core rules:
+  - **Idempotency:** Unique identifier processed exactly once.
+  - **Retry Policy:** Retry attempts (e.g. 3 attempts), backoff curve (30s → 2m → 5m), terminal exit on 4xx client errors.
+  - **State Transitions:** `PENDING_TRIGGER` → `PROCESSING` → `SENT` / `FAILED` / `SKIPPED`.
+
+### Section 3 — Processing Journey (`## 4. Detailed Journey Stages`)
+- **[MANDATORY]** Detail lifecycle: Worker wakes up → Reads payload → Evaluates conditions → Dispatches external call → Logs result + updates state.
+- **[MANDATORY]** Failure scenarios: On connection drop or invalid data → Record error log + surface UI alert badge with manual fallback action.
+
+### Section 4 — Mermaid Diagram (`## 6. Sequence Diagram`)
+- **[MANDATORY]** Enclose worker logic within a highlighted `rect rgb(...)` block:
+  ```mermaid
+  rect rgb(245, 255, 245)
+    Note over Core, Customer: Background Processing Phase
+    Core->>Job: Trigger event (ID: BKG-XXXX)
+    Job->>Storage: Read entity & evaluate conditions
+    alt Conditions satisfied
+      Job->>Gateway: Dispatch message
+      Gateway-->>Customer: Confirmation received
+      Job->>Storage: Write log → status = 'SENT'
+      Job-->>ScreenDetail: Push status badge "Sent"
+    else Dispatch failed (after retry limit)
+      Job->>Storage: Write error log → status = 'FAILED'
+      Job-->>ScreenDetail: Push alert badge "Failed" (Retry button enabled)
+    end
+  end
+  ```
+- **[STRICTLY FORBIDDEN]** Do NOT include low-level DDL schema definitions or HTTP endpoint paths in FLOW documents.
+
+---
+
+## Workflow
+
+1. Identify target `FLOW-*.md` (or scaffold if not yet existing).
+2. Assess current state: verify presence of background logic; propose additions or isolate deltas.
+3. Clarify the 5 dimensions via AskQuestion wizard (one question at a time, ≥3 options).
+4. Update all 4 mandatory sections in `FLOW-*.md`.
+
+---
+
+## Verification Checklist
+
+- [ ] Target `FLOW-*.md` accurately located.
+- [ ] System Story explicitly details background actor responsibilities.
+- [ ] Idempotency, Retry Policy, and State Transitions fully specified.
+- [ ] Mermaid diagram includes `rect` container with `alt / else` error branches.
+- [ ] No technical DDL or HTTP paths present in FLOW document.
+- [ ] AskQuestion wizard used for all ambiguous background requirements.

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

@@ -0,0 +1,47 @@
+---
+name: build-templates
+description: /build-templates — Scan FE/BE codebase and scaffold matching EJS templates and common specs.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /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.
+
+---
+
+## Rule: Pre-flight
+
+- **[MANDATORY]** Read `platform-repos.local.json` at root to resolve absolute paths to FE (`fe`) and BE (`be`).
+- **[MANDATORY]** If file is missing or paths are empty → STOP and instruct user: *"Please configure repository mappings using `/configure-repo-maps`."*
+
+---
+
+## Rule: Scan Steps
+
+- **[MANDATORY]** Frontend: Scan `package.json` + imports to identify UI Framework (`vuetify`, `shadcn-ui`, `element-plus`, `bootstrap`, etc.). Locate shared layout components (Breadcrumb, MainLayout, Table, Form).
+- **[MANDATORY]** Backend: Scan routers/controllers + shared data structures (Base Response, Paging Request) to capture API standards.
+
+---
+
+## Rule: EJS Template Generation
+
+- **[MANDATORY]** Write EJS templates to `.flowgrid/templates/` (e.g. `default-layout.ejs`, `breadcrumb-flow.ejs`).
+- **[MANDATORY]** Templates MUST accurately reflect project UI Kit (Vuetify → Vuetify component tags; Shadcn → flat design style).
+- **[STRICTLY FORBIDDEN]** Do NOT alter anchor comments `<!-- flowgrid-anchor: ... -->` in templates — these are vital data anchors for AI processing.
+- **[MANDATORY]** If an EJS template already exists with customizations → ask user before overwriting, or only append delta changes.
+
+---
+
+## Rule: Common Specs Sync
+
+- **[MANDATORY]** Create or update YAML common specs under `surfaces/common/yaml/` matching scanned shared code structures.
+
+---
+
+## Rule: Verification
+
+- **[MANDATORY]** After scaffolding templates: run `pnpm docs:render` to compile all specs and verify EJS templates contain no syntax errors.

package/harness/docs/skills/business-process/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: business-process
+description: /business-process (or /flow) — Models business action flows (actor + surface + action + outcome) as FLOW-*.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /business-process (Alias: /flow)
+
+**Mindset:** Model the process by **business actions on surfaces**, not by repository or service topology.
+
+---
+
+## Rule: Audit Interlock
+
+- **[MANDATORY]** Always run static audit first: `flowgrid audit flow <target-flow.md>`.
+  - ✅ Consume JSON gap report to fix issues or trigger AskQuestion wizard (≥3 options).
+  - ❌ Do not skip audit and proceed to authoring directly.
+
+---
+
+## Rule: Missing Information Handling & Workload Threshold (Law 2)
+
+- **[MANDATORY]** When required flow sections are absent, evaluate total missing volume:
+  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other`, (3) `Log as Tech Debt (Pending)`.
+  - **Large Scope (≥10 gaps/steps):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 gaps per phase) with disk offloading at boundaries.
+- **[STRICTLY FORBIDDEN]** Do NOT invent actors, permissions, or background logic — always confirm with user.
+
+---
+
+## Rule: Target Path Resolution
+
+- **[MANDATORY]** Resolve placement path via `.cursor/extracts/common-scope.md` §4.
+  - Surface-level: `surfaces/**/common/processes/FLOW-*.md`
+  - Architecture-level: `architecture/03-business-process/`
+- **[STRICTLY FORBIDDEN]** Do NOT use an unstandardized path like `[Target Path]/Common/Business processes`.
+
+---
+
+## Rule: Placement by Co-activation Context
+
+### When co-activated with `/common` or for surfaces:
+- **[MANDATORY]** Write pure Markdown describing business logic at the **UI surface level**.
+- **[MANDATORY]** Structure MUST follow the 6-section "Deep-dive Business Flow Specification":
+
+  1. `## 1. Context & Business Authorization Matrix` — trigger, actor table, permissions per screen `[W-*]`.
+  2. `## 2. Multi-tier User Story Chain` — Setup Story, Primary Story, Tracking Story, **System Story** (if background logic exists).
+  3. `## 3. Business Rules (BR-*) & State Lifecycle` — BR-* table + state transition matrix.
+  4. `## 4. Stage-by-Stage Journey Specification` — user actions, Data Handoff between screens (fields passed, destination targets), background processing (idempotency, retry), state feedback.
+  5. `## 5. Traceability Matrix` — 1:1 table: User Story Step ↔ Screen `[W-*]` ↔ Sequence Diagram ↔ Technical Component.
+  6. `## 6. Cross-Screen Business Sequence Diagram` — Mermaid `sequenceDiagram` showing screen-to-screen journey, actors, button actions, storage (DB Table, S3), and `rect` segments for background workers.
+
+- **[STRICTLY FORBIDDEN]** Do NOT include raw HTTP verbs (`POST /api/v1/...`), SQL queries, or DB column schema in this file.
+
+### When co-activated with `/architecture`:
+- **[MANDATORY]** Focus on technical `sequenceDiagram` for entire long-running flow: backend services, DB interactions, cronjobs, external APIs, 3rd-party handshakes.
+- Placement: `architecture/03-business-process/`.
+
+---
+
+## Rule: Background Logic
+
+- **[RECOMMENDED]** Pure CRUD flows do NOT require background logic sections — diagram ends at data persistence.
+- **[MANDATORY]** When a flow **has** background jobs / event triggers / 3rd-party sync:
+  1. Add **System Story** in Section 2 describing what the system executes autonomously.
+  2. Add **Retry / Timeout / Fallback** rules + failure scenarios in Sections 3 & 4.
+  3. Add `rect rgb(...)` segment in Mermaid diagram showing the Worker flow.
+
+---
+
+## Rule: Diagram Quality
+
+- **[MANDATORY]** Use `sequenceDiagram` when interactions between actors/surfaces/screens matter; `flowchart` when decision branching paths dominate.
+- **[MANDATORY]** Every Mermaid diagram MUST explicitly model error paths using `alt / else` (e.g.: invalid data, 3rd-party gateway failure, timeout, with UI recovery path).
+  - ✅ `alt Invalid data error` → `else Timeout failure` block
+  - ❌ Happy-path-only diagrams without error branches.
+
+---
+
+## Rule: Publishing & Naming
+
+- **[MANDATORY]** FLOW file must use **Process Code** as VitePress menu key (e.g. `FLOW-PORTAL-AUTH-CHANGE`), not the H1 heading.
+- **[STRICTLY FORBIDDEN]** Do NOT write FLOW files adjacent to a single function bundle.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** If `adoption-inventory.md` does NOT exist at workspace root → STOP: *"Run `/docs-hub /adopt` first."*
+- **[MANDATORY]** If file exists: look up `FLOW-*` candidates and map legacy module/screens. Write with `legacy-` prefix (e.g. `legacy-FLOW-checkout.md`).
+- **[MANDATORY - CROSS-FLOW LEGACY AUDIT]**: When analyzing legacy business processes (`/legacy /business-process`), Agent **MUST PROACTIVELY AUDIT END-TO-END FLOW GAPS**:
+  - Compare Data Output at Step $N$ (e.g., Screen 1 / API 1) with Input expectations at Step $N+1$ (e.g., Screen 2 / API 2) to identify schema or status misalignments.
+  - Flag orphan steps/APIs (not attached to any valid flow step) or processes lacking Confirmation / Rollback / Idempotency handling on failure.
+  - Tag issues with `[LEGACY_FLOW_GAP]` and generate Open Questions for member resolution.
+- **[STRICTLY FORBIDDEN]** Do NOT read `adoption-inventory.md` for Greenfield commands.
+
+---
+
+## Verification Checklist
+
+- [ ] Audit script run; all gaps resolved or AskQuestion wizard triggered.
+- [ ] All 6 sections present (surface-level flow) or technical `sequenceDiagram` (architecture-level flow).
+- [ ] System Story + Retry/Fallback rules present when background logic exists.
+- [ ] Mermaid diagram includes `alt / else` error paths.
+- [ ] No raw HTTP verbs, SQL, or DB columns in surface-level FLOW file.
+- [ ] File placed at correct path per `common-scope.md`; named with `FLOW-*` prefix.

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

@@ -0,0 +1,32 @@
+---
+name: call-external
+description: EXCLUSIVE #call-external hashtag — ONLY for third-party integration tags. DO NOT output fake Markdown reports.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Read `.cursor/extracts/call-external.md` for spec, OpenAPI, and implementation rules.
+
+# #call-external — Third-Party Integration Tag
+
+Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+
+---
+
+## Rule: ID Resolution
+
+- **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob) to locate `…/api/<seq>/01-backend-spec.yaml` (or `common/yaml` / integrations `api/<seq>`). NEVER treat `ir/design.yaml` as the BE contract.
+
+---
+
+## Rule: Application
+
+- **[MANDATORY]** When `#call-external` is present in the spec: document the `externalCalls[]` array and add the hashtag to the spec YAML.
+
+---
+
+## Verification Checklist
+
+- [ ] `01-backend-spec.yaml` located via ID or path resolution.
+- [ ] `externalCalls[]` documented; `#call-external` applied in spec YAML.

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

@@ -0,0 +1,46 @@
+---
+name: common
+description: EXCLUSIVE /common — Use this to define common business rules, UX/UI rules, and patterns for a Surface as Markdown documentation. DO NOT use this to generate YAML technical bundles (use /common-spec for that).
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** This is an allowed human-invoked path only. Do NOT run as a side-effect of `/spec`.
+
+# /common
+
+**Target Path:** `<LCA>/common/patterns/` — resolve LCA from `.cursor/extracts/common-scope.md` (module/cluster `common/` before surface; never invent a second tree).
+
+## Purpose
+
+Markdown rules for a **named scope** (cluster / module / surface / global). Not "always surface-wide". First **Read** `common-scope.md` and pick the LCA `common/patterns/` folder.
+
+**Gate:** Only use when the user explicitly invoked `/common` (or confirmed a grill proposal).
+
+---
+
+## Rule: Target / ID Resolution
+
+- **[MANDATORY]** Prompt MUST name **consumers** (CMP id, cluster `NN`, surface, or "all surfaces"). If ambiguous → ask; propose one LCA from `common-scope.md`.
+- **[MANDATORY]** Scaffold `common/patterns/` at that LCA only.
+- **[STRICTLY FORBIDDEN]** Do NOT create `surfaces/common` unless ≥2 surfaces share the rule.
+- **[MANDATORY]** One function only → do NOT create `common/`; attach the rule to the function bundle directly.
+- Surface-wide with no `common/` yet → run `/surfaces <name> common` first, then author `patterns/`.
+
+---
+
+## Rule: Markdown Content
+
+- **[MANDATORY]** Use clear, non-technical language geared towards Business / QA / Dev alignment.
+- **[MANDATORY]** Define rules based on surface type when applicable (e.g. Kiosk UI rules differ from Web Portal rules).
+- **[STRICTLY FORBIDDEN]** Do NOT output fake i18n tables or framework prose. Focus on actual rules (e.g. "Confirm dialog must always block background").
+- **[STRICTLY FORBIDDEN]** Do NOT generate YAML bundles here — use `/common-spec` for codegen bundles.
+
+---
+
+## Verification Checklist
+
+- [ ] Target surface resolved to `surfaces/[Surface]/`.
+- [ ] `common/` directory verified or created.
+- [ ] `.md` written under LCA `common/patterns/` from `common-scope.md` (not beside a single function).

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

@@ -0,0 +1,55 @@
+---
+name: common-spec
+extractBundle: spec-core
+description: EXCLUSIVE /common-spec — Use this to define common technical bundles (YAML) for a Surface for Codegen. DO NOT output Markdown files.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Read `.cursor/extracts/common-scope.md` first to resolve the LCA path.
+
+# /common-spec — Common Technical Bundle (YAML)
+
+**Target Path:** `<LCA>/common/yaml/<slug>/<slug>.bundle.yaml` (LCA from `common-scope.md`).
+
+**Gate:** Only use when user explicitly invokes `/common-spec` or confirmed a grill proposal to promote common.
+
+---
+
+## Rule: Platform-Agnostic Generation
+
+- **[MANDATORY]** Use `design.shell.tag` to match target surface type:
+  - Web Portal → `#shell: DataListPage`
+  - WinForms Kiosk → `#shell: KioskCheckIn`
+  - Gateway → `#shell: OtAdapter`
+- **[MANDATORY]** Populate `spec.clients` if applicable.
+- **[RECOMMENDED]** For known Web patterns (e.g. `confirm-dialog`): ask if user wants to inherit from seed template in `templates/project-skeleton/surfaces/common/yaml/`.
+- **[MANDATORY]** For non-Web surfaces → generate new bundle tailored to that requirement. Do NOT force Web template inheritance.
+
+---
+
+## Rule: Output
+
+- **[MANDATORY]** Output MUST be `.bundle.yaml`. Do NOT write `.md` directly.
+- **[MANDATORY]** All strings containing `:` must be double-quoted.
+- **[MANDATORY]** After writing: instruct user to run `flowgrid split -- <path>` (must emit `ir/design.yaml`), then `flowgrid render`. Run `flowgrid split --check` to verify.
+- **[STRICTLY FORBIDDEN]** Do NOT send BE `/api` a common FE bundle. bộ code → FE `/gen-common` only.
+
+---
+
+## Workflow
+
+1. Read `common-scope.md`. Identify consumers → one LCA `common/yaml/<slug>/`.
+   - Example module-local: `surfaces/admin/CMP-ADM-002/common/yaml/confirm-dialog/confirm-dialog.bundle.yaml`
+2. Generate `.bundle.yaml` using `portal-feature-bundle/v1` schema.
+3. Instruct user: `flowgrid split -- <path>` → `flowgrid render`.
+
+---
+
+## Verification Checklist
+
+- [ ] LCA resolved from `common-scope.md`; path correctly scoped.
+- [ ] `design.shell.tag` matches target surface type.
+- [ ] `.bundle.yaml` output only (no `.md`). YAML strings with `:` are double-quoted.
+- [ ] `flowgrid split --check` passes (emits `ir/design.yaml`).

package/harness/docs/skills/cross-cutting/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cross-cutting
+description: /cross-cutting — arc42 §08 cross-cutting concerns (Security, Logging, Caching, etc.).
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /cross-cutting — Cross-Cutting Concerns (§08)
+
+---
+
+## Rule: Output
+
+- **[MANDATORY]** Path: `architecture/08-cross-cutting/` — topic section or `{topic}.md`.
+- **[MANDATORY]** Template: `.cursor/extracts/tpl-cross-cutting.md`.
+- **[MANDATORY]** MUST include: Intent + Owner (or TBD) + Approach stub. No AI waffle.
+- **[MANDATORY]** Use `flowgrid_docs_route` for §08 topics; `flowgrid_docs_validate_links` after adding a new section.
+
+## Topics (seed)
+
+Security · Logging · Observability · Caching · Messaging · Configuration · Exception · Validation · Localization · Authorization
+
+---
+
+## Rule: Scope Boundaries
+
+- **[STRICTLY FORBIDDEN]** No Full OpenAPI / UI DSL / E2E plans in cross-cutting.
+- **[STRICTLY FORBIDDEN]** Do NOT duplicate business journeys here (those belong to `/journey`).
+
+Parent: `/architecture`

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

@@ -0,0 +1,32 @@
+---
+name: cross-entity-service
+description: EXCLUSIVE #cross-entity-service hashtag — ONLY for cross-aggregate orchestration tags. DO NOT output fake Markdown reports.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Read `.cursor/extracts/cross-entity-service.md` for trigger criteria, spec/OpenAPI tags, and implementation rules.
+
+# #cross-entity-service — Cross-Aggregate Orchestration Tag
+
+Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+
+---
+
+## Rule: ID Resolution
+
+- **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob) to locate `…/api/<seq>/01-backend-spec.yaml` (or `common/yaml`). NEVER treat `ir/design.yaml` as the BE contract.
+
+---
+
+## Rule: Application
+
+- **[MANDATORY]** When `#cross-entity-service` is present in the spec: document the `services[]` array and add the hashtag to the spec YAML.
+
+---
+
+## Verification Checklist
+
+- [ ] `01-backend-spec.yaml` located via ID or path resolution.
+- [ ] `services[]` documented; `#cross-entity-service` applied in spec YAML.

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

@@ -0,0 +1,37 @@
+---
+name: cross-service
+description: /cross-service — Models inter-service and inter-system integrations (sync/async, RPC, events, messages).
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /cross-service — Inter-Service & Inter-System Integrations
+
+**Target Path:** `<LCA>/common/cross-service.md` — LCA resolved from `.cursor/extracts/common-scope.md`.
+
+---
+
+## Rule: When to Use
+
+- **[MANDATORY]** Use when a flow crosses a service, system, or boundary: sync RPC, async messaging, event-driven handoffs, retries, idempotency, integration contracts.
+- **[STRICTLY FORBIDDEN]** Do NOT use for internal code execution paths inside a single service — that belongs in architecture internals.
+- **[STRICTLY FORBIDDEN]** Do NOT use for business action flows on a surface → use `/business-process`.
+- **[STRICTLY FORBIDDEN]** Do NOT use for runtime journey narratives focusing on user/system step order across the whole product → use `/journey`.
+
+---
+
+## Rule: Diagram Requirements
+
+- **[MANDATORY]** Use Mermaid `sequenceDiagram` for sync/async RPC, events, and messages.
+- **[MANDATORY]** Model: contract, direction, ownership, and handoff between services/systems.
+- **[MANDATORY]** Keep emphasis strictly on integration contracts and boundary ownership.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** Reference source mappings from `legacy-repos.local.json`.
+- **[MANDATORY]** Trace communication flows between legacy services/systems/boundaries.

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

@@ -0,0 +1,29 @@
+---
+name: db-erd
+description: /db-erd — Models shared business data and database ERD (entities, ownership, relationships).
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /db-erd — Business Data Model (ERD)
+
+**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).
+
+---
+
+## Rule: Modeling Approach
+
+- **[MANDATORY]** Use Mermaid `erDiagram`. Start from business entities and domain data ownership — NOT from a raw repository schema dump.
+- **[MANDATORY]** Place shared entities in the common scope when reused by multiple surfaces or modules.
+- **[STRICTLY FORBIDDEN]** Do NOT use this skill as a per-repository ORM/schema export unless the repository boundary strictly represents the actual data boundary.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** Reference source mappings from `legacy-repos.local.json`.
+- **[MANDATORY]** Map legacy schema to the business data model and entity ownership.

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

@@ -0,0 +1,30 @@
+---
+name: decision
+description: /decision — arc42 §09 ADRs (ADR-*); system decisions.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /decision — Architectural Decision Records (§09)
+
+---
+
+## Rule: Output
+
+- **[MANDATORY]** Path: `architecture/09-decisions/ADR-{NNN}-{slug}.md` + index table entry.
+- **[MANDATORY]** Template: `.cursor/extracts/tpl-adr.md`.
+- **[MANDATORY]** Link related entities: `CMP-*` / `CTR-*` / `FLOW-*` as needed.
+- **[MANDATORY]** Use `flowgrid_docs_list_ids kind:ADR` + `flowgrid_docs_validate_links` after creating a new ADR.
+
+---
+
+## Rule: Scope Boundaries
+
+- **[STRICTLY FORBIDDEN]** Do NOT place ADRs under `shared/adr` (redirect stub only if migration needed).
+- **[STRICTLY FORBIDDEN]** Do NOT move `api-catalog` / `data-model` into §09.
+- **[STRICTLY FORBIDDEN]** Platform process how-tos → `platform/` handbook, not §09.
+
+Parent: `/architecture`

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

@@ -0,0 +1,34 @@
+---
+name: deployment
+description: /deployment — optional DEP-* stub; do not invent prod topology.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /deployment — Deploy Stub-First
+
+**Business layer:** Deploy (outside module tree; thin architecture layer)  
+**Standards:** Short prose OK; diagrams → C4 `DEP-*` only when placement is confirmed.
+
+---
+
+## Rule: Default Behavior
+
+- **[MANDATORY]** If the user did NOT confirm that deployment placement matters → write/keep a **short stub only** (`tpl-deployment.md`).
+- **[STRICTLY FORBIDDEN]** Do NOT invent staging/production multi-region diagrams from imagination.
+- **[STRICTLY FORBIDDEN]** Do NOT write local IDE/WSL machine tips into the docs hub.
+- **[STRICTLY FORBIDDEN]** Never commit secrets into deployment documentation.
+
+---
+
+## Rule: When to Write Full Deployment Doc
+
+- **[MANDATORY]** Only author a full `DEP-*` deployment document when the user explicitly confirms placement matters.
+- **[MANDATORY]** Path: `Architecture/Deployment/`; ID: `DEP-*`.
+- **[MANDATORY]** Use `flowgrid_docs_list_ids kind:DEP` to check existing IDs before creating new ones.
+- **[STRICTLY FORBIDDEN]** Do NOT confuse with journey sequences (those belong to `/journey`).
+
+Parent: `/architecture`

package/harness/docs/skills/docs-hub/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: docs-hub
+extractBundle: docs-hub
+description: /docs-hub — FlowGrid docs lane MCP index (arc42 × C4 hub).
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Prefer targeted `flowgrid_docs_*` tool results over dumping `architecture/**`.
+
+# /docs-hub
+
+FlowGrid **docs lane**: index, validate, and route architecture/product Markdown from the configured docs hub (`FLOWGRID_DOCS_ROOT`). Consumer installs on FE/BE/test repos still read the member-selected docs checkout — never the code repo tree as SSOT.
+
+## Protocol
+
+```text
+flowgrid_docs_layout / flowgrid_docs_route / flowgrid_docs_list_ids
+  → flowgrid_docs_get_element
+  → flowgrid_docs_deps_of / flowgrid_docs_dependents_of
+  → flowgrid_docs_orphans / flowgrid_docs_validate_links
+```
+
+## Root and setup
+
+Document Hub:
+
+```bash
+cd /path/to/docs-hub
+flowgrid init   # project type: Document
+```
+
+Code / test consumer (pointer to docs hub):
+
+```bash
+cd /path/to/code-or-tests-repo
+flowgrid init   # set docs root when prompted
+```
+
+`FLOWGRID_DOCS_ROOT` must point at a tree with `architecture/`. Tools also accept `docsRoot` per call.
+
+## Index routing
+
+- **[MANDATORY]** Route by intent — do NOT merge repositories into one workspace graph:
+  - Architecture ID / C4 path → docs lane (`FLOWGRID_DOCS_ROOT`). **[STRICTLY FORBIDDEN]** CodeGraph for architecture Markdown.
+  - IR / registry for codegen → same `FLOWGRID_DOCS_ROOT` on consumer repos.
+  - Test plans / FLOW → `FLOWGRID_TESTS_DOC` when authoring on a test repo.
+  - Symbol / call-graph for repo X → CodeGraph MCP of repo X. **[STRICTLY FORBIDDEN]** hand-edit MCP config for platform wiring.
+  - ArtifactGraph stays local-only.
+
+## Harness scope
+
+Docs install syncs `/architecture`, `/spec`, `/adopt`, legacy variants, and the `architecture-core` extract bundle. Consumer install syncs `/docs-hub`, its rule/schema, and phase hooks.
+
+## Accelerators (optional)
+
+ArtifactGraph is optional hints only; docs lane never requires it. If unavailable, glob/read scoped Markdown under `architecture/` and `surfaces/`.
+
+At run start, assign one stable `runId`. After optional fallback reads, emit one `flowgrid.missing-optional` event per schema `.cursor/schemas/flowgrid-docs/missing-optional-event.schema.json`.
+
+## Verification Checklist
+- [ ] Index routing respected (`FLOWGRID_DOCS_ROOT` vs CodeGraph vs ArtifactGraph).
+- [ ] Hub contains `architecture/`.
+- [ ] Optional accelerator events emitted when ArtifactGraph was skipped.