---
name: yad-docs-overview
description: 'Generates the project-level SDLC-overview interactive site — the same React/Vite/Tailwind shell as the per-epic docs — showing every yadflow stage from setup → ship: the pipeline as a flow canvas, each skill/gate as a flow step, the durable .sdlc state objects as system components, and the lenses as stakeholder roles. Themed with yadflow''s own brand palette for continuity, built from config.yaml + module-help.csv + the overview diagram. The hand-maintained report is the MAIN documentation at the Pages root (report.html, also served as index.html); the interactive SPA mounts under `app/` and is reached from it (and links back). Deploys via `yad docs deploy --overview`. This is project documentation, not a gated state — it never touches any epic''s state or approvals. Use when the user says "generate the overview site", "build the SDLC overview docs", or after the pipeline (module-help.csv / config.yaml / skill count) changes.'
---

# SDLC — Author the Overview Site (project-level, the pipeline as a living map)

**Goal:** Render the **whole yadflow pipeline** — every stage from setup → ship — as an interactive site,
reusing the same shell as the per-epic docs (`skills/yad-docs/templates/app/`). Where `yad-docs`
animates one epic's flows, this animates the **workflow itself**: the Shape gates, Build, the
automation dial, the setup connectors. The hand-maintained overview report stays the **main
documentation at the Pages root** (`<base>/`, served from `public/report.html` and `public/index.html`);
this interactive SPA mounts under `<base>/app/` and is reached from the report — the report links
forward to `app/`, the app links back to the report root.

This is **project documentation, not a gated state** — there is no epic, no `state.json`, no approvals.
It only reads the pipeline definition and writes a project-level site. When a docs target is connected
(`.sdlc/docs.json`) it builds + deploys; otherwise it build-only.

## Conventions

- `{project-root}` resolves from the project working directory (the **Product**).
- The overview site lives at `{project-root}/docs/sdlc-site/`; its `dist/`/`node_modules/` are gitignored,
  the generated **source is committed**. The overview build manifest is `docs/sdlc-site/.docs-build.json`.
- The shell template is `skills/yad-docs/templates/app/`. It is copied **only when `docs/sdlc-site/`
  does not exist yet** — see Step 3. The overview site in this repo has since grown sections of its own
  (for example CheckGates, CliReference, TwoDials, Glossary, ContractLock, ReviewGate, Connectors and the
  Reference tables) and dropped the template's per-epic ones, so it is **updated in place, never
  re-copied**. Generated data satisfies `src/data/types.ts`.
- Theme: **yadflow's own brand palette** (the `:root` of the legacy report, now `docs/sdlc-site/public/report.html`) — for visual continuity with
  the existing overview, not an epic's design tokens.
- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.

## Inputs

- `action` — `generate` (default) | `refresh` | `deploy`.
- `login_gate` — `true` | `false` (default `false`).

## On Activation

### Step 1 — Read the pipeline definition (the data sources)
There is no epic; the inputs are the workflow's own config + manifest (full mapping in
`references/pipeline-model.md`):

- `skills/sdlc/config.yaml` — the Shape/Build steps, the **two dials** (`driver`/`assistance`, `advance`/`automation`),
  defaults, the review-gate rule, the build conventions, the automation defaults.
- `skills/sdlc/module-help.csv` — the **canonical skill manifest**: each skill's `phase`,
  `preceded-by` / `followed-by`, and `outputs`. This is the ordering source of truth.
- `docs/diagrams/sdlc-overview.mmd` — the overview diagram (the node/edge shape + the node classes:
  artifact / gate / earns / locked / sentinel).
- the build-plan docs under `docs/` — phase narratives for the section copy.

### Step 1b — Open the authoring branch
Open the `docs/overview` authoring branch per the shared procedure
(`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if not a
git work tree). Generate and commit on it.

### Step 2 — Model the pipeline with the shell primitives
Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping in
`references/pipeline-model.md`):

- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Shape`, `Build`, `Automation`, `Change management` (feature threads).
- **Flow steps** = the **skills/gates in order** (from `module-help.csv` `preceded-by`/`followed-by`),
  each step's `messages` = the skill's `outputs`, and `sideEffects` = the `.sdlc/` files it writes.
- **System components** = the **durable state objects** — the Product, each `.sdlc/*.json`
  (`state.json`, `approvals.json`, `repos.json`, `design.json`, `testing.json`, `learning.json`,
  `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`), the connected code repos, the
  design/testing/learning tools, and the platform.
- **Roles** = the **lenses** (analyst / pm / architect / ux / dev / tester / reviewer / engineer) → each
  to its relevant sections + paths.

### Step 3 — Generate the site into `docs/sdlc-site/`
**First check whether `docs/sdlc-site/` already exists.**

- **It does not exist** (a first build): copy the shell from `templates/app/` verbatim, then do the rest
  of this step.
- **It exists** (every build after the first): **do not copy the shell.** Copying it would overwrite the
  site's own components and delete the sections the template does not have. Instead, update the site in
  place: regenerate the data in `src/data/*.ts`, and edit a component only where the pipeline change
  needs it. Before you finish, run `git status docs/sdlc-site/` and check that nothing was deleted.

Then generate `src/data/*.ts` deterministically (same
determinism rules as `yad-docs`: stable-ID sort by skill pipeline order / phase, fixed key order, no
timestamps in the data files), theme the `:root` of `index.css` from **yadflow's brand palette** — the
the legacy report's `:root`: `--accent: #2471a3` and the node colors (`--artifact-*`, `--gate-*`,
`--earns-*`, `--locked-*`, `--sentinel-*`) — and substitute the Vite base from `.sdlc/docs.json`
`basePath` **with `app/` appended** (the SPA mounts under `<base>/app/`, e.g. `/<repo>/app/`, so the
report can own the root). `siteBasePath(docs, { overview: true })` in `cli/docs.mjs` computes this.

