yadflow 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -1,14 +1,9 @@
-# [2.12.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.11.1...v2.12.0) (2026-06-16)
-
-
-### Bug Fixes
-
-* **checks:** harden spec-link + gitlab gate templates ([#69](https://github.com/abdelrahmannasr/yadflow/issues/69)) ([42f3949](https://github.com/abdelrahmannasr/yadflow/commit/42f3949841095624db03cb17f85db3138be8b93b))
+# [2.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.12.0...v2.13.0) (2026-06-16)
 
 
 ### Features
 
-* **docs:** pipeline-shaped overview canvas + collapsible panels + content refresh ([#70](https://github.com/abdelrahmannasr/yadflow/issues/70)) ([da47b80](https://github.com/abdelrahmannasr/yadflow/commit/da47b8050ccd7aa1919bf4b364298a90cdd56012))
+* **docs:** make the report the main documentation, mount the SPA under /app/ ([#71](https://github.com/abdelrahmannasr/yadflow/issues/71)) ([1993e4d](https://github.com/abdelrahmannasr/yadflow/commit/1993e4dc282df281474ca1923acd52dbd1262dcb))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/cli/docs.mjs

@@ -43,11 +43,12 @@ export function deployTargetFromHub(hub = {}) {
 }
 
 // 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
+// subpath. The overview SPA mounts under `app/` so the hand-maintained report.html can own the
+// Pages root (`<base>/`) as the main documentation; per-epic sites nest under epics/<id>/. 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 sub = overview ? '/app' : epic ? `/epics/${epic}` : '';
   const joined = `${root}${sub}`.replace(/\/+/g, '/');
   return joined ? `${joined.replace(/\/$/, '')}/` : '/';
 }
@@ -113,12 +114,13 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVers
 
 // ---- 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
+// hand-maintained report.html owns the root (`<base>/` — the main documentation), the overview SPA
+// mounts under `app/`, and every per-epic site nests under `epics/<id>/` — matching siteBasePath
+// (overview at `<base>/app/`, 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',
+  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html; 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.12.0",
+  "version": "2.13.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 + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

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

@@ -1,6 +1,6 @@
 ---
 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. Folds the legacy hand-maintained docs/index.html report into the site as report.html (linked from the nav) and 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.'
+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)
@@ -8,8 +8,10 @@ description: 'Generates the project-level SDLC-overview interactive site — the
 **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 front gates, the build half, the
-automation dial, the setup connectors. It is the regenerable successor to the hand-maintained
-overview report, which is folded into this site as `public/report.html`.
+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
@@ -70,7 +72,8 @@ determinism rules as `yad-docs`: stable-ID sort by skill pipeline order / phase,
 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` (the overview sits at the base root, e.g. `/<repo>/`).
+`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:
@@ -91,13 +94,16 @@ doc-shell upgrade triggers a rebuild). `skillCount` rides along in the manifest
 — 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 — Fold the legacy report into the site
-Relocate the hand-maintained static report into the generated site as `docs/sdlc-site/public/report.html`
-(Vite copies `public/` verbatim into `dist/`, so it publishes alongside the app at `<base>/report.html`),
-and link it from the app nav (a "Full report" link in `TopNavBar`). The interactive overview becomes the
-primary documentation and the legacy report rides along as its detailed companion — no orphaned
-`docs/index.html` at the repo root. This generalizes the standing rule that feature work hand-updates the
-report: the overview site now **regenerates** instead.
+### 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.
@@ -106,8 +112,9 @@ report: the overview site now **regenerates** instead.
 
 ### 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 legacy report is folded in
-at `public/report.html` (linked from the nav). Never touches any epic state.
+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