yadflow 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,18 +1,9 @@
-# [2.6.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.5.0...v2.6.0) (2026-06-14)
-
-
-### Bug Fixes
-
-* allow scoped/breaking commit subjects + titles; parse only the trailer block ([63444c0](https://github.com/abdelrahmannasr/yadflow/commit/63444c08c1e33b4151c7389eb5e87f6ae682aee6))
-* harden pattern-gate CI — pass PR title via env, write body to mktemp ([2415397](https://github.com/abdelrahmannasr/yadflow/commit/2415397f81280f459785b8fa9ca29007b473561b))
-* let `yad ship` derive the PR title from the committed subject ([a5adba3](https://github.com/abdelrahmannasr/yadflow/commit/a5adba3212b236ffc5a2470b9ea50bf97c6c4138))
+# [2.8.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.7.0...v2.8.0) (2026-06-15)
 
 
 ### Features
 
-* add `yad ship` CLI to commit and open a PR/MR in one step ([c493e93](https://github.com/abdelrahmannasr/yadflow/commit/c493e93e5626eee590cd061c9e7dbc8047e78718))
-* add commit-message/pr-title/pr-template pattern gates (code + hub) ([6658837](https://github.com/abdelrahmannasr/yadflow/commit/6658837d7685b826884b665a5e7661fd6ae99828))
-* add yad-commit/yad-open-pr/yad-ship skills; rename Step E to yad-engineer-review ([c566567](https://github.com/abdelrahmannasr/yadflow/commit/c5665679e45f24ea53c682aca3a78eb52c9f984f))
+* add `yad roster` command to manage the reviewer roster any time ([#64](https://github.com/abdelrahmannasr/yadflow/issues/64)) ([4d78225](https://github.com/abdelrahmannasr/yadflow/commit/4d78225ec25579b50d24d917f217212f4820728f))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -90,6 +90,7 @@ with `npx` from your **product hub** repo — no clone needed.
 | `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
 | `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
 | `npx yadflow doctor [--json]` | Environment + state health: tools on PATH and platform auth, config files parse and point at real repos, every epic ledger loads. Exit 1 on any failure; `--json` for CI and bug reports. |
+| `yad roster list` / `yad roster add <login>` | Manage the reviewer roster + per-repo roles **any time** (not just at setup). `add` upserts a member then walks each connected repo asking for their role; `grant`/`revoke <name> <repo> <role>` and `remove <login>` round it out. A `domain-owner` grant keeps `repos.json` `domain_owners` in sync. |
 | `yad gate open <epic> <artifact>` | Open the front-half **review PR/MR** for an artifact and mark the step `in_review`. |
 | `yad gate sync <epic> [artifact]` | Pull the PR/MR's reviews + comment threads into the file ledger; **auto-advance** the step when approvals are satisfied, all threads are resolved, and the PR is merged. |
 | `yad gate comments <epic> [artifact]` | Fetch the unresolved review comments to address (then reply on the PR; reviewers resolve their threads). |
@@ -133,9 +134,10 @@ simultaneous advancements can be lost; the next event or scheduled sweep re-sync
 ### What `setup` walks you through (10 steps)
 
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 25 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 29 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
+   Edit the roster any time afterwards with `yad roster` (no need to re-run the whole wizard).
 4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
    the UI step can materialize the design; the MCP itself is confirmed later by `yad-connect-design`.
 5. **Connect a testing tool** — record the testing tool (Playwright / cypress / pytest / none) →
@@ -189,7 +191,7 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 25)
+## Agent skills (all 29)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -218,6 +220,28 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   tokens), detecting the **DeepTutor CLI on PATH** (a subprocess like Repomix — DeepTutor ships no MCP)
   and degrading to **harness-native** tutoring when absent. Idempotent and refreshable; one connection
   per project.
+- **`yad-connect-docs`** — Connects a docs/Pages target (GitHub Pages / GitLab Pages, auto-detected from
+  `hub.json`) so the generated documentation sites can deploy. Records the target + scope + base path in
+  `.sdlc/docs.json` (local-user auth, no stored tokens), degrading to **build-only** when no Pages host /
+  CLI is present. Idempotent and refreshable; one connection per project.
+
+### Living documentation (generated, themed, auto-kept-fresh)
+
+- **`yad-docs`** — Generates an **interactive documentation site** for an epic (a React + Vite + Tailwind
+  SPA: an animated front-stage flow canvas + role-based stakeholder doc pages) from the authored
+  artifacts — `epic.md`, `architecture.md`, the locked `contract.md`, `ui-design.md`, the stories — into
+  `epics/EP-<slug>/docs-site/`, themed by the **connected design system** (`DESIGN.md` / `design.json`
+  tokens → the site's CSS). The content lives in generated `src/data/*.ts`; the shell is a vendored
+  template. An **output enrichment, never a gate** — it never touches epic state, approvals, or the
+  contract lock. `generate` / `refresh` / `deploy`.
+- **`yad-docs-overview`** — Generates the project **SDLC-overview site** (`docs/sdlc-site/`) — every
+  stage from setup → ship as flow paths / system components / stakeholder roles, reusing the same shell —
+  superseding the hand-maintained `docs/index.html` (folded into the site as `public/report.html`, linked
+  from the nav).
+- **`yad-docs-sync`** — Keeps the sites fresh: detects staleness (a content hash of the authored
+  artifacts + the connected repos' HEAD shas vs each site's build manifest), regenerates + redeploys, and
+  can wire a CI job that rebuilds on push. Generalizes the rule that feature work must hand-update the
+  docs — the overview now regenerates whenever the skill set / pipeline changes.
 
 ### The learning layer (cross-cutting — any member, any stage)
 
@@ -366,9 +390,10 @@ detailed sections below expand every phase. Invoke a skill by name in your agent
    `testing.json`, lets `yad-test-cases` implement automation), `yad-connect-learning action: connect`
    (DeepTutor-first → `learning.json`, powers the cross-cutting learning layer).
 7. **(Optional) Put the hub on a platform** so the front-half review runs through real PRs:
-   `yad-connect-repos action: detect-hub`, then `action: roster` once per reviewer (login → SDLC
-   name + role), and `yad-pr-template repo:hub action: wire` / `yad-review-comments repo:hub action:
-   wire` / `yad-checks repo:hub action: wire`. With no hub platform the front gate just runs file-only.
+   `yad-connect-repos action: detect-hub`, then `yad roster add <login>` once per reviewer (login →
+   SDLC name + per-repo roles — the `add` walk asks for each connected repo's role; `yad roster grant`
+   sets one directly), and `yad-pr-template repo:hub action: wire` / `yad-review-comments repo:hub
+   action: wire` / `yad-checks repo:hub action: wire`. With no hub platform the front gate runs file-only.
 8. **Conventions:** commits and PR/MR titles follow Conventional Commits (lowercase after the type), the
    human author owns each commit with an optional per-commit `Co-Authored-By` AI trailer — see
    [`CONTRIBUTING.md`](CONTRIBUTING.md).

package/bin/yad.mjs

@@ -10,6 +10,8 @@ import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
 import { runShip } from '../cli/ship.mjs';
 import { runRepo } from '../cli/repo.mjs';
+import { runRoster } from '../cli/roster.mjs';
+import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
@@ -23,6 +25,14 @@ ${c.bold('Setup & maintenance')}
   yad doctor [--json]  Environment + state health: tools/auth, config files,
                        repo paths, epic ledgers (exit 1 on any failure)
 
+${c.bold('Reviewer roster')}
+  yad roster list                      Show every member + their roles per scope (hub + each repo)
+  yad roster add <login>               Add/edit a member, then walk the connected repos for their roles
+                                       (--name, --email, --roles "hub=owner,reviewer backend=domain-owner")
+  yad roster grant <name> <repo> <role...>   Grant role(s) for a connected repo (domain-owner|reviewer|owner)
+  yad roster revoke <name> <repo> <role...>  Remove role(s) for a repo
+  yad roster remove <login>            Delete a member from the roster
+
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
@@ -39,6 +49,12 @@ ${c.bold('Build helpers')}
   yad repo list                        Show connected repos (fresh / stale)
   yad repo refresh [name]              Re-pack a stale repo (a human decision)
 
+${c.bold('Interactive docs (generated sites)')}
+  yad docs list                        Show the docs target + per-site freshness
+  yad docs build [--epic <id>|--overview]    npm-build a generated doc site
+  yad docs deploy [--epic <id>|--overview]   Build + report the Pages deploy
+  yad docs sync [--check|--refresh|--wire]   Staleness sweep; --wire installs the Pages CI
+
 ${c.bold('Options')}
   --dir <path>          Target project root (default: cwd)
   --type <t>            commit: feat|fix|docs|refactor|test|perf|build|ci|chore|revert
@@ -48,6 +64,9 @@ ${c.bold('Options')}
   --contract-change     commit/open-pr: mark the contract surface touched
   --risk <level>        open-pr: low|medium|high (default low)
   --repo <name>         open-pr: target a registered repo by name
+  --epic <id>           docs: target one epic's site (EP-<slug>)
+  --overview            docs: target the project SDLC-overview site
+  --check/--refresh/--wire   docs sync: report stale / rebuild / install Pages CI
   --dry-run             commit: print the message, do not commit
   --force               commit: bypass the atomic-file guard / re-copy unchanged files
   --branch <head>       gate ci: the review PR/MR head branch (review/EP-<slug>/<artifact>)
@@ -56,7 +75,7 @@ ${c.bold('Options')}
   -h, --help            Show this help
   -v, --version         Print version`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -66,6 +85,10 @@ function parseArgs(argv) {
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--overview') o.overview = true;
+    else if (a === '--check') o.check = true;
+    else if (a === '--refresh') o.refresh = true;
+    else if (a === '--wire') o.wire = true;
     else if (a === '--dry-run') o.dryRun = true;
     else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
@@ -133,6 +156,18 @@ async function main() {
       await runRepo(o.dir, { action: action || 'list', name, today });
       break;
     }
+    case 'roster': {
+      const [, action, ...rest] = o._;
+      await runRoster(o.dir, { action: action || 'list', args: rest, name: o.name, email: o.email, roles: o.roles, today });
+      break;
+    }
+    case 'docs': {
+      const [, action] = o._;
+      if (o.epic && !isValidEpicId(o.epic)) { log(c.red(`invalid epic id: ${o.epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      const sync = o.wire ? 'wire' : o.refresh ? 'refresh' : 'check';
+      await runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
+      break;
+    }
     default:
       log(c.red(`unknown command: ${cmd}`));
       log(HELP);

package/cli/docs.mjs

@@ -0,0 +1,298 @@
+// `yad docs list|build|deploy|sync` — the build/deploy/staleness mechanics for the interactive
+// documentation sites generated by the yad-docs / yad-docs-overview skills. The CONTENT generation
+// (reading epic/architecture/contract/ui/stories → writing src/data/*.ts and theming index.css) is
+// the AI step inside those skills; this module only does the mechanical parts: npm build (a
+// subprocess, like yad-spec shelling npx repomix), the platform Pages wiring (reusing platform.mjs),
+// and the manifest-hash staleness check (reusing the head-sha idea from repo.mjs). It NEVER touches
+// epic state, approvals, or the contract lock — docs are an output enrichment, not a gate.
+//
+// Pure mapping fns (deployTargetFromHub / siteBasePath / docsArtifactHash / docsStale / pagesWorkflow)
+// are exported for unit tests; the side-effecting runDocs orchestrates them.
+import path from 'node:path';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { c, log, ok, info, warn, hand, fail, readJSON, run, has, exists } from './lib.mjs';
+import { PROJECT_FILES, VERSION } from './manifest.mjs';
+import { detectPlatform, platformReady } from './platform.mjs';
+import { gitHead } from './setup.mjs';
+import { contractSurfaceHash } from './epic-state.mjs';
+
+// ---- registry + site locations ------------------------------------------------------------------
+function loadDocs(root) {
+  const regPath = path.join(root, PROJECT_FILES.docsConfig);
+  return { regPath, docs: readJSON(regPath, null) };
+}
+
+// Per-epic site lives beside the epic artifacts; the overview is project-level under docs/.
+export function siteDir(root, { epic, overview } = {}) {
+  if (overview) return path.join(root, 'docs/sdlc-site');
+  return path.join(root, 'epics', epic, 'docs-site');
+}
+export function manifestPath(root, { epic, overview } = {}) {
+  if (overview) return path.join(siteDir(root, { overview }), '.docs-build.json');
+  return path.join(root, 'epics', epic, '.sdlc/docs-build.json');
+}
+
+// ---- pure: platform/target + base path ----------------------------------------------------------
+// hub.json platform -> the default Pages target (github-pages | gitlab-pages | none/build-only).
+export function deployTargetFromHub(hub = {}) {
+  const platform = hub?.platform || detectPlatform(hub?.git_url || '');
+  if (platform === 'github') return 'github-pages';
+  if (platform === 'gitlab') return 'gitlab-pages';
+  return 'none';
+}
+
+// The Vite `base` for one site: join the project base path (from docs.json) with the per-site
+// subpath. Per-epic sites nest under epics/<id>/; the overview is the Pages root. Always a
+// leading+trailing slash so it works as a Vite base and a router basename.
+export function siteBasePath(docs = {}, { epic, overview } = {}) {
+  const root = (docs.basePath || '/').replace(/\/+$/, '') || '';
+  const sub = overview ? '' : epic ? `/epics/${epic}` : '';
+  const joined = `${root}${sub}`.replace(/\/+/g, '/');
+  return joined ? `${joined.replace(/\/$/, '')}/` : '/';
+}
+
+// ---- pure: staleness ----------------------------------------------------------------------------
+// The artifacts whose content a per-epic site is generated from (any that exist contribute).
+// contract.md is deliberately EXCLUDED here: it is folded in via its CONTRACT-SURFACE block hash
+// (docsArtifactHash's `extra`), so docs-staleness tracks the same locked surface as the contract
+// lock — non-surface prose edits to contract.md don't needlessly mark the docs stale.
+export function docsArtifactFiles(root, epic) {
+  const epicRoot = path.join(root, 'epics', epic);
+  const flat = ['epic.md', 'architecture.md', 'ui-design.md', 'DESIGN.md', 'test-cases.md']
+    .map((f) => path.join(epicRoot, f));
+  const storiesDir = path.join(epicRoot, 'stories');
+  const stories = exists(storiesDir)
+    ? fs.readdirSync(storiesDir).filter((f) => f.endsWith('.md')).sort().map((f) => path.join(storiesDir, f))
+    : [];
+  return [...flat, ...stories].filter(exists).sort();
+}
+
+// sha256 over the (sorted) artifact files' bytes plus an optional `extra` string (the contract
+// surface hash) — the content baseline a site was built from. Deterministic: the file list is
+// sorted and each file is length-prefixed so concatenation is unambiguous (a + bc never collides
+// with ab + c).
+export function docsArtifactHash(files = [], extra = '') {
+  const h = createHash('sha256');
+  for (const f of [...files].sort()) {
+    const buf = fs.readFileSync(f);
+    h.update(`${path.basename(f)}:${buf.length}\n`);
+    h.update(buf);
+  }
+  if (extra) h.update(`\ncontract-surface:${extra}`);
+  return 'sha256:' + h.digest('hex');
+}
+
+// Current HEAD sha per repo the epic touches (mirrors repo.mjs head-sha staleness).
+export function repoHeadsFor(root, repos = [], registry = { repos: [] }) {
+  const out = {};
+  for (const name of repos) {
+    const entry = (registry.repos || []).find((r) => r.name === name);
+    if (!entry) continue;
+    out[name] = gitHead(path.resolve(root, entry.path)) || null;
+  }
+  return out;
+}
+
+// Compare a build manifest to the current world; list the concrete reasons it is stale.
+export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVersion } = {}) {
+  const reasons = [];
+  if (!manifest) return { stale: true, reasons: ['never built'] };
+  if (artifactHash && manifest.artifactHash && artifactHash !== manifest.artifactHash) {
+    reasons.push('authored artifacts changed');
+  }
+  for (const [repo, head] of Object.entries(repoHeads)) {
+    const was = (manifest.repoHeads || {})[repo];
+    if (head && was && head !== was) reasons.push(`repo ${repo} HEAD advanced`);
+  }
+  if (templateVersion && manifest.templateVersion && templateVersion !== manifest.templateVersion) {
+    reasons.push(`doc shell upgraded (${manifest.templateVersion} → ${templateVersion})`);
+  }
+  return { stale: reasons.length > 0, reasons };
+}
+
+// ---- pure: the Pages CI workflow (committed by `yad docs sync --wire`) ---------------------------
+// GitHub Actions deploy-pages, or a GitLab `pages` job. Both assemble a single `public/` tree: the
+// overview at the root and every per-epic site under `epics/<id>/` — matching siteBasePath's nesting
+// (overview at `<base>/`, epics at `<base>/epics/EP-<slug>/`). A concurrency group prevents the
+// deploy from retriggering. The shared shell script keeps the two platforms byte-for-byte aligned.
+const BUILD_PUBLIC = [
+  'mkdir -p public',
+  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && cp -r docs/sdlc-site/dist/. public/; fi',
+  'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/"; done',
+];
+export function pagesWorkflow(platform) {
+  if (platform === 'gitlab') {
+    return `# yad-managed — built by \`yad docs sync --wire\`. include it from .gitlab-ci.yml:
+#   include: { local: .gitlab/ci/yad-docs.yml }
+# Edit the skill, not this file.
+pages:
+  stage: deploy
+  image: node:20
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  script:
+${BUILD_PUBLIC.map((l) => `    - '${l.replace(/'/g, "'\\''")}'`).join('\n')}
+  artifacts:
+    paths: [public]
+  resource_group: pages
+`;
+  }
+  return `# yad-managed — built by \`yad docs sync --wire\`. Edit the skill, not this file.
+name: yad-docs
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: yad-docs-pages
+  cancel-in-progress: true
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Build the overview + per-epic sites into ./public
+        run: |
+${BUILD_PUBLIC.map((l) => `          ${l}`).join('\n')}
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+      - id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}
+export function pagesWorkflowPath(platform) {
+  return platform === 'gitlab' ? '.gitlab/ci/yad-docs.yml' : '.github/workflows/yad-docs.yml';
+}
+
+// ---- build (subprocess) -------------------------------------------------------------------------
+function buildSite(dir) {
+  if (!exists(dir)) { warn(`no generated site at ${path.relative(process.cwd(), dir)} — run the yad-docs skill first`); return { ok: false, missing: true }; }
+  if (!has('npm')) { warn('npm not on PATH — cannot build; the CI workflow will build on push'); return { ok: false, noNpm: true }; }
+  const install = exists(path.join(dir, 'package-lock.json')) ? ['ci'] : ['install'];
+  log(`  ${c.dim('$')} npm ${install[0]} ${c.dim(`(${path.relative(process.cwd(), dir)})`)}`);
+  const i = run('npm', install, { cwd: dir, stdio: 'inherit' });
+  if (!i.ok) { fail('npm install failed'); return { ok: false }; }
+  const b = run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
+  if (!b.ok) { fail('npm run build failed'); return { ok: false }; }
+  return { ok: true, dist: path.join(dir, 'dist') };
+}
+
+// ---- orchestration ------------------------------------------------------------------------------
+export async function runDocs(root, { action = 'list', epic, overview, sync } = {}) {
+  const { docs } = loadDocs(root);
+  const targets = overview ? [{ overview: true }] : epic ? [{ epic }] : enumerateSites(root);
+
+  if (action === 'list') {
+    if (!docs) { warn('no docs target connected (.sdlc/docs.json) — run yad-connect-docs'); }
+    else {
+      log(c.bold('\ndocs target'));
+      info(`target ${c.cyan(docs.target)}  scope ${docs.scope}  base ${docs.basePath}  ${docs.source === 'unavailable' ? c.yellow('(build-only)') : ''}`);
+    }
+    log(c.bold('\ngenerated sites'));
+    if (!targets.length) { info('none generated yet'); return { sites: 0 }; }
+    for (const t of targets) reportFreshness(root, t);
+    return { sites: targets.length };
+  }
+
+  if (action === 'build' || action === 'deploy') {
+    let built = 0;
+    for (const t of targets) {
+      const r = buildSite(siteDir(root, t));
+      if (r.ok) { built++; ok(`built ${label(t)} ${c.dim('→ ' + path.relative(root, r.dist))}`); }
+    }
+    if (action === 'deploy') {
+      const platform = docs ? (docs.target === 'gitlab-pages' ? 'gitlab' : docs.target === 'github-pages' ? 'github' : null) : null;
+      if (!platform || !platformReady(platform)) {
+        hand('no Pages platform/CLI — built locally only; commit + push so the CI workflow can publish (yad docs sync --wire)');
+      } else {
+        ok(`deploy via the ${platform} Pages workflow on push (yad docs sync --wire installs it)`);
+        if (docs?.basePath) info(`will publish under ${docs.basePath}`);
+      }
+    }
+    return { built };
+  }
+
+  if (action === 'sync') {
+    if (sync === 'wire') return wirePages(root, docs);
+    // check (default) + refresh both compute staleness; refresh additionally rebuilds.
+    const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+    let stale = 0;
+    for (const t of targets) {
+      const s = freshness(root, t, registry);
+      if (s.stale) {
+        stale++;
+        warn(`${label(t)} — ${c.yellow('stale')}: ${s.reasons.join('; ')}`);
+        if (sync === 'refresh') buildSite(siteDir(root, t));
+      } else ok(`${label(t)} ${c.dim('— fresh')}`);
+    }
+    if (stale && sync !== 'refresh') hand('regenerate content with the yad-docs / yad-docs-overview skill (the AI step), then `yad docs deploy`');
+    return { stale };
+  }
+
+  fail(`unknown docs action: ${action} (list | build | deploy | sync)`);
+  process.exitCode = 1;
+  return {};
+}
+
+// ---- helpers ------------------------------------------------------------------------------------
+function enumerateSites(root) {
+  const out = [];
+  if (exists(siteDir(root, { overview: true }))) out.push({ overview: true });
+  const epicsDir = path.join(root, 'epics');
+  if (exists(epicsDir)) {
+    for (const e of fs.readdirSync(epicsDir).sort()) {
+      if (exists(path.join(epicsDir, e, 'docs-site'))) out.push({ epic: e });
+    }
+  }
+  return out;
+}
+function label(t) { return t.overview ? 'overview (docs/sdlc-site)' : `epic ${t.epic}`; }
+
+function freshness(root, t, registry) {
+  const manifest = readJSON(manifestPath(root, t), null);
+  if (t.overview) {
+    // The overview is generated from the project pipeline definition, not an epic's artifacts.
+    const files = ['skills/sdlc/config.yaml', 'skills/sdlc/module-help.csv', 'docs/diagrams/sdlc-overview.mmd']
+      .map((f) => path.join(root, f)).filter(exists);
+    return docsStale(manifest, { artifactHash: docsArtifactHash(files), templateVersion: VERSION });
+  }
+  const epicMeta = readJSON(path.join(root, 'epics', t.epic, '.sdlc/state.json'), {});
+  const repos = epicMeta.repos || [];
+  const surface = contractSurfaceHash(path.join(root, 'epics', t.epic)); // null when no locked surface
+  return docsStale(manifest, {
+    artifactHash: docsArtifactHash(docsArtifactFiles(root, t.epic), surface || ''),
+    repoHeads: repoHeadsFor(root, repos, registry),
+    templateVersion: VERSION,
+  });
+}
+function reportFreshness(root, t) {
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const s = freshness(root, t, registry);
+  if (s.stale) warn(`${label(t)} — ${c.yellow('stale')}: ${s.reasons.join('; ')}`);
+  else ok(`${label(t)} ${c.dim('— fresh')}`);
+}
+
+function wirePages(root, docs) {
+  const platform = docs?.target === 'gitlab-pages' ? 'gitlab' : 'github';
+  const rel = pagesWorkflowPath(platform);
+  const dest = path.join(root, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, pagesWorkflow(platform));
+  ok(`wired ${rel} ${c.dim(`(${platform} Pages)`)}`);
+  if (platform === 'gitlab') hand(`include it from .gitlab-ci.yml:  include: { local: ${rel} }`);
+  else hand('commit it; set the repo Pages source to "GitHub Actions" so it publishes on push');
+  return { wired: rel };
+}

package/cli/manifest.mjs

@@ -10,7 +10,7 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 25 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
+// The 29 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
   'yad-analysis',
   'yad-epic',
@@ -22,6 +22,10 @@ export const SKILLS = [
   'yad-connect-design',
   'yad-connect-testing',
   'yad-connect-learning',
+  'yad-connect-docs',
+  'yad-docs',
+  'yad-docs-overview',
+  'yad-docs-sync',
   'yad-learn',
   'yad-spec',
   'yad-implement',
@@ -121,6 +125,7 @@ export const PROJECT_FILES = {
   designConfig: '.sdlc/design.json',
   testingConfig: '.sdlc/testing.json',
   learningConfig: '.sdlc/learning.json',
+  docsConfig: '.sdlc/docs.json',
   version: '.sdlc/cli-version.json',
 };