### Step 4 — Write the overview build manifest (the staleness baseline)
Write `docs/sdlc-site/.docs-build.json` — `yad-docs-sync` compares against it:

```json
{
  "builtAt": "<YYYY-MM-DD>",
  "theme": "yadflow-brand",
  "artifactHash": "<sha256 of config.yaml + module-help.csv + docs/diagrams/sdlc-overview.mmd>",
  "skillCount": <number of yad-* skills>,
  "deployUrl": "<url or null>"
}
```

The overview's freshness inputs are the **config + manifest + diagram**. There is **no shell version**:
the overview is not re-copied from the shell (Step 3), so a shell upgrade is not a reason to rebuild it.
An older manifest may still carry a `templateVersion` (the yad CLI version); it is ignored, because it
made the overview read stale after every release. `skillCount` rides along in the manifest as an informational field
— it is **not** a separate hash input, since `module-help.csv` already moves whenever the skill set does.
Not per-epic artifacts/repo heads.

### Step 5 — The report is the main documentation; the SPA is reached from it
The hand-maintained static report lives at `docs/sdlc-site/public/report.html` and is the **primary
documentation at the Pages root**. The deploy (`BUILD_PUBLIC` in `cli/docs.mjs`, mirrored by the Pages CI
workflow) copies it to **both** `public/index.html` (the landing `<base>/`) and `public/report.html`
(so the `<base>/report.html` URL keeps working), and copies the built SPA into `public/app/`. Wire the
two cross-links: the report links **forward** to the interactive map with a relative `app/` href (its
hero CTA); the app's `TopNavBar` "Full report" link points **back** to the report root
(`import.meta.env.BASE_URL` with the trailing `app/` stripped). No orphaned `docs/index.html` at the repo
root. This generalizes the standing rule that feature work hand-updates the report: the overview SPA now
**regenerates** instead, while the report stays the front door.

### Step 6 — Build / deploy (`action`)
- `action: generate` (default) — generate source + manifest; stop.
- `action: deploy` — drive **`yad docs deploy --overview`**: npm-build, ensure the Pages CI workflow,
  report the deploy URL. Degrades to local `dist/` when no platform CLI / `target: "none"`. A failed
  npm install or build exits 1 and names the site — report the failure, not a deploy URL.

### Step 7 — Stop. Report (no gate, no epic)
Report: the site path (`docs/sdlc-site/`), the data files produced, that the theme is the yadflow brand
palette, the deploy URL or "build-only", the staleness baseline, and that the report is the main
documentation at `<base>/` (`public/index.html` + `public/report.html`) with the interactive SPA mounted
under `<base>/app/` and cross-linked. Never touches any epic state.

## Hard rules

- **Project documentation, not a gate.** No epic, no `state.json`, no approvals — this skill never reads
  or writes any epic's gated state.
- **The overview regenerates on pipeline change.** This **generalizes** the standing rule that feature
  work hand-updates `docs/index.html` + the overview diagram + skill counts: the overview site now
  regenerates whenever `module-help.csv` / `config.yaml` / the skill count changes — and `yad-docs-sync`
  **enforces** that (it flags the overview stale when those inputs move).
- **Copy the shell once, then update in place.** The template is copied only into a missing
  `docs/sdlc-site/`. An existing site is never re-copied over, because that deletes its own sections.
  Theme only the `:root`. Never hand-edit `templates/app/` for the overview's sake.
- **Deterministic generation.** Same stable-sort / fixed-key / no-timestamp discipline as `yad-docs`.
- **Degrade gracefully.** No docs target → build-only; no `.mmd` / no build-plan docs → omit those
  sections with a note, never invent.

## Reference
- The concrete mapping of every setup→ship stage to flow paths / steps / components / roles, with each
  `yad-*` skill in pipeline order + its phase + outputs: `references/pipeline-model.md`.
- The per-epic counterpart (shell, determinism, theming): `../yad-docs/SKILL.md`.
- The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
- The staleness reconciler (reports stale sites, refreshes on request, wires the Pages build): `../yad-docs-sync/SKILL.md`.