yadflow 2.6.0 → 2.7.0

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.

package/skills/yad-docs/references/theme-map.md

@@ -0,0 +1,69 @@
+# Theme map — DESIGN tokens → `index.css` `:root`
+
+`yad-docs` themes only the **`:root` block** of the copied shell's `src/index.css` (and nothing else —
+fonts, utilities, and the rest of the file stay verbatim). The shell's design system is a dark
+CSS-custom-property theme; theming = overwriting the `:root` custom properties from the epic's design
+tokens, deterministically. Fonts are always **Space Grotesk** (display / headings) + **Noto Sans**
+(body), and the `.glass-panel` / `.flow-grid` / `.code-block` utilities and Material Symbols icon names
+are untouched.
+
+## 4-tier priority (first hit wins, per property)
+
+For each custom property, resolve its value in this order and **stamp `theme:` in `docs-build.json`** to
+the tier that supplied the palette:
+
+1. **`DESIGN.md`** (`theme: DESIGN.md`) — the epic's hand/Impeccable-authored design-system tokens. The
+   richest source; use it when present.
+2. **`design.json` / `design-links.json` palette** (`theme: design.json`) — the connected design tool's
+   palette (e.g. a Figma file's color styles read back).
+3. **code-map tokens** (`theme: design.json`-tier fallback, noted) — brand/theme tokens captured in
+   `.sdlc/code-context/<repo>/code-map.md` for repos in `epic.repos`, so the site matches the built UI.
+4. **default theme** (`theme: default`) — keep the shell's reference `:root` verbatim (the dark theme
+   below). Stamp `theme: default` so the degrade is visible.
+
+A single missing token falls through to the next tier for **that token only** (the others can still come
+from a higher tier); only a wholesale absence stamps `theme: default`.
+
+## Token → custom-property mapping
+
+Map design tokens onto these properties (the exact set the shell defines). Names match the reference
+`index.css` — do not rename or add properties.
+
+| Design token (role) | CSS custom property | Default (reference) |
+|---------------------|---------------------|---------------------|
+| page background | `--color-bg-primary` | `#141118` |
+| raised surface | `--color-bg-secondary` | `#1e1a25` |
+| higher surface | `--color-bg-tertiary` | `#2f2938` |
+| brand wash | `--color-bg-brand-soft` | `#1a0244` |
+| accent wash | `--color-bg-accent-soft` | `#25060e` |
+| panel surface | `--color-surface-dark` | `#1e1a25` |
+| highlighted surface | `--color-surface-highlight` | `#2f2938` |
+| darkest surface (code blocks) | `--color-surface-darker` | `#0f0e13` |
+| primary text | `--color-text-primary` | `#ffffff` |
+| secondary text | `--color-text-secondary` | `#a8a4b2` |
+| muted text | `--color-text-muted` | `#767284` |
+| **primary brand** | `--color-primary` | `#6116da` |
+| primary hover | `--color-primary-hover` | `#7a2ce0` |
+| primary soft | `--color-primary-soft` | `#35087c` |
+| **accent** | `--color-accent` | `#ff6490` |
+| accent hover | `--color-accent-hover` | `#fb2576` |
+| accent soft | `--color-accent-soft` | `#4f0520` |
+| light border | `--color-border-light` | `#453c53` |
+| default border | `--color-border-default` | `#342e40` |
+| strong border | `--color-border-strong` | `#141118` |
+
+### Derivation rules (deterministic)
+- The two anchors are **`--color-primary`** and **`--color-accent`**; everything else derives from them
+  and the background ramp when a source supplies only a brand + accent.
+- `*-hover` = the anchor lightened one step; `*-soft` = the anchor darkened/desaturated for washes.
+  Apply a **fixed** lightness delta (no randomness) so regeneration is byte-identical.
+- The background ramp (`bg-primary` → `bg-tertiary` → `surface-*`) is darkest→lighter; preserve that
+  ordering when mapping a source's neutrals.
+- Always emit the **full property set** in the **fixed order above** (matching the reference file), with
+  no trailing timestamp/comment — the theme contributes to the `artifactHash`, so determinism matters.
+
+## Fonts + utilities (never themed)
+Headings/`.font-display` → **Space Grotesk**; body/`.font-body` → **Noto Sans**. The `.glass-panel`,
+`.flow-grid`, `.code-block`, scrollbar, and `.logs-scrollbar` utilities are copied verbatim from the
+shell. Icons are **Material Symbols** names (e.g. `phone_iphone`, `terminal`, `bar_chart`) carried in
+the data files, not the theme.

package/skills/yad-docs/templates/app/README.md

@@ -0,0 +1,31 @@
+# yadflow docs site (template)
+
+This is the **vendored shell** that the `yad-docs` / `yad-docs-overview` skills copy to generate an
+interactive documentation site (an animated flow canvas + role-based stakeholder doc pages). It is a
+React 19 + Vite 7 + Tailwind v4 + framer-motion + zustand + react-router app.
+
+**You normally don't edit this template directly.** The skills copy it (to
+`epics/EP-<slug>/docs-site/` for a feature, or `docs/sdlc-site/` for the SDLC overview) and then
+**generate the content** into `src/data/*.ts` + the `DocSections/*` components, theme `src/index.css`
+from the connected design system, and substitute the Vite `base` (the `__BASE_PATH__` token) from
+`.sdlc/docs.json`.
+
+## What is generated vs. fixed
+
+- **Generated per site:** `src/data/{paths,components,roles,docSections,referenceData}.ts`, the
+  `:root` theme block of `src/index.css`, the referenced `DocSections/*` content, and the `base` path.
+- **Fixed shell (copied verbatim):** `src/App.tsx`, `src/main.tsx`, the `components/` /
+  `hooks/` / `store/` infrastructure, and `src/data/types.ts` (the contracts the generated data
+  satisfies).
+
+## Local commands
+
+```bash
+npm ci          # or: npm install
+npm run dev     # local preview
+npm run build   # tsc -b && vite build  → dist/
+```
+
+Build + deploy are normally driven by the CLI: `yad docs build|deploy|sync`. The login gate
+(`DOCS_REQUIRE_LOGIN` in `src/store/useAuthStore.ts`) is **off by default** — it is presentational
+only, never a security control; private docs rely on the repo / Pages access control.

package/skills/yad-docs/templates/app/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/skills/yad-docs/templates/app/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Booking Flow Visualizer</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=Noto+Sans:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
+    <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>