executable-stories-formatters 0.15.1 → 0.17.0

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import * as fs16 from "fs";
-import * as path17 from "path";
+import * as fs17 from "fs";
+import * as path18 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 path18 = err.instancePath || "/";
+    const path19 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path18}: ${message} \u2014 '${extra}'`;
+      return `${path19}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path18}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path19}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path18}: ${message}`;
+    return `${path19}: ${message}`;
   });
   return { valid: false, errors };
 }
@@ -702,6 +702,41 @@ function generateFeatureId(uri) {
 function generateScenarioId(featureId, scenarioName) {
   return `${featureId};${slugify(scenarioName)}`;
 }
+function normalizeText(text2) {
+  return text2.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
+}
+function tokenize(text2) {
+  const normalized = normalizeText(text2);
+  return normalized.length === 0 ? [] : normalized.split(" ");
+}
+function behaviourFingerprint(input) {
+  const steps = input.steps.map((step) => `${step.keyword.toLowerCase()}:${normalizeText(step.text)}`).join("\n");
+  const covers = [...input.covers ?? []].map((path19) => path19.trim()).filter(Boolean).sort().join(",");
+  if (steps.length === 0 && covers.length === 0) return "";
+  return createHash("sha1").update(`${steps}\0${covers}`).digest("hex").slice(0, 16);
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const value of a) if (b.has(value)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
+function stepTokens(steps) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    for (const token of tokenize(step.text)) tokens.add(token);
+  }
+  return tokens;
+}
+function behaviourSimilarity(a, b) {
+  const aSteps = stepTokens(a.steps);
+  const bSteps = stepTokens(b.steps);
+  if (aSteps.size === 0 || bSteps.size === 0) return 0;
+  const stepScore = jaccard(aSteps, bSteps);
+  const titleScore = jaccard(new Set(tokenize(a.scenario)), new Set(tokenize(b.scenario)));
+  return stepScore * 0.7 + titleScore * 0.3;
+}
 
 // src/converters/acl/steps.ts
 function deriveStepResults(steps, scenarioStatus, error) {
@@ -1073,7 +1108,7 @@ ${result.errors.join("\n")}`);
 
 // src/index.ts
 import "fs";
-import * as path9 from "path";
+import * as path10 from "path";
 import * as fsPromises from "fs/promises";
 
 // src/converters/acl/lines.ts
