executable-stories-formatters 0.14.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 };
 }
@@ -15864,7 +15864,8 @@ var MarkdownFormatter = class {
       includeSourceLinks: options.includeSourceLinks ?? true,
       customRenderers: options.customRenderers,
       scenarioAnchor: options.scenarioAnchor,
-      scenarioBadge: options.scenarioBadge
+      scenarioBadge: options.scenarioBadge,
+      scenarioNoteLink: options.scenarioNoteLink
     };
   }
   /**
@@ -16075,6 +16076,10 @@ var MarkdownFormatter = class {
     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})`);
@@ -16490,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("");
@@ -16599,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);
@@ -17212,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";
@@ -20747,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, "");
@@ -20862,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,
@@ -21727,7 +21732,8 @@ var ReportGenerator = class {
           traceUrlTemplate: options.astro?.markdown?.traceUrlTemplate,
           customRenderers: options.astro?.markdown?.customRenderers,
           scenarioAnchor: options.astro?.markdown?.scenarioAnchor,
-          scenarioBadge: options.astro?.markdown?.scenarioBadge
+          scenarioBadge: options.astro?.markdown?.scenarioBadge,
+          scenarioNoteLink: options.astro?.markdown?.scenarioNoteLink
         }
       },
       assetMode: options.assetMode ?? "none",
@@ -22064,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";
 }
@@ -22193,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_
 `
   }
 };
@@ -22211,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)
   };
@@ -22239,6 +22280,8 @@ function defaultName(template) {
       return "Decisions";
     case "incident":
       return "Untitled incident";
+    case "scenario-note":
+      return "Untitled scenario note";
   }
 }
 function titleFor2(template, ctx) {
@@ -22251,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, "");
@@ -22286,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();
@@ -22337,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") {
@@ -22403,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) {
@@ -22417,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 {
@@ -22450,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) {
@@ -22558,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,
@@ -22588,8 +22647,8 @@ 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) {
@@ -22685,6 +22744,58 @@ ${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 = [
   {
@@ -22712,11 +22823,12 @@ function yamlScalar3(value) {
   }
   return value;
 }
-function renderOverviewPage(links) {
+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",
@@ -22740,7 +22852,9 @@ function renderOverviewPage(links) {
     body.push(`## ${card.icon} ${card.label} (${scenarios.length} \u2014 ${counts})`, "");
     body.push(`${card.blurb}`, "");
     for (const s of scenariosSorted(scenarios)) {
-      body.push(`- ${STATUS_ICON[s.status] ?? "\u2022"} [${s.title}](${s.deepLink})`);
+      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("");
   }
@@ -22782,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);
         }
       }
@@ -22810,7 +22924,7 @@ 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;
 }
@@ -22819,50 +22933,69 @@ var CHANGE_BADGE = {
   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(`${s.sourceFile}\0${s.title}`, badge2);
+    if (badge2) byKey.set(scenarioKey(s.sourceFile, s.title), badge2);
   }
   if (byKey.size === 0) return void 0;
-  return (tc) => byKey.get(`${tc.sourceFile}\0${tc.story.scenario}`);
+  return (tc) => byKey.get(scenarioKey(tc.sourceFile, tc.story.scenario));
 }
 function readStoryReport(reportPath) {
-  if (!fs13.existsSync(reportPath)) return null;
+  if (!fs15.existsSync(reportPath)) return null;
   try {
-    return JSON.parse(fs13.readFileSync(reportPath, "utf8"));
+    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 });
-  fs13.writeFileSync(
-    path14.join(outDir, "scenario-links.json"),
+  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");
     }
@@ -22885,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({
@@ -22898,9 +23032,10 @@ async function buildDocs(options) {
       outputDir: storiesPublicDir,
       outputName: "story-report"
     }).generate(canonical);
+    const currentReport = readStoryReport(reportPath);
     let diff;
     if (options.baselinePath) {
-      const baselineResolved = path14.resolve(options.baselinePath);
+      const baselineResolved = path16.resolve(options.baselinePath);
       const baseline = readStoryReport(baselineResolved);
       if (!baseline) {
         throw new BuildDocsError(
@@ -22908,10 +23043,11 @@ async function buildDocs(options) {
           "input"
         );
       }
-      const current = readStoryReport(reportPath);
-      if (current) diff = diffStoryReports(baseline, current);
+      if (currentReport) diff = diffStoryReports(baseline, currentReport);
     }
     const scenarioBadge = changeBadgeLookup(diff);
+    const notesIndex = buildScenarioNotesIndex(notesDir);
+    const scenarioNoteLink = noteLinkLookup(currentReport, notesIndex);
     clearGeneratedPages(storyPagesDir);
     const genPages = (run, outDir) => new ReportGenerator({
       formats: ["astro"],
@@ -22925,7 +23061,8 @@ async function buildDocs(options) {
         markdown: {
           // Emit the same anchor scenario-links.json points at, so fragments resolve.
           scenarioAnchor: (tc) => scenarioAnchor(tc.story.scenario),
-          scenarioBadge
+          scenarioBadge,
+          scenarioNoteLink
         }
       }
     }).generate(run);
@@ -22936,7 +23073,7 @@ async function buildDocs(options) {
         const sub = partitioned[audience];
         audiences[audience] = sub.testCases.length;
         if (sub.testCases.length === 0) continue;
-        await genPages(sub, path14.join(storyPagesDir, audience));
+        await genPages(sub, path16.join(storyPagesDir, audience));
       }
     } else {
       await genPages(canonical, storyPagesDir);
@@ -22946,35 +23083,37 @@ async function buildDocs(options) {
       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) {
-      fs13.writeFileSync(
-        path14.join(storyPagesDir, "index.md"),
-        renderOverviewPage(linksIndex),
+      fs15.writeFileSync(
+        path16.join(storyPagesDir, "index.md"),
+        renderOverviewPage(linksIndex, notesIndex),
         "utf8"
       );
     }
-    const changesJsonPath = path14.join(storiesPublicDir, "changes.json");
-    const changesMdPath = path14.join(storyPagesDir, "changes.md");
+    const changesJsonPath = path16.join(storiesPublicDir, "changes.json");
+    const changesMdPath = path16.join(storyPagesDir, "changes.md");
     let changes;
     if (diff && linksIndex) {
-      fs13.writeFileSync(changesJsonPath, JSON.stringify(diff, null, 2), "utf8");
-      fs13.writeFileSync(changesMdPath, renderChangesPage(diff, linksIndex), "utf8");
+      fs15.writeFileSync(changesJsonPath, JSON.stringify(diff, null, 2), "utf8");
+      fs15.writeFileSync(changesMdPath, renderChangesPage(diff, linksIndex), "utf8");
       changes = diff.summary;
     } else {
-      fs13.rmSync(changesJsonPath, { force: true });
-      fs13.rmSync(changesMdPath, { force: true });
+      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, audiences, scenarioLinks, changes };
+    return { siteDir, bundledAssets, apiPages, audiences, scenarioLinks, notesIndexed, changes };
   } catch (err) {
     if (err instanceof BuildDocsError) throw err;
     throw new BuildDocsError(`Generation failed: ${err.message}`, "generation");
@@ -22982,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)) {
@@ -23044,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
@@ -23583,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) => {
@@ -23729,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")
   );
 }
@@ -23744,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);
   }
@@ -23996,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);
@@ -24055,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);
@@ -24113,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);
@@ -24140,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)}`);
@@ -24192,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;
         }
@@ -24211,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)) {
@@ -24363,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) {
@@ -24413,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(
@@ -24444,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 : [],
@@ -24554,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);
   }
@@ -24582,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(
@@ -24661,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);
   }
@@ -24688,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(
@@ -24732,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;
   }
@@ -24747,6 +24892,7 @@ function runNew(rawArgs) {
     const result = scaffoldDoc({
       template,
       name,
+      scenarioId: values["scenario-id"],
       baseDir: values.dir,
       force: values.force
     });
@@ -24849,6 +24995,7 @@ async function runBuildDocs(rawArgs) {
     console.log(`\u2713 Living docs generated in ${result.siteDir}`);
     console.log(`  \u2022 Explorer data   \u2192 public/stories/story-report.json`);
     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})`
@@ -24868,7 +25015,7 @@ async function runBuildDocs(rawArgs) {
         `  \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 = path15.relative(process.cwd(), result.siteDir) || ".";
+    const rel = path17.relative(process.cwd(), result.siteDir) || ".";
     console.log(`
 Preview: cd ${rel} && npm run dev`);
     return EXIT_SUCCESS;