yadflow 2.11.1 → 2.13.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [2.11.1](https://github.com/abdelrahmannasr/yadflow/compare/v2.11.0...v2.11.1) (2026-06-15)
+# [2.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.12.0...v2.13.0) (2026-06-16)
 
 
-### Bug Fixes
+### Features
 
-* **doctor:** scope platform-CLI auth probe to the hub host ([#68](https://github.com/abdelrahmannasr/yadflow/issues/68)) ([3cb2801](https://github.com/abdelrahmannasr/yadflow/commit/3cb28011c80645e0ff42e544a9b3d933231daeb3))
+* **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.11.1",
+  "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-checks/references/check-gates.md

@@ -18,10 +18,17 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 
 ## 1. spec-link (`templates/checks/spec-link.sh`)
 
-- Collects the `Task:` trailers across `<base>..HEAD`.
-- **FAIL** if there is no `Task:` trailer (the change does not link a story/spec).
-- For each `Task: <story>-<task>`, strips the `-T<NN>` suffix to get `<story>` and requires
-  `specs/<story>/link.md` to exist. **FAIL** if missing.
+- Checks every non-merge commit in `<base>..HEAD` **per commit** (not aggregated across the range),
+  so the report names each offending commit and one bad commit never masks the rest.
+- Maintenance commits are **exempt**: a Conventional-Commits subject of type `ci`, `chore`, `build`,
+  or `test` (optional `(scope)` / breaking `!`) **PASSes** without a link — CI wiring, dependency
+  bumps, and test-infra changes legitimately link no story.
+- For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
+- The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
+  `EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
+- Strips the `-T<NN>` suffix from the task to get `<story>` and requires `specs/<story>/link.md` to
+  exist. **FAIL** if missing.
+- An empty range (no non-merge commits) **PASSes**.
 - Portable across bash 3.2 (macOS) and 4+ (no `mapfile`).
 - **Fails closed** when `<base>` can't be resolved (so a shallow clone / wrong base never PASSes blind).
 

package/skills/yad-checks/templates/checks/spec-link.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # spec-link gate (Phase 3 build plan §C).
-# The change must link a real story/spec: every commit range under review must carry a
+# Every NON-MAINTENANCE commit must link a real story/spec: it must carry a
 # `Task: <story>-<task>` trailer whose <story> resolves to a specs/<story>/link.md.
-# Fail if the link is missing — no unlinked code reaches merge.
+# Maintenance commits (ci/chore/build/test) are EXEMPT — CI wiring, dependency bumps,
+# and test-infra changes legitimately link no story. Checked per commit (not aggregated
+# across the range), so the report names every offending commit.
 set -euo pipefail
 
 BASE="${1:-${SDLC_BASE:-origin/main}}"
@@ -14,25 +16,48 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
 fi
 RANGE="${BASE}..HEAD"
 
-# Portable across bash 3.2 (macOS) and 4+ — no mapfile.
-tasks="$(git log "$RANGE" --format='%(trailers:key=Task,valueonly)' | sed '/^$/d' | sort -u)"
+# Conventional-Commits types exempt from the spec-link requirement (optional (scope) and breaking !).
+EXEMPT='ci|chore|build|test'
 
-if [ -z "$tasks" ]; then
-  echo "FAIL [spec-link]: no 'Task: <story>-<task>' trailer in ${RANGE} — change does not link a story/spec."
-  exit 1
+# Portable across bash 3.2 (macOS) and 4+ — no mapfile; feed the loop via heredoc (not a pipe) so
+# the failure count survives the loop body.
+commits="$(git rev-list --no-merges "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [spec-link]: no non-merge commits in ${RANGE}"
+  exit 0
 fi
 
 rc=0
-while IFS= read -r t; do
-  [ -z "$t" ] && continue
-  story="$(printf '%s' "$t" | sed -E 's/-T[0-9]+$//')"
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  short="$(git log -1 --format=%h "$sha")"
+  subject="$(git log -1 --format=%s "$sha")"
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
+    echo "PASS [spec-link]: ${short} '${subject}' — maintenance commit (exempt)"
+    continue
+  fi
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  if [ -z "$task" ]; then
+    echo "FAIL [spec-link]: ${short} '${subject}' has no 'Task:' trailer"
+    rc=1
+    continue
+  fi
+  # The trailer must be a real <story>-T<NN> id. Without this guard a malformed trailer
+  # (e.g. 'EP-demo-S01' with no -T<NN>) would survive the suffix-strip unchanged and PASS
+  # whenever specs/<that>/link.md happens to exist.
+  if ! printf '%s' "$task" | grep -qE '.+-T[0-9]+$'; then
+    echo "FAIL [spec-link]: ${short} '${subject}' has a malformed Task trailer '${task}' (expected <story>-T<NN>)."
+    rc=1
+    continue
+  fi
+  story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
   if [ -f "specs/${story}/link.md" ]; then
-    echo "PASS [spec-link]: ${t} -> specs/${story}/link.md"
+    echo "PASS [spec-link]: ${short} ${task} -> specs/${story}/link.md"
   else
-    echo "FAIL [spec-link]: ${t} references specs/${story}/ but link.md is missing."
+    echo "FAIL [spec-link]: ${short} ${task} references specs/${story}/ but link.md is missing."
     rc=1
   fi
 done <<EOF
-$tasks
+$commits
 EOF
 exit "$rc"

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -9,7 +9,14 @@
 # pipeline's default stage regardless of any `stages:` order the foreign root defines — a foreign
 # `stages:` list can neither break them nor reorder them. Job names are yad-prefixed to avoid
 # colliding with the host project's own job names.
-default:
+#
+# `image:`/`tags:` live on the .sdlc_mr_only anchor below — NOT a top-level `default:`. An included
+# top-level `default:` merges into the HOST root pipeline; if the host already sets a top-level
+# `image:`, GitLab rejects the whole config ("image is defined in top-level and 'default:' entry").
+# Putting them on the anchor scopes them to the gate jobs (which all `extends: .sdlc_mr_only`) and
+# never touches the host root.
+
+.sdlc_mr_only:
   image: node:20
   # Runner selection. These jobs need a docker/dind executor; on instances whose runners are all
   # tag-locked (run_untagged: false) an untagged image job never starts. Set the YAD_RUNNER_TAGS
@@ -19,8 +26,6 @@ default:
   # instead strand it `pending` — if so, set the variable to a real tag. Single value only:
   # `tags: [$VAR]` is one tag equal to the whole variable, not a comma-split.
   tags: [$YAD_RUNNER_TAGS]
-
-.sdlc_mr_only:
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 
@@ -45,6 +50,7 @@ yad-build-test-lint:
   variables:
     YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
+    - npm ci
     - bash checks/build-test-lint.sh
 
 # Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).

package/skills/yad-docs/templates/app/src/App.tsx

@@ -14,34 +14,69 @@ import { RoleSelectPage } from './pages/RoleSelectPage';
 import { StakeholderDocPage } from './pages/StakeholderDocPage';
 import { usePlayback } from './hooks/usePlayback';
 import { useFlowStore } from './store/useFlowStore';
+import { Icon } from './components/shared/Icon';
+
+const railStyle = {
+  borderColor: 'var(--color-border-default)',
+  background: 'var(--color-bg-primary)',
+};
 
 function Dashboard() {
   usePlayback();
   const isLogsPanelOpen = useFlowStore((s) => s.isLogsPanelOpen);
+  const isLeftPanelOpen = useFlowStore((s) => s.isLeftPanelOpen);
+  const isRightPanelOpen = useFlowStore((s) => s.isRightPanelOpen);
+  const toggleLeftPanel = useFlowStore((s) => s.toggleLeftPanel);
+  const toggleRightPanel = useFlowStore((s) => s.toggleRightPanel);
 
   return (
     <div className="flex flex-1 overflow-hidden">
-      {/* Left Sidebar */}
-      <aside
-        className="w-80 flex-none flex flex-col border-r z-10"
-        style={{
-          borderColor: 'var(--color-border-default)',
-          background: 'var(--color-bg-primary)',
-        }}
-      >
-        {/* Path Selection */}
-        <div className="p-4 border-b overflow-y-auto" style={{ borderColor: 'var(--color-border-default)' }}>
-          <PathSelector />
-        </div>
+      {/* Left Sidebar (collapsible — collapse to widen the canvas) */}
+      {isLeftPanelOpen ? (
+        <aside
+          className="w-80 flex-none flex flex-col border-r z-10"
+          style={railStyle}
+        >
+          {/* Collapse header */}
+          <div className="flex items-center justify-between px-4 pt-3 pb-1">
+            <span className="text-[10px] font-bold uppercase tracking-wider" style={{ color: 'var(--color-text-muted)' }}>
+              Navigator
+            </span>
+            <button
+              onClick={toggleLeftPanel}
+              title="Collapse panel"
+              aria-label="Collapse navigator panel"
+              className="flex h-7 w-7 items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-white/5 hover:text-white"
+            >
+              <Icon name="left_panel_close" size={18} />
+            </button>
+          </div>
 
-        {/* Step Timeline */}
-        <div className="flex-1 overflow-y-auto p-4">
-          <StepList />
-        </div>
+          {/* Path Selection */}
+          <div className="p-4 border-b overflow-y-auto" style={{ borderColor: 'var(--color-border-default)' }}>
+            <PathSelector />
+          </div>
 
-        {/* Footer */}
-        <SidebarFooter />
-      </aside>
+          {/* Step Timeline */}
+          <div className="flex-1 overflow-y-auto p-4">
+            <StepList />
+          </div>
+
+          {/* Footer */}
+          <SidebarFooter />
+        </aside>
+      ) : (
+        <div className="w-10 flex-none flex flex-col items-center border-r z-10 pt-3" style={railStyle}>
+          <button
+            onClick={toggleLeftPanel}
+            title="Expand navigator"
+            aria-label="Expand navigator panel"
+            className="flex h-8 w-8 items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-white/5 hover:text-white"
+          >
+            <Icon name="left_panel_open" size={18} />
+          </button>
+        </div>
+      )}
 
       {/* Main Canvas Area */}
       <main className="flex-1 flex flex-col overflow-hidden relative flow-grid"
@@ -65,8 +100,21 @@ function Dashboard() {
         <PlaybackBar />
       </main>
 
-      {/* Right Detail Panel */}
-      <RightPanel />
+      {/* Right Detail Panel (collapsible — collapse to widen the canvas) */}
+      {isRightPanelOpen ? (
+        <RightPanel />
+      ) : (
+        <div className="w-10 flex-none flex flex-col items-center border-l z-10 pt-3" style={railStyle}>
+          <button
+            onClick={toggleRightPanel}
+            title="Expand details"
+            aria-label="Expand step-details panel"
+            className="flex h-8 w-8 items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-white/5 hover:text-white"
+          >
+            <Icon name="right_panel_open" size={18} />
+          </button>
+        </div>
+      )}
     </div>
   );
 }

package/skills/yad-docs/templates/app/src/components/Canvas/FlowCanvas.tsx

@@ -75,6 +75,26 @@ export const FlowCanvas: React.FC = () => {
 
   const messages = currentStep?.messages || [];
 
+  // Optional loop-back arc, swept below the canvas to read as "the pipeline repeats".
+  // Rendered only when both endpoint nodes exist (e.g. the SDLC-overview's
+  // trust-log → product-hub cycle); a no-op for diagrams without them.
+  const loopBack = useMemo(() => {
+    if (dims.width === 0) return null;
+    const a = COMPONENTS.find((c) => c.id === 'trust-log');
+    const b = COMPONENTS.find((c) => c.id === 'product-hub');
+    if (!a || !b) return null;
+    const x1 = (a.position.x / 100) * dims.width;
+    const y1 = (a.position.y / 100) * dims.height;
+    const x2 = (b.position.x / 100) * dims.width;
+    const y2 = (b.position.y / 100) * dims.height;
+    const yb = dims.height * 0.985;
+    return {
+      d: `M ${x1} ${y1} C ${x1} ${yb}, ${x2} ${yb}, ${x2} ${y2}`,
+      labelX: (x1 + x2) / 2,
+      labelY: dims.height * 0.92,
+    };
+  }, [dims]);
+
   return (
     <div ref={containerRef} className="relative h-full w-full overflow-hidden">
       {/* Canvas Header Overlay */}
@@ -159,6 +179,33 @@ export const FlowCanvas: React.FC = () => {
                 containerHeight={dims.height}
               />
             ))}
+
+            {/* Loop-back: the pipeline repeats per epic */}
+            {loopBack && (
+              <g>
+                <path
+                  d={loopBack.d}
+                  fill="none"
+                  stroke="#ff6490"
+                  strokeWidth={1.5}
+                  strokeDasharray="6 5"
+                  opacity={0.55}
+                  markerEnd="url(#arrowhead)"
+                />
+                <text
+                  x={loopBack.labelX}
+                  y={loopBack.labelY}
+                  textAnchor="middle"
+                  fontSize={12}
+                  fontWeight={700}
+                  letterSpacing={0.6}
+                  fill="#ff8db0"
+                  opacity={0.85}
+                >
+                  ↺ pipeline repeats per epic
+                </text>
+              </g>
+            )}
           </svg>
         )}
 

package/skills/yad-docs/templates/app/src/components/DetailPanel/RightPanel.tsx

@@ -12,6 +12,7 @@ export function RightPanel() {
   const getCurrentStep = useFlowStore((s) => s.getCurrentStep);
   const activeStepIndex = useFlowStore((s) => s.activeStepIndex);
   const selectedPath = useFlowStore((s) => s.selectedPath);
+  const toggleRightPanel = useFlowStore((s) => s.toggleRightPanel);
   const navigate = useNavigate();
   const step = getCurrentStep();
 
@@ -29,7 +30,14 @@ export function RightPanel() {
         <h3 className="text-slate-100 text-sm font-bold font-display uppercase tracking-wider">
           Step Details
         </h3>
-        <Icon name="close" size={20} className="text-slate-500 cursor-pointer hover:text-white" />
+        <button
+          onClick={toggleRightPanel}
+          title="Collapse panel"
+          aria-label="Collapse step-details panel"
+          className="flex h-7 w-7 items-center justify-center rounded-md text-slate-400 transition-colors hover:bg-white/5 hover:text-white"
+        >
+          <Icon name="right_panel_close" size={18} />
+        </button>
       </div>
 
       {!step ? (

package/skills/yad-docs/templates/app/src/components/Sidebar/StepList.tsx

@@ -43,15 +43,6 @@ export const StepList = () => {
     }
   };
 
-  // Reset expanded state when active step changes externally (playback)
-  const prevActiveRef = { current: activeStepIndex };
-  if (prevActiveRef.current !== activeStepIndex) {
-    prevActiveRef.current = activeStepIndex;
-    if (expandedIndex !== null && expandedIndex !== activeStepIndex) {
-      // Auto-expand the new active step during playback
-    }
-  }
-
   return (
     <div className="flex flex-col gap-2">
       <div className="flex items-center justify-between mb-2">

package/skills/yad-docs/templates/app/src/components/shared/CommandPalette.tsx

@@ -28,13 +28,16 @@ export function CommandPalette() {
     return () => window.removeEventListener('keydown', handler);
   }, [isOpen, toggle]);
 
-  // Reset on open
-  useEffect(() => {
+  // Reset on open — adjust state during render (not inside an effect) so it does
+  // not trigger an extra cascading render (react-hooks/set-state-in-effect).
+  const [wasOpen, setWasOpen] = useState(isOpen);
+  if (isOpen !== wasOpen) {
+    setWasOpen(isOpen);
     if (isOpen) {
       setQuery('');
       setSelectedIndex(0);
     }
-  }, [isOpen]);
+  }
 
   const results = useMemo(() => {
     if (!query.trim()) {

package/skills/yad-docs/templates/app/src/hooks/useAnimationQueue.ts

@@ -9,13 +9,22 @@ export function useAnimationQueue() {
   const [animKey, setAnimKey] = useState(0);
   const timersRef = useRef<ReturnType<typeof setTimeout>[]>([]);
 
-  // When step changes, reset and schedule completion events
+  // Reset the pulse state the instant the step (or speed) changes — done during
+  // render via the "adjust state on change" pattern rather than inside the effect,
+  // so it does not trigger an extra cascading render (react-hooks/set-state-in-effect).
+  const stepKey = `${activeStepIndex}-${speed}`;
+  const [resetKey, setResetKey] = useState(stepKey);
+  if (stepKey !== resetKey) {
+    setResetKey(stepKey);
+    setCompletedTargets(new Set());
+    setAnimKey((k) => k + 1);
+  }
+
+  // When step changes, schedule the target-pulse completion events.
   useEffect(() => {
     // Clear previous timers
     timersRef.current.forEach(clearTimeout);
     timersRef.current = [];
-    setCompletedTargets(new Set());
-    setAnimKey((k) => k + 1);
 
     // Get messages from the current step
     const step = useFlowStore.getState().getCurrentStep();

package/skills/yad-docs/templates/app/src/hooks/usePlayback.ts

@@ -30,7 +30,7 @@ export function usePlayback() {
     return () => {
       if (elapsedRef.current) clearInterval(elapsedRef.current);
     };
-  }, [playbackState]);
+  }, [playbackState, tickElapsed, resetElapsed]);
 
   // Generate logs on step change
   useEffect(() => {
@@ -56,7 +56,7 @@ export function usePlayback() {
         });
       }, msg.delay / speed);
     }
-  }, [activeStepIndex, speed]);
+  }, [activeStepIndex, speed, addLog, getCurrentSteps]);
 
   useEffect(() => {
     if (playbackState !== "playing") {
@@ -96,5 +96,5 @@ export function usePlayback() {
     return () => {
       if (timerRef.current) clearTimeout(timerRef.current);
     };
-  }, [playbackState, activeStepIndex, speed, animatingMessages]);
+  }, [playbackState, activeStepIndex, speed, animatingMessages, getCurrentSteps, nextStep, setAnimatingMessages]);
 }

package/skills/yad-docs/templates/app/src/store/useFlowStore.ts

@@ -26,6 +26,8 @@ interface FlowStore {
   isReferencePanelOpen: boolean;
   isCommandPaletteOpen: boolean;
   isLogsPanelOpen: boolean;
+  isLeftPanelOpen: boolean;
+  isRightPanelOpen: boolean;
 
   // Logs
   logs: LogEntry[];
@@ -57,6 +59,8 @@ interface FlowStore {
   toggleReferencePanel: () => void;
   toggleCommandPalette: () => void;
   toggleLogsPanel: () => void;
+  toggleLeftPanel: () => void;
+  toggleRightPanel: () => void;
 
   // Logs
   addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
@@ -90,6 +94,8 @@ export const useFlowStore = create<FlowStore>((set, get) => ({
   isReferencePanelOpen: false,
   isCommandPaletteOpen: false,
   isLogsPanelOpen: false,
+  isLeftPanelOpen: true,
+  isRightPanelOpen: true,
   logs: [],
   elapsedTime: 0,
 
@@ -157,6 +163,8 @@ export const useFlowStore = create<FlowStore>((set, get) => ({
   toggleReferencePanel: () => set((s) => ({ isReferencePanelOpen: !s.isReferencePanelOpen })),
   toggleCommandPalette: () => set((s) => ({ isCommandPaletteOpen: !s.isCommandPaletteOpen })),
   toggleLogsPanel: () => set((s) => ({ isLogsPanelOpen: !s.isLogsPanelOpen })),
+  toggleLeftPanel: () => set((s) => ({ isLeftPanelOpen: !s.isLeftPanelOpen })),
+  toggleRightPanel: () => set((s) => ({ isRightPanelOpen: !s.isRightPanelOpen })),
 
   // Logs
   addLog: (entry) => {

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