@@ -14977,12 +15012,12 @@ function highlightStepParams(text2, deps) {
 var MIN_METRIC_SAMPLES = 5;
 
 // src/formatters/html/renderers/scenario.ts
-function renderTicket(ticket, template, escapeHtml4) {
+function renderTicket(ticket, template, escapeHtml5) {
   const url = ticket.url ?? (template ? template.replace("{ticket}", ticket.id) : void 0);
   if (url) {
-    return `<a class="tag ticket-tag" href="${escapeHtml4(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml4(ticket.id)}</a>`;
+    return `<a class="tag ticket-tag" href="${escapeHtml5(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml5(ticket.id)}</a>`;
   }
-  return `<span class="tag ticket-tag">${escapeHtml4(ticket.id)}</span>`;
+  return `<span class="tag ticket-tag">${escapeHtml5(ticket.id)}</span>`;
 }
 function renderScenario(args, deps) {
   const { tc } = args;
@@ -15182,7 +15217,7 @@ function flattenTree(roots) {
   }
   return result;
 }
-function buildTooltip(span, escapeHtml4) {
+function buildTooltip(span, escapeHtml5) {
   const parts = [];
   parts.push(`${span.name} (${formatDuration(span.durationMs)})`);
   if (span.statusMessage) {
@@ -15200,7 +15235,7 @@ function buildTooltip(span, escapeHtml4) {
   if (text2.length > TOOLTIP_MAX_LENGTH) {
     text2 = text2.slice(0, TOOLTIP_MAX_LENGTH - 3) + "...";
   }
-  return escapeHtml4(text2);
+  return escapeHtml5(text2);
 }
 function renderTraceView(args, deps) {
   if (!args.spans || args.spans.length === 0) return "";
@@ -16495,14 +16530,14 @@ var TraceabilityMatrixFormatter = class {
       lines.push("");
       lines.push(`Status: ${renderRequirementStatus(req.status)}`);
       if (req.covers.length > 0) {
-        lines.push(`Covers: ${req.covers.map((path18) => `\`${path18}\``).join(", ")}`);
+        lines.push(`Covers: ${req.covers.map((path19) => `\`${path19}\``).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((path18) => `\`${path18}\``).join(", ") : "";
+        const covers = scenario.covers.length > 0 ? scenario.covers.map((path19) => `\`${path19}\``).join(", ") : "";
         lines.push(`| ${scenario.status} | ${escapePipe2(scenario.title)} | \`${source}\` | ${covers} |`);
       }
       lines.push("");
@@ -16604,8 +16639,8 @@ function extractFeatureName(testCases, uri) {
       return tc.titlePath[0];
     }
   }
-  const basename5 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
-  return basename5.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const basename6 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
+  return basename6.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function synthesizeFeature(uri, testCases) {
   const featureName = extractFeatureName(testCases, uri);
@@ -17217,8 +17252,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path18) {
-  const lower = path18.toLowerCase();
+function guessMediaType(path19) {
+  const lower = path19.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";
@@ -17359,11 +17394,11 @@ var CucumberHtmlFormatter = class {
     for (const envelope of envelopes) {
       const accepted = htmlStream.write(envelope);
       if (!accepted) {
-        await new Promise((resolve12) => htmlStream.once("drain", resolve12));
+        await new Promise((resolve13) => htmlStream.once("drain", resolve13));
       }
     }
-    await new Promise((resolve12, reject) => {
-      collector.on("finish", resolve12);
+    await new Promise((resolve13, reject) => {
+      collector.on("finish", resolve13);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -17401,6 +17436,10 @@ function titleFor(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -17449,6 +17488,8 @@ function createPrCommentSummary(diff, maxScenarios = 10) {
   addSection(lines, diff, "fixed", maxScenarios);
   addSection(lines, diff, "added", maxScenarios);
   addSection(lines, diff, "removed", maxScenarios);
+  addSection(lines, diff, "renamed", maxScenarios);
+  addSection(lines, diff, "moved", maxScenarios);
   addSection(lines, diff, "changed", maxScenarios);
   return lines.join("\n").trimEnd();
 }
@@ -17525,8 +17566,10 @@ function sortDiffs(scenarios) {
     fixed: 1,
     added: 2,
     removed: 3,
-    changed: 4,
-    unchanged: 5
+    renamed: 4,
+    moved: 5,
+    changed: 6,
+    unchanged: 7
   };
   return [...scenarios].sort((a, b) => {
     if (rank[a.kind] !== rank[b.kind]) {
@@ -17541,69 +17584,108 @@ function sortDiffs(scenarios) {
     return a.scenario.localeCompare(b.scenario);
   });
 }
+var SIMILARITY_THRESHOLD = 0.75;
+function identityInput(tc) {
+  return {
+    scenario: tc.story.scenario,
+    sourceFile: tc.sourceFile,
+    steps: tc.story.steps,
+    covers: tc.story.covers
+  };
+}
+function changedFieldsOf(flags) {
+  return Object.entries(flags).filter(([, changed]) => changed).map(([field]) => field);
+}
+function allChangedFlags(errorMessage) {
+  return {
+    status: true,
+    steps: true,
+    docs: true,
+    tags: true,
+    tickets: true,
+    source: true,
+    duration: true,
+    attachments: true,
+    error: Boolean(errorMessage),
+    titlePath: true
+  };
+}
+function matchIdentities(removed, added) {
+  const pairs = [];
+  const remainingRemoved = new Set(removed);
+  const remainingAdded = new Set(added);
+  const removedByFp = /* @__PURE__ */ new Map();
+  const addedByFp = /* @__PURE__ */ new Map();
+  for (const tc of remainingRemoved) {
+    const fp = behaviourFingerprint(identityInput(tc));
+    if (fp === "") continue;
+    (removedByFp.get(fp) ?? removedByFp.set(fp, []).get(fp)).push(tc);
+  }
+  for (const tc of remainingAdded) {
+    const fp = behaviourFingerprint(identityInput(tc));
+    if (fp === "") continue;
+    (addedByFp.get(fp) ?? addedByFp.set(fp, []).get(fp)).push(tc);
+  }
+  for (const [fp, removedGroup] of removedByFp) {
+    const addedGroup = addedByFp.get(fp);
+    if (removedGroup.length === 1 && addedGroup && addedGroup.length === 1) {
+      pairs.push({ before: removedGroup[0], after: addedGroup[0], confidence: 1, matchedBy: "fingerprint" });
+      remainingRemoved.delete(removedGroup[0]);
+      remainingAdded.delete(addedGroup[0]);
+    }
+  }
+  for (const before of [...remainingRemoved]) {
+    let best;
+    let bestScore = 0;
+    let tied = false;
+    for (const after of remainingAdded) {
+      const score = behaviourSimilarity(identityInput(before), identityInput(after));
+      if (score > bestScore) {
+        bestScore = score;
+        best = after;
+        tied = false;
+      } else if (score === bestScore) {
+        tied = true;
+      }
+    }
+    if (best && !tied && bestScore >= SIMILARITY_THRESHOLD) {
+      pairs.push({ before, after: best, confidence: Math.round(bestScore * 100) / 100, matchedBy: "similarity" });
+      remainingRemoved.delete(before);
+      remainingAdded.delete(best);
+    }
+  }
+  return {
+    pairs,
+    unmatchedRemoved: [...remainingRemoved],
+    unmatchedAdded: [...remainingAdded]
+  };
+}
+function identityKind(before, after) {
+  const titleChanged = before.story.scenario !== after.story.scenario;
+  const fileChanged = before.sourceFile !== after.sourceFile;
+  return fileChanged && !titleChanged ? "moved" : "renamed";
+}
 function diffRuns(baseline, current) {
   const baselineById = new Map(baseline.testCases.map((tc) => [tc.id, tc]));
   const currentById = new Map(current.testCases.map((tc) => [tc.id, tc]));
   const ids = /* @__PURE__ */ new Set([...baselineById.keys(), ...currentById.keys()]);
   const scenarios = [];
+  const removedCases = [];
+  const addedCases = [];
   for (const id of ids) {
     const before = baselineById.get(id);
     const after = currentById.get(id);
     if (!before && after) {
-      const flags2 = {
-        status: true,
-        steps: true,
-        docs: true,
-        tags: true,
-        tickets: true,
-        source: true,
-        duration: true,
-        attachments: true,
-        error: Boolean(after.errorMessage),
-        titlePath: true
-      };
-      scenarios.push({
-        kind: "added",
-        id,
-        scenario: after.story.scenario,
-        sourceFile: after.sourceFile,
-        sourceLine: after.sourceLine,
-        current: toScenarioSnapshot(after),
-        flags: flags2,
-        changedFields: Object.entries(flags2).filter(([, changed]) => changed).map(([field]) => field)
-      });
+      addedCases.push(after);
       continue;
     }
     if (before && !after) {
-      const flags2 = {
-        status: true,
-        steps: true,
-        docs: true,
-        tags: true,
-        tickets: true,
-        source: true,
-        duration: true,
-        attachments: true,
-        error: Boolean(before.errorMessage),
-        titlePath: true
-      };
-      scenarios.push({
-        kind: "removed",
-        id,
-        scenario: before.story.scenario,
-        sourceFile: before.sourceFile,
-        sourceLine: before.sourceLine,
-        baseline: toScenarioSnapshot(before),
-        flags: flags2,
-        changedFields: Object.entries(flags2).filter(([, changed]) => changed).map(([field]) => field)
-      });
-      continue;
-    }
-    if (!before || !after) {
+      removedCases.push(before);
       continue;
     }
+    if (!before || !after) continue;
     const flags = buildFlags(before, after);
-    const changedFields = Object.entries(flags).filter(([, changed]) => changed).map(([field]) => field);
+    const changedFields = changedFieldsOf(flags);
     const kind = getPrimaryKind(before, after, changedFields.length > 0);
     scenarios.push({
       kind,
@@ -17618,12 +17700,59 @@ function diffRuns(baseline, current) {
       durationDeltaMs: after.durationMs - before.durationMs
     });
   }
+  const { pairs, unmatchedRemoved, unmatchedAdded } = matchIdentities(removedCases, addedCases);
+  for (const { before, after, confidence, matchedBy } of pairs) {
+    const flags = buildFlags(before, after);
+    scenarios.push({
+      kind: identityKind(before, after),
+      id: after.id,
+      previousId: before.id,
+      scenario: after.story.scenario,
+      sourceFile: after.sourceFile,
+      sourceLine: after.sourceLine,
+      baseline: toScenarioSnapshot(before),
+      current: toScenarioSnapshot(after),
+      flags,
+      changedFields: changedFieldsOf(flags),
+      durationDeltaMs: after.durationMs - before.durationMs,
+      matchConfidence: confidence,
+      matchedBy
+    });
+  }
+  for (const after of unmatchedAdded) {
+    const flags = allChangedFlags(after.errorMessage);
+    scenarios.push({
+      kind: "added",
+      id: after.id,
+      scenario: after.story.scenario,
+      sourceFile: after.sourceFile,
+      sourceLine: after.sourceLine,
+      current: toScenarioSnapshot(after),
+      flags,
+      changedFields: changedFieldsOf(flags)
+    });
+  }
+  for (const before of unmatchedRemoved) {
+    const flags = allChangedFlags(before.errorMessage);
+    scenarios.push({
+      kind: "removed",
+      id: before.id,
+      scenario: before.story.scenario,
+      sourceFile: before.sourceFile,
+      sourceLine: before.sourceLine,
+      baseline: toScenarioSnapshot(before),
+      flags,
+      changedFields: changedFieldsOf(flags)
+    });
+  }
   const sorted = sortDiffs(scenarios);
   const summary = {
     totalBaseline: baseline.testCases.length,
     totalCurrent: current.testCases.length,
     added: sorted.filter((s) => s.kind === "added").length,
     removed: sorted.filter((s) => s.kind === "removed").length,
+    renamed: sorted.filter((s) => s.kind === "renamed").length,
+    moved: sorted.filter((s) => s.kind === "moved").length,
     changed: sorted.filter((s) => s.kind === "changed").length,
     regressed: sorted.filter((s) => s.kind === "regressed").length,
     fixed: sorted.filter((s) => s.kind === "fixed").length,
@@ -17651,6 +17780,10 @@ function statusLabel(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -17976,6 +18109,8 @@ window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', fun
         <div class="summary-card"><strong>${diff.summary.fixed}</strong><span>Fixed</span></div>
         <div class="summary-card"><strong>${diff.summary.added}</strong><span>Added</span></div>
         <div class="summary-card"><strong>${diff.summary.removed}</strong><span>Removed</span></div>
+        <div class="summary-card"><strong>${diff.summary.renamed}</strong><span>Renamed</span></div>
+        <div class="summary-card"><strong>${diff.summary.moved}</strong><span>Moved</span></div>
         <div class="summary-card"><strong>${diff.summary.changed}</strong><span>Changed</span></div>
         <div class="summary-card"><strong>${diff.summary.unchanged}</strong><span>Unchanged</span></div>
       </section>
@@ -18036,6 +18171,10 @@ function formatStatus(kind) {
       return "Added";
     case "removed":
       return "Removed";
+    case "renamed":
+      return "Renamed";
+    case "moved":
+      return "Moved";
     case "changed":
       return "Changed";
     default:
@@ -18188,13 +18327,13 @@ var RunDiffMarkdownFormatter = class {
       lines.push("No regressions or fixes detected. Remaining changes are neutral.");
     }
     lines.push("");
-    lines.push("| Added | Removed | Regressed | Fixed | Changed | Unchanged |");
-    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: |");
+    lines.push("| Added | Removed | Renamed | Moved | Regressed | Fixed | Changed | Unchanged |");
+    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
     lines.push(
-      `| ${diff.summary.added} | ${diff.summary.removed} | ${diff.summary.regressed} | ${diff.summary.fixed} | ${diff.summary.changed} | ${diff.summary.unchanged} |`
+      `| ${diff.summary.added} | ${diff.summary.removed} | ${diff.summary.renamed} | ${diff.summary.moved} | ${diff.summary.regressed} | ${diff.summary.fixed} | ${diff.summary.changed} | ${diff.summary.unchanged} |`
     );
     lines.push("");
-    for (const kind of ["regressed", "fixed", "added", "removed", "changed"]) {
+    for (const kind of ["regressed", "fixed", "added", "removed", "renamed", "moved", "changed"]) {
       const scenarios = diff.scenarios.filter((scenario) => scenario.kind === kind);
       if (scenarios.length === 0) continue;
       lines.push(`## ${formatStatus(kind)} (${scenarios.length})`);
@@ -19053,7 +19192,7 @@ function toRun(data, inputType, synthesize) {
   if (synthesize) raw = synthesizeStories(raw);
   return canonicalizeRun(raw);
 }
-async function regenerateArtifacts(options, deps = {}) {
+async function regenerateRun(options, deps = {}) {
   const read = deps.readFile ?? ((filePath) => fs6.readFileSync(filePath, "utf8"));
   const data = JSON.parse(read(path7.resolve(options.input)));
   const run = toRun(data, options.inputType ?? "raw", options.synthesize !== false);
@@ -19063,7 +19202,10 @@ async function regenerateArtifacts(options, deps = {}) {
     outputName: options.outputName
   });
   const result = await generator.generate(run);
-  return [...result.values()].flat();
+  return { files: [...result.values()].flat(), run };
+}
+async function regenerateArtifacts(options, deps = {}) {
+  return (await regenerateRun(options, deps)).files;
 }
 function startWatch(options, deps = {}) {
   const log = deps.log ?? ((message) => console.log(message));
@@ -19106,6 +19248,203 @@ function startWatch(options, deps = {}) {
   };
 }
 
+// src/serve.ts
+import * as fs7 from "fs";
+import * as http from "http";
+import * as path8 from "path";
+function advanceState(prev, run) {
+  if (prev.sessionBaseline === null) {
+    return { sessionBaseline: run, previous: null, current: run, runCount: 1 };
+  }
+  return {
+    sessionBaseline: prev.sessionBaseline,
+    previous: prev.current,
+    current: run,
+    runCount: prev.runCount + 1
+  };
+}
+function computeDeltas(state) {
+  if (state.current === null || state.sessionBaseline === null || state.runCount <= 1) {
+    return { session: null, iteration: null };
+  }
+  return {
+    session: diffRuns(state.sessionBaseline, state.current),
+    iteration: state.previous ? diffRuns(state.previous, state.current) : null
+  };
+}
+function pluralize(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function summarizeDiff(diff) {
+  const s = diff.summary;
+  const parts = [];
+  if (s.fixed > 0) parts.push(`+${pluralize(s.fixed, "passing")}`);
+  if (s.regressed > 0) parts.push(`${pluralize(s.regressed, "regressed")}`);
+  if (s.added > 0) parts.push(`${pluralize(s.added, "new behaviour")}`);
+  if (s.removed > 0) parts.push(`${pluralize(s.removed, "removed")}`);
+  const moved = s.renamed + s.moved;
+  if (moved > 0) parts.push(`${pluralize(moved, "renamed")}`);
+  if (s.changed > 0) parts.push(`${pluralize(s.changed, "changed")}`);
+  return parts.length > 0 ? parts.join(", ") : null;
+}
+function escapeHtml3(text2) {
+  return text2.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderDeltaStrip(state) {
+  if (state.current === null) return "";
+  const { session, iteration } = computeDeltas(state);
+  if (session === null) {
+    const label = `Run #${state.runCount} captured \u2014 baseline pinned. Watching for changes\u2026`;
+    return `<div data-es-live="strip"><strong>Live</strong> \xB7 ${escapeHtml3(label)}</div>`;
+  }
+  const sessionLine = summarizeDiff(session) ?? "no change yet";
+  let detail = "";
+  if (iteration) {
+    const iterationLine = summarizeDiff(iteration);
+    if (iterationLine) detail = ` \xB7 <span data-es-live="iteration">this iteration: ${escapeHtml3(iterationLine)}</span>`;
+  }
+  return [
+    `<div data-es-live="strip">`,
+    `<strong>Live</strong> \xB7 run #${state.runCount} \xB7 `,
+    `<span data-es-live="session">since you started: ${escapeHtml3(sessionLine)}</span>`,
+    detail,
+    `</div>`
+  ].join("");
+}
+var RELOAD_CLIENT = `<script data-es-live="client">
+(function () {
+  try {
+    var es = new EventSource("/__es_reload");
+    es.onmessage = function (e) { if (e.data === "reload") location.reload(); };
+  } catch (err) { /* SSE unavailable: stay static */ }
+})();
+</script>`;
+var STRIP_STYLE = `<style data-es-live="style">
+[data-es-live="strip"]{position:sticky;top:0;z-index:9999;font:14px/1.5 system-ui,sans-serif;
+padding:8px 16px;background:#0b1021;color:#e6e9f5;border-bottom:1px solid #2a3052}
+[data-es-live="strip"] strong{color:#7dd3fc}
+</style>`;
+function injectLiveBits(html, stripHtml) {
+  let out = html;
+  const bodyOpen = out.match(/<body[^>]*>/i);
+  if (bodyOpen) {
+    const at = bodyOpen.index + bodyOpen[0].length;
+    out = out.slice(0, at) + stripHtml + out.slice(at);
+  } else {
+    out = stripHtml + out;
+  }
+  const tail = STRIP_STYLE + RELOAD_CLIENT;
+  if (/<\/body>/i.test(out)) {
+    out = out.replace(/<\/body>/i, tail + "</body>");
+  } else {
+    out += tail;
+  }
+  return out;
+}
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png"
+};
+function watchInputDir(filePath, listener) {
+  const dir = path8.dirname(filePath);
+  const base = path8.basename(filePath);
+  fs7.mkdirSync(dir, { recursive: true });
+  const watcher = fs7.watch(dir, (_event, changed) => {
+    if (!changed || changed === base) listener();
+  });
+  return { close: () => watcher.close() };
+}
+function plainText(html) {
+  return html.replace(/<[^>]+>/g, "").trim();
+}
+function startServe(options, deps = {}) {
+  const log = deps.log ?? ((message) => console.log(message));
+  const read = deps.readFile ?? ((filePath) => fs7.readFileSync(filePath, "utf8"));
+  const port = options.port ?? 4321;
+  const host = options.host ?? "127.0.0.1";
+  let state = { sessionBaseline: null, previous: null, current: null, runCount: 0 };
+  let htmlPath = null;
+  let stripHtml = renderDeltaStrip(state);
+  const clients = /* @__PURE__ */ new Set();
+  const pushReload = () => {
+    for (const res of clients) res.write("data: reload\n\n");
+  };
+  const handler = (req, res) => {
+    const url = (req.url ?? "/").split("?")[0];
+    if (url === "/__es_reload") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive"
+      });
+      res.write("retry: 1000\n\n");
+      clients.add(res);
+      req.on("close", () => clients.delete(res));
+      return;
+    }
+    if (url === "/" || url === "/index.html") {
+      const html = htmlPath ? read(htmlPath) : "<!doctype html><html><body><h1>executable-stories</h1></body></html>";
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(injectLiveBits(html, stripHtml));
+      return;
+    }
+    const safe = path8.normalize(url).replace(/^(\.\.[/\\])+/, "");
+    const filePath = path8.join(path8.resolve(options.outputDir), safe);
+    if (filePath.startsWith(path8.resolve(options.outputDir)) && fs7.existsSync(filePath)) {
+      const ext = path8.extname(filePath).toLowerCase();
+      res.writeHead(200, { "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream" });
+      res.end(read(filePath));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  };
+  const server = deps.createServer ? deps.createServer(handler) : http.createServer(handler);
+  const watchOptions = {
+    input: options.input,
+    outputDir: options.outputDir,
+    outputName: options.outputName,
+    formats: options.formats,
+    inputType: options.inputType ?? "raw",
+    synthesize: options.synthesize !== false,
+    debounceMs: options.debounceMs
+  };
+  const watchHandle = startWatch(watchOptions, {
+    readFile: read,
+    watch: deps.watch ?? watchInputDir,
+    log: () => {
+    },
+    // serve emits its own per-run line below
+    regenerate: async (input) => {
+      if (!fs7.existsSync(path8.resolve(input))) return [];
+      const { files, run } = await regenerateRun({ ...watchOptions, input }, { readFile: read });
+      htmlPath = files.find((f) => f.endsWith(".html")) ?? htmlPath;
+      state = advanceState(state, run);
+      stripHtml = renderDeltaStrip(state);
+      log(`Run #${state.runCount}: ${plainText(stripHtml)}`);
+      pushReload();
+      return files;
+    }
+  });
+  server.listen(port, host);
+  const address = server.address();
+  const boundPort = typeof address === "object" && address ? address.port : port;
+  log(`Live docs: http://${host}:${boundPort} (Ctrl+C to stop)`);
+  return {
+    port: boundPort,
+    close: () => {
+      watchHandle.close();
+      for (const res of clients) res.end();
+      clients.clear();
+      server.close();
+    }
+  };
+}
+
 // src/behavior-diff.ts
 function classifyStatusChange(baseline, current) {
   if (baseline === void 0) return "added";
@@ -19143,7 +19482,10 @@ function diffStoryReports(baseline, current) {
     };
   });
   const summary = { added: 0, removed: 0, regressed: 0, fixed: 0, changed: 0, unchanged: 0 };
-  for (const s of scenarios) summary[s.kind] += 1;
+  for (const s of scenarios) {
+    if (s.kind === "renamed" || s.kind === "moved") continue;
+    summary[s.kind] += 1;
+  }
   return { schemaVersion: "1.0", summary, scenarios };
 }
 
@@ -20752,18 +21094,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path18) {
-  const base = path18.split("/").pop() ?? path18;
+function extensionOf(path19) {
+  const base = path19.split("/").pop() ?? path19;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path18) {
-  return TEST_INFIX.test(path18);
+function isTestFile(path19) {
+  return TEST_INFIX.test(path19);
 }
-function isReviewableSource(path18) {
-  if (isTestFile(path18)) return false;
-  if (path18.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path18));
+function isReviewableSource(path19) {
+  if (isTestFile(path19)) return false;
+  if (path19.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path19));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -20867,7 +21209,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path18) => sourceBaseKey(path18) === key
+    (path19) => sourceBaseKey(path19) === key
   );
   return {
     id: testCase.id,
@@ -21116,7 +21458,7 @@ var ReviewMarkdownFormatter = class {
 };
 
 // src/formatters/review-html.ts
-function escapeHtml3(value) {
+function escapeHtml4(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 var STRENGTH_LABEL = {
@@ -21138,22 +21480,22 @@ function statusIcon3(status) {
   }
 }
 function formatStep3(step) {
-  return `<li><strong>${escapeHtml3(step.keyword)}</strong> ${escapeHtml3(step.text)}</li>`;
+  return `<li><strong>${escapeHtml4(step.keyword)}</strong> ${escapeHtml4(step.text)}</li>`;
 }
 function inlineDoc(doc) {
   switch (doc.kind) {
     case "note":
-      return escapeHtml3(doc.text);
+      return escapeHtml4(doc.text);
     case "section":
-      return `<strong>${escapeHtml3(doc.title)}</strong>: ${escapeHtml3(doc.markdown)}`;
+      return `<strong>${escapeHtml4(doc.title)}</strong>: ${escapeHtml4(doc.markdown)}`;
     case "kv":
-      return `${escapeHtml3(doc.label)}: ${escapeHtml3(String(doc.value))}`;
+      return `${escapeHtml4(doc.label)}: ${escapeHtml4(String(doc.value))}`;
     case "code":
-      return `${escapeHtml3(doc.label)}: <code>${escapeHtml3(doc.content)}</code>`;
+      return `${escapeHtml4(doc.label)}: <code>${escapeHtml4(doc.content)}</code>`;
     case "link":
-      return `${escapeHtml3(doc.label)}: ${escapeHtml3(doc.url)}`;
+      return `${escapeHtml4(doc.label)}: ${escapeHtml4(doc.url)}`;
     default:
-      return escapeHtml3(doc.kind);
+      return escapeHtml4(doc.kind);
   }
 }
 function renderEvidenceArtifacts(testCase) {
@@ -21161,7 +21503,7 @@ function renderEvidenceArtifacts(testCase) {
   for (const att of testCase.attachments) {
     if (att.mediaType.startsWith("image/") && att.contentEncoding === "BASE64") {
       parts.push(
-        `<img class="shot" alt="${escapeHtml3(att.name)}" src="data:${escapeHtml3(att.mediaType)};base64,${att.body}" />`
+        `<img class="shot" alt="${escapeHtml4(att.name)}" src="data:${escapeHtml4(att.mediaType)};base64,${att.body}" />`
       );
     }
   }
@@ -21176,22 +21518,22 @@ function renderTicketPills(claim) {
   const tickets = claim.testCase.story.tickets ?? [];
   if (tickets.length === 0) return "";
   return `<div class="ticket-row">${tickets.map((ticket) => {
-    const label = escapeHtml3(ticket.id);
+    const label = escapeHtml4(ticket.id);
     if (ticket.url) {
-      return `<a class="ticket-pill" href="${escapeHtml3(ticket.url)}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+      return `<a class="ticket-pill" href="${escapeHtml4(ticket.url)}" target="_blank" rel="noopener noreferrer">${label}</a>`;
     }
     return `<span class="ticket-pill">${label}</span>`;
   }).join("")}</div>`;
 }
 function renderClaimCard(claim) {
   const ticketSearch = (claim.testCase.story.tickets ?? []).map((ticket) => ticket.id).join(" ");
-  const search = escapeHtml3(
+  const search = escapeHtml4(
     `${claim.scenario} ${claim.sourceFile} ${claim.changeType} ${claim.audience} ${claim.strength} ${ticketSearch}`
   ).toLowerCase();
   const steps = claim.testCase.story.steps.length > 0 ? `<ul class="step-list">${claim.testCase.story.steps.map(formatStep3).join("")}</ul>` : "";
-  const reasons = `<ul class="reasons">${claim.strengthReasons.map((r) => `<li>${escapeHtml3(r)}</li>`).join("")}</ul>`;
-  const intent = claim.intent !== void 0 ? `<div class="intent"><span class="intent-label">Why</span> ${escapeHtml3(claim.intent)}</div>` : "";
-  const covers = claim.coversFiles.length > 0 ? `<p class="covers">Covers ${claim.coversFiles.map((f) => `<code>${escapeHtml3(f)}</code>`).join(", ")}</p>` : "";
+  const reasons = `<ul class="reasons">${claim.strengthReasons.map((r) => `<li>${escapeHtml4(r)}</li>`).join("")}</ul>`;
+  const intent = claim.intent !== void 0 ? `<div class="intent"><span class="intent-label">Why</span> ${escapeHtml4(claim.intent)}</div>` : "";
+  const covers = claim.coversFiles.length > 0 ? `<p class="covers">Covers ${claim.coversFiles.map((f) => `<code>${escapeHtml4(f)}</code>`).join(", ")}</p>` : "";
   const docs = (claim.testCase.story.docs ?? []).filter(
     (d) => d.kind === "section" || d.kind === "note"
   );
@@ -21201,9 +21543,9 @@ function renderClaimCard(claim) {
       <header class="claim-header">
         <div>
           <span class="strength-badge strength-${claim.strength}">${STRENGTH_LABEL[claim.strength]}</span>
-          ${claim.changeType !== "unknown" ? `<span class="change-pill">${escapeHtml3(claim.changeType)}</span>` : ""}
-          <h3>${statusIcon3(claim.status)} ${escapeHtml3(claim.scenario)}</h3>
-          <p class="source">${escapeHtml3(`${claim.sourceFile}:${claim.sourceLine}`)}</p>
+          ${claim.changeType !== "unknown" ? `<span class="change-pill">${escapeHtml4(claim.changeType)}</span>` : ""}
+          <h3>${statusIcon3(claim.status)} ${escapeHtml4(claim.scenario)}</h3>
+          <p class="source">${escapeHtml4(`${claim.sourceFile}:${claim.sourceLine}`)}</p>
           ${renderTicketPills(claim)}
         </div>
       </header>
@@ -21218,18 +21560,18 @@ function renderClaimCard(claim) {
     </article>`;
 }
 function renderChangedFileRow(file) {
-  const claims = file.claims.length > 0 ? file.claims.map((c) => `${escapeHtml3(c.scenario)} <em>(${c.strength})</em>`).join(", ") : "\u2014";
+  const claims = file.claims.length > 0 ? file.claims.map((c) => `${escapeHtml4(c.scenario)} <em>(${c.strength})</em>`).join(", ") : "\u2014";
   return `<tr data-band="${file.band}">
     <td><span class="band-dot band-${file.band}"></span></td>
-    <td><code>${escapeHtml3(file.path)}</code></td>
-    <td>${escapeHtml3(file.changeKind)}</td>
+    <td><code>${escapeHtml4(file.path)}</code></td>
+    <td>${escapeHtml4(file.changeKind)}</td>
     <td>${claims}</td>
   </tr>`;
 }
 function renderAudienceSection2(title, claims) {
   if (claims.length === 0) return "";
   return `<section class="audience-section">
-    <h2>${escapeHtml3(title)} <span class="count">${claims.length}</span></h2>
+    <h2>${escapeHtml4(title)} <span class="count">${claims.length}</span></h2>
     <div class="claim-list">${claims.map(renderClaimCard).join("\n")}</div>
   </section>`;
 }
@@ -21319,13 +21661,13 @@ var ReviewHtmlFormatter = class {
     const themeInitJs = this.darkMode ? `${JS_THEME_TOGGLE2}
 applyTheme(getEffectiveTheme());` : "";
     const themeAttr = this.darkMode ? ' data-theme="light"' : "";
-    const refsLine = context.baseRef || context.headRef ? `<p class="subtle">Comparing ${escapeHtml3(context.baseRef ?? "base")} \u2192 ${escapeHtml3(context.headRef ?? "head")}</p>` : "";
+    const refsLine = context.baseRef || context.headRef ? `<p class="subtle">Comparing ${escapeHtml4(context.baseRef ?? "base")} \u2192 ${escapeHtml4(context.headRef ?? "head")}</p>` : "";
     return `<!doctype html>
 <html lang="en"${themeAttr}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml3(this.title)}</title>
+    <title>${escapeHtml4(this.title)}</title>
     <style>
       ${this.theme.css}
       ${REVIEW_CSS}
@@ -21335,7 +21677,7 @@ applyTheme(getEffectiveTheme());` : "";
     <main>
       <div class="hero-card card">
         <div class="review-header">
-          <h1>${escapeHtml3(this.title)}</h1>
+          <h1>${escapeHtml4(this.title)}</h1>
           ${themeToggleHtml}
         </div>
         ${refsLine}
@@ -21350,7 +21692,7 @@ applyTheme(getEffectiveTheme());` : "";
       </section>
       <section class="card priority-banner">
         <h2>Review priority</h2>
-        <p class="subtle">${escapeHtml3(priority)}</p>
+        <p class="subtle">${escapeHtml4(priority)}</p>
       </section>
       ${changedFilesPanel}
       <section class="toolbar">
@@ -21398,8 +21740,8 @@ applyTheme(getEffectiveTheme());` : "";
 };
 
 // src/deploy/ledger.ts
-import * as fs7 from "fs";
-import * as path8 from "path";
+import * as fs8 from "fs";
+import * as path9 from "path";
 function createEmptyLedger() {
   return {
     deployments: [],
@@ -21407,12 +21749,12 @@ function createEmptyLedger() {
   };
 }
 function loadLedger(ledgerPath) {
-  const resolved = path8.resolve(ledgerPath);
-  if (!fs7.existsSync(resolved)) {
+  const resolved = path9.resolve(ledgerPath);
+  if (!fs8.existsSync(resolved)) {
     return createEmptyLedger();
   }
   try {
-    const raw = JSON.parse(fs7.readFileSync(resolved, "utf8"));
+    const raw = JSON.parse(fs8.readFileSync(resolved, "utf8"));
     if (raw.schemaVersion !== 1) {
       throw new Error(`Unsupported ledger schemaVersion: ${raw.schemaVersion}`);
     }
@@ -21423,10 +21765,10 @@ function loadLedger(ledgerPath) {
   }
 }
 function saveLedger(ledger, ledgerPath) {
-  const resolved = path8.resolve(ledgerPath);
-  const dir = path8.dirname(resolved);
-  fs7.mkdirSync(dir, { recursive: true });
-  fs7.writeFileSync(resolved, JSON.stringify(ledger, null, 2), "utf8");
+  const resolved = path9.resolve(ledgerPath);
+  const dir = path9.dirname(resolved);
+  fs8.mkdirSync(dir, { recursive: true });
+  fs8.writeFileSync(resolved, JSON.stringify(ledger, null, 2), "utf8");
 }
 function getLatestDeployment(ledger, environment) {
   return [...ledger.deployments].reverse().find((d) => d.environment === environment);
@@ -21546,11 +21888,11 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   const ext = FORMAT_EXTENSIONS[format];
   const effectiveName = outputName + (outputNameSuffix ?? "");
   if (mode === "aggregated") {
-    return toPosix(path9.join(baseOutputDir, joinNameAndExt(effectiveName, ext)));
+    return toPosix(path10.join(baseOutputDir, joinNameAndExt(effectiveName, ext)));
   }
   const normalizedSource = toPosix(sourceFile);
-  const dirOfSource = path9.posix.dirname(normalizedSource);
-  let baseName = path9.posix.basename(normalizedSource);
+  const dirOfSource = path10.posix.dirname(normalizedSource);
+  let baseName = path10.posix.basename(normalizedSource);
   for (const testExt of TEST_EXTENSIONS) {
     if (baseName.endsWith(testExt)) {
       baseName = baseName.slice(0, -testExt.length);
@@ -21559,12 +21901,12 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   }
   const fileName = `${baseName}.${effectiveName}${ext}`;
   if (colocatedStyle === "adjacent") {
-    return toPosix(path9.posix.join(dirOfSource, fileName));
+    return toPosix(path10.posix.join(dirOfSource, fileName));
   }
   if (colocatedStyle === "flat") {
-    return toPosix(path9.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
+    return toPosix(path10.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
   }
-  return toPosix(path9.posix.join(baseOutputDir, dirOfSource, fileName));
+  return toPosix(path10.posix.join(baseOutputDir, dirOfSource, fileName));
 }
 function groupTestCasesByOutput(testCases, format, options, logger, outputNameSuffix) {
   const groups = /* @__PURE__ */ new Map();
@@ -21777,8 +22119,8 @@ var ReportGenerator = class {
       if (astroPaths) {
         for (const mdPath of astroPaths) {
           const content = await fsPromises.readFile(mdPath, "utf8");
-          const mdDir = path9.dirname(mdPath);
-          const assetsDir = path9.resolve(this.options.astro.assetsDir);
+          const mdDir = path10.dirname(mdPath);
+          const assetsDir = path10.resolve(this.options.astro.assetsDir);
           const result = copyMarkdownAssets({
             markdown: content,
             markdownDir: mdDir,
@@ -21809,9 +22151,9 @@ var ReportGenerator = class {
     if (groups.size === 0 && this.options.output.mode === "aggregated") {
       const ext = FORMAT_EXTENSIONS[format];
       const effectiveName = this.options.outputName + (outputNameSuffix ?? "");
-      const outputPath = toPosix(path9.join(this.options.outputDir, joinNameAndExt(effectiveName, ext)));
+      const outputPath = toPosix(path10.join(this.options.outputDir, joinNameAndExt(effectiveName, ext)));
       const content = await this.formatContent(run, format);
-      const dir = path9.dirname(outputPath);
+      const dir = path10.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       return [outputPath];
@@ -21823,7 +22165,7 @@ var ReportGenerator = class {
         testCases
       };
       const content = await this.formatContent(groupRun, format);
-      const dir = path9.dirname(outputPath);
+      const dir = path10.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       writtenPaths.push(outputPath);
@@ -21972,7 +22314,7 @@ async function generateRunComparison(args) {
   await fsPromises.mkdir(outputDir, { recursive: true });
   for (const format of args.formats) {
     const ext = format === "html" ? ".html" : ".md";
-    const outputPath = toPosix(path9.join(outputDir, `${outputName}${ext}`));
+    const outputPath = toPosix(path10.join(outputDir, `${outputName}${ext}`));
     const content = format === "html" ? new RunDiffHtmlFormatter({ title: args.title }).format(diff) : new RunDiffMarkdownFormatter({ title: args.title }).format(diff);
     await fsPromises.writeFile(outputPath, content, "utf8");
     files.push(outputPath);
@@ -21981,21 +22323,21 @@ async function generateRunComparison(args) {
 }
 
 // src/init-astro.ts
-import * as fs9 from "fs";
-import * as path10 from "path";
+import * as fs10 from "fs";
+import * as path11 from "path";
 import { fileURLToPath } from "url";
-var __dirname = path10.dirname(fileURLToPath(import.meta.url));
+var __dirname = path11.dirname(fileURLToPath(import.meta.url));
 var FRAMEWORK_DIRS = ["src/components", "src/lib", "src/styles", "src/pages"];
 var FRAMEWORK_FILES = ["tsconfig.json"];
 function isScaffoldedAstroSite(dir) {
-  return fs9.existsSync(path10.join(dir, "astro.config.mjs"));
+  return fs10.existsSync(path11.join(dir, "astro.config.mjs"));
 }
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
   const update = options.update ?? false;
-  const templateDir = path10.resolve(__dirname, "..", "templates", "astro-starlight");
-  if (!fs9.existsSync(templateDir)) {
+  const templateDir = path11.resolve(__dirname, "..", "templates", "astro-starlight");
+  if (!fs10.existsSync(templateDir)) {
     throw new Error(
       `Template directory not found at ${templateDir}. Ensure the package is installed correctly.`
     );
@@ -22003,8 +22345,8 @@ function initAstro(options = {}) {
   if (update) {
     return updateFrameworkFiles(templateDir, targetDir);
   }
-  if (fs9.existsSync(targetDir)) {
-    const entries = fs9.readdirSync(targetDir);
+  if (fs10.existsSync(targetDir)) {
+    const entries = fs10.readdirSync(targetDir);
     if (entries.length > 0 && !force) {
       throw new Error(
         `Directory "${targetDir}" already exists and is not empty. Use --force to overwrite, or --update to refresh framework files only.`
@@ -22022,25 +22364,25 @@ function updateFrameworkFiles(templateDir, targetDir) {
   }
   const updated = [];
   for (const dir of FRAMEWORK_DIRS) {
-    const src = path10.join(templateDir, dir);
-    if (!fs9.existsSync(src)) continue;
-    copyDirRecursive(src, path10.join(targetDir, dir), (rel) => updated.push(path10.join(dir, rel)));
+    const src = path11.join(templateDir, dir);
+    if (!fs10.existsSync(src)) continue;
+    copyDirRecursive(src, path11.join(targetDir, dir), (rel) => updated.push(path11.join(dir, rel)));
   }
   for (const file of FRAMEWORK_FILES) {
-    const src = path10.join(templateDir, file);
-    if (!fs9.existsSync(src)) continue;
-    fs9.copyFileSync(src, path10.join(targetDir, file));
+    const src = path11.join(templateDir, file);
+    if (!fs10.existsSync(src)) continue;
+    fs10.copyFileSync(src, path11.join(targetDir, file));
     updated.push(file);
   }
   if (mergeDependencies(templateDir, targetDir)) updated.push("package.json (deps)");
   return { targetDir, updatedFiles: updated };
 }
 function mergeDependencies(templateDir, targetDir) {
-  const tmplPkgPath = path10.join(templateDir, "package.json");
-  const userPkgPath = path10.join(targetDir, "package.json");
-  if (!fs9.existsSync(tmplPkgPath) || !fs9.existsSync(userPkgPath)) return false;
-  const tmpl = JSON.parse(fs9.readFileSync(tmplPkgPath, "utf8"));
-  const user = JSON.parse(fs9.readFileSync(userPkgPath, "utf8"));
+  const tmplPkgPath = path11.join(templateDir, "package.json");
+  const userPkgPath = path11.join(targetDir, "package.json");
+  if (!fs10.existsSync(tmplPkgPath) || !fs10.existsSync(userPkgPath)) return false;
+  const tmpl = JSON.parse(fs10.readFileSync(tmplPkgPath, "utf8"));
+  const user = JSON.parse(fs10.readFileSync(userPkgPath, "utf8"));
   user.dependencies = user.dependencies ?? {};
   let changed = false;
   for (const [name, version] of Object.entries(tmpl.dependencies ?? {})) {
@@ -22050,30 +22392,30 @@ function mergeDependencies(templateDir, targetDir) {
     }
   }
   if (changed) {
-    fs9.writeFileSync(userPkgPath, `${JSON.stringify(user, null, 2)}
+    fs10.writeFileSync(userPkgPath, `${JSON.stringify(user, null, 2)}
 `, "utf8");
   }
   return changed;
 }
 function copyDirRecursive(src, dest, onFile, baseSrc = src) {
-  fs9.mkdirSync(dest, { recursive: true });
-  const entries = fs9.readdirSync(src, { withFileTypes: true });
+  fs10.mkdirSync(dest, { recursive: true });
+  const entries = fs10.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path10.join(src, entry.name);
+    const srcPath = path11.join(src, entry.name);
     const destName = entry.name === "gitignore" ? ".gitignore" : entry.name;
-    const destPath = path10.join(dest, destName);
+    const destPath = path11.join(dest, destName);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath, onFile, baseSrc);
     } else {
-      fs9.copyFileSync(srcPath, destPath);
-      onFile?.(path10.relative(baseSrc, srcPath));
+      fs10.copyFileSync(srcPath, destPath);
+      onFile?.(path11.relative(baseSrc, srcPath));
     }
   }
 }
 
 // src/scaffold-doc.ts
-import * as fs10 from "fs";
-import * as path11 from "path";
+import * as fs11 from "fs";
+import * as path12 from "path";
 var TEMPLATES = [
   "adr",
   "runbook",
@@ -22090,7 +22432,7 @@ function isoDate(today) {
 function nextSeq(dir) {
   let max = 0;
   try {
-    for (const entry of fs10.readdirSync(dir)) {
+    for (const entry of fs11.readdirSync(dir)) {
       const match = /^(\d{1,4})-/.exec(entry);
       if (match) max = Math.max(max, Number.parseInt(match[1], 10));
     }
@@ -22247,12 +22589,12 @@ function scaffoldDoc(options) {
     );
   }
   const spec = TEMPLATE_SPECS[template];
-  const baseDir = options.baseDir ?? path11.join("src", "content", "docs");
+  const baseDir = options.baseDir ?? path12.join("src", "content", "docs");
   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);
+  const dir = path12.join(baseDir, spec.subdir);
   if (template === "scenario-note" && !scenarioId) {
     throw new Error(`Template "scenario-note" requires --scenario-id.`);
   }
@@ -22264,14 +22606,14 @@ function scaffoldDoc(options) {
     seq: nextSeq(dir)
   };
   const filename = `${spec.filename(slug2, ctx)}.mdx`;
-  const filePath = path11.join(dir, filename);
-  if (fs10.existsSync(filePath) && !options.force) {
+  const filePath = path12.join(dir, filename);
+  if (fs11.existsSync(filePath) && !options.force) {
     throw new Error(
       `File "${filePath}" already exists. Use --force to overwrite.`
     );
   }
-  fs10.mkdirSync(dir, { recursive: true });
-  fs10.writeFileSync(filePath, spec.content(ctx), "utf8");
+  fs11.mkdirSync(dir, { recursive: true });
+  fs11.writeFileSync(filePath, spec.content(ctx), "utf8");
   return { template, path: filePath, title: titleFor2(template, ctx) };
 }
 function defaultName(template) {
@@ -22312,20 +22654,20 @@ function normalizeScenarioId(input) {
 }
 
 // src/check-links.ts
-import * as fs12 from "fs";
-import * as path13 from "path";
+import * as fs13 from "fs";
+import * as path14 from "path";
 
 // src/utils/markdown-files.ts
-import * as fs11 from "fs";
-import * as path12 from "path";
+import * as fs12 from "fs";
+import * as path13 from "path";
 function collectMarkdownFiles(target) {
-  if (!fs11.existsSync(target)) return [];
-  if (fs11.statSync(target).isFile()) return [target];
+  if (!fs12.existsSync(target)) return [];
+  if (fs12.statSync(target).isFile()) return [target];
   const out = [];
   const walk = (dir) => {
-    for (const entry of fs11.readdirSync(dir, { withFileTypes: true })) {
+    for (const entry of fs12.readdirSync(dir, { withFileTypes: true })) {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-      const full = path12.join(dir, entry.name);
+      const full = path13.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (/\.mdx?$/u.test(entry.name)) out.push(full);
     }
@@ -22364,17 +22706,17 @@ function classifyLink(link2) {
 function resolutionCandidates(fromFile, link2) {
   const withoutAnchor = link2.split("#")[0];
   if (!withoutAnchor) return [];
-  const base = path13.resolve(path13.dirname(fromFile), withoutAnchor);
+  const base = path14.resolve(path14.dirname(fromFile), withoutAnchor);
   const candidates = [base];
-  if (!path13.extname(base)) {
+  if (!path14.extname(base)) {
     candidates.push(`${base}.md`, `${base}.mdx`);
-    candidates.push(path13.join(base, "index.md"), path13.join(base, "index.mdx"));
+    candidates.push(path14.join(base, "index.md"), path14.join(base, "index.mdx"));
   }
   return candidates;
 }
 function resolvesOnDisk(fromFile, link2) {
   return resolutionCandidates(fromFile, link2).some(
-    (candidate) => fs12.existsSync(candidate) && fs12.statSync(candidate).isFile()
+    (candidate) => fs13.existsSync(candidate) && fs13.statSync(candidate).isFile()
   );
 }
 async function isExternalAlive(url, timeoutMs) {
@@ -22400,7 +22742,7 @@ async function isExternalAlive(url, timeoutMs) {
 }
 async function checkLinks(options) {
   const { target, checkExternal = false, externalTimeoutMs = 8e3 } = options;
-  if (!fs12.existsSync(target)) {
+  if (!fs13.existsSync(target)) {
     throw new Error(`Path not found: ${target}`);
   }
   const files = collectMarkdownFiles(target);
@@ -22410,7 +22752,7 @@ async function checkLinks(options) {
   let skipped = 0;
   const externalCache = /* @__PURE__ */ new Map();
   for (const file of files) {
-    const content = fs12.readFileSync(file, "utf8");
+    const content = fs13.readFileSync(file, "utf8");
     for (const link2 of extractLinks(content)) {
       const kind = classifyLink(link2);
       if (kind === "anchor" || kind === "mail" || kind === "root") {
@@ -22466,8 +22808,8 @@ function formatLinkReport(report) {
 }
 
 // src/import-openapi.ts
-import * as fs13 from "fs";
-import * as path14 from "path";
+import * as fs14 from "fs";
+import * as path15 from "path";
 import { parse as parseYamlString } from "yaml";
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
 function parseYaml(raw, specPath) {
@@ -22480,9 +22822,9 @@ function parseYaml(raw, specPath) {
   }
 }
 function parseSpec(specPath) {
-  if (!fs13.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
-  const raw = fs13.readFileSync(specPath, "utf8");
-  const ext = path14.extname(specPath).toLowerCase();
+  if (!fs14.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
+  const raw = fs14.readFileSync(specPath, "utf8");
+  const ext = path15.extname(specPath).toLowerCase();
   if (ext === ".json") return JSON.parse(raw);
   if (ext === ".yaml" || ext === ".yml") return parseYaml(raw, specPath);
   try {
@@ -22513,8 +22855,8 @@ function extractEndpoints(spec) {
 }
 function loadScenarios(runFile) {
   if (!runFile) return [];
-  if (!fs13.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
-  const report = JSON.parse(fs13.readFileSync(runFile, "utf8"));
+  if (!fs14.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
+  const report = JSON.parse(fs14.readFileSync(runFile, "utf8"));
   return (report.features ?? []).flatMap((f) => f.scenarios ?? []);
 }
 function endpointRefs(endpoint) {
@@ -22621,25 +22963,25 @@ async function importOpenApi(options) {
     list.push(item);
     groups.set(item.endpoint.tag, list);
   }
-  const outputDir = options.outputDir ?? path14.join("src", "content", "docs", "api");
-  if (fs13.existsSync(outputDir) && !options.force) {
-    const entries = fs13.readdirSync(outputDir);
+  const outputDir = options.outputDir ?? path15.join("src", "content", "docs", "api");
+  if (fs14.existsSync(outputDir) && !options.force) {
+    const entries = fs14.readdirSync(outputDir);
     if (entries.length > 0) {
       throw new Error(`Output directory "${outputDir}" is not empty. Use --force to overwrite.`);
     }
   }
-  fs13.mkdirSync(outputDir, { recursive: true });
+  fs14.mkdirSync(outputDir, { recursive: true });
   const coveredCount = coverage.filter((c) => c.status === "covered").length;
   const uncoveredCount = coverage.filter((c) => c.status === "uncovered").length;
-  fs13.writeFileSync(
-    path14.join(outputDir, "index.mdx"),
+  fs14.writeFileSync(
+    path15.join(outputDir, "index.mdx"),
     renderIndex(groups, hasRun, { endpointCount: endpoints.length, coveredCount, uncoveredCount }),
     "utf8"
   );
   for (const [tag, rows] of groups) {
-    const dir = path14.join(outputDir, slug(tag));
-    fs13.mkdirSync(dir, { recursive: true });
-    fs13.writeFileSync(path14.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
+    const dir = path15.join(outputDir, slug(tag));
+    fs14.mkdirSync(dir, { recursive: true });
+    fs14.writeFileSync(path15.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
   }
   return {
     outputDir,
@@ -22651,8 +22993,8 @@ async function importOpenApi(options) {
 }
 
 // src/build-docs.ts
-import * as fs15 from "fs";
-import * as path16 from "path";
+import * as fs16 from "fs";
+import * as path17 from "path";
 
 // src/scenario-links.ts
 function scenarioAnchor(title) {
@@ -22749,8 +23091,8 @@ ${body.join("\n")}
 }
 
 // src/notes-index.ts
-import * as fs14 from "fs";
-import * as path15 from "path";
+import * as fs15 from "fs";
+import * as path16 from "path";
 import { slug as githubSlug } from "github-slugger";
 import { parse as parseYaml2 } from "yaml";
 function buildScenarioNotesIndex(notesDir) {
@@ -22761,8 +23103,8 @@ function buildScenarioNotesIndex(notesDir) {
   };
 }
 function writeNotesIndex(index, outPath) {
-  fs14.mkdirSync(path15.dirname(outPath), { recursive: true });
-  fs14.writeFileSync(outPath, JSON.stringify(index, null, 2), "utf8");
+  fs15.mkdirSync(path16.dirname(outPath), { recursive: true });
+  fs15.writeFileSync(outPath, JSON.stringify(index, null, 2), "utf8");
   return index;
 }
 function notesByScenarioId(index) {
@@ -22779,10 +23121,10 @@ function noteLinkMarkdown(note) {
   return `[Business context \u2192](${noteHref(note)})`;
 }
 function readScenarioNote(filePath, notesDir) {
-  const relative5 = path15.relative(notesDir, filePath);
+  const relative5 = path16.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 frontmatter = parseFrontmatter(fs15.readFileSync(filePath, "utf8"));
+  const scenarioId = typeof frontmatter.scenarioId === "string" && frontmatter.scenarioId.trim().length > 0 ? frontmatter.scenarioId.trim() : path16.basename(stem);
   const title = typeof frontmatter.title === "string" && frontmatter.title.trim().length > 0 ? frontmatter.title.trim() : `Business context \u2014 ${scenarioId}`;
   return {
     scenarioId,
@@ -22797,7 +23139,7 @@ function parseFrontmatter(source) {
   return parsed && typeof parsed === "object" ? parsed : {};
 }
 function toRouteSlug(stem) {
-  return stem.split(path15.sep).map((segment) => githubSlug(segment)).join("/").replace(/\/index$/u, "");
+  return stem.split(path16.sep).map((segment) => githubSlug(segment)).join("/").replace(/\/index$/u, "");
 }
 
 // src/overview-page.ts
@@ -22900,22 +23242,22 @@ var BuildDocsError = class extends Error {
 };
 var isRemote = (p) => /^(?:https?:|data:)/i.test(p);
 function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets") {
-  if (!fs15.existsSync(reportPath)) return 0;
-  const report = JSON.parse(fs15.readFileSync(reportPath, "utf8"));
+  if (!fs16.existsSync(reportPath)) return 0;
+  const report = JSON.parse(fs16.readFileSync(reportPath, "utf8"));
   let copied = 0;
   const bundle = (value) => {
-    const rel = copyAsset(path16.resolve(value), assetsDir);
+    const rel = copyAsset(path17.resolve(value), assetsDir);
     copied++;
-    return `${baseUrl}/${path16.basename(rel)}`;
+    return `${baseUrl}/${path17.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) && fs15.existsSync(e.path)) {
+        if (typeof e.path === "string" && !isRemote(e.path) && fs16.existsSync(e.path)) {
           e.path = bundle(e.path);
         }
-        if (typeof e.poster === "string" && !isRemote(e.poster) && fs15.existsSync(e.poster)) {
+        if (typeof e.poster === "string" && !isRemote(e.poster) && fs16.existsSync(e.poster)) {
           e.poster = bundle(e.poster);
         }
       }
@@ -22928,7 +23270,7 @@ function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets"
     }
   }
   if (copied > 0) {
-    fs15.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf8");
+    fs16.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf8");
   }
   return copied;
 }
@@ -22951,9 +23293,9 @@ function changeBadgeLookup(diff) {
   return (tc) => byKey.get(scenarioKey(tc.sourceFile, tc.story.scenario));
 }
 function readStoryReport(reportPath) {
-  if (!fs15.existsSync(reportPath)) return null;
+  if (!fs16.existsSync(reportPath)) return null;
   try {
-    return JSON.parse(fs15.readFileSync(reportPath, "utf8"));
+    return JSON.parse(fs16.readFileSync(reportPath, "utf8"));
   } catch {
     return null;
   }
@@ -22978,28 +23320,28 @@ 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"),
+  fs16.writeFileSync(
+    path17.join(outDir, "scenario-links.json"),
     JSON.stringify(index, null, 2),
     "utf8"
   );
   return index;
 }
 function clearGeneratedPages(dir) {
-  if (!fs15.existsSync(dir)) return;
-  for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
-    const full = path16.join(dir, entry.name);
+  if (!fs16.existsSync(dir)) return;
+  for (const entry of fs16.readdirSync(dir, { withFileTypes: true })) {
+    const full = path17.join(dir, entry.name);
     if (entry.isDirectory()) {
       clearGeneratedPages(full);
-      if (fs15.readdirSync(full).length === 0) fs15.rmdirSync(full);
+      if (fs16.readdirSync(full).length === 0) fs16.rmdirSync(full);
     } else if (/\.mdx?$/.test(entry.name)) {
-      fs15.rmSync(full);
+      fs16.rmSync(full);
     }
   }
 }
 function loadCanonicalRun(rawRunPath, synthesize) {
   try {
-    const data = JSON.parse(fs15.readFileSync(path16.resolve(rawRunPath), "utf8"));
+    const data = JSON.parse(fs16.readFileSync(path17.resolve(rawRunPath), "utf8"));
     if (data.schemaVersion !== 1) {
       throw new BuildDocsError(`Unsupported schemaVersion ${data.schemaVersion}. Supported: 1.`, "schema");
     }
@@ -23022,19 +23364,19 @@ ${schemaResult.errors.map((e) => `  ${e}`).join("\n")}`,
   }
 }
 async function buildDocs(options) {
-  const siteDir = path16.resolve(options.siteDir);
+  const siteDir = path17.resolve(options.siteDir);
   if (!isScaffoldedAstroSite(siteDir)) {
     throw new BuildDocsError(
       `"${siteDir}" is not a scaffolded Astro docs site (no astro.config.mjs). Run "executable-stories init-astro <dir>" first, then pass it with --site-dir <dir>.`,
       "usage"
     );
   }
-  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 storiesPublicDir = path17.join(siteDir, "public", "stories");
+  const assetsDir = path17.join(storiesPublicDir, "assets");
+  const storyPagesDir = path17.join(siteDir, "src", "content", "docs", "stories");
+  const notesDir = path17.join(siteDir, "src", "content", "docs", "notes");
+  const apiDir = path17.join(siteDir, "src", "content", "docs", "api");
+  const reportPath = path17.join(storiesPublicDir, "story-report.json");
   const canonical = loadCanonicalRun(options.rawRunPath, options.synthesizeStories ?? true);
   try {
     await new ReportGenerator({
@@ -23045,7 +23387,7 @@ async function buildDocs(options) {
     const currentReport = readStoryReport(reportPath);
     let diff;
     if (options.baselinePath) {
-      const baselineResolved = path16.resolve(options.baselinePath);
+      const baselineResolved = path17.resolve(options.baselinePath);
       const baseline = readStoryReport(baselineResolved);
       if (!baseline) {
         throw new BuildDocsError(
@@ -23083,7 +23425,7 @@ async function buildDocs(options) {
         const sub = partitioned[audience];
         audiences[audience] = sub.testCases.length;
         if (sub.testCases.length === 0) continue;
-        await genPages(sub, path16.join(storyPagesDir, audience));
+        await genPages(sub, path17.join(storyPagesDir, audience));
       }
     } else {
       await genPages(canonical, storyPagesDir);
@@ -23093,30 +23435,30 @@ 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"));
+    writeNotesIndex(notesIndex, path17.join(storiesPublicDir, "notes-index.json"));
     const notesIndexed = notesIndex.notes.length;
     if (linksIndex) {
-      fs15.writeFileSync(
-        path16.join(storyPagesDir, "index.md"),
+      fs16.writeFileSync(
+        path17.join(storyPagesDir, "index.md"),
         renderOverviewPage(linksIndex, notesIndex),
         "utf8"
       );
     }
-    const changesJsonPath = path16.join(storiesPublicDir, "changes.json");
-    const changesMdPath = path16.join(storyPagesDir, "changes.md");
+    const changesJsonPath = path17.join(storiesPublicDir, "changes.json");
+    const changesMdPath = path17.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");
+      fs16.writeFileSync(changesJsonPath, JSON.stringify(diff, null, 2), "utf8");
+      fs16.writeFileSync(changesMdPath, renderChangesPage(diff, linksIndex), "utf8");
       changes = diff.summary;
     } else {
-      fs15.rmSync(changesJsonPath, { force: true });
-      fs15.rmSync(changesMdPath, { force: true });
+      fs16.rmSync(changesJsonPath, { force: true });
+      fs16.rmSync(changesMdPath, { force: true });
     }
     let apiPages = 0;
     if (options.openapiPath) {
       const res = await importOpenApi({
-        specPath: path16.resolve(options.openapiPath),
+        specPath: path17.resolve(options.openapiPath),
         outputDir: apiDir,
         runFile: reportPath,
         force: true
@@ -23131,11 +23473,11 @@ async function buildDocs(options) {
 }
 
 // src/config.ts
-import { existsSync as existsSync13 } from "fs";
-import { resolve as resolve10 } from "path";
+import { existsSync as existsSync14 } from "fs";
+import { resolve as resolve11 } from "path";
 async function loadConfig(configPath) {
-  const resolved = configPath ? resolve10(configPath) : resolve10(process.cwd(), "executable-stories.config.js");
-  if (!existsSync13(resolved)) return {};
+  const resolved = configPath ? resolve11(configPath) : resolve11(process.cwd(), "executable-stories.config.js");
+  if (!existsSync14(resolved)) return {};
   const mod = await import(resolved);
   const config = mod.default;
   if (!config || typeof config !== "object" || Array.isArray(config)) {
@@ -23163,6 +23505,7 @@ USAGE
   executable-stories format <file> [options]
   executable-stories format --stdin [options]
   executable-stories watch <raw-run.json> [options]
+  executable-stories serve <raw-run.json> [--port <n>] [--host <host>] [options]
   executable-stories compare <baseline-file> <current-file> [options]
   executable-stories gate-release <dev-run.json> <rc-run.json> [options]
   executable-stories review <file> --changed-files <path> [options]
@@ -23186,6 +23529,7 @@ USAGE
 SUBCOMMANDS
   format             Read raw test results and generate reports
   watch              Regenerate reports whenever the raw-run file changes (live agent index)
+  serve              Live docs URL: regenerate + browser reload + "what changed since you started" (for agent loops)
   compare            Compare two runs and generate a diff report
   gate-release       Verify a release candidate against the dev test baseline (RC gate)
   review             Generate an Evidence Review of AI-authored changes (correlate a run to the diff)
@@ -23404,9 +23748,9 @@ async function parseCliArgs(argv) {
     process.exit(EXIT_SUCCESS);
   }
   const subcommand = args[0];
-  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "check" && subcommand !== "goal" && subcommand !== "triage" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "build-docs" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
+  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "serve" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "check" && subcommand !== "goal" && subcommand !== "triage" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "build-docs" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
     console.error(
-      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "gate-release", "deploy", "review", "list", "check", "goal", "triage", "validate", "init-astro", "build-docs", "new", "check-links", "import-openapi", "publish-confluence", or "publish-jira".`
+      `Unknown subcommand: "${subcommand}". Use "format", "watch", "serve", "compare", "gate-release", "deploy", "review", "list", "check", "goal", "triage", "validate", "init-astro", "build-docs", "new", "check-links", "import-openapi", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -23524,6 +23868,8 @@ async function parseCliArgs(argv) {
       "webhook-hmac-timestamp": { type: "boolean", default: false },
       "asset-mode": { type: "string", default: "none" },
       "allow-missing-assets": { type: "boolean", default: false },
+      port: { type: "string" },
+      host: { type: "string" },
       "pr-summary": { type: "boolean", default: false },
       "pr-summary-file": { type: "string" },
       "fail-on-regression": { type: "boolean", default: false },
@@ -23746,7 +24092,9 @@ async function parseCliArgs(argv) {
     headRef: values["head-ref"],
     failOn: failOnRaw,
     minEvidence: minEvidenceRaw,
-    config: values["config"]
+    config: values["config"],
+    servePort: values["port"] ? Number.parseInt(values["port"], 10) : 4321,
+    serveHost: values["host"] ?? "127.0.0.1"
   };
   return { args: cliArgs, pluginConfig, customRequested };
 }
@@ -23754,27 +24102,27 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path17.resolve(args.inputFile);
-  if (!fs16.existsSync(filePath)) {
+  const filePath = path18.resolve(args.inputFile);
+  if (!fs17.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
     process.exit(EXIT_USAGE);
   }
-  return fs16.readFileSync(filePath, "utf8");
+  return fs17.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path17.resolve(filePath);
-  if (!fs16.existsSync(resolved)) {
+  const resolved = path18.resolve(filePath);
+  if (!fs17.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
-  return fs16.readFileSync(resolved, "utf8");
+  return fs17.readFileSync(resolved, "utf8");
 }
 function readStdin() {
-  return new Promise((resolve12, reject) => {
+  return new Promise((resolve13, reject) => {
     const chunks = [];
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve12(chunks.join("")));
+    process.stdin.on("end", () => resolve13(chunks.join("")));
     process.stdin.on("error", reject);
   });
 }
@@ -23900,14 +24248,14 @@ function tryNormalizeRunFromText(text2, args) {
   }
 }
 function listBaselineCandidates(currentFile, args) {
-  const baselineDir = path17.resolve(args.baselineDir ?? path17.dirname(currentFile));
-  const currentResolved = path17.resolve(currentFile);
-  if (!fs16.existsSync(baselineDir)) {
+  const baselineDir = path18.resolve(args.baselineDir ?? path18.dirname(currentFile));
+  const currentResolved = path18.resolve(currentFile);
+  if (!fs17.existsSync(baselineDir)) {
     console.error(`Error: baseline directory not found: ${baselineDir}`);
     process.exit(EXIT_USAGE);
   }
-  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(
+  const entries = fs17.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path18.join(baselineDir, entry.name)).filter((candidate) => path18.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -23915,14 +24263,14 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   const candidates = listBaselineCandidates(currentFile, args);
   const comparable = [];
   for (const candidate of candidates) {
-    const run = tryNormalizeRunFromText(fs16.readFileSync(candidate, "utf8"), args);
+    const run = tryNormalizeRunFromText(fs17.readFileSync(candidate, "utf8"), args);
     if (run) {
       comparable.push({ file: candidate, run });
     }
   }
   if (comparable.length === 0) {
     console.error(
-      `Error: no compatible baseline files found in ${path17.resolve(args.baselineDir ?? path17.dirname(currentFile))}.`
+      `Error: no compatible baseline files found in ${path18.resolve(args.baselineDir ?? path18.dirname(currentFile))}.`
     );
     process.exit(EXIT_USAGE);
   }
@@ -24124,6 +24472,24 @@ async function main() {
     });
     return;
   }
+  if (args.subcommand === "serve") {
+    if (!args.inputFile) {
+      console.error("Error: serve requires an input file (the raw-run JSON the framework writes).");
+      process.exit(EXIT_USAGE);
+    }
+    const serveFormats = args.formats.includes("html") ? args.formats : [...args.formats, "html"];
+    startServe({
+      input: args.inputFile,
+      outputDir: args.outputDir,
+      outputName: args.outputName,
+      formats: serveFormats,
+      inputType: args.inputType === "canonical" ? "canonical" : "raw",
+      synthesize: args.synthesizeStories,
+      port: args.servePort,
+      host: args.serveHost
+    });
+    return;
+  }
   const text2 = await readInput(args);
   if (args.inputType === "ndjson") {
     if (args.subcommand === "validate") {
@@ -24167,9 +24533,9 @@ async function main() {
       process.exit(EXIT_SCHEMA_VALIDATION);
     }
     if (args.emitCanonical) {
-      const outPath = path17.resolve(args.emitCanonical);
-      fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
-      fs16.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path18.resolve(args.emitCanonical);
+      fs17.mkdirSync(path18.dirname(outPath), { recursive: true });
+      fs17.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -24226,9 +24592,9 @@ ${msg}`);
     }
     const run = data;
     if (args.emitCanonical) {
-      const outPath = path17.resolve(args.emitCanonical);
-      fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
-      fs16.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path18.resolve(args.emitCanonical);
+      fs17.mkdirSync(path18.dirname(outPath), { recursive: true });
+      fs17.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -24284,9 +24650,9 @@ ${msg}`);
     process.exit(EXIT_CANONICAL_VALIDATION);
   }
   if (args.emitCanonical) {
-    const outPath = path17.resolve(args.emitCanonical);
-    fs16.mkdirSync(path17.dirname(outPath), { recursive: true });
-    fs16.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
+    const outPath = path18.resolve(args.emitCanonical);
+    fs17.mkdirSync(path18.dirname(outPath), { recursive: true });
+    fs17.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
@@ -24311,9 +24677,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 = path17.join(outputDir, filename);
-      fs16.mkdirSync(outputDir, { recursive: true });
-      fs16.writeFileSync(filepath, content, "utf8");
+      const filepath = path18.join(outputDir, filename);
+      fs17.mkdirSync(outputDir, { recursive: true });
+      fs17.writeFileSync(filepath, content, "utf8");
       console.log(`Generated: ${filepath}`);
     } catch (err) {
       console.error(`Error running custom formatter "${formatName}": ${err instanceof Error ? err.message : String(err)}`);
@@ -24363,13 +24729,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return;
-  const historyPath = path17.resolve(args.historyFile);
+  const historyPath = path18.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs16.readFileSync(p, "utf8");
+          return fs17.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -24382,11 +24748,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path17.dirname(historyPath);
-  fs16.mkdirSync(dir, { recursive: true });
+  const dir = path18.dirname(historyPath);
+  fs17.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs16.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs17.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -24534,11 +24900,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)}` : "";
-  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");
+  fs17.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path18.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path18.join(outputDir, `${baseName}${suffix}.html`);
+  fs17.writeFileSync(mdPath, markdown, "utf8");
+  fs17.writeFileSync(htmlPath, html, "utf8");
   return [mdPath, htmlPath];
 }
 function evaluateReviewGate(review, args) {
@@ -24584,9 +24950,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 = path17.resolve(args.prSummaryFile);
-    fs16.mkdirSync(path17.dirname(outputPath), { recursive: true });
-    fs16.writeFileSync(outputPath, result.prSummary, "utf8");
+    const outputPath = path18.resolve(args.prSummaryFile);
+    fs17.mkdirSync(path18.dirname(outputPath), { recursive: true });
+    fs17.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -24615,13 +24981,13 @@ function printCompareResult(result, args, startMs) {
   }
 }
 function loadReleasePolicy(policyPath) {
-  const resolved = path17.resolve(policyPath);
-  if (!fs16.existsSync(resolved)) {
+  const resolved = path18.resolve(policyPath);
+  if (!fs17.existsSync(resolved)) {
     console.error(`Error: release policy file not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
   try {
-    const raw = JSON.parse(fs16.readFileSync(resolved, "utf8"));
+    const raw = JSON.parse(fs17.readFileSync(resolved, "utf8"));
     return {
       allowedOmissions: Array.isArray(raw.allowedOmissions) ? raw.allowedOmissions : [],
       allowedRegressions: Array.isArray(raw.allowedRegressions) ? raw.allowedRegressions : [],
@@ -24725,7 +25091,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 (!fs16.existsSync(inputFile)) {
+  if (!fs17.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -24753,7 +25119,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 = fs16.readFileSync(path17.resolve(inputFile), "utf8");
+  const adf = fs17.readFileSync(path18.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -24832,7 +25198,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 (!fs16.existsSync(inputFile)) {
+  if (!fs17.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -24859,7 +25225,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     process.exit(EXIT_USAGE);
   }
   const mode = modeRaw;
-  const adf = fs16.readFileSync(path17.resolve(inputFile), "utf8");
+  const adf = fs17.readFileSync(path18.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -25047,7 +25413,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 = path17.relative(process.cwd(), result.siteDir) || ".";
+    const rel = path18.relative(process.cwd(), result.siteDir) || ".";
     console.log(`
 Preview: cd ${rel} && npm run dev`);
     return EXIT_SUCCESS;
@@ -25274,7 +25640,9 @@ function createDefaultCliArgs() {
     failOnAddedFailures: false,
     failOnRemoval: false,
     failOnNew: false,
-    baselineMode: "explicit"
+    baselineMode: "explicit",
+    servePort: 4321,
+    serveHost: "127.0.0.1"
   };
 }
 main().catch((err) => {