yadflow 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,18 +1,15 @@
-# [2.6.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.5.0...v2.6.0) (2026-06-14)
+# [2.7.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.6.0...v2.7.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))
+* drop unused today param from runDocs (lint) ([1c255f1](https://github.com/abdelrahmannasr/yadflow/commit/1c255f1c848b9571502e29b142a07366612d638c))
+* publish per-epic docs sites in CI + check shell-version staleness ([9862646](https://github.com/abdelrahmannasr/yadflow/commit/9862646fbe910de8ad8248a5f1bb586a5604b18f))
 
 
 ### 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 interactive documentation skills + yad docs CLI ([4bf7a25](https://github.com/abdelrahmannasr/yadflow/commit/4bf7a25c38e28ef47704a8e2f5acec2f724e4e29))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -133,7 +133,7 @@ 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`.
 4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
@@ -189,7 +189,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 +218,27 @@ 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`.
+- **`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)
 

package/bin/yad.mjs

@@ -10,6 +10,7 @@ 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 { 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)}
@@ -39,6 +40,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 +55,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 +66,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']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -66,6 +76,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 +147,13 @@ async function main() {
       await runRepo(o.dir, { action: action || 'list', name, 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',
 };
 

package/docs/index.html

@@ -284,7 +284,7 @@
     <div class="lane">
       <div class="lane-title">0 · One-time setup (team lead, per project)</div>
       <div class="flow-v">
-        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 25 skills into your IDE dirs</small></div>
+        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 29 skills into your IDE dirs</small></div>
         <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Wire each repo</strong><small><code>yad-checks</code> · <code>yad-pr-template</code> · <code>yad-review-comments</code> (CI gates, PR template, comment scaffold)</small></div>
         <div class="arrow-v">▼</div>
@@ -447,7 +447,7 @@ each code repo/
   <div class="term"><strong>State machine</strong><span class="badge b-core">core</span><br>The core design: the workflow is a fixed set of <em>states</em> (steps). Each state does its work and waits at a gate. The states never change — only the <em>trigger</em> (who moves work forward) changes. That is what lets the team start fully manual and automate gradually without rebuilding anything.</div>
   <div class="term"><strong>Product hub (product repo)</strong><span class="badge b-core">core</span><br>The git repo that holds the shared “thinking”: epics, architecture, the contract, UI design, stories, reviews and all state. The brain of the project. Code never lives here.</div>
   <div class="term"><strong>Code repo</strong><span class="badge b-core">core</span><br>A separate git repo holding real application code (e.g. backend, mobile, dashboard). Each story’s spec lives inside the code repo it belongs to, with a link back to the story in the hub.</div>
-  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 25 skills live and where you pull updates from. No real product work happens inside it.</div>
+  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 29 skills live and where you pull updates from. No real product work happens inside it.</div>
   <div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate, ending at <code>ready-for-build</code>. <strong>Test cases</strong> is a parallel, non-blocking track that opens at the stories gate and runs alongside the build half. Permanently human-approved.</div>
   <div class="term"><strong>Back half / build half (“build”)</strong><span class="badge b-core">core</span><br>The second half, run once per story per code repo, inside that repo: spec → implement → checks → PR → ship. These mechanical steps may earn automation over time.</div>
   <div class="term"><strong>Gate</strong><span class="badge b-core">core</span><br>A stopping point after a step. The step writes its output and <em>waits</em>; a human must approve before the workflow moves on. “Every step stops at a gate” is the heart of the whole system.</div>
@@ -684,7 +684,7 @@ each code repo/
 
 <!-- ======================================================= -->
 <section id="skills">
-  <h2>6. The 25 skills — what each does, how to use it, and when</h2>
+  <h2>6. The 29 skills — what each does, how to use it, and when</h2>
   <p>A <strong>skill</strong> is an agent you invoke <em>by name</em> in your AI IDE — you just ask in
   plain words, e.g. <em>“run <code>yad-epic</code>”</em>, adding any inputs the skill needs
   (<code>repo: backend</code>, <code>story: EP-…-S01</code>, <code>action: wire</code>, …).
@@ -979,7 +979,7 @@ yad-status EP-istifta-inquiries     # one epic in detail</code></pre>
 
   <div class="skillcard">
     <h4><code>npx yadflow setup</code></h4>
-    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Ten steps: preflight (git/node check), install all 25 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect a testing tool (Playwright-first; optional), connect a learning tool (DeepTutor-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
+    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Ten steps: preflight (git/node check), install all 29 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect a testing tool (Playwright-first; optional), connect a learning tool (DeepTutor-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
     <div class="row"><span class="lbl lbl-how">How</span></div>
 <pre><code>cd &lt;product-hub-repo&gt;
 npx yadflow setup</code></pre>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.6.0",
-  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 25 yad-* skills.",
+  "version": "2.7.0",
+  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 29 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",

package/skills/sdlc/config.yaml

@@ -176,6 +176,25 @@ learning:
   # tokens in the registry (kb name + sources are plain references, never credentials). Opt-in, never a gate.
   auth: user
 
+# Interactive documentation (yad-connect-docs / yad-docs / yad-docs-overview / yad-docs-sync) — the
+# generated React+Vite+Tailwind doc SITES. yad-docs builds a per-epic site (epics/EP-<slug>/docs-site/)
+# from the authored artifacts, themed by the connected design system; yad-docs-overview builds the
+# project SDLC-overview site (docs/sdlc-site/) from the pipeline definition, superseding docs/index.html.
+# The deploy TARGET is a Pages host, auto-detected from hub.platform (github->github-pages,
+# gitlab->gitlab-pages, null->build-only). The yad CLI does the npm build + Pages wiring + staleness;
+# the content generation is the AI step. Docs are an OUTPUT ENRICHMENT — never a gate, never touch state.
+docs:
+  registry: "{project-root}/.sdlc/docs.json"         # project-wide docs/Pages connection (NOT per-epic)
+  targets: [github-pages, gitlab-pages]               # supported Pages hosts; auto-detected from hub.platform
+  scope: hub                                          # publish from: hub (default) | <repo-name> | dedicated
+  degrade: build-only                                 # no Pages host / no gh|glab => build the dist, publish via CI
+  login_gate: false                                   # public docs by default (the client-side gate is presentational only)
+  manifest: "{project-root}/epics/EP-<slug>/.sdlc/docs-build.json"   # per-epic staleness baseline (yad-docs)
+  overview: "{project-root}/docs/sdlc-site/"          # the project SDLC-overview site (yad-docs-overview)
+  # Auth: `yad-connect-docs` records only how to reach the Pages host (platform + base path); it stores NO
+  # tokens — publishing runs as the LOCAL user's own gh/glab or the platform CI. Idempotent, refreshable.
+  auth: user
+
 # Hub platform + front-half review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
 # The product hub is itself a git repo on a platform. With the bridge enabled, the front-half review/
 # comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-connect-design yad-connect-testing yad-connect-learning yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
+SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos 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 yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -24,3 +24,7 @@ SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E:
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
 SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's back-half loop (spec→tasks→implement→checks) in one code repo, reading each step's automation dial from build-state — on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log. Realizes Step B (a clean checks pass auto-advances to the engineer review when earned; any FAIL / scope overrun / contract touch HALTS). set-dial earns/reverts a step's automation (machine_advance gated by the trust threshold; front states and engineer-review refused); kill/unkill toggles the system-wide kill switch. Front states and the human merge gate never auto-advance.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human_approve|machine_advance},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
 SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full front-state chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in the build half, also print each back-half step's automation dial and status, the trust record (runs / % approved-unchanged / earned vs gathering evidence), and the system-wide kill-switch state.",,{epic: EP-<slug>},1-front,,,false,,
+SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/hub.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: hub|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
+SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
+SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Supersedes the hand-maintained docs/index.html (left as a thin redirect for one release). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
+SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + the doc-shell version vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml