executable-stories-formatters 0.9.0 → 0.11.0

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import * as fs8 from "fs";
-import * as path9 from "path";
+import * as fs13 from "fs";
+import * as path14 from "path";
 
 // src/validation/schema-validator.ts
 import Ajv from "ajv/dist/2020.js";
@@ -209,6 +209,11 @@ var raw_run_schema_default = {
           type: "integer",
           minimum: 0,
           description: "Order in which the story was defined in source (for stable sorting)."
+        },
+        otelSpans: {
+          type: "array",
+          items: { type: "object" },
+          description: "OpenTelemetry spans captured for this scenario (from autotel), used to render a trace waterfall."
         }
       },
       required: ["scenario"],
@@ -397,6 +402,20 @@ var raw_run_schema_default = {
           required: ["kind", "path", "phase"],
           additionalProperties: false
         },
+        {
+          type: "object",
+          description: "Video reference with optional caption and poster image.",
+          properties: {
+            kind: { const: "video" },
+            path: { type: "string" },
+            caption: { type: "string" },
+            poster: { type: "string" },
+            phase: { $ref: "#/$defs/DocPhase" },
+            children: { type: "array", items: { $ref: "#/$defs/DocEntry" }, description: "Nested child doc entries for grouping." }
+          },
+          required: ["kind", "path", "phase"],
+          additionalProperties: false
+        },
         {
           type: "object",
           description: "Custom documentation entry with arbitrary data.",
@@ -539,17 +558,17 @@ function validateRawRun(data) {
     return { valid: true, errors: [] };
   }
   const errors = (validate.errors ?? []).map((err) => {
-    const path10 = err.instancePath || "/";
+    const path15 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path10}: ${message} \u2014 '${extra}'`;
+      return `${path15}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path10}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path15}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path10}: ${message}`;
+    return `${path15}: ${message}`;
   });
   return { valid: false, errors };
 }
@@ -1024,7 +1043,7 @@ ${result.errors.join("\n")}`);
 
 // src/index.ts
 import "fs";
-import * as path7 from "path";
+import * as path8 from "path";
 import * as fsPromises from "fs/promises";
 
 // src/converters/acl/lines.ts
@@ -1486,6 +1505,15 @@ function copyDocEntry(entry) {
         phase: entry.phase,
         ...children
       };
+    case "video":
+      return {
+        kind: "video",
+        path: entry.path,
+        ...entry.caption ? { caption: entry.caption } : {},
+        ...entry.poster ? { poster: entry.poster } : {},
+        phase: entry.phase,
+        ...children
+      };
     case "custom":
       return {
         kind: "custom",
@@ -1569,6 +1597,9 @@ function buildScenario(tc, featureId) {
   if (tickets && tickets.length > 0) {
     scenario.tickets = tickets.map((t) => t.url ? { id: t.id, url: t.url } : { id: t.id });
   }
+  if (tc.story.covers && tc.story.covers.length > 0) {
+    scenario.covers = [...tc.story.covers];
+  }
   return scenario;
 }
 function deriveFeatureTitle(group, relSourceFile) {
@@ -1692,6 +1723,181 @@ var StoryReportJsonFormatter = class {
   }
 };
 
+// src/formatters/scenario-index-json.ts
+var ScenarioIndexJsonFormatter = class {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      pretty: options.pretty ?? true,
+      filters: options.filters
+    };
+  }
+  toIndex(run) {
+    return toScenarioIndex(toStoryReport(run), this.options.filters);
+  }
+  format(run) {
+    const index = this.toIndex(run);
+    return this.options.pretty ? JSON.stringify(index, null, 2) : JSON.stringify(index);
+  }
+};
+function toScenarioIndex(report, filters = {}) {
+  const scenarios = report.features.flatMap(
+    (feature) => feature.scenarios.map((scenario) => toScenarioIndexItem(feature, scenario))
+  ).filter((scenario) => matchesFilters(scenario, filters));
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: summarize(scenarios),
+    scenarios
+  };
+}
+function toScenarioIndexItem(feature, scenario) {
+  return {
+    id: scenario.id,
+    title: scenario.title,
+    status: scenario.status,
+    feature: feature.title,
+    sourceFile: feature.sourceFile,
+    sourceLine: scenario.sourceLine,
+    tags: scenario.tags,
+    tickets: scenario.tickets ?? [],
+    covers: scenario.covers ?? [],
+    durationMs: scenario.durationMs,
+    steps: scenario.steps.map((step) => ({
+      id: step.id,
+      index: step.index,
+      keyword: step.keyword,
+      text: step.text,
+      status: step.status,
+      durationMs: step.durationMs,
+      errorMessage: step.errorMessage,
+      docKinds: step.docEntries.map((entry) => entry.kind)
+    })),
+    docKinds: scenario.docEntries.map((entry) => entry.kind),
+    error: scenario.errorMessage ? { message: scenario.errorMessage, stack: scenario.errorStack } : void 0
+  };
+}
+function matchesFilters(scenario, filters) {
+  if (filters.statuses?.length && !filters.statuses.includes(scenario.status)) {
+    return false;
+  }
+  if (filters.tags?.length && !filters.tags.some((tag) => scenario.tags.includes(tag))) {
+    return false;
+  }
+  if (filters.sourceFiles?.length && !filters.sourceFiles.some((sourceFile) => scenario.sourceFile.includes(sourceFile))) {
+    return false;
+  }
+  return true;
+}
+function summarize(scenarios) {
+  return {
+    total: scenarios.length,
+    passed: scenarios.filter((scenario) => scenario.status === "passed").length,
+    failed: scenarios.filter((scenario) => scenario.status === "failed").length,
+    skipped: scenarios.filter((scenario) => scenario.status === "skipped").length,
+    pending: scenarios.filter((scenario) => scenario.status === "pending").length,
+    durationMs: scenarios.reduce((total, scenario) => total + scenario.durationMs, 0)
+  };
+}
+
+// src/formatters/behavior-manifest-json.ts
+var BehaviorManifestJsonFormatter = class {
+  pretty;
+  constructor(options = {}) {
+    this.pretty = options.pretty ?? true;
+  }
+  toManifest(run) {
+    return toBehaviorManifest(toStoryReport(run));
+  }
+  format(run) {
+    const manifest = this.toManifest(run);
+    return this.pretty ? JSON.stringify(manifest, null, 2) : JSON.stringify(manifest);
+  }
+};
+function toBehaviorManifest(report) {
+  const index = toScenarioIndex(report);
+  const bySource = /* @__PURE__ */ new Map();
+  const byTag = /* @__PURE__ */ new Map();
+  const docKinds = /* @__PURE__ */ new Set();
+  const debuggerIssues = [];
+  for (const scenario of index.scenarios) {
+    const source = bySource.get(scenario.sourceFile) ?? {
+      path: scenario.sourceFile,
+      scenarioCount: 0,
+      failed: 0,
+      tags: []
+    };
+    source.scenarioCount += 1;
+    if (scenario.status === "failed") source.failed += 1;
+    source.tags = [.../* @__PURE__ */ new Set([...source.tags, ...scenario.tags])].sort();
+    bySource.set(scenario.sourceFile, source);
+    for (const tag of scenario.tags) {
+      const tagEntry = byTag.get(tag) ?? { name: tag, scenarioCount: 0 };
+      tagEntry.scenarioCount += 1;
+      byTag.set(tag, tagEntry);
+    }
+    for (const kind of scenario.docKinds) docKinds.add(kind);
+    for (const step of scenario.steps) {
+      for (const kind of step.docKinds) docKinds.add(kind);
+    }
+    if (!scenarioHasDocs(scenario)) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-docs",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no doc entries."
+      });
+    }
+    if (scenario.tags.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-tags",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no tags."
+      });
+    }
+    if (scenario.covers.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-covers",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario declares no covers (product-code paths), so code\u2192scenario lookup cannot find it."
+      });
+    }
+    if (scenario.sourceLine === void 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-source-line",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no source line."
+      });
+    }
+  }
+  const scenariosWithDocs = index.scenarios.filter(scenarioHasDocs).length;
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: index.summary,
+    sourceFiles: [...bySource.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    tags: [...byTag.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    docCoverage: {
+      scenariosWithDocs,
+      scenariosWithoutDocs: index.scenarios.length - scenariosWithDocs,
+      docKinds: [...docKinds].sort()
+    },
+    debugger: debuggerIssues
+  };
+}
+function scenarioHasDocs(scenario) {
+  return scenario.docKinds.length > 0 || scenario.steps.some((step) => step.docKinds.length > 0);
+}
+
 // src/formatters/html/renderers/index.ts
 import * as fs2 from "fs";
 import * as path3 from "path";
@@ -14422,10 +14628,10 @@ function renderDocMermaid(entry, deps) {
 function renderDocScreenshot(entry, deps) {
   const alt = entry.alt ?? "Screenshot";
   const embedEnabled = deps.embedScreenshots ?? true;
-  const isRemote = /^(?:https?:|data:)/i.test(entry.path);
-  const embedAttempted = !isRemote && embedEnabled && !!deps.readScreenshot;
+  const isRemote2 = /^(?:https?:|data:)/i.test(entry.path);
+  const embedAttempted = !isRemote2 && embedEnabled && !!deps.readScreenshot;
   const inlined = embedAttempted ? deps.readScreenshot(entry.path) : void 0;
-  const isAbsoluteFsPath = !isRemote && /^(?:[/\\]|[A-Za-z]:[/\\])/.test(entry.path);
+  const isAbsoluteFsPath = !isRemote2 && /^(?:[/\\]|[A-Za-z]:[/\\])/.test(entry.path);
   if (embedAttempted && inlined === void 0 && isAbsoluteFsPath) {
     const captionHtml = entry.alt ? `<div class="doc-screenshot-caption">${deps.escapeHtml(entry.alt)}</div>` : "";
     return `<div class="doc-screenshot doc-screenshot-missing">
@@ -14440,6 +14646,23 @@ function renderDocScreenshot(entry, deps) {
   ${entry.alt ? `<div class="doc-screenshot-caption">${deps.escapeHtml(entry.alt)}</div>` : ""}
 </div>`;
 }
+function renderDocVideo(entry, deps) {
+  const isRemote2 = /^(?:https?:|data:)/i.test(entry.path);
+  const isAbsoluteFsPath = !isRemote2 && /^(?:[/\\]|[A-Za-z]:[/\\])/.test(entry.path);
+  const captionHtml = entry.caption ? `<div class="doc-video-caption">${deps.escapeHtml(entry.caption)}</div>` : "";
+  if ((deps.embedScreenshots ?? true) && isAbsoluteFsPath) {
+    return `<div class="doc-video doc-video-missing">
+  <div class="doc-video-missing-label">Video unavailable</div>
+  <div class="doc-video-missing-path">${deps.escapeHtml(entry.path)}</div>
+  ${captionHtml}
+</div>`;
+  }
+  const poster = entry.poster ? ` poster="${deps.escapeHtml(entry.poster)}"` : "";
+  return `<div class="doc-video">
+  <video class="doc-video-player" controls preload="metadata"${poster} src="${deps.escapeHtml(entry.path)}"></video>
+  ${captionHtml}
+</div>`;
+}
 function renderDocCustom(entry, deps) {
   if (entry.type === "visual" && entry.data && typeof entry.data === "object") {
     const data = entry.data;
@@ -14493,6 +14716,9 @@ function renderDocEntry(entry, deps) {
     case "screenshot":
       html = renderDocScreenshot(entry, deps);
       break;
+    case "video":
+      html = renderDocVideo(entry, deps);
+      break;
     case "custom":
       html = renderDocCustom(entry, deps);
       break;
@@ -15814,6 +16040,19 @@ var MarkdownFormatter = class {
       case "screenshot":
         lines.push(`${indent}![${entry.alt ?? "Screenshot"}](${entry.path})`);
         break;
+      case "video": {
+        const poster = entry.poster ? ` poster="${entry.poster}"` : "";
+        lines.push(`${indent}`);
+        lines.push(`${indent}<video controls preload="metadata"${poster} class="doc-video">`);
+        lines.push(`${indent}  <source src="${entry.path}" />`);
+        lines.push(`${indent}</video>`);
+        if (entry.caption) {
+          lines.push(`${indent}`);
+          lines.push(`${indent}*${entry.caption}*`);
+        }
+        lines.push(`${indent}`);
+        break;
+      }
       case "custom":
         if (entry.type === "visual" && entry.data && typeof entry.data === "object") {
           const data = entry.data;
@@ -15913,8 +16152,8 @@ function extractFeatureName(testCases, uri) {
       return tc.titlePath[0];
     }
   }
-  const basename3 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
-  return basename3.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  const basename4 = uri.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
+  return basename4.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function synthesizeFeature(uri, testCases) {
   const featureName = extractFeatureName(testCases, uri);
@@ -16526,8 +16765,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path10) {
-  const lower = path10.toLowerCase();
+function guessMediaType(path15) {
+  const lower = path15.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";
@@ -16668,11 +16907,11 @@ var CucumberHtmlFormatter = class {
     for (const envelope of envelopes) {
       const accepted = htmlStream.write(envelope);
       if (!accepted) {
-        await new Promise((resolve8) => htmlStream.once("drain", resolve8));
+        await new Promise((resolve11) => htmlStream.once("drain", resolve11));
       }
     }
-    await new Promise((resolve8, reject) => {
-      collector.on("finish", resolve8);
+    await new Promise((resolve11, reject) => {
+      collector.on("finish", resolve11);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -17003,6 +17242,8 @@ function formatDocEntry(doc) {
       return `${escapeHtml2(doc.title ?? "mermaid diagram")}: <code>${escapeHtml2(doc.code)}</code>`;
     case "screenshot":
       return `${doc.alt ? `${escapeHtml2(doc.alt)}: ` : ""}${escapeHtml2(doc.path)}`;
+    case "video":
+      return `${doc.caption ? `${escapeHtml2(doc.caption)}: ` : ""}${escapeHtml2(doc.path)}`;
     case "custom":
       return `${escapeHtml2(doc.type)}: ${escapeHtml2(JSON.stringify(doc.data))}`;
   }
@@ -17459,6 +17700,8 @@ function formatDocEntry2(doc) {
       return `${doc.title ?? "mermaid diagram"}: \`${doc.code}\``;
     case "screenshot":
       return `${doc.alt ? `${doc.alt}: ` : ""}${doc.path}`;
+    case "video":
+      return `${doc.caption ? `${doc.caption}: ` : ""}${doc.path}`;
     case "custom":
       return `${doc.type}: ${JSON.stringify(doc.data)}`;
   }
@@ -17704,19 +17947,35 @@ function replaceAssetRef(html, original, replacement) {
   return html;
 }
 
+// src/utils/source-file.ts
+function cleanTestStem(fileName) {
+  const base = fileName.split(/[\\/]/).pop() ?? fileName;
+  const stripped = base.replace(/\.(story\.)?(test|spec|cy)\.[cm]?[jt]sx?$/i, "");
+  if (stripped !== base) return stripped;
+  return base.replace(/\.[^.]+$/, "");
+}
+function humanizeSourceFile(fileName) {
+  return cleanTestStem(fileName).split(/[-_.\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
 // src/formatters/astro.ts
 var AstroFormatter = class _AstroFormatter {
   markdownFormatter;
   title;
+  perFileTitle;
   constructor(options = {}) {
     this.title = options.markdown?.title ?? "User Stories";
+    this.perFileTitle = options.perFileTitle ?? false;
     this.markdownFormatter = new MarkdownFormatter({
       ...options.markdown,
       title: this.title,
       stepStyle: "gherkin",
       includeFrontMatter: false,
       includeSummaryTable: false,
-      includeMetadata: false
+      includeMetadata: false,
+      // A per-file page is one file already — group by suite/describe so the
+      // body shows clean section headings, not the redundant source path.
+      groupBy: this.perFileTitle ? "suite" : options.markdown?.groupBy ?? "file"
     });
   }
   format(run) {
@@ -17726,13 +17985,31 @@ var AstroFormatter = class _AstroFormatter {
     return `${frontmatter}
 ${body}`;
   }
+  /**
+   * Title for the page. A per-file page (one source file — i.e. colocated mode)
+   * is titled by its suite/describe name, falling back to a humanized filename,
+   * so the docs nav reads "Convert Currency" not "User Stories" six times over.
+   * Multi-file (aggregated) pages keep the configured title.
+   */
+  deriveTitle(run) {
+    if (!this.perFileTitle) return this.title;
+    const sourceFiles = new Set(
+      run.testCases.map((tc) => tc.sourceFile).filter((f) => f && f !== "unknown")
+    );
+    if (sourceFiles.size !== 1) return this.title;
+    const suites = new Set(
+      run.testCases.map((tc) => tc.titlePath?.[0]).filter((s) => Boolean(s))
+    );
+    if (suites.size === 1) return [...suites][0];
+    return humanizeSourceFile([...sourceFiles][0]) || this.title;
+  }
   buildFrontmatter(run) {
     const badge = _AstroFormatter.computeBadge(run.testCases);
     const count = run.testCases.length;
     const description = `${count} scenario${count !== 1 ? "s" : ""} \u2014 ${badge.text.toLowerCase()}`;
     const lines = [
       "---",
-      `title: ${this.title}`,
+      `title: ${yamlScalar(this.deriveTitle(run))}`,
       `description: ${description}`,
       "sidebar:",
       "  badge:",
@@ -17750,6 +18027,12 @@ ${body}`;
     return { text: "Passed", variant: "success" };
   }
 };
+function yamlScalar(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
 
 // src/formatters/confluence.ts
 var ConfluenceFormatter = class {
@@ -18026,6 +18309,15 @@ ${tc.errorStack}` : "");
           ])
         );
         break;
+      case "video":
+        content.push(
+          paragraph([
+            text(entry.caption ?? "Video", strong()),
+            text(": "),
+            link(entry.path, entry.path)
+          ])
+        );
+        break;
       case "custom":
         content.push(paragraph([text(`[${entry.type}]`, strong())]));
         content.push(codeBlock(JSON.stringify(entry.data ?? null, null, 2), "json"));
@@ -18195,6 +18487,13 @@ function scanMarkdownAssets(markdown) {
       found.add(src);
     }
   }
+  const posterRe = /<video[^>]+\bposter=["']([^"']+)["'][^>]*>/gi;
+  while ((match = posterRe.exec(stripped)) !== null) {
+    const src = match[1].trim();
+    if (isLocalPath(src)) {
+      found.add(src);
+    }
+  }
   return Array.from(found);
 }
 function splitByCode(markdown) {
@@ -18245,6 +18544,19 @@ function rewriteProseSegment(prose, assetsBaseUrl, pathMap) {
       return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
     }
   );
+  result = result.replace(
+    /(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi,
+    (full, pre, src, post) => {
+      const trimmed = src.trim();
+      if (!isLocalPath(trimmed)) return full;
+      if (pathMap) {
+        const mapped = pathMap.get(trimmed);
+        if (mapped === void 0) return full;
+        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
+      }
+      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
+    }
+  );
   return result;
 }
 function rewriteAssetPaths(markdown, assetsBaseUrl, pathMap) {
@@ -18283,6 +18595,68 @@ function copyMarkdownAssets(options) {
   };
 }
 
+// src/watch.ts
+import * as fs6 from "fs";
+import * as path7 from "path";
+function toRun(data, inputType, synthesize) {
+  if (inputType === "canonical") return data;
+  let raw = data;
+  if (synthesize) raw = synthesizeStories(raw);
+  return canonicalizeRun(raw);
+}
+async function regenerateArtifacts(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);
+  const generator = new ReportGenerator({
+    formats: options.formats,
+    outputDir: options.outputDir,
+    outputName: options.outputName
+  });
+  const result = await generator.generate(run);
+  return [...result.values()].flat();
+}
+function startWatch(options, deps = {}) {
+  const log = deps.log ?? ((message) => console.log(message));
+  const regenerate = deps.regenerate ?? ((input) => regenerateArtifacts({ ...options, input }, deps));
+  const watchFn = deps.watch ?? ((filePath, listener) => fs6.watch(filePath, listener));
+  const debounceMs = options.debounceMs ?? 150;
+  let timer;
+  let running = false;
+  let pending = false;
+  const run = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      const files = await regenerate(options.input);
+      log(`Regenerated ${files.length} artifact file(s) from ${options.input}`);
+    } catch (error) {
+      log(`Watch regeneration failed: ${error.message}`);
+    } finally {
+      running = false;
+      if (pending) {
+        pending = false;
+        trigger();
+      }
+    }
+  };
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => void run(), debounceMs);
+  };
+  trigger();
+  const watcher = watchFn(path7.resolve(options.input), trigger);
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
 // src/publishers/confluence.ts
 function parseAdf(adf) {
   let parsed;
@@ -18980,10 +19354,10 @@ _...and ${summary.failedTests.length - maxFailedTests} more_`;
 }
 async function sendSlackNotification(args, deps) {
   const { summary, webhookUrl, maxFailedTests = 5 } = args;
-  const { fetch, logger } = deps;
+  const { fetch: fetch2, logger } = deps;
   const payload = buildSlackPayload(summary, maxFailedTests);
   try {
-    const response = await fetch(webhookUrl, {
+    const response = await fetch2(webhookUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload)
@@ -19134,10 +19508,10 @@ function buildTeamsPayload(summary, maxFailedTests) {
 }
 async function sendTeamsNotification(args, deps) {
   const { summary, webhookUrl, maxFailedTests = 5 } = args;
-  const { fetch, logger } = deps;
+  const { fetch: fetch2, logger } = deps;
   const payload = buildTeamsPayload(summary, maxFailedTests);
   try {
-    const response = await fetch(webhookUrl, {
+    const response = await fetch2(webhookUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload)
@@ -19185,7 +19559,7 @@ function signBody(args) {
 // src/notifiers/webhook.ts
 async function sendWebhookNotification(args, deps) {
   const { summary, options } = args;
-  const { fetch, logger } = deps;
+  const { fetch: fetch2, logger } = deps;
   const payload = {
     schemaVersion: 1,
     event: "test_run_finished",
@@ -19207,7 +19581,7 @@ async function sendWebhookNotification(args, deps) {
     }
   }
   try {
-    const response = await fetch(options.url, {
+    const response = await fetch2(options.url, {
       method: options.method ?? "POST",
       headers,
       body
@@ -19286,7 +19660,7 @@ async function sendNotifications(args, deps) {
     logger.warn("notifications: skipped (fetch unavailable)");
     return;
   }
-  const fetch = deps.fetch;
+  const fetch2 = deps.fetch;
   const slackWebhookUrl = notification?.slackWebhookUrl ?? env.SLACK_WEBHOOK_URL;
   const teamsWebhookUrl = notification?.teamsWebhookUrl ?? env.TEAMS_WEBHOOK_URL;
   const globalCondition = notification?.condition ?? "on-failure";
@@ -19302,7 +19676,7 @@ async function sendNotifications(args, deps) {
     promises.push(
       sendSlackNotification(
         { summary, webhookUrl: slackWebhookUrl, maxFailedTests },
-        { fetch, logger }
+        { fetch: fetch2, logger }
       ).then(() => void 0)
     );
   }
@@ -19310,7 +19684,7 @@ async function sendNotifications(args, deps) {
     promises.push(
       sendTeamsNotification(
         { summary, webhookUrl: teamsWebhookUrl, maxFailedTests },
-        { fetch, logger }
+        { fetch: fetch2, logger }
       ).then(() => void 0)
     );
   }
@@ -19320,7 +19694,7 @@ async function sendNotifications(args, deps) {
     promises.push(
       sendWebhookNotification(
         { summary, options: webhook, maxFailedTests },
-        { fetch, logger }
+        { fetch: fetch2, logger }
       ).then(() => void 0)
     );
   }
@@ -19451,12 +19825,22 @@ function listScenarios(args, _deps) {
   const { testCases, format } = args;
   if (format === "json") {
     const items = testCases.map((tc) => ({
+      id: tc.id,
       scenario: tc.story.scenario,
       status: tc.status,
       sourceFile: tc.sourceFile,
       sourceLine: tc.sourceLine,
+      suitePath: tc.story.suitePath ?? tc.titlePath.slice(0, -1),
       tags: tc.tags,
-      id: tc.id
+      tickets: tc.story.tickets ?? [],
+      covers: tc.story.covers ?? [],
+      durationMs: tc.durationMs,
+      error: tc.errorMessage ? {
+        message: tc.errorMessage,
+        stack: tc.errorStack
+      } : void 0,
+      steps: tc.story.steps.map((step, index) => toScenarioStep(step, index, tc)),
+      docKinds: collectDocKinds(tc)
     }));
     return JSON.stringify(items, null, 2);
   }
@@ -19529,6 +19913,34 @@ function listScenarios(args, _deps) {
   ];
   return lines.join("\n");
 }
+function toScenarioStep(step, index, testCase) {
+  const result = testCase.stepResults.find(
+    (candidate) => candidate.index === index || candidate.stepId === step.id
+  );
+  return {
+    id: step.id,
+    index,
+    keyword: step.keyword,
+    text: step.text,
+    status: result?.status ?? testCase.status,
+    durationMs: result?.durationMs ?? step.durationMs ?? 0,
+    errorMessage: result?.errorMessage,
+    mode: step.mode,
+    docKinds: (step.docs ?? []).map((doc) => doc.kind)
+  };
+}
+function collectDocKinds(testCase) {
+  const kinds = /* @__PURE__ */ new Set();
+  for (const doc of testCase.story.docs ?? []) {
+    kinds.add(doc.kind);
+  }
+  for (const step of testCase.story.steps) {
+    for (const doc of step.docs ?? []) {
+      kinds.add(doc.kind);
+    }
+  }
+  return [...kinds].sort();
+}
 
 // src/review/conventions.ts
 var CHANGE_TAG_PREFIX = "change:";
@@ -19576,18 +19988,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path10) {
-  const base = path10.split("/").pop() ?? path10;
+function extensionOf(path15) {
+  const base = path15.split("/").pop() ?? path15;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path10) {
-  return TEST_INFIX.test(path10);
+function isTestFile(path15) {
+  return TEST_INFIX.test(path15);
 }
-function isReviewableSource(path10) {
-  if (isTestFile(path10)) return false;
-  if (path10.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path10));
+function isReviewableSource(path15) {
+  if (isTestFile(path15)) return false;
+  if (path15.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path15));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -19691,7 +20103,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path10) => sourceBaseKey(path10) === key
+    (path15) => sourceBaseKey(path15) === key
   );
   return {
     id: testCase.id,
@@ -20224,6 +20636,7 @@ applyTheme(getEffectiveTheme());` : "";
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   astro: ".md",
+  "behavior-manifest-json": ".behavior-manifest.json",
   markdown: ".md",
   html: ".html",
   "cucumber-html": ".cucumber.html",
@@ -20231,8 +20644,13 @@ var FORMAT_EXTENSIONS = {
   "cucumber-json": ".cucumber.json",
   "cucumber-messages": ".ndjson",
   confluence: ".adf.json",
+  "scenario-index-json": ".scenarios-index.json",
   "story-report-json": ".story-report.json"
 };
+function joinNameAndExt(name, ext) {
+  const stutter = `.${name}.`;
+  return ext.startsWith(stutter) ? `${name}.${ext.slice(stutter.length)}` : `${name}${ext}`;
+}
 var TEST_EXTENSIONS = [
   ".test.ts",
   ".test.tsx",
@@ -20258,11 +20676,11 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   const ext = FORMAT_EXTENSIONS[format];
   const effectiveName = outputName + (outputNameSuffix ?? "");
   if (mode === "aggregated") {
-    return toPosix(path7.join(baseOutputDir, `${effectiveName}${ext}`));
+    return toPosix(path8.join(baseOutputDir, joinNameAndExt(effectiveName, ext)));
   }
   const normalizedSource = toPosix(sourceFile);
-  const dirOfSource = path7.posix.dirname(normalizedSource);
-  let baseName = path7.posix.basename(normalizedSource);
+  const dirOfSource = path8.posix.dirname(normalizedSource);
+  let baseName = path8.posix.basename(normalizedSource);
   for (const testExt of TEST_EXTENSIONS) {
     if (baseName.endsWith(testExt)) {
       baseName = baseName.slice(0, -testExt.length);
@@ -20271,9 +20689,12 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   }
   const fileName = `${baseName}.${effectiveName}${ext}`;
   if (colocatedStyle === "adjacent") {
-    return toPosix(path7.posix.join(dirOfSource, fileName));
+    return toPosix(path8.posix.join(dirOfSource, fileName));
   }
-  return toPosix(path7.posix.join(baseOutputDir, dirOfSource, fileName));
+  if (colocatedStyle === "flat") {
+    return toPosix(path8.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
+  }
+  return toPosix(path8.posix.join(baseOutputDir, dirOfSource, fileName));
 }
 function groupTestCasesByOutput(testCases, format, options, logger, outputNameSuffix) {
   const groups = /* @__PURE__ */ new Map();
@@ -20359,6 +20780,12 @@ var ReportGenerator = class {
       storyReportJson: {
         pretty: options.storyReportJson?.pretty ?? true
       },
+      scenarioIndexJson: {
+        pretty: options.scenarioIndexJson?.pretty ?? true
+      },
+      behaviorManifestJson: {
+        pretty: options.behaviorManifestJson?.pretty ?? true
+      },
       cucumberMessages: {
         uriStrategy: options.cucumberMessages?.uriStrategy ?? "sourceFile",
         includeSynthetics: options.cucumberMessages?.includeSynthetics ?? true,
@@ -20474,8 +20901,8 @@ var ReportGenerator = class {
       if (astroPaths) {
         for (const mdPath of astroPaths) {
           const content = await fsPromises.readFile(mdPath, "utf8");
-          const mdDir = path7.dirname(mdPath);
-          const assetsDir = path7.resolve(this.options.astro.assetsDir);
+          const mdDir = path8.dirname(mdPath);
+          const assetsDir = path8.resolve(this.options.astro.assetsDir);
           const result = copyMarkdownAssets({
             markdown: content,
             markdownDir: mdDir,
@@ -20506,9 +20933,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(path7.join(this.options.outputDir, `${effectiveName}${ext}`));
+      const outputPath = toPosix(path8.join(this.options.outputDir, joinNameAndExt(effectiveName, ext)));
       const content = await this.formatContent(run, format);
-      const dir = path7.dirname(outputPath);
+      const dir = path8.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       return [outputPath];
@@ -20520,7 +20947,7 @@ var ReportGenerator = class {
         testCases
       };
       const content = await this.formatContent(groupRun, format);
-      const dir = path7.dirname(outputPath);
+      const dir = path8.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       writtenPaths.push(outputPath);
@@ -20586,6 +21013,8 @@ var ReportGenerator = class {
       case "astro": {
         const formatter = new AstroFormatter({
           assetsBaseUrl: this.options.astro.assetsBaseUrl,
+          // Colocated = one page per file, so title each by its own suite/file.
+          perFileTitle: this.options.output.mode === "colocated",
           markdown: this.options.astro.markdown
         });
         return formatter.format(run);
@@ -20633,6 +21062,18 @@ var ReportGenerator = class {
         });
         return formatter.format(run);
       }
+      case "scenario-index-json": {
+        const formatter = new ScenarioIndexJsonFormatter({
+          pretty: this.options.scenarioIndexJson.pretty
+        });
+        return formatter.format(run);
+      }
+      case "behavior-manifest-json": {
+        const formatter = new BehaviorManifestJsonFormatter({
+          pretty: this.options.behaviorManifestJson.pretty
+        });
+        return formatter.format(run);
+      }
       default:
         throw new Error(`Unknown format: ${format}`);
     }
@@ -20646,7 +21087,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(path7.join(outputDir, `${outputName}${ext}`));
+    const outputPath = toPosix(path8.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);
@@ -20655,50 +21096,745 @@ async function generateRunComparison(args) {
 }
 
 // src/init-astro.ts
-import * as fs7 from "fs";
-import * as path8 from "path";
+import * as fs8 from "fs";
+import * as path9 from "path";
 import { fileURLToPath } from "url";
-var __dirname = path8.dirname(fileURLToPath(import.meta.url));
+var __dirname = path9.dirname(fileURLToPath(import.meta.url));
+var FRAMEWORK_DIRS = ["src/components", "src/lib", "src/styles", "src/pages"];
+var FRAMEWORK_FILES = ["tsconfig.json"];
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
-  if (fs7.existsSync(targetDir)) {
-    const entries = fs7.readdirSync(targetDir);
+  const update = options.update ?? false;
+  const templateDir = path9.resolve(__dirname, "..", "templates", "astro-starlight");
+  if (!fs8.existsSync(templateDir)) {
+    throw new Error(
+      `Template directory not found at ${templateDir}. Ensure the package is installed correctly.`
+    );
+  }
+  if (update) {
+    return updateFrameworkFiles(templateDir, targetDir);
+  }
+  if (fs8.existsSync(targetDir)) {
+    const entries = fs8.readdirSync(targetDir);
     if (entries.length > 0 && !force) {
       throw new Error(
-        `Directory "${targetDir}" already exists and is not empty. Use --force to overwrite.`
+        `Directory "${targetDir}" already exists and is not empty. Use --force to overwrite, or --update to refresh framework files only.`
       );
     }
   }
-  const templateDir = path8.resolve(__dirname, "..", "templates", "astro-starlight");
-  if (!fs7.existsSync(templateDir)) {
-    throw new Error(
-      `Template directory not found at ${templateDir}. Ensure the package is installed correctly.`
-    );
-  }
   copyDirRecursive(templateDir, targetDir);
   return { targetDir };
 }
-function copyDirRecursive(src, dest) {
-  fs7.mkdirSync(dest, { recursive: true });
-  const entries = fs7.readdirSync(src, { withFileTypes: true });
+function updateFrameworkFiles(templateDir, targetDir) {
+  if (!fs8.existsSync(targetDir) || !fs8.existsSync(path9.join(targetDir, "astro.config.mjs"))) {
+    throw new Error(
+      `"${targetDir}" does not look like a scaffolded docs site. Run init-astro (without --update) first.`
+    );
+  }
+  const updated = [];
+  for (const dir of FRAMEWORK_DIRS) {
+    const src = path9.join(templateDir, dir);
+    if (!fs8.existsSync(src)) continue;
+    copyDirRecursive(src, path9.join(targetDir, dir), (rel) => updated.push(path9.join(dir, rel)));
+  }
+  for (const file of FRAMEWORK_FILES) {
+    const src = path9.join(templateDir, file);
+    if (!fs8.existsSync(src)) continue;
+    fs8.copyFileSync(src, path9.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 = path9.join(templateDir, "package.json");
+  const userPkgPath = path9.join(targetDir, "package.json");
+  if (!fs8.existsSync(tmplPkgPath) || !fs8.existsSync(userPkgPath)) return false;
+  const tmpl = JSON.parse(fs8.readFileSync(tmplPkgPath, "utf8"));
+  const user = JSON.parse(fs8.readFileSync(userPkgPath, "utf8"));
+  user.dependencies = user.dependencies ?? {};
+  let changed = false;
+  for (const [name, version] of Object.entries(tmpl.dependencies ?? {})) {
+    if (!(name in user.dependencies)) {
+      user.dependencies[name] = version;
+      changed = true;
+    }
+  }
+  if (changed) {
+    fs8.writeFileSync(userPkgPath, `${JSON.stringify(user, null, 2)}
+`, "utf8");
+  }
+  return changed;
+}
+function copyDirRecursive(src, dest, onFile, baseSrc = src) {
+  fs8.mkdirSync(dest, { recursive: true });
+  const entries = fs8.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path8.join(src, entry.name);
-    const destPath = path8.join(dest, entry.name);
+    const srcPath = path9.join(src, entry.name);
+    const destPath = path9.join(dest, entry.name);
     if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
+      copyDirRecursive(srcPath, destPath, onFile, baseSrc);
     } else {
-      fs7.copyFileSync(srcPath, destPath);
+      fs8.copyFileSync(srcPath, destPath);
+      onFile?.(path9.relative(baseSrc, srcPath));
+    }
+  }
+}
+
+// src/scaffold-doc.ts
+import * as fs9 from "fs";
+import * as path10 from "path";
+var TEMPLATES = ["adr", "runbook", "decision-log", "incident"];
+function slugify3(input) {
+  return input.toLowerCase().trim().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
+}
+function isoDate(today) {
+  return today.toISOString().slice(0, 10);
+}
+function nextSeq(dir) {
+  let max = 0;
+  try {
+    for (const entry of fs9.readdirSync(dir)) {
+      const match = /^(\d{1,4})-/.exec(entry);
+      if (match) max = Math.max(max, Number.parseInt(match[1], 10));
     }
+  } catch {
+  }
+  return String(max + 1).padStart(4, "0");
+}
+var COMPONENTS = "../../../components";
+var TEMPLATE_SPECS = {
+  adr: {
+    subdir: "adr",
+    filename: (slug2, ctx) => `${ctx.seq}-${slug2}`,
+    content: (ctx) => `---
+title: 'ADR ${ctx.seq} \u2014 ${ctx.name}'
+description: '${ctx.name}'
+# Link the stories that prove this decision. The badge under the title turns
+# red the moment any of them fail, so this record can't drift from the code.
+verifiedBy: []
+---
+
+## Status
+
+**Proposed** \u2014 proposed \xB7 accepted \xB7 superseded \xB7 deprecated
+
+## Context
+
+_What problem are we solving? What constraints and forces apply?_
+
+## Decision
+
+_What did we decide to do?_
+
+## Consequences
+
+_What becomes easier, and what becomes harder, as a result?_
+
+## Verified by
+
+Add the story ids or tags that exercise this decision to \`verifiedBy\` in the
+frontmatter above. Until you do, the badge reads **Unverified** \u2014 by design.
+`
+  },
+  runbook: {
+    subdir: "runbooks",
+    filename: (slug2) => slug2,
+    content: (ctx) => `---
+title: 'Runbook \u2014 ${ctx.name}'
+description: 'Operational runbook for ${ctx.name}'
+---
+
+import Checklist from '${COMPONENTS}/Checklist.astro';
+import VerifiedStep from '${COMPONENTS}/VerifiedStep.astro';
+
+_When to use this runbook, prerequisites, and who to contact._
+
+## Steps
+
+Each step linked with \`story=\` shows a live green check when its test passed in
+the last run \u2014 so this runbook is trustworthy, not aspirational.
+
+<Checklist>
+  <VerifiedStep story="">Describe the first action, and link the story that verifies it.</VerifiedStep>
+  <VerifiedStep>A manual step with no automated check.</VerifiedStep>
+</Checklist>
+
+## Rollback
+
+_How to safely undo if something goes wrong._
+`
+  },
+  "decision-log": {
+    subdir: "decisions",
+    filename: (slug2) => slug2,
+    content: (ctx) => `---
+title: 'Decision log \u2014 ${ctx.name}'
+description: 'Running log of decisions for ${ctx.name}'
+---
+
+A lightweight running log. For weightier decisions, scaffold a full ADR with
+\`executable-stories new adr\`.
+
+| Date | Decision | Owner | Verified by |
+| ---- | -------- | ----- | ----------- |
+| ${ctx.isoDate} | _What was decided_ | _Who_ | _story id or tag_ |
+`
+  },
+  incident: {
+    subdir: "incidents",
+    filename: (slug2, ctx) => `${ctx.isoDate}-${slug2}`,
+    content: (ctx) => `---
+title: 'Incident \u2014 ${ctx.name}'
+description: 'Post-mortem for ${ctx.name}'
+# Link the regression story added to stop this recurring.
+verifiedBy: []
+---
+
+## Summary
+
+_What happened, who was affected, and for how long._
+
+## Timeline
+
+| Time | Event |
+| ---- | ----- |
+| ${ctx.isoDate} | Detected |
+
+## Root cause
+
+_The underlying cause, not just the trigger._
+
+## Resolution
+
+_How it was fixed._
+
+## Action items
+
+- [ ] Add a regression story and link it in \`verifiedBy\` so a silent recurrence
+  becomes a failing badge.
+`
+  }
+};
+function isTemplateName(value) {
+  return TEMPLATES.includes(value);
+}
+function scaffoldDoc(options) {
+  const { template } = options;
+  if (!isTemplateName(template)) {
+    throw new Error(
+      `Unknown template "${template}". Available: ${TEMPLATES.join(", ")}.`
+    );
+  }
+  const spec = TEMPLATE_SPECS[template];
+  const baseDir = options.baseDir ?? path10.join("src", "content", "docs");
+  const today = options.today ?? /* @__PURE__ */ new Date();
+  const name = (options.name ?? "").trim() || defaultName(template);
+  const slug2 = slugify3(name);
+  const dir = path10.join(baseDir, spec.subdir);
+  const ctx = {
+    name,
+    slug: slug2,
+    isoDate: isoDate(today),
+    seq: nextSeq(dir)
+  };
+  const filename = `${spec.filename(slug2, ctx)}.mdx`;
+  const filePath = path10.join(dir, filename);
+  if (fs9.existsSync(filePath) && !options.force) {
+    throw new Error(
+      `File "${filePath}" already exists. Use --force to overwrite.`
+    );
+  }
+  fs9.mkdirSync(dir, { recursive: true });
+  fs9.writeFileSync(filePath, spec.content(ctx), "utf8");
+  return { template, path: filePath, title: titleFor2(template, ctx) };
+}
+function defaultName(template) {
+  switch (template) {
+    case "adr":
+      return "Untitled decision";
+    case "runbook":
+      return "Untitled runbook";
+    case "decision-log":
+      return "Decisions";
+    case "incident":
+      return "Untitled incident";
+  }
+}
+function titleFor2(template, ctx) {
+  switch (template) {
+    case "adr":
+      return `ADR ${ctx.seq} \u2014 ${ctx.name}`;
+    case "runbook":
+      return `Runbook \u2014 ${ctx.name}`;
+    case "decision-log":
+      return `Decision log \u2014 ${ctx.name}`;
+    case "incident":
+      return `Incident \u2014 ${ctx.name}`;
+  }
+}
+
+// src/check-links.ts
+import * as fs10 from "fs";
+import * as path11 from "path";
+function stripCode(markdown) {
+  let out = markdown.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1\s*$/gm, "");
+  out = out.replace(/(`+)(?:(?!\1).)+\1/g, "");
+  return out;
+}
+function extractLinks(markdown) {
+  const stripped = stripCode(markdown);
+  const found = [];
+  const mdRe = /!?\[[^\]]*\]\(\s*<?([^)\s"'<>]+)>?(?:\s+["'][^"']*["'])?\s*\)/g;
+  let match;
+  while ((match = mdRe.exec(stripped)) !== null) {
+    found.push(match[1].trim());
+  }
+  const htmlRe = /<[a-z][^>]*\b(?:href|src)=["']([^"']+)["']/gi;
+  while ((match = htmlRe.exec(stripped)) !== null) {
+    found.push(match[1].trim());
+  }
+  return found.filter(Boolean);
+}
+function classifyLink(link2) {
+  if (/^(?:https?:)?\/\//i.test(link2)) return "external";
+  if (/^mailto:/i.test(link2)) return "mail";
+  if (link2.startsWith("#")) return "anchor";
+  if (link2.startsWith("/")) return "root";
+  return "internal";
+}
+function resolutionCandidates(fromFile, link2) {
+  const withoutAnchor = link2.split("#")[0];
+  if (!withoutAnchor) return [];
+  const base = path11.resolve(path11.dirname(fromFile), withoutAnchor);
+  const candidates = [base];
+  if (!path11.extname(base)) {
+    candidates.push(`${base}.md`, `${base}.mdx`);
+    candidates.push(path11.join(base, "index.md"), path11.join(base, "index.mdx"));
+  }
+  return candidates;
+}
+function resolvesOnDisk(fromFile, link2) {
+  return resolutionCandidates(fromFile, link2).some(
+    (candidate) => fs10.existsSync(candidate) && fs10.statSync(candidate).isFile()
+  );
+}
+function collectDocFiles(target) {
+  const stat = fs10.statSync(target);
+  if (stat.isFile()) return [target];
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of fs10.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const full = path11.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();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, { method, signal: controller.signal, redirect: "follow" });
+      return res.status < 400;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  try {
+    return await attempt("HEAD");
+  } catch {
+    try {
+      return await attempt("GET");
+    } catch {
+      return false;
+    }
+  }
+}
+async function checkLinks(options) {
+  const { target, checkExternal = false, externalTimeoutMs = 8e3 } = options;
+  if (!fs10.existsSync(target)) {
+    throw new Error(`Path not found: ${target}`);
+  }
+  const files = collectDocFiles(target);
+  const broken = [];
+  let linksChecked = 0;
+  let externalChecked = 0;
+  let skipped = 0;
+  const externalCache = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const content = fs10.readFileSync(file, "utf8");
+    for (const link2 of extractLinks(content)) {
+      const kind = classifyLink(link2);
+      if (kind === "anchor" || kind === "mail" || kind === "root") {
+        skipped += 1;
+        continue;
+      }
+      if (kind === "external") {
+        if (!checkExternal) {
+          skipped += 1;
+          continue;
+        }
+        externalChecked += 1;
+        linksChecked += 1;
+        let pending = externalCache.get(link2);
+        if (!pending) {
+          pending = isExternalAlive(link2, externalTimeoutMs);
+          externalCache.set(link2, pending);
+        }
+        if (!await pending) {
+          broken.push({ file, link: link2, reason: "external URL unreachable" });
+        }
+        continue;
+      }
+      linksChecked += 1;
+      if (!resolvesOnDisk(file, link2)) {
+        broken.push({ file, link: link2, reason: "target file not found" });
+      }
+    }
+  }
+  return {
+    filesScanned: files.length,
+    linksChecked,
+    brokenCount: broken.length,
+    broken,
+    externalChecked,
+    skipped
+  };
+}
+function formatLinkReport(report) {
+  const lines = [];
+  lines.push(
+    `Scanned ${report.filesScanned} file(s), checked ${report.linksChecked} link(s) (${report.skipped} skipped).`
+  );
+  if (report.brokenCount === 0) {
+    lines.push("\u2713 No broken links.");
+  } else {
+    lines.push(`\u2715 ${report.brokenCount} broken link(s):`);
+    for (const b of report.broken) {
+      lines.push(`  ${b.file}: ${b.link} \u2014 ${b.reason}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/import-openapi.ts
+import * as fs11 from "fs";
+import * as path12 from "path";
+import { parse as parseYamlString } from "yaml";
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
+function parseYaml(raw, specPath) {
+  try {
+    return parseYamlString(raw);
+  } catch (err) {
+    throw new Error(`Could not parse YAML spec ${specPath}: ${err.message}`, {
+      cause: err
+    });
+  }
+}
+function parseSpec(specPath) {
+  if (!fs11.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
+  const raw = fs11.readFileSync(specPath, "utf8");
+  const ext = path12.extname(specPath).toLowerCase();
+  if (ext === ".json") return JSON.parse(raw);
+  if (ext === ".yaml" || ext === ".yml") return parseYaml(raw, specPath);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return parseYaml(raw, specPath);
+  }
+}
+function extractEndpoints(spec) {
+  const paths = spec.paths ?? {};
+  const endpoints = [];
+  for (const [route, item] of Object.entries(paths)) {
+    if (!item || typeof item !== "object") continue;
+    for (const method of HTTP_METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== "object") continue;
+      const tags = Array.isArray(op.tags) && op.tags.length > 0 ? op.tags : ["API"];
+      endpoints.push({
+        method: method.toUpperCase(),
+        path: route,
+        operationId: typeof op.operationId === "string" ? op.operationId : void 0,
+        summary: typeof op.summary === "string" && op.summary || typeof op.description === "string" && op.description || "",
+        tag: String(tags[0])
+      });
+    }
+  }
+  return endpoints;
+}
+function loadScenarios(runFile) {
+  if (!runFile) return [];
+  if (!fs11.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
+  const report = JSON.parse(fs11.readFileSync(runFile, "utf8"));
+  return (report.features ?? []).flatMap((f) => f.scenarios ?? []);
+}
+function endpointRefs(endpoint) {
+  const refs = [
+    endpoint.operationId,
+    `${endpoint.method} ${endpoint.path}`,
+    endpoint.path
+  ].filter((r) => Boolean(r));
+  return refs;
+}
+function scenarioMatchesEndpoint(scenario, refs) {
+  const tags = scenario.tags ?? [];
+  return refs.some(
+    (ref) => scenario.id === ref || scenario.title === ref || tags.includes(ref)
+  );
+}
+function computeCoverage(endpoints, scenarios) {
+  return endpoints.map((endpoint) => {
+    const refs = endpointRefs(endpoint);
+    const matched = scenarios.filter((s) => scenarioMatchesEndpoint(s, refs));
+    let status;
+    if (matched.length === 0) status = "uncovered";
+    else if (matched.some((s) => s.status === "failed")) status = "failing";
+    else status = "covered";
+    return {
+      endpoint,
+      status,
+      stories: matched.map((s) => ({
+        id: s.id ?? s.title ?? "",
+        title: s.title ?? s.id ?? "story",
+        status: s.status ?? "passed"
+      }))
+    };
+  });
+}
+function slug(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "api";
+}
+function yamlQuote(value) {
+  return value.replace(/'/g, "''");
+}
+function coverageSummary(rows) {
+  return {
+    total: rows.length,
+    covered: rows.filter((r) => r.status === "covered").length,
+    failing: rows.filter((r) => r.status === "failing").length,
+    uncovered: rows.filter((r) => r.status === "uncovered").length
+  };
+}
+function renderTagPage(tag, rows, hasRun) {
+  const endpoints = rows.map((r) => ({
+    method: r.endpoint.method,
+    path: r.endpoint.path,
+    summary: r.endpoint.summary || "",
+    status: r.status,
+    stories: r.stories
+  }));
+  const summary = coverageSummary(rows);
+  return `---
+title: 'API \u2014 ${yamlQuote(tag)}'
+description: 'Endpoints for ${yamlQuote(tag)}, linked to the stories that exercise them.'
+---
+
+import ApiOperations from '@components/ApiOperations.astro';
+
+<ApiOperations
+  tag={${JSON.stringify(tag)}}
+  hasRun={${hasRun}}
+  summary={${JSON.stringify(summary)}}
+  endpoints={${JSON.stringify(endpoints)}}
+/>
+`;
+}
+function renderIndex(groups, hasRun, totals) {
+  const rows = [...groups.entries()].map(([tag, eps]) => {
+    const covered = eps.filter((e) => e.status === "covered").length;
+    const cov = hasRun ? ` | ${covered}/${eps.length} covered` : "";
+    return `- [${tag}](./${slug(tag)}/) \u2014 ${eps.length} endpoint(s)${cov}`;
+  }).join("\n");
+  const coverageNote = hasRun ? `
+**${totals.coveredCount} of ${totals.endpointCount} endpoints** are covered by a passing story.` + (totals.uncoveredCount > 0 ? ` \u26A0 ${totals.uncoveredCount} endpoint(s) have no verifying test.` : "") : "\nRe-run with `--run <story-report.json>` to show per-endpoint test coverage.";
+  return `---
+title: 'API reference'
+description: 'API endpoints generated from OpenAPI, linked to verifying stories.'
+---
+
+${coverageNote}
+
+${rows}
+`;
+}
+async function importOpenApi(options) {
+  const spec = parseSpec(options.specPath);
+  const endpoints = extractEndpoints(spec);
+  if (endpoints.length === 0) {
+    throw new Error(`No endpoints found in ${options.specPath} (expected an OpenAPI "paths" object).`);
+  }
+  const scenarios = loadScenarios(options.runFile);
+  const hasRun = Boolean(options.runFile);
+  const coverage = computeCoverage(endpoints, scenarios);
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of coverage) {
+    const list = groups.get(item.endpoint.tag) ?? [];
+    list.push(item);
+    groups.set(item.endpoint.tag, list);
+  }
+  const outputDir = options.outputDir ?? path12.join("src", "content", "docs", "api");
+  if (fs11.existsSync(outputDir) && !options.force) {
+    const entries = fs11.readdirSync(outputDir);
+    if (entries.length > 0) {
+      throw new Error(`Output directory "${outputDir}" is not empty. Use --force to overwrite.`);
+    }
+  }
+  fs11.mkdirSync(outputDir, { recursive: true });
+  const coveredCount = coverage.filter((c) => c.status === "covered").length;
+  const uncoveredCount = coverage.filter((c) => c.status === "uncovered").length;
+  fs11.writeFileSync(
+    path12.join(outputDir, "index.mdx"),
+    renderIndex(groups, hasRun, { endpointCount: endpoints.length, coveredCount, uncoveredCount }),
+    "utf8"
+  );
+  for (const [tag, rows] of groups) {
+    const dir = path12.join(outputDir, slug(tag));
+    fs11.mkdirSync(dir, { recursive: true });
+    fs11.writeFileSync(path12.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
+  }
+  return {
+    outputDir,
+    pageCount: groups.size + 1,
+    endpointCount: endpoints.length,
+    coveredCount,
+    uncoveredCount
+  };
+}
+
+// src/build-docs.ts
+import * as fs12 from "fs";
+import * as path13 from "path";
+var BuildDocsError = class extends Error {
+  constructor(message, kind) {
+    super(message);
+    this.kind = kind;
+    this.name = "BuildDocsError";
+  }
+};
+var isRemote = (p) => /^(?:https?:|data:)/i.test(p);
+function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets") {
+  if (!fs12.existsSync(reportPath)) return 0;
+  const report = JSON.parse(fs12.readFileSync(reportPath, "utf8"));
+  let copied = 0;
+  const bundle = (value) => {
+    const rel = copyAsset(path13.resolve(value), assetsDir);
+    copied++;
+    return `${baseUrl}/${path13.basename(rel)}`;
+  };
+  const visit = (entries) => {
+    for (const entry of entries ?? []) {
+      const e = entry;
+      if (e.kind === "screenshot" || e.kind === "video") {
+        if (typeof e.path === "string" && !isRemote(e.path) && fs12.existsSync(e.path)) {
+          e.path = bundle(e.path);
+        }
+        if (typeof e.poster === "string" && !isRemote(e.poster) && fs12.existsSync(e.poster)) {
+          e.poster = bundle(e.poster);
+        }
+      }
+      if (Array.isArray(e.children)) visit(e.children);
+    }
+  };
+  for (const feature of report.features ?? []) {
+    for (const scenario of feature.scenarios ?? []) {
+      visit(scenario.docEntries);
+    }
+  }
+  if (copied > 0) {
+    fs12.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf8");
+  }
+  return copied;
+}
+function clearGeneratedPages(dir) {
+  if (!fs12.existsSync(dir)) return;
+  for (const entry of fs12.readdirSync(dir, { withFileTypes: true })) {
+    const full = path13.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      clearGeneratedPages(full);
+      if (fs12.readdirSync(full).length === 0) fs12.rmdirSync(full);
+    } else if (/\.mdx?$/.test(entry.name)) {
+      fs12.rmSync(full);
+    }
+  }
+}
+function loadCanonicalRun(rawRunPath, synthesize) {
+  try {
+    const data = JSON.parse(fs12.readFileSync(path13.resolve(rawRunPath), "utf8"));
+    if (data.schemaVersion !== 1) {
+      throw new BuildDocsError(`Unsupported schemaVersion ${data.schemaVersion}. Supported: 1.`, "schema");
+    }
+    const schemaResult = validateRawRun(data);
+    if (!schemaResult.valid) {
+      throw new BuildDocsError(
+        `Schema validation failed:
+${schemaResult.errors.map((e) => `  ${e}`).join("\n")}`,
+        "schema"
+      );
+    }
+    let raw = data;
+    if (synthesize) raw = synthesizeStories(raw);
+    const canonical = canonicalizeRun(raw);
+    assertValidRun(canonical);
+    return canonical;
+  } catch (err) {
+    if (err instanceof BuildDocsError) throw err;
+    throw new BuildDocsError(`Could not read raw run "${rawRunPath}": ${err.message}`, "input");
+  }
+}
+async function buildDocs(options) {
+  const siteDir = path13.resolve(options.siteDir);
+  const storiesPublicDir = path13.join(siteDir, "public", "stories");
+  const assetsDir = path13.join(storiesPublicDir, "assets");
+  const storyPagesDir = path13.join(siteDir, "src", "content", "docs", "stories");
+  const apiDir = path13.join(siteDir, "src", "content", "docs", "api");
+  const reportPath = path13.join(storiesPublicDir, "story-report.json");
+  const canonical = loadCanonicalRun(options.rawRunPath, options.synthesizeStories ?? true);
+  try {
+    await new ReportGenerator({
+      formats: ["story-report-json"],
+      outputDir: storiesPublicDir,
+      outputName: "story-report"
+    }).generate(canonical);
+    clearGeneratedPages(storyPagesDir);
+    await new ReportGenerator({
+      formats: ["astro"],
+      outputDir: storyPagesDir,
+      outputName: "index",
+      output: { mode: "colocated", colocatedStyle: "flat" },
+      assetMode: "copy",
+      astro: { assetsDir, assetsBaseUrl: "/stories/assets" }
+    }).generate(canonical);
+    const bundledAssets = bundleExplorerAssets(reportPath, assetsDir);
+    let apiPages = 0;
+    if (options.openapiPath) {
+      const res = await importOpenApi({
+        specPath: path13.resolve(options.openapiPath),
+        outputDir: apiDir,
+        runFile: reportPath,
+        force: true
+      });
+      apiPages = res.pageCount;
+    }
+    return { siteDir, bundledAssets, apiPages };
+  } catch (err) {
+    if (err instanceof BuildDocsError) throw err;
+    throw new BuildDocsError(`Generation failed: ${err.message}`, "generation");
   }
 }
 
 // src/config.ts
-import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve6 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { resolve as resolve9 } from "path";
 async function loadConfig(configPath) {
-  const resolved = configPath ? resolve6(configPath) : resolve6(process.cwd(), "executable-stories.config.js");
-  if (!existsSync7(resolved)) return {};
+  const resolved = configPath ? resolve9(configPath) : resolve9(process.cwd(), "executable-stories.config.js");
+  if (!existsSync11(resolved)) return {};
   const mod = await import(resolved);
   const config = mod.default;
   if (!config || typeof config !== "object" || Array.isArray(config)) {
@@ -20729,23 +21865,31 @@ USAGE
   executable-stories validate <file>
   executable-stories validate --stdin
   executable-stories init-astro [directory]
+  executable-stories new <template> "<name>" [options]
+  executable-stories check-links <dir> [options]
+  executable-stories import-openapi <spec> [options]
   executable-stories publish-confluence <file.adf.json> [options]
   executable-stories publish-jira <file.adf.json> [options]
 
 SUBCOMMANDS
   format             Read raw test results and generate reports
+  watch              Regenerate reports whenever the raw-run file changes (live agent index)
   compare            Compare two runs and generate a diff report
   review             Generate an Evidence Review of AI-authored changes (correlate a run to the diff)
   list               List scenarios from a test run (text table or JSON)
   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)
+  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
   publish-jira       Publish an ADF JSON file to a Jira issue (as comment or description)
 
 OPTIONS
-  --format <formats>            Comma-separated formats: html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, astro, confluence, story-report-json, or custom names from config (default: html)
+  --format <formats>            Comma-separated formats: html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, astro, confluence, story-report-json, scenario-index-json, behavior-manifest-json, or custom names from config (default: html)
                                   astro             Themed Markdown (for Astro docs sites with matching CSS)
                                   confluence        Atlassian Document Format (ADF) JSON for Confluence / Jira
+                                  behavior-manifest-json Agent-readable behavior manifest and debugger warnings
                                   html              Custom HTML report (accessible, dark mode, mermaid)
                                   cucumber-html     Official Cucumber HTML report
                                   markdown          Markdown documentation
@@ -20753,6 +21897,7 @@ OPTIONS
                                   cucumber-json     Cucumber JSON
                                   cucumber-messages Raw NDJSON (Cucumber Messages)
                                   story-report-json StoryReport v1 JSON (consumed by executable-stories-react and other UI renderers)
+                                  scenario-index-json Storybook-like scenario index for agents and explorers
   --config <path>               Path to executable-stories.config.js (default: ./executable-stories.config.js)
   --input-type <type>           Input type: raw, canonical, or ndjson (default: raw)
   --output-dir <dir>            Output directory (default: reports)
@@ -20863,9 +22008,9 @@ async function parseCliArgs(argv) {
     process.exit(EXIT_SUCCESS);
   }
   const subcommand = args[0];
-  if (subcommand !== "format" && subcommand !== "compare" && subcommand !== "review" && subcommand !== "list" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
+  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "review" && subcommand !== "list" && 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", "compare", "review", "list", "validate", "init-astro", "publish-confluence", or "publish-jira".`
+      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "review", "list", "validate", "init-astro", "build-docs", "new", "check-links", "import-openapi", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -20881,8 +22026,14 @@ async function parseCliArgs(argv) {
     const initArgs = args.slice(1);
     const targetDir = initArgs.find((a) => !a.startsWith("--")) ?? "./story-docs";
     const force = initArgs.includes("--force");
+    const update = initArgs.includes("--update");
     try {
-      const result = initAstro({ targetDir, force });
+      const result = initAstro({ targetDir, force, update });
+      if (update) {
+        console.log(`Updated framework files in ${result.targetDir} (content left untouched)`);
+        console.log(`  Refreshed: ${result.updatedFiles?.length ?? 0} file(s)`);
+        process.exit(EXIT_SUCCESS);
+      }
       console.log(`Scaffolded Astro docs site at ${result.targetDir}`);
       console.log("");
       console.log("Themes available in src/styles/themes/:");
@@ -20895,20 +22046,26 @@ async function parseCliArgs(argv) {
       console.log("");
       console.log("To change theme, edit astro.config.mjs customCss array.");
       console.log("");
-      console.log("");
       console.log("Next steps:");
       console.log(`  cd ${result.targetDir}`);
       console.log("  pnpm install    # or npm install");
       console.log("  pnpm dev        # start the dev server");
       console.log("");
-      console.log("Generate story docs with:");
-      console.log(`  executable-stories format run.json --format astro --output-dir ${result.targetDir}/src/content/docs/stories --asset-mode copy`);
+      console.log("Generate everything (story pages, explorer data, API pages) in one step:");
+      console.log(`  executable-stories build-docs run.json --site-dir ${result.targetDir} [--openapi spec.json]`);
+      console.log("");
+      console.log("Later, pull template/design improvements without losing your content:");
+      console.log(`  executable-stories init-astro ${result.targetDir} --update`);
       process.exit(EXIT_SUCCESS);
     } catch (err) {
       console.error(`Error: ${err.message}`);
       process.exit(EXIT_USAGE);
     }
   }
+  if (subcommand === "new") process.exit(runNew(args.slice(1)));
+  if (subcommand === "check-links") process.exit(await runCheckLinks(args.slice(1)));
+  if (subcommand === "import-openapi") process.exit(await runImportOpenApi(args.slice(1)));
+  if (subcommand === "build-docs") process.exit(await runBuildDocs(args.slice(1)));
   const { values, positionals } = parseArgs({
     args: args.slice(1),
     options: {
@@ -21004,7 +22161,7 @@ async function parseCliArgs(argv) {
   }
   const pluginConfig = await loadConfig(values["config"]);
   const customFormatterNames = new Set(Object.keys(pluginConfig.formatters ?? {}));
-  const builtInFormats = /* @__PURE__ */ new Set(["astro", "confluence", "html", "markdown", "junit", "cucumber-json", "cucumber-messages", "cucumber-html", "story-report-json"]);
+  const builtInFormats = /* @__PURE__ */ new Set(["astro", "behavior-manifest-json", "confluence", "html", "markdown", "junit", "cucumber-json", "cucumber-messages", "cucumber-html", "scenario-index-json", "story-report-json"]);
   const formatStr = values.format;
   const allRequestedFormats = formatStr.split(",").map((f) => f.trim());
   const builtInRequested = allRequestedFormats.filter((f) => builtInFormats.has(f));
@@ -21012,7 +22169,7 @@ async function parseCliArgs(argv) {
   const unknownFormats = allRequestedFormats.filter((f) => !builtInFormats.has(f) && !customFormatterNames.has(f));
   if (unknownFormats.length > 0) {
     const knownCustom = customFormatterNames.size > 0 ? `, ${[...customFormatterNames].join(", ")}` : "";
-    console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: astro, confluence, html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, story-report-json${knownCustom}.`);
+    console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: astro, behavior-manifest-json, confluence, html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, scenario-index-json, story-report-json${knownCustom}.`);
     process.exit(EXIT_USAGE);
   }
   const formats = builtInRequested;
@@ -21164,27 +22321,27 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path9.resolve(args.inputFile);
-  if (!fs8.existsSync(filePath)) {
+  const filePath = path14.resolve(args.inputFile);
+  if (!fs13.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(filePath, "utf8");
+  return fs13.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path9.resolve(filePath);
-  if (!fs8.existsSync(resolved)) {
+  const resolved = path14.resolve(filePath);
+  if (!fs13.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(resolved, "utf8");
+  return fs13.readFileSync(resolved, "utf8");
 }
 function readStdin() {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve11, reject) => {
     const chunks = [];
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve8(chunks.join("")));
+    process.stdin.on("end", () => resolve11(chunks.join("")));
     process.stdin.on("error", reject);
   });
 }
@@ -21310,14 +22467,14 @@ function tryNormalizeRunFromText(text2, args) {
   }
 }
 function listBaselineCandidates(currentFile, args) {
-  const baselineDir = path9.resolve(args.baselineDir ?? path9.dirname(currentFile));
-  const currentResolved = path9.resolve(currentFile);
-  if (!fs8.existsSync(baselineDir)) {
+  const baselineDir = path14.resolve(args.baselineDir ?? path14.dirname(currentFile));
+  const currentResolved = path14.resolve(currentFile);
+  if (!fs13.existsSync(baselineDir)) {
     console.error(`Error: baseline directory not found: ${baselineDir}`);
     process.exit(EXIT_USAGE);
   }
-  const entries = fs8.readdirSync(baselineDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile()).map((entry) => path9.join(baselineDir, entry.name)).filter((candidate) => path9.resolve(candidate) !== currentResolved).filter(
+  const entries = fs13.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path14.join(baselineDir, entry.name)).filter((candidate) => path14.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -21325,14 +22482,14 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   const candidates = listBaselineCandidates(currentFile, args);
   const comparable = [];
   for (const candidate of candidates) {
-    const run = tryNormalizeRunFromText(fs8.readFileSync(candidate, "utf8"), args);
+    const run = tryNormalizeRunFromText(fs13.readFileSync(candidate, "utf8"), args);
     if (run) {
       comparable.push({ file: candidate, run });
     }
   }
   if (comparable.length === 0) {
     console.error(
-      `Error: no compatible baseline files found in ${path9.resolve(args.baselineDir ?? path9.dirname(currentFile))}.`
+      `Error: no compatible baseline files found in ${path14.resolve(args.baselineDir ?? path14.dirname(currentFile))}.`
     );
     process.exit(EXIT_USAGE);
   }
@@ -21409,6 +22566,24 @@ async function main() {
     console.log(output);
     process.exit(EXIT_SUCCESS);
   }
+  if (args.subcommand === "watch") {
+    if (!args.inputFile) {
+      console.error("Error: watch requires an input file (the raw-run JSON the framework writes).");
+      process.exit(EXIT_USAGE);
+    }
+    console.log(
+      `Watching ${args.inputFile} \u2192 regenerating [${args.formats.join(", ")}] into ${args.outputDir}/ (Ctrl+C to stop)`
+    );
+    startWatch({
+      input: args.inputFile,
+      outputDir: args.outputDir,
+      outputName: args.outputName,
+      formats: args.formats,
+      inputType: args.inputType === "canonical" ? "canonical" : "raw",
+      synthesize: args.synthesizeStories
+    });
+    return;
+  }
   const text2 = await readInput(args);
   if (args.inputType === "ndjson") {
     if (args.subcommand === "validate") {
@@ -21452,9 +22627,9 @@ async function main() {
       process.exit(EXIT_SCHEMA_VALIDATION);
     }
     if (args.emitCanonical) {
-      const outPath = path9.resolve(args.emitCanonical);
-      fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-      fs8.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path14.resolve(args.emitCanonical);
+      fs13.mkdirSync(path14.dirname(outPath), { recursive: true });
+      fs13.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -21511,9 +22686,9 @@ ${msg}`);
     }
     const run = data;
     if (args.emitCanonical) {
-      const outPath = path9.resolve(args.emitCanonical);
-      fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-      fs8.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path14.resolve(args.emitCanonical);
+      fs13.mkdirSync(path14.dirname(outPath), { recursive: true });
+      fs13.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -21569,9 +22744,9 @@ ${msg}`);
     process.exit(EXIT_CANONICAL_VALIDATION);
   }
   if (args.emitCanonical) {
-    const outPath = path9.resolve(args.emitCanonical);
-    fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-    fs8.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
+    const outPath = path14.resolve(args.emitCanonical);
+    fs13.mkdirSync(path14.dirname(outPath), { recursive: true });
+    fs13.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
@@ -21596,9 +22771,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 = path9.join(outputDir, filename);
-      fs8.mkdirSync(outputDir, { recursive: true });
-      fs8.writeFileSync(filepath, content, "utf8");
+      const filepath = path14.join(outputDir, filename);
+      fs13.mkdirSync(outputDir, { recursive: true });
+      fs13.writeFileSync(filepath, content, "utf8");
       console.log(`Generated: ${filepath}`);
     } catch (err) {
       console.error(`Error running custom formatter "${formatName}": ${err instanceof Error ? err.message : String(err)}`);
@@ -21648,13 +22823,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return;
-  const historyPath = path9.resolve(args.historyFile);
+  const historyPath = path14.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs8.readFileSync(p, "utf8");
+          return fs13.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -21667,11 +22842,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path9.dirname(historyPath);
-  fs8.mkdirSync(dir, { recursive: true });
+  const dir = path14.dirname(historyPath);
+  fs13.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs8.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs13.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -21818,11 +22993,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)}` : "";
-  fs8.mkdirSync(outputDir, { recursive: true });
-  const mdPath = path9.join(outputDir, `${baseName}${suffix}.md`);
-  const htmlPath = path9.join(outputDir, `${baseName}${suffix}.html`);
-  fs8.writeFileSync(mdPath, markdown, "utf8");
-  fs8.writeFileSync(htmlPath, html, "utf8");
+  fs13.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path14.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path14.join(outputDir, `${baseName}${suffix}.html`);
+  fs13.writeFileSync(mdPath, markdown, "utf8");
+  fs13.writeFileSync(htmlPath, html, "utf8");
   return [mdPath, htmlPath];
 }
 function evaluateReviewGate(review, args) {
@@ -21868,9 +23043,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 = path9.resolve(args.prSummaryFile);
-    fs8.mkdirSync(path9.dirname(outputPath), { recursive: true });
-    fs8.writeFileSync(outputPath, result.prSummary, "utf8");
+    const outputPath = path14.resolve(args.prSummaryFile);
+    fs13.mkdirSync(path14.dirname(outputPath), { recursive: true });
+    fs13.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -21961,7 +23136,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 (!fs8.existsSync(inputFile)) {
+  if (!fs13.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -21989,7 +23164,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 = fs8.readFileSync(path9.resolve(inputFile), "utf8");
+  const adf = fs13.readFileSync(path14.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -22068,7 +23243,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 (!fs8.existsSync(inputFile)) {
+  if (!fs13.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -22095,7 +23270,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     process.exit(EXIT_USAGE);
   }
   const mode = modeRaw;
-  const adf = fs8.readFileSync(path9.resolve(inputFile), "utf8");
+  const adf = fs13.readFileSync(path14.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -22136,6 +23311,142 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     process.exit(EXIT_GENERATION);
   }
 }
+function runNew(rawArgs) {
+  const { values, positionals } = parseArgs({
+    args: rawArgs,
+    options: { dir: { type: "string" }, force: { type: "boolean", default: false } },
+    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(`Templates: ${TEMPLATES.join(", ")}`);
+    return EXIT_USAGE;
+  }
+  try {
+    const result = scaffoldDoc({
+      template,
+      name,
+      baseDir: values.dir,
+      force: values.force
+    });
+    console.log(`Created ${result.template}: ${result.path}`);
+    console.log(`  Title: ${result.title}`);
+    console.log("");
+    console.log("Next: fill in the content and link verifying stories in `verifiedBy`.");
+    return EXIT_SUCCESS;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return EXIT_USAGE;
+  }
+}
+async function runCheckLinks(rawArgs) {
+  const { values, positionals } = parseArgs({
+    args: rawArgs,
+    options: {
+      external: { type: "boolean", default: false },
+      json: { type: "boolean", default: false }
+    },
+    allowPositionals: true,
+    strict: true
+  });
+  try {
+    const report = await checkLinks({
+      target: positionals[0] ?? ".",
+      checkExternal: values.external
+    });
+    console.log(values.json ? JSON.stringify(report, null, 2) : formatLinkReport(report));
+    return report.brokenCount > 0 ? EXIT_GENERATION : EXIT_SUCCESS;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return EXIT_USAGE;
+  }
+}
+async function runImportOpenApi(rawArgs) {
+  const { values, positionals } = parseArgs({
+    args: rawArgs,
+    options: {
+      "output-dir": { type: "string" },
+      run: { type: "string" },
+      force: { type: "boolean", default: false }
+    },
+    allowPositionals: true,
+    strict: true
+  });
+  const spec = positionals[0];
+  if (!spec) {
+    console.error(`Usage: executable-stories import-openapi <spec.json|yaml> [--output-dir <dir>] [--run <story-report.json>] [--force]`);
+    return EXIT_USAGE;
+  }
+  try {
+    const result = await importOpenApi({
+      specPath: spec,
+      outputDir: values["output-dir"],
+      runFile: values.run,
+      force: values.force
+    });
+    console.log(`Generated ${result.pageCount} API page(s) at ${result.outputDir}`);
+    console.log(`  Covered endpoints: ${result.coveredCount} / ${result.endpointCount}`);
+    if (result.uncoveredCount > 0) {
+      console.log(`  \u26A0 ${result.uncoveredCount} endpoint(s) have no verifying story`);
+    }
+    return EXIT_SUCCESS;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return EXIT_USAGE;
+  }
+}
+async function runBuildDocs(rawArgs) {
+  const { values, positionals } = parseArgs({
+    args: rawArgs,
+    options: {
+      "site-dir": { type: "string" },
+      openapi: { type: "string" },
+      "no-synthesize-stories": { type: "boolean", default: false }
+    },
+    allowPositionals: true,
+    strict: true
+  });
+  const rawRunPath = positionals[0];
+  if (!rawRunPath) {
+    console.error(
+      `Usage: executable-stories build-docs <raw-run.json> [--site-dir <dir>] [--openapi <spec>]`
+    );
+    return EXIT_USAGE;
+  }
+  try {
+    const result = await buildDocs({
+      rawRunPath,
+      siteDir: values["site-dir"] ?? ".",
+      openapiPath: values.openapi,
+      synthesizeStories: !values["no-synthesize-stories"]
+    });
+    console.log(`\u2713 Living docs generated in ${result.siteDir}`);
+    console.log(`  \u2022 Explorer data   \u2192 public/stories/story-report.json`);
+    console.log(`  \u2022 Story pages     \u2192 src/content/docs/stories`);
+    if (result.bundledAssets > 0) {
+      console.log(`  \u2022 Bundled assets  \u2192 public/stories/assets (${result.bundledAssets})`);
+    }
+    if (result.apiPages > 0) {
+      console.log(`  \u2022 API pages       \u2192 src/content/docs/api (${result.apiPages})`);
+    }
+    const rel = path14.relative(process.cwd(), result.siteDir) || ".";
+    console.log(`
+Preview: cd ${rel} && npm run dev`);
+    return EXIT_SUCCESS;
+  } catch (err) {
+    if (err instanceof BuildDocsError) {
+      console.error(err.message);
+      if (err.kind === "schema") return EXIT_SCHEMA_VALIDATION;
+      if (err.kind === "generation") return EXIT_GENERATION;
+      return EXIT_USAGE;
+    }
+    console.error(`Error: ${err.message}`);
+    return EXIT_USAGE;
+  }
+}
 main().catch((err) => {
   console.error(err);
   process.exit(EXIT_USAGE);