yadflow 2.5.0 → 2.7.0

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -32,6 +32,33 @@ jobs:
         with: { node-version: "20" }
       - run: bash checks/build-test-lint.sh
 
+  # Pattern gates: commit subject + PR title + PR body all follow the convention (profile: code).
+  commit-message:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/commit-message.sh --profile code "origin/${{ github.base_ref }}"
+
+  # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
+  pr-title:
+    runs-on: ubuntu-latest
+    env:
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash checks/pr-title.sh --profile code "$PR_TITLE"
+
+  pr-template:
+    runs-on: ubuntu-latest
+    env:
+      PR_BODY: ${{ github.event.pull_request.body }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
+          bash checks/pr-template.sh --profile code "$body"
+
   # No unverified commits from unverified users: platform-Verified signature + allowlisted author.
   verified-commits:
     runs-on: ubuntu-latest

package/skills/yad-checks/templates/github/yad-hub-checks.yml

@@ -0,0 +1,36 @@
+# yad-managed: yad-checks
+# Pattern gates for the PRODUCT HUB: every PR (including the front-half review/EP-* PRs) must follow
+# the hub conventions — Conventional-Commits commit subjects, a `review: <artifact> (EP-<slug>)` PR
+# title, and a PR body that uses the hub artifact-review template. They run with `--profile hub`.
+# Standalone workflow so it never collides with the code-repo yad-checks workflow.
+name: yad-hub-checks
+on:
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  commit-message:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/commit-message.sh --profile hub "origin/${{ github.base_ref }}"
+
+  # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
+  pr-title:
+    runs-on: ubuntu-latest
+    env:
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash checks/pr-title.sh --profile hub "$PR_TITLE"
+
+  pr-template:
+    runs-on: ubuntu-latest
+    env:
+      PR_BODY: ${{ github.event.pull_request.body }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
+          bash checks/pr-template.sh --profile hub "$body"

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -45,6 +45,26 @@ yad-build-test-lint:
   script:
     - bash checks/build-test-lint.sh
 
+# Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).
+yad-commit-message:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/commit-message.sh --profile code "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-pr-title:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/pr-title.sh --profile code "$CI_MERGE_REQUEST_TITLE"
+
+yad-pr-template:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
+    - bash checks/pr-template.sh --profile code "$body"
+
 # No unverified commits from unverified users: platform-Verified signature + allowlisted author.
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot
 # read the commit-signature API. Without it the job FAILS closed with guidance.

package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml

@@ -0,0 +1,39 @@
+# yad-managed-include: yad-checks
+# Pattern gates for the PRODUCT HUB, as an INCLUDABLE fragment. Pulled into the hub's root
+# .gitlab-ci.yml via:
+#   include:
+#     - local: '.gitlab/ci/yad-hub-checks.yml'
+# Every MR (including the front-half review/EP-* MRs) must follow the hub conventions — a
+# Conventional-Commits commit subject, a `review: <artifact> (EP-<slug>)` MR title, and an MR body
+# that uses the hub artifact-review template. They run with `--profile hub`.
+# Job names are yad-hub-prefixed so they coexist with any code-repo fragment in one pipeline; jobs use
+# `needs: []` and no `stage:` so a foreign `stages:` list can neither break nor reorder them.
+default:
+  image: node:20
+  tags: [$YAD_RUNNER_TAGS]
+
+.yad_hub_mr_only:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+
+variables:
+  GIT_DEPTH: "0"   # full history so the commit gate can diff against the target branch
+
+yad-hub-commit-message:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - bash checks/commit-message.sh --profile hub "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-hub-pr-title:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - bash checks/pr-title.sh --profile hub "$CI_MERGE_REQUEST_TITLE"
+
+yad-hub-pr-template:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
+    - bash checks/pr-template.sh --profile hub "$body"

package/skills/yad-commit/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: yad-commit
+description: 'Build-half helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task → Contract-Change → Co-Authored-By), and an atomic-file guard (≤3 files). The human git author OWNS the commit; an assisting AI is recorded only as a Co-Authored-By footer, chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none — default none, human-only). Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
+---
+
+# SDLC — Commit by Convention (build-half helper)
+
+**Goal:** Turn ONE staged atomic change into a single commit that satisfies the project conventions
+(`CONTRIBUTING.md` / `config.yaml` `build`): a Conventional-Commits subject, the fixed trailer order
+`Task → Contract-Change → Co-Authored-By`, and the atomic-file guard. This is the standalone commit
+step — the same engine `yad-implement` and `yad-ship` use. It **never auto-advances**; it just commits.
+
+## Conventions
+
+- Run **inside the repo holding the staged change** — a code repo under
+  `{project-root}/demo-repos/<repo>/`, or the product hub itself. Use absolute paths.
+- **Stage first.** Only the staged (`git add`) atomic change is committed. The guard refuses more than
+  `ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead.
+- **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
+  `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
+- **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
+  with `--task`, else derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
+  task-scoped, so the trailer is optional there.
+- **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract
+  surface; it routes the change back to the architecture gate.
+- **AI co-author footer** — `--ai <id>` records the assisting tool as a `Co-Authored-By` trailer. The
+  human is always the author; `--ai none` (the default) is an explicit human-only commit.
+
+## Inputs
+
+- `type`    — Conventional-Commits type (required).
+- `message` — the subject text (required), `-m "<subject>"`.
+- `ai`      — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none`).
+- `task`    — Task trailer (optional; derived from the branch when omitted).
+- `contractChange` — flag; mark the contract surface touched.
+
+## On Activation
+
+### Step 1 — Confirm the atomic stage
+Confirm the change is staged and stays within the file boundary (≤3 files where possible). If more is
+staged, split it into separate commits rather than passing `--force`.
+
+### Step 2 — Commit by convention
+Run the CLI from the repo root:
+```
+yad commit --type <type> -m "<subject>" [--ai <id>] [--task <id>] [--contract-change] [--dry-run]
+```
+Use `--dry-run` first to preview the exact message (subject + trailer block) without committing. The
+CLI validates the type, rejects a trailing period, and emits the trailers in the fixed order.
+
+### Step 3 — Stop (no auto-advance)
+Report what was committed (files + Task). If `--contract-change` was set, note that it routes back to
+the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
+
+## Hard rules
+
+- **One staged atomic change = one commit.** Never bundle; never exceed the file boundary silently.
+- **The human author owns the commit.** The AI is only a `Co-Authored-By` footer, chosen per-commit.
+- **Trailer order is fixed:** `Task → Contract-Change → Co-Authored-By`.
+- **Never widen the contract here.** A contract touch is flagged (`--contract-change`), not hidden.
+
+## Reference
+- Branch/commit conventions + the file-boundary rule: `../yad-implement/references/implement-conventions.md`.
+- The full convention text: `CONTRIBUTING.md`; the config: `skills/sdlc/config.yaml` `build`.
+- The gate that enforces the subject pattern: `../yad-checks/references/check-gates.md` (`commit-message`).
+- Open the PR/MR after committing: `../yad-open-pr/SKILL.md`; both at once: `../yad-ship/SKILL.md`.

package/skills/yad-connect-docs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: yad-connect-docs
+description: 'Connects a docs/Pages publishing target to the product hub so the interactive-docs steps can build and deploy the generated SPA — not just commit its source. Registers the target into the project-wide .sdlc/docs.json (GitHub Pages / GitLab Pages / build-only), auto-detecting the platform from .sdlc/hub.json and resolving the Vite base path, with local-user auth and no stored tokens. Detects whether gh/glab is present and degrades to build-only when absent. Run at setup or any time the publish target changes. Reusable, idempotent, refreshable. Use when the user says "connect docs", "connect Pages", "refresh the docs connection", or "list the docs connection".'
+---
+
+# SDLC — Connect a Docs/Pages Target (make the docs steps publishable)
+
+**Goal:** Let the interactive-docs steps (`yad-docs` per epic, `yad-docs-overview` project-wide)
+**build and deploy** the generated React/Vite SPA to a real URL — a GitHub Pages or GitLab Pages site —
+instead of only committing its source. This skill **connects** a publishing target to the product hub
+and records *how* to reach it (the platform, the publish scope, the base path) — never a credential.
+
+This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+epic's approvals. It only writes the project-wide docs registry. `yad-docs` / `yad-docs-overview`
+consume it: when a target is connected, they theme + generate the site and drive `yad docs deploy`;
+when nothing is connected (`target: "none"`), they still generate and **npm-build** the site but stop
+at a local `dist/` — build-only, no publish, exactly as before.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The target is **GitHub-Pages-first but pluggable** — a *publish adapter*, mirroring the GitHub/GitLab
+  platform adapter the hub already uses. `github-pages` and `gitlab-pages` are the providers; `none` →
+  build-only (deliberate, no error).
+- The platform CLI (`gh` / `glab`) is a **subprocess**, used read/deploy-only via the user's own auth —
+  never installed by this skill, never given a token. Absent ⇒ degrade to build-only (`source:
+  "unavailable"`).
+- Registry: `{project-root}/.sdlc/docs.json` (project-wide, shared across all epics + the overview —
+  NOT per-epic), the sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`.
+- Per-epic / overview build manifests (`docs-build.json`) are written later by `yad-docs` /
+  `yad-docs-overview`, not here. This skill describes the *connection*; it does not build.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `target` — `github-pages` | `gitlab-pages` | `none`. Default **auto-detected** from `.sdlc/hub.json`
+  `platform` (github → `github-pages`, gitlab → `gitlab-pages`, null/no hub → `none`).
+- `scope` — `hub` (default) | `<repo-name>` | `dedicated`. Where the Pages site is published from (the
+  hub repo, one connected code repo, or a dedicated docs repo).
+- `public` — `true` (default) | `false`. Whether the published site is public.
+- `base_path` — optional explicit override of the Vite `base` (otherwise resolved, Step 2).
+
+## On Activation
+
+### Step 1 — Resolve the target + detect the platform (the publish adapter)
+Determine the `target`. If not given, read `{project-root}/.sdlc/hub.json` `platform` and map it the same
+way the hub bridge maps repos: `github` → `github-pages`, `gitlab` → `gitlab-pages`, `null`/no hub →
+`none` (deliberate build-only). Reject a `target` value outside the three providers (fall back to the
+detected default with a warning, the way `registerRepo` falls back on an unknown platform).
+
+Then **probe the platform CLI** in the user's own session — `gh --version` / `gh auth status` for
+GitHub, `glab --version` / `glab auth status` for GitLab. Record `source`:
+- CLI present + authenticated → `source: "gh"` | `"glab"` (deploy can publish via the platform).
+- CLI absent or unauthenticated → `source: "unavailable"` — record it and report that `yad-docs` will
+  **build-only** (npm build to a local `dist/`, no publish) until the CLI is available. No error — the
+  publish is purely additive, exactly like the `gh`/`glab` review bridge degrading.
+
+**Auth is the local user's own** (`gh`/`glab`/git already on this device). The skill **stores no
+tokens**; everything in the registry is a plain reference. Do **not** install a CLI as part of this step.
+
+### Step 2 — Decide the publish scope + resolve the base path
+Resolve `scope` → `publishRepo`:
+- `hub` (default) → publish from the hub repo (read its name from `hub.json` `git_url`).
+- `<repo-name>` → publish from that connected code repo (must exist in `.sdlc/repos.json`).
+- `dedicated` → a dedicated docs repo the user names (recorded as `publishRepo`).
+
+Resolve `basePath` (the Vite `base`) per the table in `references/docs-registry.md`:
+- **GitHub *project* Pages** (a repo that is not `<user>.github.io`) serve under `/<repo>/` → `basePath =
+  "/<repo>/"`. Per-epic sites nest under `/<repo>/epics/EP-<slug>/`; the overview under `/<repo>/`.
+- **GitHub user/org Pages** (`<user>.github.io`) and **GitLab Pages** serve at the domain root → `basePath
+  = "/"`.
+- An explicit `base_path` input always wins (recorded verbatim, normalized to a leading + trailing `/`).
+
+### Step 3 — Record the connection in the registry (idempotent)
+Upsert into `{project-root}/.sdlc/docs.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "target": "github-pages",
+  "scope": "hub",
+  "publishRepo": "<repo or hub name>",
+  "basePath": "/<repo>/",
+  "public": true,
+  "auth": "user",
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "gh"
+}
+```
+
+- `target: "none"` records a deliberate build-only project: `{ "target": "none", "scope": "hub",
+  "publishRepo": null, "basePath": "/", "source": "unavailable", ... }`.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
+  one docs target at a time; switching targets is just another `connect`).
+
+### Step 4 — Report (never auto-advance)
+Report the connected `target`, its `scope`/`publishRepo`, the resolved `basePath`, whether the platform
+CLI is available (or that the docs steps will degrade to **build-only**), and that **`yad-docs` /
+`yad-docs-overview` will now build + deploy here**. Nothing auto-advances; this is setup. **Do not build
+the site here — `yad-docs` builds.**
+
+## Other actions
+
+- **`refresh`** — re-detect the platform CLI and re-resolve the base path (after the user authenticates a
+  session, renames the publish repo, or switches `scope`), updating `lastSyncedAt`. Same machinery as
+  `connect`. Re-detection may flip `source` between `gh`/`glab` and `unavailable` — report the change.
+- **`list`** — print the current connection: `target`, `scope`/`publishRepo`, `basePath`, `public`, and a
+  **available/unavailable** flag for the platform CLI (best-effort, the user's own session). No target
+  connected ⇒ "build-only".
+- **`disconnect`** — remove the registry file (or set `target: "none"`). The platform's own Pages site is
+  **never touched** — only the hub's record of it.
+
+## Hard rules
+
+- **Local-user auth only; store no tokens.** Connect through the user's own `gh`/`glab`/git; never embed a
+  PAT or any credential in the registry. Everything recorded is a plain reference.
+- **Degrade gracefully.** No target / no platform CLI → the docs steps **build-only** (local `dist/`) with
+  no error. Publishing is additive, never a blocker — the same discipline as the `gh`/`glab` review bridge.
+- **Setup, not a gate.** Never touch `.sdlc/state.json`, approvals, or the contract lock from here.
+- **Idempotent + refreshable.** `connect`/`refresh` are safe to re-run; a project carries one docs
+  connection at a time.
+- **Describe the connection; do not build here.** This skill records *how to reach* the target.
+  `yad-docs` / `yad-docs-overview` generate, build, and deploy the site.
+
+## Reference
+- Registry schema, the base-path resolution table, and the freshness/degrade rules:
+  `references/docs-registry.md`.
+- The connect pattern this mirrors (design tool): `../yad-connect-design/SKILL.md`.
+- The connect pattern this mirrors (code repos + hub detection): `../yad-connect-repos/SKILL.md`.
+- The consumers — how `yad-docs` / `yad-docs-overview` build + deploy: `../yad-docs/SKILL.md`,
+  `../yad-docs-overview/SKILL.md`.

package/skills/yad-connect-docs/references/docs-registry.md

@@ -0,0 +1,74 @@
+# `.sdlc/docs.json` — the docs/Pages registry
+
+Project-wide, shared across every epic's docs site **and** the project overview site (NOT per-epic).
+The sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`. Written by
+`yad-connect-docs`; read by `yad-docs`, `yad-docs-overview`, `yad-docs-sync`, and the `yad docs` CLI.
+Holds **no credentials** — every field is a plain reference. Auth is always the local user's own
+`gh`/`glab`/git session.
+
+## Schema
+
+```json
+{
+  "target": "github-pages | gitlab-pages | none",
+  "scope": "hub | <repo-name> | dedicated",
+  "publishRepo": "<repo or hub name>",
+  "basePath": "/<repo>/",
+  "public": true,
+  "auth": "user",
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "gh | glab | unavailable"
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `target` | The publish adapter. `none` = deliberate build-only (no publish, no error). |
+| `scope` | Where the Pages site publishes from: the `hub` repo, one connected `<repo-name>`, or a `dedicated` docs repo. |
+| `publishRepo` | The concrete repo name resolved from `scope`. `null` when `target: "none"`. |
+| `basePath` | The Vite `base` substituted into each generated site (resolution table below). Normalized to a leading + trailing `/`. |
+| `public` | Whether the published site is public. |
+| `auth` | Always `"user"` — local-user / platform-CLI session. No token is ever stored. |
+| `connectedAt` / `lastSyncedAt` | ISO dates the connection was first written / last re-detected. |
+| `source` | `gh`/`glab` when the platform CLI is present + authenticated (publish works); `unavailable` when absent (build-only). |
+
+`target: "none"` records `{ "target": "none", "publishRepo": null, "basePath": "/", "source":
+"unavailable", ... }`.
+
+## Platform auto-detection (from `.sdlc/hub.json`)
+
+When `target` is not given, map the hub's `platform` the same way `yad-connect-repos` maps a repo host:
+
+| `hub.json` `platform` | default `target` |
+|-----------------------|------------------|
+| `github` | `github-pages` |
+| `gitlab` | `gitlab-pages` |
+| `null` / no hub.json | `none` (build-only) |
+
+## Base-path resolution table
+
+GitHub serves *project* Pages under a `/<repo>/` prefix, so Vite's `base` must match or every asset 404s.
+User/org Pages and GitLab Pages serve at the domain root.
+
+| Target + repo kind | `basePath` | Per-epic site URL | Overview site URL |
+|--------------------|------------|-------------------|-------------------|
+| GitHub **project** Pages (repo ≠ `<user>.github.io`) | `/<repo>/` | `/<repo>/epics/EP-<slug>/` | `/<repo>/` |
+| GitHub **user/org** Pages (`<user>.github.io`) | `/` | `/epics/EP-<slug>/` | `/` |
+| GitLab Pages | `/` | `/epics/EP-<slug>/` | `/` |
+| explicit `base_path` input | as given (normalized) | nests `epics/EP-<slug>/` under it | the given base |
+
+An explicit `base_path` input always wins. `yad-docs` substitutes `basePath` into the shell's Vite
+config; per-epic sites append `epics/EP-<slug>/` so they nest under the overview without colliding.
+
+## Freshness + degrade rules
+
+- **Freshness** here is connection-level, not content-level: `lastSyncedAt` reflects the last `refresh`.
+  *Site* staleness (artifacts/repos moved, shell upgraded) is tracked separately in each site's
+  `docs-build.json` and reconciled by `yad-docs-sync` — not here.
+- **`list`** flags the platform CLI **available/unavailable** by probing `gh auth status` / `glab auth
+  status` in the user's own session (best-effort). A flip to `unavailable` means the docs steps
+  degrade to build-only until the CLI is back.
+- **Degrade is silent + non-blocking.** No target / no CLI ⇒ `yad-docs` still generates + npm-builds the
+  site to a local `dist/`; only the publish step is skipped. The same discipline as the design-tool MCP
+  and the `gh`/`glab` review bridge being absent.

package/skills/yad-docs/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: yad-docs
+description: 'Generates the per-epic interactive documentation site — a vendored React/Vite/Tailwind SPA with an animated flow canvas and role-based stakeholder doc pages — from the epic''s approved artifacts (epic, architecture, the locked contract, UI design, stories, code-context, test cases). Themes it from the design tokens, wires the docs.json base path, and drives `yad docs build/deploy` to publish to Pages (or build-only when no target). This is an OUTPUT ENRICHMENT, never a gated front state: it never mutates state.json steps, approvals, or the contract lock. Use when the user says "generate the docs site", "build the interactive docs", or "deploy the epic docs".'
+---
+
+# SDLC — Author the Interactive Docs Site (per-epic, output enrichment)
+
+**Goal:** Turn an epic's approved artifacts into a **living, interactive documentation site** — a
+vendored React 19 + Vite 7 + Tailwind v4 SPA with an animated **flow canvas** (system components on a
+canvas, animated messages, playback, a system-logs terminal, a right detail panel) and **role-based
+stakeholder doc pages** (each lens → a set of doc sections). The shell is generic; the **content** is
+generated entirely into `src/data/*.ts` and the theme into `src/index.css`.
+
+This is an **output enrichment**, exactly like `design-links.json` / `test-links.json` — **NOT a gated
+front state.** It **never** mutates `.sdlc/state.json` `steps[]`, `approvals.json`, or
+`contract-lock.json`, and it never adds a `state.json` step. It reads the *approved* shape and renders
+it; it never decides approval. When a docs target is connected (`yad-connect-docs` → `.sdlc/docs.json`)
+the site is built + deployed; when none is, it is npm-built to a local `dist/` (build-only).
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- Artifacts live under `{project-root}/epics/EP-<slug>/`. The generated site lives at
+  `epics/EP-<slug>/docs-site/`; its `dist/` and `node_modules/` are gitignored, the generated **source
+  is committed**.
+- The shell template is `skills/yad-docs/templates/app/` — copied **verbatim**, never modified in place.
+  Generated data must satisfy the types in `src/data/types.ts`.
+- The docs target is recorded in `{project-root}/.sdlc/docs.json` (`yad-connect-docs`). The per-epic
+  build manifest (the staleness baseline) is `epics/EP-<slug>/.sdlc/docs-build.json`.
+- The actual data-file **generation** (reading artifacts → writing `src/data/*.ts`, theming
+  `index.css`) is the **AI step** inside this skill; the `yad docs` CLI only does the npm build +
+  platform deploy + staleness hashing.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `epic` — `EP-<slug>` (ask if not provided).
+- `action` — `generate` (default) | `refresh` | `deploy`.
+- `login_gate` — `true` | `false` (default `false`). When on, the generated site gates behind a local
+  login screen (`useAuthStore`); default off (public docs).
+
+## On Activation
+
+### Step 1 — Resolve the epic + check the *shape* is approved (NOT the gate)
+Resolve `EP-<slug>`. Read `.sdlc/state.json`. Require **at least** that the epic exists and its
+`epic-review` step has `status == "done"` (so the docs never describe an *unapproved* shape) — but do
+**NOT** require any specific `currentStep`. Docs are an enrichment that runs over whatever is approved
+so far. **Never touch `approvals.json` or `contract-lock.json`.** If `epic-review` has not passed, stop
+and point the user at the gate (`yad-review-gate`); do not render an unapproved epic.
+
+### Step 1b — Open the authoring branch
+Open the `docs/EP-<slug>` authoring branch per the shared procedure
+(`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
+`{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Generate and commit the site source on it.
+
+### Step 2 — Read the inputs (the data sources)
+Load each artifact and note what it feeds (full table in `references/data-mapping.md`):
+
+- `epic.md` → **ExecutiveSummary** + **PMRoadmap** sections.
+- `architecture.md` → **system components** (`components.ts`) + **flow paths** + the **Deployment** and
+  **Security** doc sections.
+- `contract.md` `CONTRACT-SURFACE` → **ApiReference** / **StatusMachine** / **DbSchema** — the
+  **authoritative** API source. The docs **cannot drift** from the locked contract; render the surface
+  exactly as locked (cross-check `contract-lock.json`'s hash matches, but never modify it).
+- `ui-design.md` + `DESIGN.md` + `.sdlc/design-links.json` → flow-path **UI states**, the `index.css`
+  **theme**, and a **Screens** section (linking the design-tool frames when present).
+- `stories/*.md` → **one FlowPath each** (acceptance criteria → animated `FlowStep` messages +
+  `sideEffects`).
+- `.sdlc/repos.json` + `.sdlc/code-context/<repo>/code-map.md` (for each repo in `epic.repos`) → real
+  module/endpoint names that **enrich** the components. **Staleness:** if a repo's current HEAD ≠ its
+  registry `syncedHead`, **warn** and stamp `code-context: stale` in the manifest — suggest `yad repo
+  refresh <repo>` (a human decision); **never auto-refresh**.
+- `test-cases.md` + `.sdlc/test-links.json` → the **TestPlan** section.
+
+Greenfield-safe: any absent input (no design tool, no test cases, no repos) degrades that section to
+empty/omitted with a note — never invent content.
+
+### Step 3 — Generate the site into `epics/EP-<slug>/docs-site/`
+Copy the shell from `templates/app/` **verbatim**, then:
+
+1. **Generate `src/data/*.ts` deterministically** — `paths.ts`, `components.ts`, `roles.ts`,
+   `docSections.ts`, `referenceData.ts` (mapping in `references/data-mapping.md`). Sort by **stable
+   IDs** (story `S0N`, repo name, endpoint `method+path`), use a **fixed key order**, and write **NO
+   timestamps inside the data files** — so regenerating an unchanged input yields a byte-identical file
+   (the staleness hash depends on it). Data must satisfy `src/data/types.ts`
+   (`FlowPath`/`FlowStep`/`AnimatedMessage`/`SystemComponent`/`StakeholderView`, etc.).
+2. **Derive stakeholder roles** (`roles.ts`) from the hub roster roles (`.sdlc/hub.json`) ∩ the yadflow
+   lens set (analyst / pm / architect / ux / dev / tester / reviewer / engineer) ∩ the stories' `repos:`
+   tags — each role → its relevant doc `sectionIds` + `relevantPathIds` (`references/data-mapping.md`).
+3. **Theme the `:root` block of `src/index.css`** from the design tokens, by the 4-tier priority in
+   `references/theme-map.md`: **DESIGN.md → design.json/design-links.json palette → code-map tokens →
+   default theme** (stamp `theme: default` in the manifest when it falls through to the shell default).
+   Keep fonts Space Grotesk + Noto Sans and the `.glass-panel`/`.flow-grid`/`.code-block` utilities.
+4. **Substitute the Vite base** from `.sdlc/docs.json` `basePath` (per-epic sites nest under
+   `/<repo>/epics/EP-<slug>/`). Read `docs.json` for the base path + target; if absent, default base
+   `/` and treat as build-only.
+5. **Set the login-gate flag** (`login_gate`, default off).
+
+### Step 4 — Write the build manifest (the staleness baseline)
+Write `epics/EP-<slug>/.sdlc/docs-build.json` — the baseline `yad-docs-sync` compares against:
+
+```json
+{
+  "builtAt": "<YYYY-MM-DD>",
+  "theme": "design.json | DESIGN.md | default",
+  "artifactHash": "<sha256 of epic.md + architecture.md + contract.md CONTRACT-SURFACE + ui-design.md + each story>",
+  "repoHeads": { "<repo>": "<HEAD sha>" },
+  "deployUrl": "<url or null>",
+  "templateVersion": "<shell template version>"
+}
+```
+
+Do **NOT** add a `state.json` step — docs are an enrichment, exactly like `design-links.json`.
+Optionally record a `docs:` line in a `DOCS.md` index under the epic.
+
+### Step 5 — Build / deploy (`action`)
+- `action: generate` (default) — generate the source + manifest; stop. The CLI may npm-build to verify,
+  but no publish.
+- `action: deploy` — drive **`yad docs deploy --epic <id>`**: it npm-builds the site (`npm ci && npm run
+  build` as a subprocess, like `yad-spec` shelling `npx repomix`), ensures the Pages CI workflow is
+  present, and reports the deploy URL (publish happens via CI). **Degrades** to the local `dist/` path
+  when no platform CLI / `target: "none"` (build-only).
+
+### Step 6 — Stop. Report (NEVER auto-advance)
+Report: the site path (`epics/EP-<slug>/docs-site/`), the data files produced, the **theme source** (or
+the default-theme degrade), the **deploy URL** or "build-only", and the **staleness baseline**
+(`docs-build.json`). **NEVER auto-advance, NEVER record approval — this is not a gate.** Note any
+`code-context: stale` warning so the human can refresh the repo cache.
+
+## Hard rules
+
+- **Output enrichment, never a gate.** This skill **MUST NEVER** mutate `.sdlc/state.json` `steps[]`,
+  `approvals.json`, or `contract-lock.json`, and never adds a state step — exactly how `yad-ui` writes
+  `design-links.json` without changing the locked step shape.
+- **Docs cannot drift from the locked contract.** The contract surface is the authoritative API source;
+  render it as locked. Never edit `contract-lock.json` or the contract here.
+- **Deterministic generation.** Stable-ID sort, fixed key order, no timestamps inside `src/data/*.ts` —
+  so an unchanged input regenerates byte-identically and the staleness hash is meaningful.
+- **Never auto-refresh a stale repo.** HEAD ≠ `syncedHead` ⇒ warn + stamp `code-context: stale`; the
+  refresh is a human decision (`yad repo refresh`).
+- **Degrade gracefully.** No docs target → build-only (local `dist/`). No design tokens → default theme.
+  Absent inputs → omitted sections. No error — the site is additive.
+- **Copy the shell verbatim.** Generate only `src/data/*.ts`, the `:root` of `index.css`, and the Vite
+  base. Never hand-edit `templates/app/`.
+
+## Reference
+- The deterministic DESIGN-token → CSS-custom-property mapping + 4-tier priority + default fallback:
+  `references/theme-map.md`.
+- The full artifact → data-structure table, determinism rules, and role derivation:
+  `references/data-mapping.md`.
+- The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
+- The design tokens this themes from: `../yad-connect-design/SKILL.md`.
+- The code-context the data enriches: `../yad-connect-repos/SKILL.md`.
+- The authoring pattern (front-state author that writes link artifacts without gating):
+  `../yad-ui/SKILL.md`.
+- State schema + the "Authoring branches" procedure: `../yad-epic/references/state-schema.md`.
+- The project overview site + the staleness/CI reconciler: `../yad-docs-overview/SKILL.md`,
+  `../yad-docs-sync/SKILL.md`.

package/skills/yad-docs/references/data-mapping.md

@@ -0,0 +1,75 @@
+# Data mapping — artifacts → `src/data/*.ts`
+
+`yad-docs` copies the shell verbatim and **generates** the five data modules under `src/data/`. The
+shell renders whatever these export, as long as it satisfies `src/data/types.ts`
+(`FlowPath` / `FlowStep` / `AnimatedMessage` / `SystemComponent` / `StakeholderView` / `RoleConfig` /
+`DocSectionConfig`). The generation is the AI step; it must be **deterministic** (rules at the bottom).
+
+## Artifact → data-structure table
+
+| Generated file | Exports | Fed by (artifact) | What maps |
+|----------------|---------|-------------------|-----------|
+| `components.ts` | `COMPONENTS: SystemComponent[]` | `architecture.md` system components + `code-map.md` module/endpoint names | each durable component → `{ id, label, icon, color, position, description }`; canvas `position` laid out deterministically; real module names from the code-map enrich `label`/`description`. |
+| `paths.ts` | `FLOW_PATHS: FlowPath[]` | `stories/*.md` (one FlowPath each) + `architecture.md` flows | each story → one `FlowPath` (`id`, `label`, `icon`, `color`, `category`, `steps[]`); each acceptance criterion → a `FlowStep` whose `messages: AnimatedMessage[]` animate the request/response/event/job and whose `sideEffects` record jobs/notifications/pubsub. UI states (from `ui-design.md`) annotate each step. |
+| `roles.ts` | `ROLES: RoleConfig[]` | hub roster (`.sdlc/hub.json`) + the yadflow lens set + stories' `repos:` tags | each stakeholder lens → `{ slug, label, shortLabel, icon, color, description, sectionIds, relevantPathIds }` (role derivation below). |
+| `docSections.ts` | `DOC_SECTIONS: DocSectionConfig[]` | `epic.md`, `architecture.md`, `contract.md`, `ui-design.md`, `test-cases.md` | the ordered doc-section registry (`{ id, title, icon, iconColor, component }`); each section id is referenced from `roles.ts`. |
+| `referenceData.ts` | the reference tables/payloads the doc-section components render | `contract.md` CONTRACT-SURFACE (authoritative) + `architecture.md` + `test-cases.md` | API reference rows, the status machine, the DB schema, feature flags, error codes, the test plan — the structured data behind the doc sections. |
+
+## Section sources (the doc sections + their artifact)
+
+| Doc section(s) | Artifact source |
+|----------------|-----------------|
+| ExecutiveSummary, PMRoadmap | `epic.md` |
+| FlowOverview, system components, Deployment, Security | `architecture.md` |
+| **ApiReference, StatusMachine, DbSchema** | `contract.md` **CONTRACT-SURFACE — authoritative, must not drift from `contract-lock.json`** |
+| Rider/Driver/role UI states, Screens, the theme | `ui-design.md` + `DESIGN.md` + `design-links.json` |
+| TestPlan, FlowPathsChecklist, ErrorCodes | `test-cases.md` + `test-links.json` |
+
+Any absent input degrades its section to empty/omitted (greenfield-safe); never invent content. The
+contract is rendered exactly as locked — the docs are a *view* of the locked surface, never a re-author.
+
+## Role derivation (`roles.ts`)
+
+A stakeholder role is generated for each lens that is **both** present in the hub roster **and** relevant
+to this epic:
+
+1. Start from the **yadflow lens set**: `analyst`, `pm`, `architect`, `ux`, `dev`, `tester`, `reviewer`,
+   `engineer`.
+2. Intersect with the **hub roster** roles (`.sdlc/hub.json` `roster[].roles`) — only emit lenses the
+   team actually has (an unmapped lens is dropped, never invented).
+3. For the `dev`/`engineer` lenses, **fan out per `repos:` tag** present across the epic's stories (e.g.
+   a `backend` dev role and a `mobile` dev role), so each repo audience gets its own integration view —
+   mirroring the reference site's per-app dev roles.
+4. Each role maps to its relevant `sectionIds` (which doc sections it should see) + `relevantPathIds`
+   (which FlowPaths/stories touch it). Keep these stable: derive `relevantPathIds` from the stories
+   tagged with that role's repo, sorted by story id.
+
+## Determinism rules (load-bearing — the data feeds `artifactHash`)
+
+- **Sort by stable IDs:** stories by `S0N`, repos by name, endpoints by `method + path`, roles by lens
+  order above. Never sort by anything time- or order-of-discovery-dependent.
+- **Fixed key order** in every emitted object (match the `types.ts` field order).
+- **No timestamps inside `src/data/*.ts`.** Build/deploy times live only in `docs-build.json`.
+- Colors/icons assigned to paths/components/roles come from the theme + a **fixed** lens→icon/color map
+  (Material Symbols names), not randomly — so regenerating an unchanged input yields a byte-identical
+  file, and the staleness hash only moves when an *artifact* actually moves.
+- IDs are derived from the source IDs (story id → `FlowPath.id`, repo/module name → component `id`), never
+  freshly minted, so links stay stable across regenerations.
+
+## The DocSection components are NOT purely data-driven — regenerate their content too
+
+The vendored shell ships the reference app's `src/components/DocSections/*.tsx` **with hardcoded
+booking-domain content inline** (e.g. `ApiReferenceSection.tsx` declares a literal `ENDPOINTS`
+array). They are NOT yet wired to read everything from `referenceData.ts`. So generation has two
+parts, both the AI step:
+
+1. **Data files** — write `src/data/{paths,components,roles,docSections,referenceData}.ts` from the
+   artifacts (the table above).
+2. **Section content** — for every section a role references, replace the inline constants inside the
+   matching `DocSections/<Name>Section.tsx` with this epic's content (or refactor the section to read
+   its rows from `referenceData.ts`). A section left with the reference's booking content is a bug —
+   the docs would describe the wrong system. The contract surface is the authoritative source for the
+   API/StatusMachine/DbSchema sections.
+
+Keep both deterministic (sorted, fixed key order, no timestamps) so the build manifest hash only moves
+when an artifact actually moves.