executable-stories-formatters 0.9.0 → 0.10.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 fs9 from "fs";
+import * as path10 from "path";
 
 // src/validation/schema-validator.ts
 import Ajv from "ajv/dist/2020.js";
@@ -539,17 +539,17 @@ function validateRawRun(data) {
     return { valid: true, errors: [] };
   }
   const errors = (validate.errors ?? []).map((err) => {
-    const path10 = err.instancePath || "/";
+    const path11 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path10}: ${message} \u2014 '${extra}'`;
+      return `${path11}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path10}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path11}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path10}: ${message}`;
+    return `${path11}: ${message}`;
   });
   return { valid: false, errors };
 }
@@ -1024,7 +1024,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
@@ -1569,6 +1569,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 +1695,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";
@@ -16526,8 +16704,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path10) {
-  const lower = path10.toLowerCase();
+function guessMediaType(path11) {
+  const lower = path11.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 +16846,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((resolve9) => htmlStream.once("drain", resolve9));
       }
     }
-    await new Promise((resolve8, reject) => {
-      collector.on("finish", resolve8);
+    await new Promise((resolve9, reject) => {
+      collector.on("finish", resolve9);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -18283,6 +18461,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;
@@ -19451,12 +19691,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 +19779,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 +19854,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path10) {
-  const base = path10.split("/").pop() ?? path10;
+function extensionOf(path11) {
+  const base = path11.split("/").pop() ?? path11;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path10) {
-  return TEST_INFIX.test(path10);
+function isTestFile(path11) {
+  return TEST_INFIX.test(path11);
 }
-function isReviewableSource(path10) {
-  if (isTestFile(path10)) return false;
-  if (path10.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path10));
+function isReviewableSource(path11) {
+  if (isTestFile(path11)) return false;
+  if (path11.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path11));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -19691,7 +19969,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path10) => sourceBaseKey(path10) === key
+    (path11) => sourceBaseKey(path11) === key
   );
   return {
     id: testCase.id,
@@ -20224,6 +20502,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,6 +20510,7 @@ 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"
 };
 var TEST_EXTENSIONS = [
@@ -20258,11 +20538,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, `${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 +20551,9 @@ 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));
+  return toPosix(path8.posix.join(baseOutputDir, dirOfSource, fileName));
 }
 function groupTestCasesByOutput(testCases, format, options, logger, outputNameSuffix) {
   const groups = /* @__PURE__ */ new Map();
@@ -20359,6 +20639,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 +20760,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 +20792,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, `${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 +20806,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);
@@ -20633,6 +20919,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 +20944,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,23 +20953,23 @@ 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));
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
-  if (fs7.existsSync(targetDir)) {
-    const entries = fs7.readdirSync(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.`
       );
     }
   }
-  const templateDir = path8.resolve(__dirname, "..", "templates", "astro-starlight");
-  if (!fs7.existsSync(templateDir)) {
+  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.`
     );
@@ -20680,24 +20978,24 @@ function initAstro(options = {}) {
   return { targetDir };
 }
 function copyDirRecursive(src, dest) {
-  fs7.mkdirSync(dest, { recursive: true });
-  const entries = fs7.readdirSync(src, { withFileTypes: true });
+  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);
     } else {
-      fs7.copyFileSync(srcPath, destPath);
+      fs8.copyFileSync(srcPath, destPath);
     }
   }
 }
 
 // src/config.ts
 import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 async function loadConfig(configPath) {
-  const resolved = configPath ? resolve6(configPath) : resolve6(process.cwd(), "executable-stories.config.js");
+  const resolved = configPath ? resolve7(configPath) : resolve7(process.cwd(), "executable-stories.config.js");
   if (!existsSync7(resolved)) return {};
   const mod = await import(resolved);
   const config = mod.default;
@@ -20734,6 +21032,7 @@ USAGE
 
 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)
@@ -20743,9 +21042,10 @@ SUBCOMMANDS
   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 +21053,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 +21164,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 !== "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", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -20903,6 +21204,9 @@ async function parseCliArgs(argv) {
       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("");
+      console.log("Generate the Storybook-like scenario explorer data with:");
+      console.log(`  executable-stories format run.json --format story-report-json --output-dir ${result.targetDir}/public/stories --output-name story-report`);
       process.exit(EXIT_SUCCESS);
     } catch (err) {
       console.error(`Error: ${err.message}`);
@@ -21004,7 +21308,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 +21316,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 +21468,27 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path9.resolve(args.inputFile);
-  if (!fs8.existsSync(filePath)) {
+  const filePath = path10.resolve(args.inputFile);
+  if (!fs9.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(filePath, "utf8");
+  return fs9.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path9.resolve(filePath);
-  if (!fs8.existsSync(resolved)) {
+  const resolved = path10.resolve(filePath);
+  if (!fs9.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(resolved, "utf8");
+  return fs9.readFileSync(resolved, "utf8");
 }
 function readStdin() {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, 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", () => resolve9(chunks.join("")));
     process.stdin.on("error", reject);
   });
 }
@@ -21310,14 +21614,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 = path10.resolve(args.baselineDir ?? path10.dirname(currentFile));
+  const currentResolved = path10.resolve(currentFile);
+  if (!fs9.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 = fs9.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path10.join(baselineDir, entry.name)).filter((candidate) => path10.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -21325,14 +21629,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(fs9.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 ${path10.resolve(args.baselineDir ?? path10.dirname(currentFile))}.`
     );
     process.exit(EXIT_USAGE);
   }
@@ -21409,6 +21713,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 +21774,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 = path10.resolve(args.emitCanonical);
+      fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+      fs9.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -21511,9 +21833,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 = path10.resolve(args.emitCanonical);
+      fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+      fs9.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -21569,9 +21891,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 = path10.resolve(args.emitCanonical);
+    fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+    fs9.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
@@ -21596,9 +21918,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 = path10.join(outputDir, filename);
+      fs9.mkdirSync(outputDir, { recursive: true });
+      fs9.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 +21970,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return;
-  const historyPath = path9.resolve(args.historyFile);
+  const historyPath = path10.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs8.readFileSync(p, "utf8");
+          return fs9.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -21667,11 +21989,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path9.dirname(historyPath);
-  fs8.mkdirSync(dir, { recursive: true });
+  const dir = path10.dirname(historyPath);
+  fs9.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs8.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs9.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -21818,11 +22140,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");
+  fs9.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path10.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path10.join(outputDir, `${baseName}${suffix}.html`);
+  fs9.writeFileSync(mdPath, markdown, "utf8");
+  fs9.writeFileSync(htmlPath, html, "utf8");
   return [mdPath, htmlPath];
 }
 function evaluateReviewGate(review, args) {
@@ -21868,9 +22190,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 = path10.resolve(args.prSummaryFile);
+    fs9.mkdirSync(path10.dirname(outputPath), { recursive: true });
+    fs9.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -21961,7 +22283,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 (!fs9.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -21989,7 +22311,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 = fs9.readFileSync(path10.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -22068,7 +22390,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 (!fs9.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -22095,7 +22417,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 = fs9.readFileSync(path10.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(