executable-stories-formatters 0.13.0 → 0.15.0

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import * as fs14 from "fs";
-import * as path15 from "path";
+import * as fs16 from "fs";
+import * as path17 from "path";
 
 // src/validation/schema-validator.ts
 import Ajv from "ajv/dist/2020.js";
@@ -588,17 +588,17 @@ function validateRawRun(data) {
     return { valid: true, errors: [] };
   }
   const errors = (validate.errors ?? []).map((err) => {
-    const path16 = err.instancePath || "/";
+    const path18 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path16}: ${message} \u2014 '${extra}'`;
+      return `${path18}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path16}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path18}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path16}: ${message}`;
+    return `${path18}: ${message}`;
   });
   return { valid: false, errors };
 }
@@ -1237,7 +1237,7 @@ var CucumberJsonFormatter = class {
   /**
    * Build a single step.
    */
-  buildStep(step, result, line, index, attachments, isLastStep, hasFailedStep) {
+  buildStep(step, result, line2, index, attachments, isLastStep, hasFailedStep) {
     const keyword = this.options.keywordSpacing ? `${step.keyword} ` : step.keyword;
     const stepResult = this.buildStepResult(result);
     const embeddings = this.buildEmbeddings(attachments, result, isLastStep, hasFailedStep);
@@ -1245,7 +1245,7 @@ var CucumberJsonFormatter = class {
     embeddings.push(...screenshotEmbeddings);
     const jsonStep = {
       keyword,
-      line,
+      line: line2,
       name: step.text,
       result: stepResult
     };
@@ -15792,8 +15792,8 @@ var JUnitFormatter = class {
       case "section": {
         const lines = [];
         lines.push(`${indent}${entry.title}:`);
-        for (const line of entry.markdown.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of entry.markdown.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15802,8 +15802,8 @@ var JUnitFormatter = class {
         if (entry.title) {
           lines.push(`${indent}${entry.title}:`);
         }
-        for (const line of entry.code.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of entry.code.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15815,8 +15815,8 @@ var JUnitFormatter = class {
         const dataStr = JSON.stringify(entry.data, null, 2);
         const lines = [];
         lines.push(`${indent}[${entry.type}]:`);
-        for (const line of dataStr.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of dataStr.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15862,7 +15862,10 @@ var MarkdownFormatter = class {
       ticketUrlTemplate: options.ticketUrlTemplate,
       traceUrlTemplate: options.traceUrlTemplate,
       includeSourceLinks: options.includeSourceLinks ?? true,
-      customRenderers: options.customRenderers
+      customRenderers: options.customRenderers,
+      scenarioAnchor: options.scenarioAnchor,
+      scenarioBadge: options.scenarioBadge,
+      scenarioNoteLink: options.scenarioNoteLink
     };
   }
   /**
@@ -16049,6 +16052,11 @@ var MarkdownFormatter = class {
    * Render a single scenario.
    */
   renderScenario(lines, tc) {
+    const anchorId = this.options.scenarioAnchor?.(tc);
+    if (anchorId) {
+      lines.push(`<a id="${anchorId}"></a>`);
+      lines.push("");
+    }
     if (this.options.customRenderers?.renderScenarioHeader) {
       const custom = this.options.customRenderers.renderScenarioHeader(tc);
       if (custom !== null) {
@@ -16064,6 +16072,14 @@ var MarkdownFormatter = class {
       icon = this.getStatusIcon(tc.status) + " ";
     }
     lines.push(`${headingPrefix} ${icon}${tc.story.scenario}`);
+    const badge2 = this.options.scenarioBadge?.(tc);
+    if (badge2) {
+      lines.push(badge2);
+    }
+    const noteLink = this.options.scenarioNoteLink?.(tc);
+    if (noteLink) {
+      lines.push(noteLink);
+    }
     if (this.options.includeSourceLinks && this.options.permalinkBaseUrl && tc.sourceFile !== "unknown") {
       const permalink = this.buildPermalink(tc);
       lines.push(`Source: [${tc.sourceFile}](${permalink})`);
@@ -16138,8 +16154,8 @@ var MarkdownFormatter = class {
   buildPermalink(tc) {
     const base = this.options.permalinkBaseUrl.replace(/\/$/, "");
     const file = tc.sourceFile;
-    const line = tc.sourceLine > 0 ? `#L${tc.sourceLine}` : "";
-    return `${base}/${file}${line}`;
+    const line2 = tc.sourceLine > 0 ? `#L${tc.sourceLine}` : "";
+    return `${base}/${file}${line2}`;
   }
   /**
    * Render a step.
@@ -16207,8 +16223,8 @@ var MarkdownFormatter = class {
           lines.push(`${indent}`);
         }
         lines.push(`${indent}\`\`\`${entry.lang ?? ""}`);
-        for (const line of (entry.content ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.content ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16231,8 +16247,8 @@ var MarkdownFormatter = class {
       case "section":
         lines.push(`${indent}**${entry.title}**`);
         lines.push(`${indent}`);
-        for (const line of (entry.markdown ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.markdown ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}`);
         break;
@@ -16241,8 +16257,8 @@ var MarkdownFormatter = class {
           lines.push(`${indent}**${entry.title}**`);
         }
         lines.push(`${indent}\`\`\`mermaid`);
-        for (const line of (entry.code ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.code ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         break;
@@ -16272,8 +16288,8 @@ var MarkdownFormatter = class {
         lines.push(`${indent}<summary>${htmlLabel}</summary>`);
         lines.push(`${indent}`);
         lines.push(`${indent}\`\`\`html`);
-        for (const line of (entry.content ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.content ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16295,8 +16311,8 @@ var MarkdownFormatter = class {
         lines.push(`${indent}**[${entry.type}]**`);
         lines.push(`${indent}`);
         lines.push(`${indent}\`\`\`json`);
-        for (const line of JSON.stringify(entry.data ?? null, null, 2).split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of JSON.stringify(entry.data ?? null, null, 2).split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16479,14 +16495,14 @@ var TraceabilityMatrixFormatter = class {
       lines.push("");
       lines.push(`Status: ${renderRequirementStatus(req.status)}`);
       if (req.covers.length > 0) {
-        lines.push(`Covers: ${req.covers.map((path16) => `\`${path16}\``).join(", ")}`);
+        lines.push(`Covers: ${req.covers.map((path18) => `\`${path18}\``).join(", ")}`);
       }
       lines.push("");
       lines.push("| Status | Scenario | Source | Covers |");
       lines.push("| --- | --- | --- | --- |");
       for (const scenario of req.scenarios) {
         const source = `${scenario.sourceFile}:${scenario.sourceLine}`;
-        const covers = scenario.covers.length > 0 ? scenario.covers.map((path16) => `\`${path16}\``).join(", ") : "";
+        const covers = scenario.covers.length > 0 ? scenario.covers.map((path18) => `\`${path18}\``).join(", ") : "";
         lines.push(`| ${scenario.status} | ${escapePipe2(scenario.title)} | \`${source}\` | ${covers} |`);
       }
       lines.push("");
@@ -16588,8 +16604,8 @@ function extractFeatureName(testCases, uri) {
       return tc.titlePath[0];
     }
   }
-  const basename4 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
-  return basename4.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const basename5 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
+  return basename5.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function synthesizeFeature(uri, testCases) {
   const featureName = extractFeatureName(testCases, uri);
@@ -16807,60 +16823,60 @@ function buildStepArguments(step, stepLine) {
   }
   return {};
 }
-function docEntryToDocString(doc, line) {
+function docEntryToDocString(doc, line2) {
   switch (doc.kind) {
     case "code":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: doc.lang,
         content: doc.content,
         delimiter: '"""'
       };
     case "note":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: doc.text,
         delimiter: '"""'
       };
     case "section":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/markdown",
         content: doc.markdown,
         delimiter: '"""'
       };
     case "mermaid":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/x-mermaid",
         content: doc.code,
         delimiter: '"""'
       };
     case "kv":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: `${doc.label}: ${typeof doc.value === "string" ? doc.value : JSON.stringify(doc.value)}`,
         delimiter: '"""'
       };
     case "link":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/markdown",
         content: `[${doc.label}](${doc.url})`,
         delimiter: '"""'
       };
     case "custom":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "application/json",
         content: JSON.stringify(doc.data, null, 2),
         delimiter: '"""'
       };
     case "tag":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: doc.names.map((n) => `@${n}`).join(" "),
         delimiter: '"""'
@@ -16870,18 +16886,18 @@ function docEntryToDocString(doc, line) {
       return void 0;
   }
 }
-function buildDataTable(table2, line) {
+function buildDataTable(table2, line2) {
   const rows = [];
   rows.push({
-    location: { line },
+    location: { line: line2 },
     cells: table2.columns.map((col) => ({
-      location: { line },
+      location: { line: line2 },
       value: col
     })),
     id: ""
   });
   for (let r = 0; r < table2.rows.length; r++) {
-    const rowLine = line + 1 + r;
+    const rowLine = line2 + 1 + r;
     rows.push({
       location: { line: rowLine },
       cells: table2.rows[r].map((cell) => ({
@@ -16892,7 +16908,7 @@ function buildDataTable(table2, line) {
     });
   }
   return {
-    location: { line },
+    location: { line: line2 },
     rows
   };
 }
@@ -17201,8 +17217,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path16) {
-  const lower = path16.toLowerCase();
+function guessMediaType(path18) {
+  const lower = path18.toLowerCase();
   if (lower.endsWith(".png")) return "image/png";
   if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
   if (lower.endsWith(".gif")) return "image/gif";
@@ -18444,17 +18460,17 @@ ${body}`;
     return humanizeSourceFile([...sourceFiles][0]) || this.title;
   }
   buildFrontmatter(run) {
-    const badge = _AstroFormatter.computeBadge(run.testCases);
+    const badge2 = _AstroFormatter.computeBadge(run.testCases);
     const count2 = run.testCases.length;
-    const description = `${count2} scenario${count2 !== 1 ? "s" : ""} \u2014 ${badge.text.toLowerCase()}`;
+    const description = `${count2} scenario${count2 !== 1 ? "s" : ""} \u2014 ${badge2.text.toLowerCase()}`;
     const lines = [
       "---",
       `title: ${yamlScalar(this.deriveTitle(run))}`,
       `description: ${description}`,
       "sidebar:",
       "  badge:",
-      `    text: ${badge.text}`,
-      `    variant: ${badge.variant}`,
+      `    text: ${badge2.text}`,
+      `    variant: ${badge2.variant}`,
       "---"
     ];
     return lines.join("\n");
@@ -18910,12 +18926,16 @@ function groupBy7(items, keyFn) {
 import * as fs5 from "fs";
 import * as path6 from "path";
 var SKIP_PREFIXES = ["http://", "https://", "data:", "#"];
-function isLocalPath(src) {
+function isRemoteRef(src) {
   const trimmed = src.trim();
-  if (SKIP_PREFIXES.some((prefix) => trimmed.startsWith(prefix))) {
-    return false;
-  }
-  return !path6.posix.isAbsolute(trimmed) && !path6.win32.isAbsolute(trimmed);
+  return SKIP_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+function isAbsoluteRef(src) {
+  const trimmed = src.trim();
+  return path6.posix.isAbsolute(trimmed) || path6.win32.isAbsolute(trimmed);
+}
+function isRelativeLocalPath(src) {
+  return !isRemoteRef(src) && !isAbsoluteRef(src);
 }
 function stripCodeContent(markdown) {
   let result = markdown.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1\s*$/gm, "");
@@ -18931,21 +18951,21 @@ function scanMarkdownAssets(markdown) {
   let match;
   while ((match = mdImageRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
   const htmlSrcRe = /<(?:img|source|video)[^>]+\bsrc=["']([^"']+)["'][^>]*>/gi;
   while ((match = htmlSrcRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
   const posterRe = /<video[^>]+\bposter=["']([^"']+)["'][^>]*>/gi;
   while ((match = posterRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
@@ -18971,48 +18991,21 @@ function isCode(segment) {
   const trimmed = segment.trimStart();
   return trimmed.startsWith("`") || trimmed.startsWith("~") || trimmed.startsWith("<pre") || trimmed.startsWith("<code");
 }
+function resolveRewrite(trimmed, assetsBaseUrl, pathMap) {
+  if (isRemoteRef(trimmed)) return null;
+  if (pathMap) {
+    const mapped = pathMap.get(trimmed);
+    return mapped === void 0 ? null : `${assetsBaseUrl}/${mapped}`;
+  }
+  if (!isRelativeLocalPath(trimmed)) return null;
+  return `${assetsBaseUrl}/${trimmed}`;
+}
 function rewriteProseSegment(prose, assetsBaseUrl, pathMap) {
-  let result = prose;
-  result = result.replace(
-    /(!\[[^\]]*\]\()([^)"'\s]+)((?:\s+["'][^"']*["'])?\s*\))/g,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  result = result.replace(
-    /(<(?:img|source|video)[^>]+\bsrc=["'])([^"']+)(["'][^>]*>)/gi,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  result = result.replace(
-    /(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  return result;
+  const rewrite = (full, pre, src, post) => {
+    const target = resolveRewrite(src.trim(), assetsBaseUrl, pathMap);
+    return target === null ? full : `${pre}${target}${post}`;
+  };
+  return prose.replace(/(!\[[^\]]*\]\()([^)"'\s]+)((?:\s+["'][^"']*["'])?\s*\))/g, rewrite).replace(/(<(?:img|source|video)[^>]+\bsrc=["'])([^"']+)(["'][^>]*>)/gi, rewrite).replace(/(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi, rewrite);
 }
 function rewriteAssetPaths(markdown, assetsBaseUrl, pathMap) {
   return splitByCode(markdown).map((seg) => isCode(seg) ? seg : rewriteProseSegment(seg, assetsBaseUrl, pathMap)).join("");
@@ -19029,8 +19022,9 @@ function copyMarkdownAssets(options) {
   const pathMap = /* @__PURE__ */ new Map();
   const missing = [];
   for (const ref of refs) {
-    const absPath = path6.resolve(markdownDir, ref);
+    const absPath = isAbsoluteRef(ref) ? ref : path6.resolve(markdownDir, ref);
     if (!fs5.existsSync(absPath)) {
+      if (isAbsoluteRef(ref)) continue;
       if (!allowMissing) {
         throw new Error(`Asset not found: ${absPath}`);
       }
@@ -19112,6 +19106,47 @@ function startWatch(options, deps = {}) {
   };
 }
 
+// src/behavior-diff.ts
+function classifyStatusChange(baseline, current) {
+  if (baseline === void 0) return "added";
+  if (current === void 0) return "removed";
+  if (baseline === current) return "unchanged";
+  if (baseline === "passed" && current === "failed") return "regressed";
+  if (baseline === "failed" && current === "passed") return "fixed";
+  return "changed";
+}
+function scenarioMap(report) {
+  const map = /* @__PURE__ */ new Map();
+  for (const feature of report.features) {
+    for (const scenario of feature.scenarios) {
+      map.set(scenario.id, { scenario, sourceFile: feature.sourceFile });
+    }
+  }
+  return map;
+}
+function diffStoryReports(baseline, current) {
+  const base = scenarioMap(baseline);
+  const curr = scenarioMap(current);
+  const ids = [.../* @__PURE__ */ new Set([...base.keys(), ...curr.keys()])];
+  const scenarios = ids.map((id) => {
+    const b = base.get(id);
+    const c = curr.get(id);
+    const kind = classifyStatusChange(b?.scenario.status, c?.scenario.status);
+    const meta = c ?? b;
+    return {
+      id,
+      title: meta.scenario.title,
+      sourceFile: meta.sourceFile,
+      kind,
+      baselineStatus: b?.scenario.status,
+      currentStatus: c?.scenario.status
+    };
+  });
+  const summary = { added: 0, removed: 0, regressed: 0, fixed: 0, changed: 0, unchanged: 0 };
+  for (const s of scenarios) summary[s.kind] += 1;
+  return { schemaVersion: "1.0", summary, scenarios };
+}
+
 // src/publishers/confluence.ts
 function parseAdf(adf) {
   let parsed;
@@ -19344,7 +19379,7 @@ async function updateDescription(issueKey, base, adf, headers, fetchFn) {
 // src/converters/ndjson-parser.ts
 function parseNdjson(ndjson) {
   const lines = ndjson.trim().split("\n").filter(Boolean);
-  const envelopes = lines.map((line) => JSON.parse(line));
+  const envelopes = lines.map((line2) => JSON.parse(line2));
   return parseEnvelopes(envelopes);
 }
 function parseEnvelopes(envelopes) {
@@ -20717,18 +20752,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path16) {
-  const base = path16.split("/").pop() ?? path16;
+function extensionOf(path18) {
+  const base = path18.split("/").pop() ?? path18;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path16) {
-  return TEST_INFIX.test(path16);
+function isTestFile(path18) {
+  return TEST_INFIX.test(path18);
 }
-function isReviewableSource(path16) {
-  if (isTestFile(path16)) return false;
-  if (path16.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path16));
+function isReviewableSource(path18) {
+  if (isTestFile(path18)) return false;
+  if (path18.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path18));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -20832,7 +20867,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path16) => sourceBaseKey(path16) === key
+    (path18) => sourceBaseKey(path18) === key
   );
   return {
     id: testCase.id,
@@ -21695,7 +21730,10 @@ var ReportGenerator = class {
           permalinkBaseUrl: options.astro?.markdown?.permalinkBaseUrl,
           ticketUrlTemplate: options.astro?.markdown?.ticketUrlTemplate,
           traceUrlTemplate: options.astro?.markdown?.traceUrlTemplate,
-          customRenderers: options.astro?.markdown?.customRenderers
+          customRenderers: options.astro?.markdown?.customRenderers,
+          scenarioAnchor: options.astro?.markdown?.scenarioAnchor,
+          scenarioBadge: options.astro?.markdown?.scenarioBadge,
+          scenarioNoteLink: options.astro?.markdown?.scenarioNoteLink
         }
       },
       assetMode: options.assetMode ?? "none",
@@ -22032,7 +22070,13 @@ function copyDirRecursive(src, dest, onFile, baseSrc = src) {
 // src/scaffold-doc.ts
 import * as fs10 from "fs";
 import * as path11 from "path";
-var TEMPLATES = ["adr", "runbook", "decision-log", "incident"];
+var TEMPLATES = [
+  "adr",
+  "runbook",
+  "decision-log",
+  "incident",
+  "scenario-note"
+];
 function slugify3(input) {
   return input.toLowerCase().trim().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
 }
@@ -22161,6 +22205,30 @@ _How it was fixed._
 
 - [ ] Add a regression story and link it in \`verifiedBy\` so a silent recurrence
   becomes a failing badge.
+`
+  },
+  "scenario-note": {
+    subdir: "notes",
+    filename: (_slug, ctx) => ctx.scenarioId ?? ctx.slug,
+    content: (ctx) => `---
+title: 'Business context \u2014 ${ctx.name}'
+description: 'Stakeholder context for ${ctx.name}'
+scenarioId: ${ctx.scenarioId}
+# Link this note back to the scenario it explains so the badge and explorer stay aligned.
+verifiedBy: [${ctx.scenarioId}]
+---
+
+This page is hand-written commentary for a generated scenario. It is never
+overwritten by \`build-docs\`.
+
+## Why this behavior matters
+
+_Describe the business rule, policy, customer promise, or operational nuance._
+
+## Caveats
+
+- _What readers should know when this scenario passes_
+- _Any assumptions, exclusions, or follow-up links_
 `
   }
 };
@@ -22179,10 +22247,15 @@ function scaffoldDoc(options) {
   const today = options.today ?? /* @__PURE__ */ new Date();
   const name = (options.name ?? "").trim() || defaultName(template);
   const slug2 = slugify3(name);
+  const scenarioId = normalizeScenarioId(options.scenarioId);
   const dir = path11.join(baseDir, spec.subdir);
+  if (template === "scenario-note" && !scenarioId) {
+    throw new Error(`Template "scenario-note" requires --scenario-id.`);
+  }
   const ctx = {
     name,
     slug: slug2,
+    scenarioId,
     isoDate: isoDate(today),
     seq: nextSeq(dir)
   };
@@ -22207,6 +22280,8 @@ function defaultName(template) {
       return "Decisions";
     case "incident":
       return "Untitled incident";
+    case "scenario-note":
+      return "Untitled scenario note";
   }
 }
 function titleFor2(template, ctx) {
@@ -22219,12 +22294,43 @@ function titleFor2(template, ctx) {
       return `Decision log \u2014 ${ctx.name}`;
     case "incident":
       return `Incident \u2014 ${ctx.name}`;
+    case "scenario-note":
+      return `Business context \u2014 ${ctx.name}`;
   }
 }
+function normalizeScenarioId(input) {
+  const value = input?.trim();
+  if (!value) return void 0;
+  if (value.includes("/") || value.includes("\\")) {
+    throw new Error(`scenarioId must not contain path separators.`);
+  }
+  return value;
+}
 
 // src/check-links.ts
+import * as fs12 from "fs";
+import * as path13 from "path";
+
+// src/utils/markdown-files.ts
 import * as fs11 from "fs";
 import * as path12 from "path";
+function collectMarkdownFiles(target) {
+  if (!fs11.existsSync(target)) return [];
+  if (fs11.statSync(target).isFile()) return [target];
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of fs11.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const full = path12.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (/\.mdx?$/u.test(entry.name)) out.push(full);
+    }
+  };
+  walk(target);
+  return out;
+}
+
+// src/check-links.ts
 function stripCode(markdown) {
   let out = markdown.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1\s*$/gm, "");
   out = out.replace(/(`+)(?:(?!\1).)+\1/g, "");
@@ -22254,34 +22360,19 @@ function classifyLink(link2) {
 function resolutionCandidates(fromFile, link2) {
   const withoutAnchor = link2.split("#")[0];
   if (!withoutAnchor) return [];
-  const base = path12.resolve(path12.dirname(fromFile), withoutAnchor);
+  const base = path13.resolve(path13.dirname(fromFile), withoutAnchor);
   const candidates = [base];
-  if (!path12.extname(base)) {
+  if (!path13.extname(base)) {
     candidates.push(`${base}.md`, `${base}.mdx`);
-    candidates.push(path12.join(base, "index.md"), path12.join(base, "index.mdx"));
+    candidates.push(path13.join(base, "index.md"), path13.join(base, "index.mdx"));
   }
   return candidates;
 }
 function resolvesOnDisk(fromFile, link2) {
   return resolutionCandidates(fromFile, link2).some(
-    (candidate) => fs11.existsSync(candidate) && fs11.statSync(candidate).isFile()
+    (candidate) => fs12.existsSync(candidate) && fs12.statSync(candidate).isFile()
   );
 }
-function collectDocFiles(target) {
-  const stat = fs11.statSync(target);
-  if (stat.isFile()) return [target];
-  const out = [];
-  const walk = (dir) => {
-    for (const entry of fs11.readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-      const full = path12.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (/\.mdx?$/.test(entry.name)) out.push(full);
-    }
-  };
-  walk(target);
-  return out;
-}
 async function isExternalAlive(url, timeoutMs) {
   const attempt = async (method) => {
     const controller = new AbortController();
@@ -22305,17 +22396,17 @@ async function isExternalAlive(url, timeoutMs) {
 }
 async function checkLinks(options) {
   const { target, checkExternal = false, externalTimeoutMs = 8e3 } = options;
-  if (!fs11.existsSync(target)) {
+  if (!fs12.existsSync(target)) {
     throw new Error(`Path not found: ${target}`);
   }
-  const files = collectDocFiles(target);
+  const files = collectMarkdownFiles(target);
   const broken = [];
   let linksChecked = 0;
   let externalChecked = 0;
   let skipped = 0;
   const externalCache = /* @__PURE__ */ new Map();
   for (const file of files) {
-    const content = fs11.readFileSync(file, "utf8");
+    const content = fs12.readFileSync(file, "utf8");
     for (const link2 of extractLinks(content)) {
       const kind = classifyLink(link2);
       if (kind === "anchor" || kind === "mail" || kind === "root") {
@@ -22371,8 +22462,8 @@ function formatLinkReport(report) {
 }
 
 // src/import-openapi.ts
-import * as fs12 from "fs";
-import * as path13 from "path";
+import * as fs13 from "fs";
+import * as path14 from "path";
 import { parse as parseYamlString } from "yaml";
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
 function parseYaml(raw, specPath) {
@@ -22385,9 +22476,9 @@ function parseYaml(raw, specPath) {
   }
 }
 function parseSpec(specPath) {
-  if (!fs12.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
-  const raw = fs12.readFileSync(specPath, "utf8");
-  const ext = path13.extname(specPath).toLowerCase();
+  if (!fs13.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
+  const raw = fs13.readFileSync(specPath, "utf8");
+  const ext = path14.extname(specPath).toLowerCase();
   if (ext === ".json") return JSON.parse(raw);
   if (ext === ".yaml" || ext === ".yml") return parseYaml(raw, specPath);
   try {
@@ -22418,8 +22509,8 @@ function extractEndpoints(spec) {
 }
 function loadScenarios(runFile) {
   if (!runFile) return [];
-  if (!fs12.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
-  const report = JSON.parse(fs12.readFileSync(runFile, "utf8"));
+  if (!fs13.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
+  const report = JSON.parse(fs13.readFileSync(runFile, "utf8"));
   return (report.features ?? []).flatMap((f) => f.scenarios ?? []);
 }
 function endpointRefs(endpoint) {
@@ -22526,25 +22617,25 @@ async function importOpenApi(options) {
     list.push(item);
     groups.set(item.endpoint.tag, list);
   }
-  const outputDir = options.outputDir ?? path13.join("src", "content", "docs", "api");
-  if (fs12.existsSync(outputDir) && !options.force) {
-    const entries = fs12.readdirSync(outputDir);
+  const outputDir = options.outputDir ?? path14.join("src", "content", "docs", "api");
+  if (fs13.existsSync(outputDir) && !options.force) {
+    const entries = fs13.readdirSync(outputDir);
     if (entries.length > 0) {
       throw new Error(`Output directory "${outputDir}" is not empty. Use --force to overwrite.`);
     }
   }
-  fs12.mkdirSync(outputDir, { recursive: true });
+  fs13.mkdirSync(outputDir, { recursive: true });
   const coveredCount = coverage.filter((c) => c.status === "covered").length;
   const uncoveredCount = coverage.filter((c) => c.status === "uncovered").length;
-  fs12.writeFileSync(
-    path13.join(outputDir, "index.mdx"),
+  fs13.writeFileSync(
+    path14.join(outputDir, "index.mdx"),
     renderIndex(groups, hasRun, { endpointCount: endpoints.length, coveredCount, uncoveredCount }),
     "utf8"
   );
   for (const [tag, rows] of groups) {
-    const dir = path13.join(outputDir, slug(tag));
-    fs12.mkdirSync(dir, { recursive: true });
-    fs12.writeFileSync(path13.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
+    const dir = path14.join(outputDir, slug(tag));
+    fs13.mkdirSync(dir, { recursive: true });
+    fs13.writeFileSync(path14.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
   }
   return {
     outputDir,
@@ -22556,8 +22647,246 @@ async function importOpenApi(options) {
 }
 
 // src/build-docs.ts
-import * as fs13 from "fs";
-import * as path14 from "path";
+import * as fs15 from "fs";
+import * as path16 from "path";
+
+// src/scenario-links.ts
+function scenarioAnchor(title) {
+  return `scenario-${slugify(title)}`;
+}
+function buildScenarioLinks(report, options = {}) {
+  const audienceSplit = options.audienceSplit ?? false;
+  const baseUrl = (options.baseUrl ?? "/stories").replace(/\/$/, "");
+  const scenarios = {};
+  for (const feature of report.features) {
+    const stem = slugify(cleanTestStem(feature.sourceFile));
+    for (const scenario of feature.scenarios) {
+      const audience = deriveAudience(feature.sourceFile, scenario.tags);
+      const url = audienceSplit ? `${baseUrl}/${audience}/${stem}/` : `${baseUrl}/${stem}/`;
+      const anchor = scenarioAnchor(scenario.title);
+      scenarios[scenario.id] = {
+        id: scenario.id,
+        title: scenario.title,
+        audience,
+        status: scenario.status,
+        sourceFile: feature.sourceFile,
+        url,
+        anchor,
+        deepLink: `${url}#${anchor}`
+      };
+    }
+  }
+  return { schemaVersion: "1.0", runId: report.runId, baseUrl, scenarios };
+}
+
+// src/changes-page.ts
+var GROUPS = [
+  { kind: "regressed", heading: "Regressed", icon: "\u26A0\uFE0F" },
+  { kind: "removed", heading: "Removed", icon: "\u{1F5D1}\uFE0F" },
+  { kind: "added", heading: "Added", icon: "\u2728" },
+  { kind: "fixed", heading: "Fixed", icon: "\u2705" },
+  { kind: "changed", heading: "Changed", icon: "\u{1F501}" }
+];
+function yamlScalar2(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
+function badge(summary) {
+  if (summary.regressed > 0 || summary.removed > 0) return { text: "Regressed", variant: "danger" };
+  if (summary.added > 0 || summary.fixed > 0 || summary.changed > 0)
+    return { text: "Updated", variant: "tip" };
+  return { text: "No changes", variant: "note" };
+}
+function line(entry, links) {
+  const link2 = links.scenarios[entry.id];
+  const label = link2 ? `[${entry.title}](${link2.deepLink})` : entry.title;
+  const transition = entry.baselineStatus && entry.currentStatus && entry.baselineStatus !== entry.currentStatus ? ` \u2014 \`${entry.baselineStatus}\` \u2192 \`${entry.currentStatus}\`` : "";
+  return `- ${label} \`${entry.sourceFile}\`${transition}`;
+}
+function renderChangesPage(diff, links) {
+  const b = badge(diff.summary);
+  const { added, removed, regressed, fixed, changed } = diff.summary;
+  const totalChanged = added + removed + regressed + fixed + changed;
+  const frontmatter = [
+    "---",
+    "title: What's changed",
+    `description: ${yamlScalar2(
+      totalChanged === 0 ? "No behavioural changes since the baseline" : `${totalChanged} scenario${totalChanged !== 1 ? "s" : ""} changed since the baseline`
+    )}`,
+    "sidebar:",
+    "  order: 0",
+    "  badge:",
+    `    text: ${b.text}`,
+    `    variant: ${b.variant}`,
+    "---"
+  ].join("\n");
+  const body = [];
+  if (totalChanged === 0) {
+    body.push("No behavioural changes since the baseline run. \u2705");
+  } else {
+    body.push(
+      `**${regressed}** regressed \xB7 **${removed}** removed \xB7 **${added}** added \xB7 **${fixed}** fixed \xB7 **${changed}** changed`,
+      ""
+    );
+    for (const group of GROUPS) {
+      const entries = diff.scenarios.filter((s) => s.kind === group.kind);
+      if (entries.length === 0) continue;
+      body.push(`## ${group.icon} ${group.heading} (${entries.length})`, "");
+      for (const entry of entries) body.push(line(entry, links));
+      body.push("");
+    }
+  }
+  return `${frontmatter}
+
+${body.join("\n")}
+`;
+}
+
+// src/notes-index.ts
+import * as fs14 from "fs";
+import * as path15 from "path";
+import { slug as githubSlug } from "github-slugger";
+import { parse as parseYaml2 } from "yaml";
+function buildScenarioNotesIndex(notesDir) {
+  const entries = collectMarkdownFiles(notesDir).map((filePath) => readScenarioNote(filePath, notesDir)).filter((entry) => entry !== null).sort((a, b) => a.slug.localeCompare(b.slug));
+  return {
+    schemaVersion: "1.0",
+    notes: entries
+  };
+}
+function writeNotesIndex(index, outPath) {
+  fs14.mkdirSync(path15.dirname(outPath), { recursive: true });
+  fs14.writeFileSync(outPath, JSON.stringify(index, null, 2), "utf8");
+  return index;
+}
+function notesByScenarioId(index) {
+  const map = /* @__PURE__ */ new Map();
+  for (const note of index.notes) {
+    if (!map.has(note.scenarioId)) map.set(note.scenarioId, note);
+  }
+  return map;
+}
+function noteHref(note) {
+  return `/notes/${note.slug}/`;
+}
+function noteLinkMarkdown(note) {
+  return `[Business context \u2192](${noteHref(note)})`;
+}
+function readScenarioNote(filePath, notesDir) {
+  const relative5 = path15.relative(notesDir, filePath);
+  const stem = relative5.replace(/\.(?:md|mdx)$/u, "");
+  const frontmatter = parseFrontmatter(fs14.readFileSync(filePath, "utf8"));
+  const scenarioId = typeof frontmatter.scenarioId === "string" && frontmatter.scenarioId.trim().length > 0 ? frontmatter.scenarioId.trim() : path15.basename(stem);
+  const title = typeof frontmatter.title === "string" && frontmatter.title.trim().length > 0 ? frontmatter.title.trim() : `Business context \u2014 ${scenarioId}`;
+  return {
+    scenarioId,
+    slug: toRouteSlug(stem),
+    title
+  };
+}
+function parseFrontmatter(source) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(source);
+  if (!match) return {};
+  const parsed = parseYaml2(match[1]);
+  return parsed && typeof parsed === "object" ? parsed : {};
+}
+function toRouteSlug(stem) {
+  return stem.split(path15.sep).map((segment) => githubSlug(segment)).join("/").replace(/\/index$/u, "");
+}
+
+// src/overview-page.ts
+var AUDIENCE_CARDS = [
+  {
+    key: "engineer",
+    label: "Engineer",
+    icon: "\u{1F527}",
+    blurb: "Unit & integration behaviour \u2014 how the system works under the hood."
+  },
+  {
+    key: "stakeholder",
+    label: "Stakeholder",
+    icon: "\u{1F3AC}",
+    blurb: "End-to-end journeys \u2014 what the product does, with video and traces."
+  }
+];
+var STATUS_ICON = {
+  passed: "\u2705",
+  failed: "\u274C",
+  skipped: "\u23ED\uFE0F",
+  pending: "\u{1F6A7}"
+};
+function yamlScalar3(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
+function renderOverviewPage(links, notesIndex) {
+  const all = Object.values(links.scenarios);
+  const total = all.length;
+  const passed = all.filter((s) => s.status === "passed").length;
+  const failed = all.filter((s) => s.status === "failed").length;
+  const notesById = notesByScenarioId(notesIndex ?? { schemaVersion: "1.0", notes: [] });
+  const frontmatter = [
+    "---",
+    "title: Stories",
+    `description: ${yamlScalar3(
+      `${total} scenario${total !== 1 ? "s" : ""} \u2014 ${passed} passed, ${failed} failed`
+    )}`,
+    "sidebar:",
+    "  order: 1",
+    "---"
+  ].join("\n");
+  const body = [
+    `**${total}** scenarios \xB7 **${passed}** passed \xB7 **${failed}** failed`,
+    ""
+  ];
+  for (const card of AUDIENCE_CARDS) {
+    const scenarios = all.filter((s) => s.audience === card.key);
+    if (scenarios.length === 0) continue;
+    const cardPassed = scenarios.filter((s) => s.status === "passed").length;
+    const cardFailed = scenarios.filter((s) => s.status === "failed").length;
+    const counts = cardFailed > 0 ? `${cardPassed} passed, ${cardFailed} failed` : `${cardPassed} passed`;
+    body.push(`## ${card.icon} ${card.label} (${scenarios.length} \u2014 ${counts})`, "");
+    body.push(`${card.blurb}`, "");
+    for (const s of scenariosSorted(scenarios)) {
+      const note = notesById.get(s.id);
+      const noteSuffix = note ? ` \xB7 ${noteLinkMarkdown(note)}` : "";
+      body.push(`- ${STATUS_ICON[s.status] ?? "\u2022"} [${s.title}](${s.deepLink})${noteSuffix}`);
+    }
+    body.push("");
+  }
+  return `${frontmatter}
+
+${body.join("\n")}
+`;
+}
+function scenariosSorted(scenarios) {
+  return [...scenarios].sort((a, b) => {
+    const aFail = a.status === "failed" ? 0 : 1;
+    const bFail = b.status === "failed" ? 0 : 1;
+    if (aFail !== bFail) return aFail - bFail;
+    return a.title.localeCompare(b.title);
+  });
+}
+
+// src/build-docs.ts
+var AUDIENCES = ["engineer", "stakeholder"];
+function partitionByAudience(run) {
+  const buckets = {
+    engineer: [],
+    stakeholder: []
+  };
+  for (const tc of run.testCases) {
+    buckets[deriveAudience(tc.sourceFile, tc.tags)].push(tc);
+  }
+  return {
+    engineer: { ...run, testCases: buckets.engineer },
+    stakeholder: { ...run, testCases: buckets.stakeholder }
+  };
+}
 var BuildDocsError = class extends Error {
   constructor(message, kind) {
     super(message);
@@ -22567,22 +22896,22 @@ var BuildDocsError = class extends Error {
 };
 var isRemote = (p) => /^(?:https?:|data:)/i.test(p);
 function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets") {
-  if (!fs13.existsSync(reportPath)) return 0;
-  const report = JSON.parse(fs13.readFileSync(reportPath, "utf8"));
+  if (!fs15.existsSync(reportPath)) return 0;
+  const report = JSON.parse(fs15.readFileSync(reportPath, "utf8"));
   let copied = 0;
   const bundle = (value) => {
-    const rel = copyAsset(path14.resolve(value), assetsDir);
+    const rel = copyAsset(path16.resolve(value), assetsDir);
     copied++;
-    return `${baseUrl}/${path14.basename(rel)}`;
+    return `${baseUrl}/${path16.basename(rel)}`;
   };
   const visit = (entries) => {
     for (const entry of entries ?? []) {
       const e = entry;
       if (e.kind === "screenshot" || e.kind === "video" || e.kind === "html") {
-        if (typeof e.path === "string" && !isRemote(e.path) && fs13.existsSync(e.path)) {
+        if (typeof e.path === "string" && !isRemote(e.path) && fs15.existsSync(e.path)) {
           e.path = bundle(e.path);
         }
-        if (typeof e.poster === "string" && !isRemote(e.poster) && fs13.existsSync(e.poster)) {
+        if (typeof e.poster === "string" && !isRemote(e.poster) && fs15.existsSync(e.poster)) {
           e.poster = bundle(e.poster);
         }
       }
@@ -22595,25 +22924,78 @@ function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets"
     }
   }
   if (copied > 0) {
-    fs13.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf8");
+    fs15.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf8");
   }
   return copied;
 }
+var CHANGE_BADGE = {
+  added: "\u{1F195} **New** _since last run_",
+  fixed: "\u2705 **Fixed** _since last run_",
+  regressed: "\u26A0\uFE0F **Regressed** _since last run_"
+};
+function scenarioKey(sourceFile, title) {
+  return `${sourceFile}\0${title}`;
+}
+function changeBadgeLookup(diff) {
+  if (!diff) return void 0;
+  const byKey = /* @__PURE__ */ new Map();
+  for (const s of diff.scenarios) {
+    const badge2 = CHANGE_BADGE[s.kind];
+    if (badge2) byKey.set(scenarioKey(s.sourceFile, s.title), badge2);
+  }
+  if (byKey.size === 0) return void 0;
+  return (tc) => byKey.get(scenarioKey(tc.sourceFile, tc.story.scenario));
+}
+function readStoryReport(reportPath) {
+  if (!fs15.existsSync(reportPath)) return null;
+  try {
+    return JSON.parse(fs15.readFileSync(reportPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function noteLinkLookup(report, notesIndex) {
+  if (!report) return void 0;
+  const noteById = notesByScenarioId(notesIndex);
+  if (noteById.size === 0) return void 0;
+  const idByKey = /* @__PURE__ */ new Map();
+  for (const feature of report.features) {
+    for (const scenario of feature.scenarios) {
+      idByKey.set(scenarioKey(feature.sourceFile, scenario.title), scenario.id);
+    }
+  }
+  return (tc) => {
+    const id = idByKey.get(scenarioKey(tc.sourceFile, tc.story.scenario));
+    const note = id ? noteById.get(id) : void 0;
+    return note ? noteLinkMarkdown(note) : void 0;
+  };
+}
+function writeScenarioLinks(reportPath, outDir, options = {}) {
+  const report = readStoryReport(reportPath);
+  if (!report) return null;
+  const index = buildScenarioLinks(report, { audienceSplit: options.audienceSplit });
+  fs15.writeFileSync(
+    path16.join(outDir, "scenario-links.json"),
+    JSON.stringify(index, null, 2),
+    "utf8"
+  );
+  return index;
+}
 function clearGeneratedPages(dir) {
-  if (!fs13.existsSync(dir)) return;
-  for (const entry of fs13.readdirSync(dir, { withFileTypes: true })) {
-    const full = path14.join(dir, entry.name);
+  if (!fs15.existsSync(dir)) return;
+  for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
+    const full = path16.join(dir, entry.name);
     if (entry.isDirectory()) {
       clearGeneratedPages(full);
-      if (fs13.readdirSync(full).length === 0) fs13.rmdirSync(full);
+      if (fs15.readdirSync(full).length === 0) fs15.rmdirSync(full);
     } else if (/\.mdx?$/.test(entry.name)) {
-      fs13.rmSync(full);
+      fs15.rmSync(full);
     }
   }
 }
 function loadCanonicalRun(rawRunPath, synthesize) {
   try {
-    const data = JSON.parse(fs13.readFileSync(path14.resolve(rawRunPath), "utf8"));
+    const data = JSON.parse(fs15.readFileSync(path16.resolve(rawRunPath), "utf8"));
     if (data.schemaVersion !== 1) {
       throw new BuildDocsError(`Unsupported schemaVersion ${data.schemaVersion}. Supported: 1.`, "schema");
     }
@@ -22636,12 +23018,13 @@ ${schemaResult.errors.map((e) => `  ${e}`).join("\n")}`,
   }
 }
 async function buildDocs(options) {
-  const siteDir = path14.resolve(options.siteDir);
-  const storiesPublicDir = path14.join(siteDir, "public", "stories");
-  const assetsDir = path14.join(storiesPublicDir, "assets");
-  const storyPagesDir = path14.join(siteDir, "src", "content", "docs", "stories");
-  const apiDir = path14.join(siteDir, "src", "content", "docs", "api");
-  const reportPath = path14.join(storiesPublicDir, "story-report.json");
+  const siteDir = path16.resolve(options.siteDir);
+  const storiesPublicDir = path16.join(siteDir, "public", "stories");
+  const assetsDir = path16.join(storiesPublicDir, "assets");
+  const storyPagesDir = path16.join(siteDir, "src", "content", "docs", "stories");
+  const notesDir = path16.join(siteDir, "src", "content", "docs", "notes");
+  const apiDir = path16.join(siteDir, "src", "content", "docs", "api");
+  const reportPath = path16.join(storiesPublicDir, "story-report.json");
   const canonical = loadCanonicalRun(options.rawRunPath, options.synthesizeStories ?? true);
   try {
     await new ReportGenerator({
@@ -22649,27 +23032,88 @@ async function buildDocs(options) {
       outputDir: storiesPublicDir,
       outputName: "story-report"
     }).generate(canonical);
+    const currentReport = readStoryReport(reportPath);
+    let diff;
+    if (options.baselinePath) {
+      const baselineResolved = path16.resolve(options.baselinePath);
+      const baseline = readStoryReport(baselineResolved);
+      if (!baseline) {
+        throw new BuildDocsError(
+          `Baseline story-report not found or unreadable: ${baselineResolved}`,
+          "input"
+        );
+      }
+      if (currentReport) diff = diffStoryReports(baseline, currentReport);
+    }
+    const scenarioBadge = changeBadgeLookup(diff);
+    const notesIndex = buildScenarioNotesIndex(notesDir);
+    const scenarioNoteLink = noteLinkLookup(currentReport, notesIndex);
     clearGeneratedPages(storyPagesDir);
-    await new ReportGenerator({
+    const genPages = (run, outDir) => new ReportGenerator({
       formats: ["astro"],
-      outputDir: storyPagesDir,
+      outputDir: outDir,
       outputName: "index",
       output: { mode: "colocated", colocatedStyle: "flat" },
       assetMode: "copy",
-      astro: { assetsDir, assetsBaseUrl: "/stories/assets" }
-    }).generate(canonical);
+      astro: {
+        assetsDir,
+        assetsBaseUrl: "/stories/assets",
+        markdown: {
+          // Emit the same anchor scenario-links.json points at, so fragments resolve.
+          scenarioAnchor: (tc) => scenarioAnchor(tc.story.scenario),
+          scenarioBadge,
+          scenarioNoteLink
+        }
+      }
+    }).generate(run);
+    const audiences = { engineer: 0, stakeholder: 0 };
+    if (options.audienceSplit ?? false) {
+      const partitioned = partitionByAudience(canonical);
+      for (const audience of AUDIENCES) {
+        const sub = partitioned[audience];
+        audiences[audience] = sub.testCases.length;
+        if (sub.testCases.length === 0) continue;
+        await genPages(sub, path16.join(storyPagesDir, audience));
+      }
+    } else {
+      await genPages(canonical, storyPagesDir);
+    }
     const bundledAssets = bundleExplorerAssets(reportPath, assetsDir);
+    const linksIndex = writeScenarioLinks(reportPath, storiesPublicDir, {
+      audienceSplit: options.audienceSplit ?? false
+    });
+    const scenarioLinks = linksIndex ? Object.keys(linksIndex.scenarios).length : 0;
+    writeNotesIndex(notesIndex, path16.join(storiesPublicDir, "notes-index.json"));
+    const notesIndexed = notesIndex.notes.length;
+    if (linksIndex) {
+      fs15.writeFileSync(
+        path16.join(storyPagesDir, "index.md"),
+        renderOverviewPage(linksIndex, notesIndex),
+        "utf8"
+      );
+    }
+    const changesJsonPath = path16.join(storiesPublicDir, "changes.json");
+    const changesMdPath = path16.join(storyPagesDir, "changes.md");
+    let changes;
+    if (diff && linksIndex) {
+      fs15.writeFileSync(changesJsonPath, JSON.stringify(diff, null, 2), "utf8");
+      fs15.writeFileSync(changesMdPath, renderChangesPage(diff, linksIndex), "utf8");
+      changes = diff.summary;
+    } else {
+      fs15.rmSync(changesJsonPath, { force: true });
+      fs15.rmSync(changesMdPath, { force: true });
+    }
     let apiPages = 0;
     if (options.openapiPath) {
       const res = await importOpenApi({
-        specPath: path14.resolve(options.openapiPath),
+        specPath: path16.resolve(options.openapiPath),
         outputDir: apiDir,
         runFile: reportPath,
         force: true
       });
       apiPages = res.pageCount;
     }
-    return { siteDir, bundledAssets, apiPages };
+    return { siteDir, bundledAssets, apiPages, audiences, scenarioLinks, notesIndexed, changes };
   } catch (err) {
     if (err instanceof BuildDocsError) throw err;
     throw new BuildDocsError(`Generation failed: ${err.message}`, "generation");
@@ -22677,11 +23121,11 @@ async function buildDocs(options) {
 }
 
 // src/config.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import { resolve as resolve10 } from "path";
 async function loadConfig(configPath) {
   const resolved = configPath ? resolve10(configPath) : resolve10(process.cwd(), "executable-stories.config.js");
-  if (!existsSync12(resolved)) return {};
+  if (!existsSync13(resolved)) return {};
   const mod = await import(resolved);
   const config = mod.default;
   if (!config || typeof config !== "object" || Array.isArray(config)) {
@@ -22739,7 +23183,7 @@ SUBCOMMANDS
   triage             Discovery worklist for agent loops: failing scenarios, regressions first, each with the code it covers
   validate           Validate a JSON file against the schema (no output generated)
   init-astro         Scaffold an Astro docs site for story output (Starlight with themed CSS)
-  new                Scaffold a docs page from a template (adr, runbook, decision-log, incident)
+  new                Scaffold a docs page from a template (adr, runbook, decision-log, incident, scenario-note)
   check-links        Scan docs for broken internal/external links (CI-friendly exit code)
   import-openapi     Generate API doc pages from an OpenAPI spec, linked to verifying stories
   publish-confluence Publish an ADF JSON file to a Confluence page via REST API
@@ -23278,20 +23722,20 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path15.resolve(args.inputFile);
-  if (!fs14.existsSync(filePath)) {
+  const filePath = path17.resolve(args.inputFile);
+  if (!fs16.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
     process.exit(EXIT_USAGE);
   }
-  return fs14.readFileSync(filePath, "utf8");
+  return fs16.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path15.resolve(filePath);
-  if (!fs14.existsSync(resolved)) {
+  const resolved = path17.resolve(filePath);
+  if (!fs16.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
-  return fs14.readFileSync(resolved, "utf8");
+  return fs16.readFileSync(resolved, "utf8");
 }
 function readStdin() {
   return new Promise((resolve12, reject) => {
@@ -23424,14 +23868,14 @@ function tryNormalizeRunFromText(text2, args) {
   }
 }
 function listBaselineCandidates(currentFile, args) {
-  const baselineDir = path15.resolve(args.baselineDir ?? path15.dirname(currentFile));
-  const currentResolved = path15.resolve(currentFile);
-  if (!fs14.existsSync(baselineDir)) {
+  const baselineDir = path17.resolve(args.baselineDir ?? path17.dirname(currentFile));
+  const currentResolved = path17.resolve(currentFile);
+  if (!fs16.existsSync(baselineDir)) {
     console.error(`Error: baseline directory not found: ${baselineDir}`);
     process.exit(EXIT_USAGE);
   }
-  const entries = fs14.readdirSync(baselineDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile()).map((entry) => path15.join(baselineDir, entry.name)).filter((candidate) => path15.resolve(candidate) !== currentResolved).filter(
+  const entries = fs16.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path17.join(baselineDir, entry.name)).filter((candidate) => path17.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -23439,14 +23883,14 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   const candidates = listBaselineCandidates(currentFile, args);
   const comparable = [];
   for (const candidate of candidates) {
-    const run = tryNormalizeRunFromText(fs14.readFileSync(candidate, "utf8"), args);
+    const run = tryNormalizeRunFromText(fs16.readFileSync(candidate, "utf8"), args);
     if (run) {
       comparable.push({ file: candidate, run });
     }
   }
   if (comparable.length === 0) {
     console.error(
-      `Error: no compatible baseline files found in ${path15.resolve(args.baselineDir ?? path15.dirname(currentFile))}.`
+      `Error: no compatible baseline files found in ${path17.resolve(args.baselineDir ?? path17.dirname(currentFile))}.`
     );
     process.exit(EXIT_USAGE);
   }
@@ -23691,9 +24135,9 @@ async function main() {
       process.exit(EXIT_SCHEMA_VALIDATION);
     }
     if (args.emitCanonical) {
-      const outPath = path15.resolve(args.emitCanonical);
-      fs14.mkdirSync(path15.dirname(outPath), { recursive: true });
-      fs14.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path17.resolve(args.emitCanonical);
+      fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
+      fs16.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -23750,9 +24194,9 @@ ${msg}`);
     }
     const run = data;
     if (args.emitCanonical) {
-      const outPath = path15.resolve(args.emitCanonical);
-      fs14.mkdirSync(path15.dirname(outPath), { recursive: true });
-      fs14.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path17.resolve(args.emitCanonical);
+      fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
+      fs16.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -23808,9 +24252,9 @@ ${msg}`);
     process.exit(EXIT_CANONICAL_VALIDATION);
   }
   if (args.emitCanonical) {
-    const outPath = path15.resolve(args.emitCanonical);
-    fs14.mkdirSync(path15.dirname(outPath), { recursive: true });
-    fs14.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
+    const outPath = path17.resolve(args.emitCanonical);
+    fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
+    fs16.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
@@ -23835,9 +24279,9 @@ function runCustomFormatters(run, customRequested, formatters, args) {
       const ext = formatter.fileExtension ?? formatName;
       const baseName = args.outputName ?? "report";
       const filename = args.outputNameTimestamp ? `${baseName}-${Math.floor(run.startedAtMs / 1e3)}.${ext}` : `${baseName}.${ext}`;
-      const filepath = path15.join(outputDir, filename);
-      fs14.mkdirSync(outputDir, { recursive: true });
-      fs14.writeFileSync(filepath, content, "utf8");
+      const filepath = path17.join(outputDir, filename);
+      fs16.mkdirSync(outputDir, { recursive: true });
+      fs16.writeFileSync(filepath, content, "utf8");
       console.log(`Generated: ${filepath}`);
     } catch (err) {
       console.error(`Error running custom formatter "${formatName}": ${err instanceof Error ? err.message : String(err)}`);
@@ -23887,13 +24331,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return;
-  const historyPath = path15.resolve(args.historyFile);
+  const historyPath = path17.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs14.readFileSync(p, "utf8");
+          return fs16.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -23906,11 +24350,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path15.dirname(historyPath);
-  fs14.mkdirSync(dir, { recursive: true });
+  const dir = path17.dirname(historyPath);
+  fs16.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs14.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs16.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -24008,9 +24452,9 @@ function mapStatus(status) {
 function parseNameStatus(text2) {
   const files = [];
   for (const raw of text2.split("\n")) {
-    const line = raw.trim();
-    if (!line) continue;
-    const cols = line.includes("	") ? line.split("	") : line.split(/\s+/);
+    const line2 = raw.trim();
+    if (!line2) continue;
+    const cols = line2.includes("	") ? line2.split("	") : line2.split(/\s+/);
     const status = cols[0];
     if (!status) continue;
     const filePath = /^[RC]/i.test(status) && cols.length >= 3 ? cols[cols.length - 1] : cols[1];
@@ -24058,11 +24502,11 @@ function writeReviewReport(review, args) {
   const outputDir = args.outputDir ?? "reports";
   const baseName = args.outputName ?? "evidence-review";
   const suffix = args.outputNameTimestamp ? `-${Math.floor(review.run.startedAtMs / 1e3)}` : "";
-  fs14.mkdirSync(outputDir, { recursive: true });
-  const mdPath = path15.join(outputDir, `${baseName}${suffix}.md`);
-  const htmlPath = path15.join(outputDir, `${baseName}${suffix}.html`);
-  fs14.writeFileSync(mdPath, markdown, "utf8");
-  fs14.writeFileSync(htmlPath, html, "utf8");
+  fs16.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path17.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path17.join(outputDir, `${baseName}${suffix}.html`);
+  fs16.writeFileSync(mdPath, markdown, "utf8");
+  fs16.writeFileSync(htmlPath, html, "utf8");
   return [mdPath, htmlPath];
 }
 function evaluateReviewGate(review, args) {
@@ -24108,9 +24552,9 @@ function printResult(result, args, startMs, droppedMissingStory = 0) {
 function printCompareResult(result, args, startMs) {
   const durationMs = Date.now() - startMs;
   if (result.prSummary && args.prSummaryFile) {
-    const outputPath = path15.resolve(args.prSummaryFile);
-    fs14.mkdirSync(path15.dirname(outputPath), { recursive: true });
-    fs14.writeFileSync(outputPath, result.prSummary, "utf8");
+    const outputPath = path17.resolve(args.prSummaryFile);
+    fs16.mkdirSync(path17.dirname(outputPath), { recursive: true });
+    fs16.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -24139,13 +24583,13 @@ function printCompareResult(result, args, startMs) {
   }
 }
 function loadReleasePolicy(policyPath) {
-  const resolved = path15.resolve(policyPath);
-  if (!fs14.existsSync(resolved)) {
+  const resolved = path17.resolve(policyPath);
+  if (!fs16.existsSync(resolved)) {
     console.error(`Error: release policy file not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
   try {
-    const raw = JSON.parse(fs14.readFileSync(resolved, "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(resolved, "utf8"));
     return {
       allowedOmissions: Array.isArray(raw.allowedOmissions) ? raw.allowedOmissions : [],
       allowedRegressions: Array.isArray(raw.allowedRegressions) ? raw.allowedRegressions : [],
@@ -24249,7 +24693,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: missing ADF file argument. Run with --help for usage.");
     process.exit(EXIT_USAGE);
   }
-  if (!fs14.existsSync(inputFile)) {
+  if (!fs16.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -24277,7 +24721,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: --title is required when creating a new page");
     process.exit(EXIT_USAGE);
   }
-  const adf = fs14.readFileSync(path15.resolve(inputFile), "utf8");
+  const adf = fs16.readFileSync(path17.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -24356,7 +24800,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: missing ADF file argument. Run with --help for usage.");
     process.exit(EXIT_USAGE);
   }
-  if (!fs14.existsSync(inputFile)) {
+  if (!fs16.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -24383,7 +24827,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     process.exit(EXIT_USAGE);
   }
   const mode = modeRaw;
-  const adf = fs14.readFileSync(path15.resolve(inputFile), "utf8");
+  const adf = fs16.readFileSync(path17.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -24427,14 +24871,20 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
 function runNew(rawArgs) {
   const { values, positionals } = parseArgs({
     args: rawArgs,
-    options: { dir: { type: "string" }, force: { type: "boolean", default: false } },
+    options: {
+      dir: { type: "string" },
+      force: { type: "boolean", default: false },
+      "scenario-id": { type: "string" }
+    },
     allowPositionals: true,
     strict: true
   });
   const template = positionals[0];
   const name = positionals.slice(1).join(" ");
   if (!template) {
-    console.error(`Usage: executable-stories new <template> "<name>" [--dir <docs-dir>] [--force]`);
+    console.error(
+      `Usage: executable-stories new <template> "<name>" [--dir <docs-dir>] [--scenario-id <id>] [--force]`
+    );
     console.error(`Templates: ${TEMPLATES.join(", ")}`);
     return EXIT_USAGE;
   }
@@ -24442,6 +24892,7 @@ function runNew(rawArgs) {
     const result = scaffoldDoc({
       template,
       name,
+      scenarioId: values["scenario-id"],
       baseDir: values.dir,
       force: values.force
     });
@@ -24517,7 +24968,9 @@ async function runBuildDocs(rawArgs) {
     options: {
       "site-dir": { type: "string" },
       openapi: { type: "string" },
-      "no-synthesize-stories": { type: "boolean", default: false }
+      "no-synthesize-stories": { type: "boolean", default: false },
+      "audience-split": { type: "boolean", default: false },
+      baseline: { type: "string" }
     },
     allowPositionals: true,
     strict: true
@@ -24525,27 +24978,44 @@ async function runBuildDocs(rawArgs) {
   const rawRunPath = positionals[0];
   if (!rawRunPath) {
     console.error(
-      `Usage: executable-stories build-docs <raw-run.json> [--site-dir <dir>] [--openapi <spec>]`
+      `Usage: executable-stories build-docs <raw-run.json> [--site-dir <dir>] [--openapi <spec>] [--baseline <prev-story-report.json>] [--audience-split]`
     );
     return EXIT_USAGE;
   }
+  const audienceSplit = values["audience-split"];
   try {
     const result = await buildDocs({
       rawRunPath,
       siteDir: values["site-dir"] ?? ".",
       openapiPath: values.openapi,
-      synthesizeStories: !values["no-synthesize-stories"]
+      synthesizeStories: !values["no-synthesize-stories"],
+      audienceSplit,
+      baselinePath: values.baseline
     });
     console.log(`\u2713 Living docs generated in ${result.siteDir}`);
     console.log(`  \u2022 Explorer data   \u2192 public/stories/story-report.json`);
-    console.log(`  \u2022 Story pages     \u2192 src/content/docs/stories`);
+    console.log(`  \u2022 Deep links      \u2192 public/stories/scenario-links.json (${result.scenarioLinks})`);
+    console.log(`  \u2022 Note links      \u2192 public/stories/notes-index.json (${result.notesIndexed})`);
+    if (audienceSplit) {
+      console.log(
+        `  \u2022 Story pages     \u2192 src/content/docs/stories/{engineer,stakeholder} (engineer: ${result.audiences.engineer}, stakeholder: ${result.audiences.stakeholder})`
+      );
+    } else {
+      console.log(`  \u2022 Story pages     \u2192 src/content/docs/stories`);
+    }
     if (result.bundledAssets > 0) {
       console.log(`  \u2022 Bundled assets  \u2192 public/stories/assets (${result.bundledAssets})`);
     }
     if (result.apiPages > 0) {
       console.log(`  \u2022 API pages       \u2192 src/content/docs/api (${result.apiPages})`);
     }
-    const rel = path15.relative(process.cwd(), result.siteDir) || ".";
+    if (result.changes) {
+      const c = result.changes;
+      console.log(
+        `  \u2022 What's changed  \u2192 src/content/docs/stories/changes.md (+${c.added} added, ${c.regressed} regressed, ${c.fixed} fixed, ${c.removed} removed)`
+      );
+    }
+    const rel = path17.relative(process.cwd(), result.siteDir) || ".";
     console.log(`
 Preview: cd ${rel} && npm run dev`);
     return EXIT_SUCCESS;