executable-stories-formatters 1.9.2 → 1.11.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { parseArgs as parseArgs2 } from "util";
-import * as fs15 from "fs";
-import * as path17 from "path";
+import { parseArgs as parseArgs3 } from "util";
+import * as fs17 from "fs";
+import * as path19 from "path";
 
 // src/validation/schema-validator.ts
 import Ajv from "ajv/dist/2020.js";
@@ -941,28 +941,28 @@ function validateRawRun(data) {
     return { valid: true, errors: [] };
   }
   const errors = (validate.errors ?? []).map((err) => {
-    const path18 = err.instancePath || "/";
+    const path20 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path18}: ${message} \u2014 '${extra}'`;
+      return `${path20}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path18}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path20}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path18}: ${message}`;
+    return `${path20}: ${message}`;
   });
   return { valid: false, errors };
 }
 
 // src/cli.ts
-import { synthesizeStories as synthesizeStories3 } from "executable-stories-core/converters/synthesize";
-import { canonicalizeRun as canonicalizeRun5 } from "executable-stories-core/converters/acl/index";
+import { synthesizeStories as synthesizeStories4 } from "executable-stories-core/converters/synthesize";
+import { canonicalizeRun as canonicalizeRun6 } from "executable-stories-core/converters/acl/index";
 import { assertValidRun as assertValidRun2 } from "executable-stories-core/converters/acl/validate";
 
 // src/index.ts
-import * as path7 from "path";
+import * as path8 from "path";
 import * as fsPromises from "fs/promises";
 import { toStoryReportWithIndex } from "executable-stories-core/converters/story-report";
 
@@ -1610,50 +1610,50 @@ function scenarioLines(scenario) {
   if (scenario.errorMessage) lines.push(indent(`error: ${scenario.errorMessage}`, "  "));
   return lines;
 }
-function docLines(entry, pad) {
-  const lines = ownDocLines(entry, pad);
-  for (const child of entry.children ?? []) lines.push(...docLines(child, pad + "  "));
+function docLines(entry, pad2) {
+  const lines = ownDocLines(entry, pad2);
+  for (const child of entry.children ?? []) lines.push(...docLines(child, pad2 + "  "));
   return lines;
 }
-function ownDocLines(entry, pad) {
+function ownDocLines(entry, pad2) {
   switch (entry.kind) {
     case "note":
-      return [indent(entry.text, pad)];
+      return [indent(entry.text, pad2)];
     case "tag":
       return [];
     // already on the scenario's tag line
     case "kv":
-      return [`${pad}${entry.label}: ${compact(entry.value)}`];
+      return [`${pad2}${entry.label}: ${compact(entry.value)}`];
     case "code":
-      return [`${pad}code ${entry.label}${entry.lang ? ` (${entry.lang})` : ""}:`, indent(entry.content, pad + "  ")];
+      return [`${pad2}code ${entry.label}${entry.lang ? ` (${entry.lang})` : ""}:`, indent(entry.content, pad2 + "  ")];
     case "table":
       return [
-        `${pad}table ${entry.label}: ${entry.columns.join(" | ")}`,
-        ...entry.rows.map((row) => `${pad}  ${row.join(" | ")}`)
+        `${pad2}table ${entry.label}: ${entry.columns.join(" | ")}`,
+        ...entry.rows.map((row) => `${pad2}  ${row.join(" | ")}`)
       ];
     case "link":
-      return [`${pad}link ${entry.label}: ${entry.url}`];
+      return [`${pad2}link ${entry.label}: ${entry.url}`];
     case "section":
-      return [`${pad}section ${entry.title}:`, indent(entry.markdown, pad + "  ")];
+      return [`${pad2}section ${entry.title}:`, indent(entry.markdown, pad2 + "  ")];
     case "mermaid":
-      return [`${pad}mermaid${entry.title ? ` ${entry.title}` : ""}:`, indent(entry.code, pad + "  ")];
+      return [`${pad2}mermaid${entry.title ? ` ${entry.title}` : ""}:`, indent(entry.code, pad2 + "  ")];
     case "screenshot":
-      return [`${pad}screenshot ${entry.path}${entry.alt ? ` \u2014 ${entry.alt}` : ""}`];
+      return [`${pad2}screenshot ${entry.path}${entry.alt ? ` \u2014 ${entry.alt}` : ""}`];
     case "video":
-      return [`${pad}video ${entry.path}${entry.caption ? ` \u2014 ${entry.caption}` : ""}`];
+      return [`${pad2}video ${entry.path}${entry.caption ? ` \u2014 ${entry.caption}` : ""}`];
     case "html":
-      return [`${pad}html ${entry.title ?? entry.path ?? entry.url ?? "(inline)"}`];
+      return [`${pad2}html ${entry.title ?? entry.path ?? entry.url ?? "(inline)"}`];
     case "state":
-      return [`${pad}state${entry.label ? ` ${entry.label}` : ""}: ${compact(entry.value)}`];
+      return [`${pad2}state${entry.label ? ` ${entry.label}` : ""}: ${compact(entry.value)}`];
     case "custom":
-      return [`${pad}custom ${entry.type}: ${compact(entry.data)}`];
+      return [`${pad2}custom ${entry.type}: ${compact(entry.data)}`];
   }
 }
 function compact(value) {
   return typeof value === "string" ? value : JSON.stringify(value);
 }
-function indent(text2, pad) {
-  return text2.split("\n").map((line) => pad + line).join("\n");
+function indent(text2, pad2) {
+  return text2.split("\n").map((line) => pad2 + line).join("\n");
 }
 
 // src/formatters/junit-xml.ts
@@ -2556,9 +2556,9 @@ var MAX_FUZZ = 2;
 var normalize = (line) => line.trim();
 var HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@ ?(.*)$/;
 function stripPathPrefix(raw) {
-  const path18 = raw.split("	")[0].trim();
-  if (path18 === "/dev/null") return void 0;
-  return path18.replace(/^[ab]\//, "");
+  const path20 = raw.split("	")[0].trim();
+  if (path20 === "/dev/null") return void 0;
+  return path20.replace(/^[ab]\//, "");
 }
 function parseUnifiedDiff(patch) {
   const files = [];
@@ -2638,7 +2638,7 @@ function createAnchor(args) {
   };
 }
 function changedRunCandidates(anchor, file, fileIndex) {
-  const path18 = file.newPath ?? file.oldPath ?? "";
+  const path20 = file.newPath ?? file.oldPath ?? "";
   const out = [];
   file.hunks.forEach((hunk, hunkIndex) => {
     outer: for (let i = 0; i + anchor.changed.length <= hunk.lines.length; i++) {
@@ -2649,7 +2649,7 @@ function changedRunCandidates(anchor, file, fileIndex) {
           continue outer;
         }
       }
-      out.push({ fileIndex, file: path18, hunkIndex, lineIndex: i, lines: hunk.lines });
+      out.push({ fileIndex, file: path20, hunkIndex, lineIndex: i, lines: hunk.lines });
     }
   });
   return out;
@@ -2746,18 +2746,18 @@ function deriveChangeType(tags) {
   }
   return "unknown";
 }
-function extensionOf(path18) {
-  const base = path18.split("/").pop() ?? path18;
+function extensionOf(path20) {
+  const base = path20.split("/").pop() ?? path20;
   const dot = base.lastIndexOf(".");
   return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
 }
-function isTestFile(path18) {
-  return TEST_INFIX.test(path18);
+function isTestFile(path20) {
+  return TEST_INFIX.test(path20);
 }
-function isReviewableSource(path18) {
-  if (isTestFile(path18)) return false;
-  if (path18.endsWith(".d.ts")) return false;
-  return CODE_EXTENSIONS.has(extensionOf(path18));
+function isReviewableSource(path20) {
+  if (isTestFile(path20)) return false;
+  if (path20.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path20));
 }
 function testBaseKey(testFile) {
   return testFile.replace(TEST_INFIX, "");
@@ -2861,7 +2861,7 @@ function toClaim(testCase, changedSourcePaths) {
   const { strength, reasons } = gradeEvidence(testCase, audience);
   const key = testBaseKey(testCase.sourceFile);
   const coversFiles = changedSourcePaths.filter(
-    (path18) => sourceBaseKey(path18) === key
+    (path20) => sourceBaseKey(path20) === key
   );
   return {
     id: testCase.id,
@@ -3033,14 +3033,14 @@ var TraceabilityMatrixFormatter = class {
       lines.push("");
       lines.push(`Status: ${renderRequirementStatus(req.status)}`);
       if (req.covers.length > 0) {
-        lines.push(`Covers: ${req.covers.map((path18) => `\`${path18}\``).join(", ")}`);
+        lines.push(`Covers: ${req.covers.map((path20) => `\`${path20}\``).join(", ")}`);
       }
       lines.push("");
       lines.push("| Status | Scenario | Source | Covers |");
       lines.push("| --- | --- | --- | --- |");
       for (const scenario of req.scenarios) {
         const source = `${scenario.sourceFile}:${scenario.sourceLine}`;
-        const covers = scenario.covers.length > 0 ? scenario.covers.map((path18) => `\`${path18}\``).join(", ") : "";
+        const covers = scenario.covers.length > 0 ? scenario.covers.map((path20) => `\`${path20}\``).join(", ") : "";
         lines.push(`| ${scenario.status} | ${escapePipe2(scenario.title)} | \`${source}\` | ${covers} |`);
       }
       lines.push("");
@@ -3483,9 +3483,9 @@ function buildDataTable(table2, line) {
     const rowLine = line + 1 + r;
     rows.push({
       location: { line: rowLine },
-      cells: table2.rows[r].map((cell) => ({
+      cells: table2.rows[r].map((cell2) => ({
         location: { line: rowLine },
-        value: cell
+        value: cell2
       })),
       id: ""
     });
@@ -3586,7 +3586,7 @@ function buildPickleTable(table2) {
   });
   for (const row of table2.rows) {
     rows.push({
-      cells: row.map((cell) => ({ value: cell }))
+      cells: row.map((cell2) => ({ value: cell2 }))
     });
   }
   return { rows };
@@ -3805,8 +3805,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path18) {
-  const lower = path18.toLowerCase();
+function guessMediaType(path20) {
+  const lower = path20.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";
@@ -3947,11 +3947,11 @@ var CucumberHtmlFormatter = class {
     for (const envelope of envelopes) {
       const accepted = htmlStream.write(envelope);
       if (!accepted) {
-        await new Promise((resolve10) => htmlStream.once("drain", resolve10));
+        await new Promise((resolve12) => htmlStream.once("drain", resolve12));
       }
     }
-    await new Promise((resolve10, reject) => {
-      collector.on("finish", resolve10);
+    await new Promise((resolve12, reject) => {
+      collector.on("finish", resolve12);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -4685,7 +4685,7 @@ function formatDocEntry(doc) {
       return `${escapeHtml2(doc.label)}${doc.lang ? ` (${escapeHtml2(doc.lang)})` : ""}: <code>${escapeHtml2(doc.content)}</code>`;
     case "table": {
       const header = `<tr>${doc.columns.map((c) => `<th>${escapeHtml2(c)}</th>`).join("")}</tr>`;
-      const rows = doc.rows.map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml2(cell)}</td>`).join("")}</tr>`).join("");
+      const rows = doc.rows.map((row) => `<tr>${row.map((cell2) => `<td>${escapeHtml2(cell2)}</td>`).join("")}</tr>`).join("");
       return `${escapeHtml2(doc.label)}<table>${header}${rows}</table>`;
     }
     case "link":
@@ -5722,7 +5722,7 @@ ${tc.errorStack}` : "");
           table([
             tableRow(entry.columns.map((c) => tableHeader(c))),
             ...entry.rows.map(
-              (row) => tableRow(row.map((cell) => tableCell(cell)))
+              (row) => tableRow(row.map((cell2) => tableCell(cell2)))
             )
           ])
         );
@@ -6157,230 +6157,1611 @@ function replaceAssetRefInData(html, original, replacement) {
 
 // src/index.ts
 import { STORY_META_KEY } from "executable-stories-core/types/story";
-import {
-  STORY_REPORT_SCHEMA_VERSION,
-  STORY_REPORT_SCHEMA_MAJOR
-} from "executable-stories-core/types/story-report";
-import { ES_THEME_TOKENS_CSS as ES_THEME_TOKENS_CSS2, ES_THEME_TOKEN_VALUES } from "executable-stories-core/theme/tokens";
-import { canonicalizeRun as canonicalizeRun3 } from "executable-stories-core/converters/acl/index";
-import { normalizeStatus } from "executable-stories-core/converters/acl/index";
-import { generateTestCaseId } from "executable-stories-core/converters/acl/index";
-import { generateRunId } from "executable-stories-core/converters/acl/index";
-import { slugify as slugify2 } from "executable-stories-core/converters/acl/index";
-import { deriveStepResults } from "executable-stories-core/converters/acl/index";
-import { mergeStepResults } from "executable-stories-core/converters/acl/index";
-import { resolveAttachment } from "executable-stories-core/converters/acl/index";
-import { resolveAttachments } from "executable-stories-core/converters/acl/index";
-import {
-  validateCanonicalRun,
-  assertValidRun
-} from "executable-stories-core/converters/acl/validate";
 
-// src/watch.ts
+// src/sync/engine.ts
+import { behaviourFingerprint as behaviourFingerprint2, behaviourSimilarity as behaviourSimilarity2 } from "executable-stories-core/converters/acl/ids";
+
+// src/sync/lockfile.ts
 import * as fs4 from "fs";
 import * as path5 from "path";
-import { canonicalizeRun } from "executable-stories-core/converters/acl/index";
-import { synthesizeStories } from "executable-stories-core/converters/synthesize";
-function toRun(data, inputType, synthesize) {
-  if (inputType === "canonical") return data;
-  let raw = data;
-  if (synthesize) raw = synthesizeStories(raw);
-  return canonicalizeRun(raw);
-}
-async function regenerateRun(options, deps = {}) {
-  const read = deps.readFile ?? ((filePath) => fs4.readFileSync(filePath, "utf8"));
-  const data = JSON.parse(read(path5.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
+import { createHash as createHash5 } from "crypto";
+var DEFAULT_LOCKFILE_PATH = ".executable-stories/sync.lock.json";
+var LOCKFILE_VERSION = 1;
+function emptyLockfile() {
+  return { version: LOCKFILE_VERSION, providers: {} };
+}
+function hashCaseBody(body) {
+  const canonical = JSON.stringify({
+    title: body.title.trim(),
+    steps: body.steps.map((s) => `${s.keyword.toLowerCase()}:${s.text.trim()}`),
+    description: body.description.trim()
   });
-  const result = await generator.generate(run);
-  return { files: [...result.values()].flat(), run };
-}
-async function regenerateArtifacts(options, deps = {}) {
-  return (await regenerateRun(options, deps)).files;
-}
-function startWatch(options, deps = {}) {
-  const log = deps.log ?? ((message) => console.log(message));
-  const regenerate = deps.regenerate ?? ((input) => regenerateArtifacts({ ...options, input }, deps));
-  const watchFn = deps.watch ?? ((filePath, listener) => fs4.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(path5.resolve(options.input), trigger);
-  return {
-    close: () => {
-      if (timer) clearTimeout(timer);
-      watcher.close();
-    }
-  };
+  return createHash5("sha1").update(canonical).digest("hex").slice(0, 16);
 }
-
-// src/index.ts
-import { advanceState, initialRunState } from "executable-stories-core";
-import { toStoryReport as toStoryReport6 } from "executable-stories-core/converters/story-report";
-
-// src/publishers/confluence.ts
-function parseAdf(adf) {
+function parseLockfile(contents, label) {
   let parsed;
   try {
-    parsed = JSON.parse(adf);
+    parsed = JSON.parse(contents);
   } catch (err) {
     throw new Error(
-      `ADF payload is not valid JSON: ${err.message}`
+      `Sync lockfile at ${label} is not valid JSON: ${err.message}
+Fix or delete it \u2014 deleting orphans every existing case binding, so prefer fixing.`
     );
   }
-  if (!parsed || typeof parsed !== "object" || parsed.type !== "doc" || !Array.isArray(parsed.content)) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Sync lockfile at ${label} must contain an object.`);
+  }
+  const lock = parsed;
+  if (lock.version !== LOCKFILE_VERSION) {
     throw new Error(
-      `ADF payload must be an object with { version, type: "doc", content: [...] }`
+      `Sync lockfile at ${label} has version ${String(lock.version)}, expected ${LOCKFILE_VERSION}.`
     );
   }
-  return parsed;
+  return { version: LOCKFILE_VERSION, providers: lock.providers ?? {} };
 }
-function basicAuthHeader(auth) {
-  const raw = `${auth.email}:${auth.token}`;
-  const encoded = typeof Buffer !== "undefined" ? Buffer.from(raw, "utf8").toString("base64") : btoa(raw);
-  return `Basic ${encoded}`;
+function serializeLockfile(lock) {
+  const providers = {};
+  for (const provider of Object.keys(lock.providers).sort()) {
+    const entries = lock.providers[provider] ?? {};
+    const sorted = {};
+    for (const key of Object.keys(entries).sort()) sorted[key] = entries[key];
+    providers[provider] = sorted;
+  }
+  return `${JSON.stringify({ version: LOCKFILE_VERSION, providers }, null, 2)}
+`;
 }
-async function parseErrorBody(response) {
-  try {
-    const body = await response.text();
-    return body ? body.slice(0, 800) : "";
-  } catch {
-    return "";
+function entriesFor(lock, provider) {
+  return lock.providers[provider] ?? {};
+}
+function setEntry(lock, provider, fingerprint, entry) {
+  lock.providers[provider] ??= {};
+  lock.providers[provider][fingerprint] = entry;
+}
+
+// src/sync/engine.ts
+var DEFAULT_DUPLICATE_THRESHOLD = 0.7;
+var PARTIAL_RUN_ORPHAN_RATIO = 0.25;
+function normalizeTitle(text2) {
+  return text2.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
+}
+function renderDocs(docs, depth = 0) {
+  if (!docs || docs.length === 0) return "";
+  const lines = [];
+  for (const doc of docs) {
+    switch (doc.kind) {
+      case "note":
+        lines.push(doc.text);
+        break;
+      case "kv":
+        lines.push(`**${doc.label}:** ${formatValue(doc.value)}`);
+        break;
+      case "state":
+        lines.push(`**${doc.label ?? "State"}:** ${formatValue(doc.value)}`);
+        break;
+      case "code":
+        lines.push(`**${doc.label}**`, "", "```" + (doc.lang ?? ""), doc.content, "```");
+        break;
+      case "table":
+        lines.push(
+          `**${doc.label}**`,
+          "",
+          `| ${doc.columns.join(" | ")} |`,
+          `| ${doc.columns.map(() => "---").join(" | ")} |`,
+          ...doc.rows.map((row) => `| ${row.join(" | ")} |`)
+        );
+        break;
+      case "link":
+        lines.push(`[${doc.label}](${doc.url})`);
+        break;
+      case "section":
+        lines.push(`${"#".repeat(Math.min(6, depth + 3))} ${doc.title}`, "", doc.markdown);
+        break;
+      case "mermaid":
+        lines.push(...doc.title ? [`**${doc.title}**`, ""] : [], "```mermaid", doc.code, "```");
+        break;
+      case "screenshot":
+        lines.push(`_Screenshot: ${doc.alt ?? doc.path}_`);
+        break;
+      case "video":
+        lines.push(`_Video: ${doc.caption ?? doc.path}_`);
+        break;
+      case "html":
+        lines.push(`_Embedded: ${doc.title ?? doc.url ?? doc.path ?? "html"}_`);
+        break;
+      case "custom":
+        lines.push(`_${doc.type}_: ${formatValue(doc.data)}`);
+        break;
+      case "tag":
+        break;
+    }
+    const children = renderDocs(doc.children, depth + 1);
+    if (children) lines.push(children);
   }
+  return lines.join("\n");
 }
-async function publishConfluencePage(args, deps) {
-  parseAdf(args.adf);
-  if (!args.pageId && !args.spaceId) {
-    throw new Error(
-      "publishConfluencePage requires either pageId (update) or spaceId (create)"
+function formatValue(value) {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+function scenarioUrl(config, tc) {
+  if (!config.reportUrl) return void 0;
+  const base = config.reportUrl.replace(/\/$/, "");
+  const anchor = config.scenarioAnchor?.(tc);
+  return anchor ? `${base}#${anchor}` : base;
+}
+function toCaseBody(tc, config) {
+  const sections = [];
+  const docs = renderDocs(tc.story.docs);
+  if (docs) sections.push(docs);
+  const tickets = tc.story.tickets ?? [];
+  if (tickets.length > 0) {
+    sections.push(
+      `**Requirements:** ${tickets.map((t) => t.url ? `[${t.id}](${t.url})` : t.id).join(", ")}`
     );
   }
-  if (!args.pageId && !args.title) {
-    throw new Error("Creating a new page requires a title");
+  if (tc.story.covers?.length) {
+    sections.push(`**Covers:** ${tc.story.covers.join(", ")}`);
   }
-  const base = args.baseUrl.replace(/\/$/, "");
-  const fetchFn = deps.fetch ?? globalThis.fetch;
-  if (!fetchFn) {
-    throw new Error("No fetch implementation available (Node >= 22 expected)");
+  sections.push(`_Generated from ${tc.sourceFile}:${tc.sourceLine} by executable-stories. Edit the test, not this case._`);
+  const links = [];
+  const report = scenarioUrl(config, tc);
+  if (report) links.push({ label: "Living documentation", url: report });
+  for (const ticket of tickets) {
+    if (ticket.url) links.push({ label: ticket.id, url: ticket.url });
   }
-  const headers = {
-    Authorization: basicAuthHeader(deps.auth),
-    Accept: "application/json",
-    "Content-Type": "application/json"
+  return {
+    title: tc.story.scenario,
+    steps: tc.story.steps.map((s) => ({ keyword: s.keyword, text: s.text })),
+    description: sections.join("\n\n"),
+    links
   };
-  if (args.pageId) {
-    return updatePage(args, base, headers, fetchFn);
-  }
-  return createPage(args, base, headers, fetchFn);
 }
-async function updatePage(args, base, headers, fetchFn) {
-  const getUrl = `${base}/api/v2/pages/${encodeURIComponent(args.pageId)}`;
-  const getResp = await fetchFn(getUrl, { method: "GET", headers });
-  if (!getResp.ok) {
-    const body = await parseErrorBody(getResp);
-    throw new Error(
-      `GET ${getUrl} failed with ${getResp.status} ${getResp.statusText}${body ? `: ${body}` : ""}`
-    );
-  }
-  const current = await getResp.json();
-  const nextVersion = current.version.number + 1;
-  const title = args.title ?? current.title;
-  const putUrl = `${base}/api/v2/pages/${encodeURIComponent(args.pageId)}`;
-  const putResp = await fetchFn(putUrl, {
-    method: "PUT",
-    headers,
-    body: JSON.stringify({
-      id: args.pageId,
-      status: "current",
-      title,
-      body: {
-        representation: "atlas_doc_format",
-        value: args.adf
-      },
-      version: { number: nextVersion }
+function projectBehaviours(run, config) {
+  const fingerprints = run.testCases.map(
+    (tc) => behaviourFingerprint2({
+      scenario: tc.story.scenario,
+      sourceFile: tc.sourceFile,
+      steps: tc.story.steps.map((s) => ({ keyword: s.keyword, text: s.text })),
+      covers: tc.story.covers
     })
-  });
-  if (!putResp.ok) {
-    const body = await parseErrorBody(putResp);
-    throw new Error(
-      `PUT ${putUrl} failed with ${putResp.status} ${putResp.statusText}${body ? `: ${body}` : ""}`
-    );
+  );
+  const counts = /* @__PURE__ */ new Map();
+  for (const fp of fingerprints) {
+    if (fp) counts.set(fp, (counts.get(fp) ?? 0) + 1);
   }
-  const updated = await putResp.json();
-  return {
-    id: updated.id,
-    title: updated.title,
-    version: updated.version.number,
-    url: buildPageUrl(base, updated._links?.webui, updated.id),
-    action: "updated"
-  };
+  return run.testCases.map((tc, index) => {
+    const fp = fingerprints[index];
+    const unique = fp !== "" && counts.get(fp) === 1;
+    return {
+      fingerprint: unique ? fp : tc.id,
+      testCase: tc,
+      body: toCaseBody(tc, config)
+    };
+  });
 }
-async function createPage(args, base, headers, fetchFn) {
-  const body = {
-    spaceId: args.spaceId,
-    status: "current",
-    title: args.title,
-    body: {
-      representation: "atlas_doc_format",
-      value: args.adf
+function roleFor(attachment) {
+  const type = attachment.mediaType.toLowerCase();
+  if (type.startsWith("image/")) return "screenshot";
+  if (type.startsWith("video/")) return "video";
+  if (attachment.name.toLowerCase().includes("trace")) return "trace";
+  return "log";
+}
+function decode(attachment) {
+  return attachment.contentEncoding === "BASE64" ? Uint8Array.from(Buffer.from(attachment.body, "base64")) : new TextEncoder().encode(attachment.body);
+}
+function collectAttachments(args) {
+  const { testCase, policy, maxBytes } = args;
+  if (policy === "none") return { attachments: [], oversized: [] };
+  if (policy === "failed" && testCase.status !== "failed") return { attachments: [], oversized: [] };
+  const attachments = [];
+  const oversized = [];
+  for (const raw of testCase.attachments) {
+    const body = decode(raw);
+    if (maxBytes !== void 0 && body.byteLength > maxBytes) {
+      oversized.push({ filename: raw.name, bytes: body.byteLength, limit: maxBytes });
+      continue;
     }
-  };
-  if (args.parentId) body.parentId = args.parentId;
-  const postUrl = `${base}/api/v2/pages`;
-  const resp = await fetchFn(postUrl, {
-    method: "POST",
-    headers,
-    body: JSON.stringify(body)
-  });
-  if (!resp.ok) {
-    const errBody = await parseErrorBody(resp);
-    throw new Error(
-      `POST ${postUrl} failed with ${resp.status} ${resp.statusText}${errBody ? `: ${errBody}` : ""}`
-    );
+    attachments.push({
+      filename: raw.name,
+      mediaType: raw.mediaType,
+      body,
+      role: roleFor(raw)
+    });
   }
-  const created = await resp.json();
+  return { attachments, oversized };
+}
+function toCaseResult(args) {
+  const { behaviour, caseId, provider, config } = args;
+  const tc = behaviour.testCase;
+  if (tc.status === "pending") return void 0;
+  const { attachments, oversized } = collectAttachments({
+    testCase: tc,
+    policy: config.attach ?? "failed",
+    maxBytes: provider.maxAttachmentBytes
+  });
   return {
-    id: created.id,
-    title: created.title,
-    version: created.version.number,
-    url: buildPageUrl(base, created._links?.webui, created.id),
-    action: "created"
+    result: {
+      caseId,
+      status: tc.status,
+      durationMs: tc.durationMs,
+      message: tc.errorMessage,
+      url: scenarioUrl(config, tc),
+      attachments: attachments.length > 0 ? attachments : void 0
+    },
+    oversized
   };
 }
-function buildPageUrl(base, webui, id) {
-  if (webui) {
-    return webui.startsWith("http") ? webui : `${base}${webui}`;
-  }
-  return `${base}/pages/${id}`;
+function ticketBinding(tc, config) {
+  const prefix = config.ticketPrefix;
+  if (!prefix) return void 0;
+  const match = (tc.story.tickets ?? []).find((t) => t.id.startsWith(prefix));
+  if (!match) return void 0;
+  return config.ticketPrefixStrip === false ? match.id : match.id.slice(prefix.length);
+}
+async function analyzeSync(args) {
+  const { run, provider, lockfile, config } = args;
+  const local = projectBehaviours(run, config);
+  const remoteCases = await provider.listCases();
+  const remoteById = new Map(remoteCases.map((c) => [c.id, c]));
+  const locked = entriesFor(lockfile, provider.name);
+  const create = [];
+  const update = [];
+  const unchanged = [];
+  const adopted = [];
+  const skipped = [];
+  const results = [];
+  const oversized = [];
+  const boundCaseIds = /* @__PURE__ */ new Set();
+  let driftUncheckable = 0;
+  for (const behaviour of local) {
+    const entry = locked[behaviour.fingerprint];
+    const caseId = entry?.caseId ?? ticketBinding(behaviour.testCase, config);
+    const remote2 = caseId ? remoteById.get(caseId) : void 0;
+    if (!caseId) {
+      create.push({
+        fingerprint: behaviour.fingerprint,
+        scenario: behaviour.body.title,
+        body: behaviour.body
+      });
+      continue;
+    }
+    if (!remote2) {
+      skipped.push({
+        fingerprint: behaviour.fingerprint,
+        caseId,
+        url: entry?.url ?? "",
+        title: entry?.title ?? behaviour.body.title,
+        reason: "case-missing"
+      });
+      continue;
+    }
+    boundCaseIds.add(caseId);
+    const pending = toCaseResult({ behaviour, caseId, provider, config });
+    if (pending) {
+      results.push(pending.result);
+      oversized.push(...pending.oversized);
+    }
+    const planned = {
+      fingerprint: behaviour.fingerprint,
+      caseId,
+      url: remote2.url,
+      scenario: behaviour.body.title,
+      body: behaviour.body
+    };
+    if (!entry?.owned) {
+      adopted.push(planned);
+      continue;
+    }
+    const remoteHash = remote2.body ? hashCaseBody(remote2.body) : void 0;
+    if (remoteHash !== void 0 && remoteHash !== entry.hash) {
+      skipped.push({
+        fingerprint: behaviour.fingerprint,
+        caseId,
+        url: remote2.url,
+        title: remote2.title,
+        reason: "remote-edited"
+      });
+      continue;
+    }
+    const baseline = remoteHash ?? entry.hash;
+    if (baseline !== "" && hashCaseBody(behaviour.body) === baseline) {
+      unchanged.push(planned);
+    } else {
+      update.push(planned);
+    }
+    if (remoteHash === void 0) driftUncheckable += 1;
+  }
+  const byNormalizedTitle = /* @__PURE__ */ new Map();
+  for (const behaviour of local) byNormalizedTitle.set(normalizeTitle(behaviour.body.title), behaviour);
+  const threshold = config.duplicateThreshold ?? DEFAULT_DUPLICATE_THRESHOLD;
+  const remote = remoteCases.map((remoteCase) => {
+    if (boundCaseIds.has(remoteCase.id)) {
+      return { case: remoteCase, classification: "automated" };
+    }
+    const titleMatch = byNormalizedTitle.get(normalizeTitle(remoteCase.title));
+    if (titleMatch) {
+      return {
+        case: remoteCase,
+        classification: "duplicated",
+        resembles: titleMatch.body.title
+      };
+    }
+    if (remoteCase.body && remoteCase.body.steps.length > 0) {
+      let best;
+      for (const behaviour of local) {
+        const score = behaviourSimilarity2(
+          {
+            scenario: remoteCase.title,
+            sourceFile: "",
+            steps: remoteCase.body.steps
+          },
+          {
+            scenario: behaviour.body.title,
+            sourceFile: behaviour.testCase.sourceFile,
+            steps: behaviour.body.steps
+          }
+        );
+        if (!best || score > best.score) best = { behaviour, score };
+      }
+      if (best && best.score >= threshold) {
+        return {
+          case: remoteCase,
+          classification: "possible-duplicate",
+          resembles: best.behaviour.body.title,
+          similarity: Number(best.score.toFixed(2))
+        };
+      }
+    }
+    return { case: remoteCase, classification: "manual-only" };
+  });
+  const localFingerprints = new Set(local.map((b) => b.fingerprint));
+  const orphaned = Object.entries(locked).filter(([fingerprint]) => !localFingerprints.has(fingerprint)).map(([fingerprint, entry]) => ({
+    fingerprint,
+    caseId: entry.caseId,
+    url: entry.url,
+    title: entry.title
+  }));
+  const lockedCount = Object.keys(locked).length;
+  const partialRunWarning = lockedCount > 0 && orphaned.length / lockedCount > PARTIAL_RUN_ORPHAN_RATIO ? `${orphaned.length} of ${lockedCount} bindings have no matching story. If this run was filtered (a -t/--grep flag, a single file), those are not deletions. Nothing is removed either way.` : void 0;
+  const unsupported = [];
+  if (create.length > 0 && !provider.createCase) unsupported.push("createCase");
+  if (update.length > 0 && !provider.updateCase) unsupported.push("updateCase");
+  if (results.length > 0 && !provider.recordResults) unsupported.push("recordResults");
+  const byRole = {};
+  let files = 0;
+  let bytes = 0;
+  for (const result of results) {
+    for (const attachment of result.attachments ?? []) {
+      files += 1;
+      bytes += attachment.body.byteLength;
+      const role = attachment.role ?? "log";
+      byRole[role] = (byRole[role] ?? 0) + 1;
+    }
+  }
+  return {
+    provider: provider.name,
+    target: provider.describeTarget?.(),
+    local,
+    remote,
+    create,
+    update,
+    unchanged,
+    adopted,
+    skipped,
+    orphaned,
+    results,
+    attachments: { files, bytes, oversized, byRole },
+    unsupported,
+    driftUncheckable,
+    partialRunWarning
+  };
+}
+async function applySync(args, deps) {
+  const { analysis, provider, lockfile, config } = args;
+  const result = {
+    created: [],
+    updated: [],
+    resultsRecorded: 0,
+    resultsSkipped: [],
+    attachmentsUploaded: 0,
+    errors: []
+  };
+  const byFingerprint = new Map(analysis.local.map((b) => [b.fingerprint, b]));
+  const results = [...analysis.results];
+  if (analysis.create.length > 0 && provider.createCase) {
+    for (const planned of analysis.create) {
+      try {
+        const created = await provider.createCase(planned.body);
+        setEntry(lockfile, provider.name, planned.fingerprint, {
+          caseId: created.id,
+          url: created.url,
+          hash: hashCaseBody(created.body ?? planned.body),
+          title: created.title,
+          owned: true
+        });
+        result.created.push({ scenario: planned.scenario, caseId: created.id, url: created.url });
+        const behaviour = byFingerprint.get(planned.fingerprint);
+        if (behaviour) {
+          const pending = toCaseResult({ behaviour, caseId: created.id, provider, config });
+          if (pending) results.push(pending.result);
+        }
+      } catch (err) {
+        result.errors.push(`create "${planned.scenario}": ${err.message}`);
+      }
+    }
+  }
+  if (analysis.update.length > 0 && provider.updateCase) {
+    for (const planned of analysis.update) {
+      try {
+        const updated = await provider.updateCase(planned.caseId, planned.body);
+        setEntry(lockfile, provider.name, planned.fingerprint, {
+          caseId: updated.id,
+          url: updated.url,
+          hash: hashCaseBody(updated.body ?? planned.body),
+          title: updated.title,
+          owned: true
+        });
+        result.updated.push({ scenario: planned.scenario, caseId: updated.id, url: updated.url });
+      } catch (err) {
+        result.errors.push(`update "${planned.scenario}" (${planned.caseId}): ${err.message}`);
+      }
+    }
+  }
+  for (const planned of analysis.unchanged) {
+    const existing = entriesFor(lockfile, provider.name)[planned.fingerprint];
+    if (existing) {
+      setEntry(lockfile, provider.name, planned.fingerprint, { ...existing, url: planned.url });
+    }
+  }
+  for (const planned of analysis.adopted) {
+    setEntry(lockfile, provider.name, planned.fingerprint, {
+      caseId: planned.caseId,
+      url: planned.url,
+      hash: "",
+      title: planned.scenario,
+      owned: false
+    });
+  }
+  if (results.length > 0 && provider.recordResults) {
+    try {
+      const summary = await provider.recordResults(results);
+      result.resultsRecorded = summary.recorded;
+      result.resultsSkipped = summary.skipped;
+      result.attachmentsUploaded = summary.attachmentsUploaded;
+      result.runUrl = summary.runUrl;
+    } catch (err) {
+      result.errors.push(`record results: ${err.message}`);
+    }
+  } else if (results.length > 0) {
+    deps.logger.warn(
+      `${provider.name} does not support recording results \u2014 ${results.length} execution(s) not pushed.`
+    );
+  }
+  return result;
+}
+
+// src/sync/report.ts
+var MANUAL_ONLY_LIMIT = 50;
+function summarize2(analysis) {
+  const count2 = (kind) => analysis.remote.filter((c) => c.classification === kind).length;
+  return {
+    provider: analysis.provider,
+    target: analysis.target,
+    totalCases: analysis.remote.length,
+    automated: count2("automated"),
+    duplicated: count2("duplicated"),
+    possibleDuplicate: count2("possible-duplicate"),
+    manualOnly: count2("manual-only"),
+    untracked: analysis.create.length,
+    adopted: analysis.adopted.length
+  };
+}
+function sectionBreakdown(analysis) {
+  const sections = /* @__PURE__ */ new Map();
+  for (const entry of analysis.remote) {
+    const name = entry.case.section ?? "(no section)";
+    const bucket2 = sections.get(name) ?? { total: 0, automated: 0 };
+    bucket2.total += 1;
+    if (entry.classification === "automated") bucket2.automated += 1;
+    sections.set(name, bucket2);
+  }
+  return [...sections.entries()].map(([name, value]) => ({ name, ...value })).sort((a, b) => b.automated - a.automated || b.total - a.total);
+}
+function renderCoverageText(analysis) {
+  const summary = summarize2(analysis);
+  const lines = [];
+  lines.push(`${analysis.provider}: ${analysis.target ?? "(target not described)"} (${summary.totalCases} cases)`);
+  lines.push("");
+  lines.push(`  ${pad(summary.automated)}  automated        already covered by a story`);
+  lines.push(`  ${pad(summary.duplicated)}  duplicated       manual case duplicates an automated story`);
+  if (summary.possibleDuplicate > 0) {
+    lines.push(`  ${pad(summary.possibleDuplicate)}  possible dupe    similar to a story, needs a human to confirm`);
+  }
+  lines.push(`  ${pad(summary.manualOnly)}  manual only      no automated equivalent`);
+  lines.push(`  ${pad(summary.untracked)}  untracked        story with no case`);
+  if (summary.adopted > 0) {
+    lines.push(`  ${pad(summary.adopted)}  linked           story bound to a hand-authored case`);
+  }
+  const sections = sectionBreakdown(analysis).filter((s) => s.automated > 0);
+  if (sections.length > 0) {
+    const top = sections[0];
+    lines.push("");
+    lines.push(`Biggest overlap: "${top.name}" section, ${top.automated} of ${top.total} automated.`);
+  }
+  if (analysis.orphaned.length > 0) {
+    lines.push("");
+    lines.push(`${analysis.orphaned.length} case(s) bound to a story that no longer exists. Nothing was removed.`);
+  }
+  if (analysis.partialRunWarning) {
+    lines.push("");
+    lines.push(`Note: ${analysis.partialRunWarning}`);
+  }
+  return lines.join("\n");
+}
+function pad(value) {
+  return String(value).padStart(4, " ");
+}
+function renderCoverageMarkdown(analysis) {
+  const summary = summarize2(analysis);
+  const lines = [];
+  lines.push(`# Test coverage vs ${analysis.provider}`);
+  lines.push("");
+  if (analysis.target) lines.push(`**Target:** ${analysis.target}`, "");
+  lines.push("| Cases | Count | Meaning |");
+  lines.push("| --- | ---: | --- |");
+  lines.push(`| Automated | ${summary.automated} | Already covered by a story |`);
+  lines.push(`| Duplicated | ${summary.duplicated} | Manual case duplicates an automated story |`);
+  lines.push(`| Possible duplicate | ${summary.possibleDuplicate} | Similar to a story, needs review |`);
+  lines.push(`| Manual only | ${summary.manualOnly} | No automated equivalent |`);
+  lines.push(`| Untracked stories | ${summary.untracked} | Story with no case |`);
+  lines.push("");
+  const duplicates = analysis.remote.filter(
+    (c) => c.classification === "duplicated" || c.classification === "possible-duplicate"
+  );
+  if (duplicates.length > 0) {
+    lines.push("## Retire these first");
+    lines.push("");
+    lines.push("Manual cases an automated story already covers.");
+    lines.push("");
+    lines.push("| Case | Title | Covered by | Confidence |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const entry of duplicates) {
+      const confidence = entry.classification === "duplicated" ? "exact title" : `similarity ${entry.similarity}`;
+      lines.push(
+        `| [${entry.case.id}](${entry.case.url}) | ${escapeCell2(entry.case.title)} | ${escapeCell2(entry.resembles ?? "")} | ${confidence} |`
+      );
+    }
+    lines.push("");
+  }
+  const manualOnly = analysis.remote.filter((c) => c.classification === "manual-only");
+  if (manualOnly.length > 0) {
+    lines.push("## Not automated yet");
+    lines.push("");
+    lines.push("Cases with no automated equivalent. This is the backlog.");
+    lines.push("");
+    lines.push("| Case | Title | Section |");
+    lines.push("| --- | --- | --- |");
+    for (const entry of manualOnly.slice(0, MANUAL_ONLY_LIMIT)) {
+      lines.push(
+        `| [${entry.case.id}](${entry.case.url}) | ${escapeCell2(entry.case.title)} | ${escapeCell2(entry.case.section ?? "")} |`
+      );
+    }
+    if (manualOnly.length > MANUAL_ONLY_LIMIT) {
+      lines.push("");
+      lines.push(
+        `_${manualOnly.length - MANUAL_ONLY_LIMIT} more not listed here. The JSON artifact has all ${manualOnly.length}._`
+      );
+    }
+    lines.push("");
+  }
+  if (analysis.create.length > 0) {
+    lines.push("## Stories with no case");
+    lines.push("");
+    for (const planned of analysis.create) lines.push(`- ${planned.scenario}`);
+    lines.push("");
+  }
+  if (analysis.orphaned.length > 0) {
+    lines.push("## Cases with no story");
+    lines.push("");
+    lines.push("Bound to a story that has since been deleted. Nothing was removed automatically.");
+    lines.push("");
+    for (const orphan of analysis.orphaned) {
+      lines.push(`- [${orphan.caseId}](${orphan.url}) ${escapeCell2(orphan.title)}`);
+    }
+    lines.push("");
+  }
+  const sections = sectionBreakdown(analysis);
+  if (sections.length > 1) {
+    lines.push("## By section");
+    lines.push("");
+    lines.push("| Section | Automated | Total |");
+    lines.push("| --- | ---: | ---: |");
+    for (const section of sections) {
+      lines.push(`| ${escapeCell2(section.name)} | ${section.automated} | ${section.total} |`);
+    }
+    lines.push("");
+  }
+  if (analysis.partialRunWarning) {
+    lines.push(`> ${analysis.partialRunWarning}`, "");
+  }
+  return lines.join("\n");
+}
+function escapeCell2(text2) {
+  return text2.replace(/\|/g, "\\|");
+}
+function buildCoverageJson(analysis) {
+  return {
+    schema: "executable-stories/sync-coverage/v1",
+    ...summarize2(analysis),
+    cases: analysis.remote.map((entry) => ({
+      id: entry.case.id,
+      url: entry.case.url,
+      title: entry.case.title,
+      section: entry.case.section,
+      classification: entry.classification,
+      resembles: entry.resembles,
+      similarity: entry.similarity
+    })),
+    untrackedScenarios: analysis.create.map((c) => c.scenario),
+    orphaned: analysis.orphaned.map((o) => ({ caseId: o.caseId, url: o.url, title: o.title })),
+    sections: sectionBreakdown(analysis)
+  };
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function renderPlan(analysis, opts) {
+  const lines = [];
+  lines.push(`${analysis.provider}: ${analysis.target ?? "(target not described)"}`);
+  lines.push("");
+  lines.push(`  + create    ${pad(analysis.create.length)} cases`);
+  lines.push(`  ~ update    ${pad(analysis.update.length)} cases`);
+  lines.push(`  = unchanged ${pad(analysis.unchanged.length)} cases`);
+  if (analysis.adopted.length > 0) {
+    lines.push(`  \xB7 linked    ${pad(analysis.adopted.length)} cases  (hand-authored, results only)`);
+  }
+  if (analysis.skipped.length > 0) {
+    const edited = analysis.skipped.filter((s) => s.reason === "remote-edited").length;
+    const missing = analysis.skipped.filter((s) => s.reason === "case-missing").length;
+    if (edited > 0) {
+      lines.push(`  ! skipped   ${pad(edited)} cases  (edited in ${analysis.provider} since last sync)`);
+    }
+    if (missing > 0) {
+      lines.push(`  ! skipped   ${pad(missing)} cases  (bound case no longer exists)`);
+    }
+  }
+  if (analysis.orphaned.length > 0) {
+    lines.push(`  ? orphaned  ${pad(analysis.orphaned.length)} cases  (story deleted from codebase, never removed)`);
+  }
+  lines.push(`  \u2192 results   ${pad(analysis.results.length)} executions`);
+  if (analysis.attachments.files > 0) {
+    const roles = Object.entries(analysis.attachments.byRole).map(([role, count2]) => `${count2} ${role}${count2 === 1 ? "" : "s"}`).join(", ");
+    lines.push(
+      `  \u2191 upload    ${pad(analysis.attachments.files)} attachments (${roles}, ${formatBytes(analysis.attachments.bytes)})`
+    );
+  }
+  for (const oversized of analysis.attachments.oversized) {
+    lines.push(
+      `  ! oversized ${oversized.filename} (${formatBytes(oversized.bytes)}, provider limit ${formatBytes(oversized.limit)})`
+    );
+  }
+  for (const capability of analysis.unsupported) {
+    lines.push(`  ! ${analysis.provider} does not support ${capability} \u2014 those changes are not applied`);
+  }
+  if (analysis.driftUncheckable > 0) {
+    lines.push(
+      `  ! ${analysis.driftUncheckable} case(s): ${analysis.provider} returned no body, so a hand edit to them cannot be detected`
+    );
+  }
+  if (analysis.partialRunWarning) {
+    lines.push("");
+    lines.push(`Note: ${analysis.partialRunWarning}`);
+  }
+  if (analysis.skipped.some((s) => s.reason === "remote-edited")) {
+    lines.push("");
+    lines.push("Skipped cases were edited by hand after we last wrote them. Nothing overwrites them.");
+    for (const skip of analysis.skipped.filter((s) => s.reason === "remote-edited")) {
+      lines.push(`  ${skip.caseId} ${skip.title} ${skip.url}`);
+    }
+  }
+  if (opts.dryRun && hasWork(analysis)) {
+    lines.push("");
+    lines.push("Nothing was written. Run the same command with --apply to make these changes.");
+  }
+  return lines.join("\n");
+}
+function hasWork(analysis) {
+  return analysis.create.length > 0 || analysis.update.length > 0 || analysis.results.length > 0;
+}
+function renderApplyResult(result) {
+  const lines = [];
+  for (const created of result.created) {
+    lines.push(`  + ${created.caseId}  ${created.scenario}  ${created.url}`);
+  }
+  for (const updated of result.updated) {
+    lines.push(`  ~ ${updated.caseId}  ${updated.scenario}`);
+  }
+  lines.push("");
+  lines.push(
+    `Created ${result.created.length}, updated ${result.updated.length}, recorded ${result.resultsRecorded} execution(s), uploaded ${result.attachmentsUploaded} attachment(s).`
+  );
+  if (result.runUrl) lines.push(`Run: ${result.runUrl}`);
+  for (const skipped of result.resultsSkipped) {
+    lines.push(`  ! result for case ${skipped.caseId} not recorded: ${skipped.reason}`);
+  }
+  for (const error of result.errors) {
+    lines.push(`  \u2717 ${error}`);
+  }
+  return lines.join("\n");
+}
+
+// src/sync/adapters/case-text.ts
+var BDD_KEYWORDS = ["Given", "When", "Then", "And", "But"];
+function encodeStepText(step) {
+  const keyword = step.keyword.trim();
+  return keyword ? `${keyword} ${step.text}` : step.text;
+}
+function decodeStepText(content) {
+  const trimmed = content.trim();
+  const firstSpace = trimmed.indexOf(" ");
+  if (firstSpace > 0) {
+    const head = trimmed.slice(0, firstSpace);
+    if (BDD_KEYWORDS.some((keyword) => keyword.toLowerCase() === head.toLowerCase())) {
+      return { keyword: head, text: trimmed.slice(firstSpace + 1) };
+    }
+  }
+  return { keyword: "", text: trimmed };
+}
+function encodeDescription(body) {
+  if (body.links.length === 0) return body.description;
+  const links = body.links.map((link2) => `- [${link2.label}](${link2.url})`).join("\n");
+  return `${body.description}
+
+${links}`;
+}
+function decodeDescription(raw) {
+  const links = [];
+  const lines = raw.split("\n");
+  let cut = lines.length;
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = lines[index].trim();
+    if (line === "") continue;
+    const match = /^- \[([^\]]+)\]\(([^)]+)\)$/.exec(line);
+    if (!match) break;
+    links.unshift({ label: match[1], url: match[2] });
+    cut = index;
+  }
+  return { description: lines.slice(0, cut).join("\n").trim(), links };
+}
+
+// src/sync/adapters/testrail.ts
+var DEFAULT_STEPS_FIELD = "custom_steps_separated";
+var DEFAULT_DESCRIPTION_FIELD = "custom_preconds";
+var DEFAULT_MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+var PAGE_LIMIT = 250;
+var MAX_ATTEMPTS = 3;
+function unwrapList(payload, key) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && typeof payload === "object") {
+    const list = payload[key];
+    if (Array.isArray(list)) return list;
+  }
+  return [];
+}
+function encodeElapsed(durationMs) {
+  const seconds = Math.floor(durationMs / 1e3);
+  if (seconds < 1) return void 0;
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+}
+function authHint(status) {
+  if (status === 401) {
+    return "\n  TESTRAIL_USERNAME must be the login email and TESTRAIL_API_KEY an API key from My Settings -> API Keys. A password fails here when the instance enforces API keys.";
+  }
+  if (status === 403) {
+    return "\n  The credentials were accepted but the request was refused. Usually the API is disabled: an admin enables it under Administration -> Site Settings -> API.";
+  }
+  return "";
+}
+function createTestRailProvider(config, auth, deps) {
+  const base = config.url.replace(/\/$/, "");
+  const stepsField = config.fields?.steps ?? DEFAULT_STEPS_FIELD;
+  const descriptionField = config.fields?.description ?? DEFAULT_DESCRIPTION_FIELD;
+  const basicAuth = Buffer.from(`${auth.username}:${auth.apiKey}`).toString("base64");
+  let projectName;
+  let suiteName;
+  const sectionNames = /* @__PURE__ */ new Map();
+  async function api(method, init) {
+    const url = `${base}/index.php?/api/v2/${method}`;
+    const headers = {
+      Authorization: `Basic ${basicAuth}`
+    };
+    let body;
+    if (init?.form) {
+      body = init.form;
+    } else if (init?.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(init.body);
+    }
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const response = await deps.fetch(url, {
+        method: body === void 0 ? "GET" : "POST",
+        headers,
+        body
+      });
+      if (response.status === 429 && attempt < MAX_ATTEMPTS - 1) {
+        const retryAfter = Number(response.headers.get("retry-after") ?? "1");
+        deps.logger.warn(`TestRail rate limit hit, retrying in ${retryAfter}s`);
+        await new Promise((resolve12) => setTimeout(resolve12, Math.max(1, retryAfter) * 1e3));
+        continue;
+      }
+      const text2 = await response.text();
+      if (text2.length === 0) {
+        if (response.ok) return void 0;
+        throw new Error(
+          `TestRail ${method} failed (${response.status}) with an empty response${authHint(response.status)}`
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(text2);
+      } catch {
+        throw new Error(
+          `TestRail ${method} returned HTML rather than JSON (status ${response.status}).
+  Check that sync.testrail.url is the instance root, e.g. https://acme.testrail.io, with no path after it.`
+        );
+      }
+      if (!response.ok) {
+        const detail = parsed.error ?? text2;
+        throw new Error(
+          `TestRail ${method} failed (${response.status}): ${detail}${authHint(response.status)}`
+        );
+      }
+      return parsed;
+    }
+    throw new Error(`TestRail ${method} failed: rate limited after ${MAX_ATTEMPTS} attempts`);
+  }
+  async function paginate(method, key) {
+    const all = [];
+    for (let offset = 0; ; offset += PAGE_LIMIT) {
+      const page = await api(`${method}&limit=${PAGE_LIMIT}&offset=${offset}`);
+      const items = unwrapList(page, key);
+      all.push(...items);
+      if (items.length < PAGE_LIMIT) return all;
+    }
+  }
+  function caseUrl(id) {
+    return `${base}/index.php?/cases/view/${id}`;
+  }
+  function toRemoteCase(raw, context) {
+    if (raw?.id === void 0) {
+      throw new Error(
+        `TestRail ${context} returned no case id. The response was: ${JSON.stringify(raw)?.slice(0, 200)}`
+      );
+    }
+    const title = typeof raw.title === "string" ? raw.title : "";
+    const steps = Array.isArray(raw[stepsField]) ? raw[stepsField] : [];
+    const rawDescription = typeof raw[descriptionField] === "string" ? raw[descriptionField] : "";
+    const { description, links } = decodeDescription(rawDescription);
+    return {
+      id: String(raw.id),
+      url: caseUrl(raw.id),
+      title,
+      section: raw.section_id === void 0 ? void 0 : sectionNames.get(raw.section_id),
+      body: {
+        title,
+        steps: steps.map((step) => decodeStepText(step.content ?? "")),
+        description,
+        links
+      }
+    };
+  }
+  function bodyToPayload(body) {
+    const payload = {
+      title: body.title,
+      [stepsField]: body.steps.map((step) => ({ content: encodeStepText(step), expected: "" })),
+      [descriptionField]: encodeDescription(body)
+    };
+    if (config.templateId !== void 0) payload["template_id"] = config.templateId;
+    return payload;
+  }
+  const suiteQuery = config.suiteId === void 0 ? "" : `&suite_id=${config.suiteId}`;
+  return {
+    name: "testrail",
+    maxAttachmentBytes: config.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+    describeTarget() {
+      const project = projectName ?? `project ${config.projectId}`;
+      const suite = suiteName ?? (config.suiteId === void 0 ? void 0 : `suite ${config.suiteId}`);
+      return suite ? `${project} / ${suite}` : project;
+    },
+    async listCases() {
+      try {
+        const project = await api(`get_project/${config.projectId}`);
+        projectName = project?.name;
+        if (config.suiteId !== void 0) {
+          const suite = await api(`get_suite/${config.suiteId}`);
+          suiteName = suite?.name;
+        }
+        const sections = await paginate(
+          `get_sections/${config.projectId}${suiteQuery}`,
+          "sections"
+        );
+        for (const section of sections) sectionNames.set(section.id, section.name);
+      } catch (err) {
+        deps.logger.warn(`TestRail metadata lookup failed, continuing without names: ${err.message}`);
+      }
+      const cases = await paginate(`get_cases/${config.projectId}${suiteQuery}`, "cases");
+      return cases.map((raw) => toRemoteCase(raw, "get_cases"));
+    },
+    async createCase(body) {
+      if (config.sectionId === void 0) {
+        throw new Error(
+          "TestRail needs a sectionId to create cases. Set sync.testrail.sectionId to the section new cases should land in."
+        );
+      }
+      const created = await api(`add_case/${config.sectionId}`, {
+        body: bodyToPayload(body)
+      });
+      return toRemoteCase(created, `add_case/${config.sectionId}`);
+    },
+    async updateCase(id, body) {
+      const updated = await api(`update_case/${id}`, { body: bodyToPayload(body) });
+      return toRemoteCase(updated, `update_case/${id}`);
+    },
+    async recordResults(results) {
+      const statusIds = {
+        passed: config.statusIds?.passed ?? 1,
+        failed: config.statusIds?.failed ?? 5,
+        skipped: config.statusIds?.skipped
+      };
+      const skipped = [];
+      const sendable = [];
+      for (const result of results) {
+        const caseId = Number(result.caseId);
+        if (!Number.isFinite(caseId)) {
+          skipped.push({ caseId: result.caseId, reason: "case id is not numeric" });
+          continue;
+        }
+        const statusId = result.status === "skipped" ? statusIds.skipped : statusIds[result.status];
+        if (statusId === void 0) {
+          skipped.push({
+            caseId: result.caseId,
+            reason: "no TestRail status id configured for skipped (set sync.testrail.statusIds.skipped)"
+          });
+          continue;
+        }
+        sendable.push({ result, caseId, statusId });
+      }
+      if (sendable.length === 0) {
+        return { recorded: 0, skipped, attachmentsUploaded: 0 };
+      }
+      let runId = config.runId;
+      if (runId === void 0) {
+        const name = `${config.runName ?? "executable-stories"} ${(/* @__PURE__ */ new Date()).toISOString()}`;
+        const run = await api(`add_run/${config.projectId}`, {
+          body: {
+            ...config.suiteId === void 0 ? {} : { suite_id: config.suiteId },
+            name,
+            include_all: false,
+            // Deduplicated: two stories can carry the same ticket id, and
+            // TestRail rejects a run whose case list repeats one.
+            case_ids: [...new Set(sendable.map((s) => s.caseId))]
+          }
+        });
+        runId = run.id;
+      }
+      const runUrl = `${base}/index.php?/runs/view/${runId}`;
+      const payload = sendable.map(({ result, caseId, statusId }) => {
+        const elapsed = encodeElapsed(result.durationMs);
+        const comment = [result.message, result.url ? `Living documentation: ${result.url}` : void 0].filter(Boolean).join("\n\n");
+        return {
+          case_id: caseId,
+          status_id: statusId,
+          ...comment ? { comment } : {},
+          ...elapsed ? { elapsed } : {}
+        };
+      });
+      const recorded = unwrapList(
+        await api(`add_results_for_cases/${runId}`, { body: { results: payload } }),
+        "results"
+      );
+      let attachmentsUploaded = 0;
+      for (const [index, entry] of recorded.entries()) {
+        const source = sendable[index]?.result;
+        for (const attachment of source?.attachments ?? []) {
+          try {
+            const form = new FormData();
+            const bytes = attachment.body.buffer.slice(
+              attachment.body.byteOffset,
+              attachment.body.byteOffset + attachment.body.byteLength
+            );
+            form.append(
+              "attachment",
+              new Blob([bytes], { type: attachment.mediaType }),
+              attachment.filename
+            );
+            await api(`add_attachment_to_result/${entry.id}`, { form });
+            attachmentsUploaded += 1;
+          } catch (err) {
+            deps.logger.warn(
+              `TestRail attachment "${attachment.filename}" failed: ${err.message}`
+            );
+          }
+        }
+      }
+      if (config.closeRun && config.runId === void 0) {
+        await api(`close_run/${runId}`, { body: {} });
+      }
+      return {
+        runId: String(runId),
+        runUrl,
+        recorded: recorded.length,
+        skipped,
+        attachmentsUploaded
+      };
+    }
+  };
+}
+
+// src/sync/adapters/xray.ts
+var DEFAULT_XRAY_BASE = "https://xray.cloud.getxray.app";
+var DEFAULT_TEST_TYPE = "Manual";
+var DEFAULT_MAX_ATTACHMENT_BYTES2 = 32 * 1024 * 1024;
+var PAGE_LIMIT2 = 100;
+function toAdf(text2) {
+  const paragraphs = text2.split("\n\n").filter((block) => block.trim() !== "");
+  return {
+    version: 1,
+    type: "doc",
+    content: paragraphs.length === 0 ? [{ type: "paragraph", content: [] }] : paragraphs.map((block) => ({
+      type: "paragraph",
+      content: [{ type: "text", text: block }]
+    }))
+  };
+}
+function fromAdf(value) {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object") return "";
+  const blocks = [];
+  const walk = (node, collected) => {
+    if (!node || typeof node !== "object") return;
+    const typed = node;
+    if (typed.type === "text" && typeof typed.text === "string") collected.push(typed.text);
+    for (const child of typed.content ?? []) walk(child, collected);
+  };
+  for (const node of value.content ?? []) {
+    const collected = [];
+    walk(node, collected);
+    blocks.push(collected.join(""));
+  }
+  return blocks.join("\n\n").trim();
+}
+function createXrayProvider(config, auth, deps) {
+  const xrayBase = (config.xrayBaseUrl ?? DEFAULT_XRAY_BASE).replace(/\/$/, "");
+  const jiraBase = config.jiraBaseUrl.replace(/\/$/, "");
+  const jql = config.jql ?? `project = "${config.projectKey}" AND issuetype = Test`;
+  const issueIds = /* @__PURE__ */ new Map();
+  let token;
+  async function authenticate() {
+    if (token) return token;
+    const response = await deps.fetch(`${xrayBase}/api/v2/authenticate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ client_id: auth.clientId, client_secret: auth.clientSecret })
+    });
+    const text2 = await response.text();
+    if (!response.ok) {
+      throw new Error(
+        `Xray authentication failed (${response.status}): ${text2}
+  XRAY_CLIENT_ID and XRAY_CLIENT_SECRET come from Jira -> Apps -> Xray -> API Keys. A Jira API token is a different credential and is rejected here.`
+      );
+    }
+    token = JSON.parse(text2).replace(/^"|"$/g, "");
+    return token;
+  }
+  async function graphql(query, variables) {
+    const bearer = await authenticate();
+    const response = await deps.fetch(`${xrayBase}/api/v2/graphql`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${bearer}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ query, variables })
+    });
+    const text2 = await response.text();
+    if (!response.ok) throw new Error(`Xray GraphQL failed (${response.status}): ${text2}`);
+    const payload = JSON.parse(text2);
+    if (payload.errors?.length) {
+      throw new Error(`Xray GraphQL error: ${payload.errors.map((e) => e.message).join("; ")}`);
+    }
+    return payload.data;
+  }
+  function issueUrl(key) {
+    return `${jiraBase}/browse/${key}`;
+  }
+  function toRemoteCase(test) {
+    const key = test.jira?.key ?? test.issueId;
+    if (!key) {
+      throw new Error(
+        `Xray returned a test with neither a Jira key nor an issue id: ${JSON.stringify(test)?.slice(0, 200)}`
+      );
+    }
+    if (test.jira?.key) issueIds.set(test.jira.key, test.issueId);
+    const { description, links } = decodeDescription(fromAdf(test.jira?.description));
+    return {
+      id: key,
+      url: issueUrl(key),
+      title: test.jira?.summary ?? key,
+      body: {
+        title: test.jira?.summary ?? key,
+        steps: (test.steps ?? []).map((step) => decodeStepText(step.action ?? "")),
+        description,
+        links
+      }
+    };
+  }
+  async function jiraUpdate(key, fields) {
+    if (!auth.jiraEmail || !auth.jiraToken) {
+      deps.logger.warn(
+        `Xray: summary/description for ${key} left unchanged. Set JIRA_EMAIL and JIRA_TOKEN to update Jira fields (steps are updated either way).`
+      );
+      return;
+    }
+    const basic = Buffer.from(`${auth.jiraEmail}:${auth.jiraToken}`).toString("base64");
+    const response = await deps.fetch(`${jiraBase}/rest/api/3/issue/${key}`, {
+      method: "PUT",
+      headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ fields })
+    });
+    if (!response.ok) {
+      throw new Error(`Jira update of ${key} failed (${response.status}): ${await response.text()}`);
+    }
+  }
+  return {
+    name: "xray",
+    maxAttachmentBytes: config.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES2,
+    describeTarget() {
+      return `${config.projectKey} (${jiraBase})`;
+    },
+    async listCases() {
+      const tests = [];
+      for (let start = 0; ; start += PAGE_LIMIT2) {
+        const data = await graphql(
+          `query($jql: String!, $limit: Int!, $start: Int!) {
+             getTests(jql: $jql, limit: $limit, start: $start) {
+               total
+               results {
+                 issueId
+                 jira(fields: ["key", "summary", "description"])
+                 steps { id action data result }
+               }
+             }
+           }`,
+          { jql, limit: PAGE_LIMIT2, start }
+        );
+        const page = data.getTests?.results ?? [];
+        tests.push(...page);
+        if (page.length < PAGE_LIMIT2) break;
+      }
+      return tests.map(toRemoteCase);
+    },
+    async createCase(body) {
+      const data = await graphql(
+        `mutation($testType: UpdateTestTypeInput!, $steps: [CreateStepInput], $jira: JSON!) {
+           createTest(testType: $testType, steps: $steps, jira: $jira) {
+             test { issueId jira(fields: ["key", "summary", "description"]) }
+             warnings
+           }
+         }`,
+        {
+          testType: { name: config.testType ?? DEFAULT_TEST_TYPE },
+          steps: body.steps.map((step) => ({ action: encodeStepText(step), result: "" })),
+          jira: {
+            fields: {
+              summary: body.title,
+              description: toAdf(encodeDescription(body)),
+              project: { key: config.projectKey }
+            }
+          }
+        }
+      );
+      const created = data.createTest?.test;
+      if (!created) throw new Error(`Xray createTest returned no test for "${body.title}"`);
+      for (const warning of data.createTest?.warnings ?? []) deps.logger.warn(`Xray: ${warning}`);
+      return toRemoteCase(created);
+    },
+    async updateCase(id, body) {
+      const issueId = issueIds.get(id);
+      if (!issueId) {
+        throw new Error(`Xray: no internal issue id cached for ${id}. Run listCases first.`);
+      }
+      const current = await graphql(
+        `query($issueId: String!) { getTest(issueId: $issueId) { steps { id } } }`,
+        { issueId }
+      );
+      const existing = current.getTest?.steps ?? [];
+      for (const [index, step] of body.steps.entries()) {
+        const action = encodeStepText(step);
+        const target = existing[index];
+        if (target) {
+          await graphql(
+            `mutation($stepId: String!, $step: UpdateStepInput!) {
+               updateTestStep(stepId: $stepId, step: $step)
+             }`,
+            { stepId: target.id, step: { action, result: "" } }
+          );
+        } else {
+          await graphql(
+            `mutation($issueId: String!, $step: CreateStepInput!) {
+               addTestStep(issueId: $issueId, step: $step) { id }
+             }`,
+            { issueId, step: { action, result: "" } }
+          );
+        }
+      }
+      for (const surplus of existing.slice(body.steps.length).reverse()) {
+        await graphql(`mutation($stepId: String!) { removeTestStep(stepId: $stepId) }`, {
+          stepId: surplus.id
+        });
+      }
+      await jiraUpdate(id, {
+        summary: body.title,
+        description: toAdf(encodeDescription(body))
+      });
+      return {
+        id,
+        url: issueUrl(id),
+        title: body.title,
+        body
+      };
+    },
+    async recordResults(results) {
+      const statuses = {
+        passed: config.statuses?.passed ?? "PASSED",
+        failed: config.statuses?.failed ?? "FAILED",
+        skipped: config.statuses?.skipped ?? "TODO"
+      };
+      let attachmentsUploaded = 0;
+      const tests = results.map((result) => {
+        const evidence = (result.attachments ?? []).map((attachment) => {
+          attachmentsUploaded += 1;
+          return {
+            data: Buffer.from(attachment.body).toString("base64"),
+            filename: attachment.filename,
+            contentType: attachment.mediaType
+          };
+        });
+        const comment = [result.message, result.url ? `Living documentation: ${result.url}` : void 0].filter(Boolean).join("\n\n");
+        return {
+          testKey: result.caseId,
+          status: statuses[result.status],
+          ...comment ? { comment } : {},
+          ...evidence.length > 0 ? { evidence } : {}
+        };
+      });
+      const bearer = await authenticate();
+      const payload = {
+        ...config.testExecutionKey ? { testExecutionKey: config.testExecutionKey } : {},
+        info: {
+          summary: `${config.executionSummary ?? "executable-stories"} ${(/* @__PURE__ */ new Date()).toISOString()}`,
+          project: config.projectKey,
+          ...config.testPlanKey ? { testPlanKey: config.testPlanKey } : {}
+        },
+        tests
+      };
+      const response = await deps.fetch(`${xrayBase}/api/v2/import/execution`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${bearer}`, "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      const text2 = await response.text();
+      if (!response.ok) {
+        throw new Error(`Xray import execution failed (${response.status}): ${text2}`);
+      }
+      const imported = JSON.parse(text2);
+      return {
+        runId: imported.key,
+        runUrl: imported.key ? issueUrl(imported.key) : void 0,
+        recorded: tests.length,
+        skipped: [],
+        attachmentsUploaded
+      };
+    }
+  };
+}
+
+// src/sync/adapters/index.ts
+var PROVIDER_NAMES = ["testrail", "xray"];
+function isProviderName(value) {
+  return PROVIDER_NAMES.includes(value);
+}
+function required(env, name, hint) {
+  const value = env[name];
+  if (!value) throw new Error(`Missing ${name}. ${hint}`);
+  return value;
+}
+function buildProvider(args, deps) {
+  const { name, targets, env } = args;
+  if (name === "testrail") {
+    const config2 = targets.testrail;
+    if (!config2) {
+      throw new Error(
+        'No TestRail config found. Add a `sync: { testrail: { url, projectId } }` block to executable-stories.config.mjs, or run "executable-stories sync testrail --init".'
+      );
+    }
+    const provider2 = createTestRailProvider(
+      config2,
+      {
+        username: required(env, "TESTRAIL_USERNAME", "This is the login email of the TestRail account."),
+        apiKey: required(
+          env,
+          "TESTRAIL_API_KEY",
+          "Generate one in TestRail under My Settings -> API Keys. A password will not work when the instance requires API keys."
+        )
+      },
+      deps
+    );
+    return {
+      provider: provider2,
+      // TestRail ids are numeric and conventionally written "C1234" in a ticket,
+      // so the prefix is decoration and gets stripped.
+      engineDefaults: { ticketPrefix: "C", ticketPrefixStrip: true }
+    };
+  }
+  const config = targets.xray;
+  if (!config) {
+    throw new Error(
+      'No Xray config found. Add a `sync: { xray: { jiraBaseUrl, projectKey } }` block to executable-stories.config.mjs, or run "executable-stories sync xray --init".'
+    );
+  }
+  const provider = createXrayProvider(
+    config,
+    {
+      clientId: required(env, "XRAY_CLIENT_ID", "Create an API key pair in Jira under Apps -> Xray -> API Keys."),
+      clientSecret: required(env, "XRAY_CLIENT_SECRET", "This is the secret half of the Xray API key pair."),
+      jiraEmail: env["JIRA_EMAIL"],
+      jiraToken: env["JIRA_TOKEN"]
+    },
+    deps
+  );
+  return {
+    provider,
+    // An Xray case id is a Jira issue key, so the project prefix is part of the
+    // id and must survive.
+    engineDefaults: { ticketPrefix: `${config.projectKey}-`, ticketPrefixStrip: false }
+  };
+}
+
+// src/index.ts
+import {
+  STORY_REPORT_SCHEMA_VERSION,
+  STORY_REPORT_SCHEMA_MAJOR
+} from "executable-stories-core/types/story-report";
+import { ES_THEME_TOKENS_CSS as ES_THEME_TOKENS_CSS2, ES_THEME_TOKEN_VALUES } from "executable-stories-core/theme/tokens";
+import { canonicalizeRun as canonicalizeRun3 } from "executable-stories-core/converters/acl/index";
+import { normalizeStatus } from "executable-stories-core/converters/acl/index";
+import { generateTestCaseId } from "executable-stories-core/converters/acl/index";
+import { generateRunId } from "executable-stories-core/converters/acl/index";
+import { slugify as slugify2 } from "executable-stories-core/converters/acl/index";
+import { deriveStepResults } from "executable-stories-core/converters/acl/index";
+import { mergeStepResults } from "executable-stories-core/converters/acl/index";
+import { resolveAttachment } from "executable-stories-core/converters/acl/index";
+import { resolveAttachments } from "executable-stories-core/converters/acl/index";
+import {
+  validateCanonicalRun,
+  assertValidRun
+} from "executable-stories-core/converters/acl/validate";
+
+// src/watch.ts
+import * as fs5 from "fs";
+import * as path6 from "path";
+import { canonicalizeRun } from "executable-stories-core/converters/acl/index";
+import { synthesizeStories } from "executable-stories-core/converters/synthesize";
+function toRun(data, inputType, synthesize) {
+  if (inputType === "canonical") return data;
+  let raw = data;
+  if (synthesize) raw = synthesizeStories(raw);
+  return canonicalizeRun(raw);
+}
+async function regenerateRun(options, deps = {}) {
+  const read = deps.readFile ?? ((filePath) => fs5.readFileSync(filePath, "utf8"));
+  const data = JSON.parse(read(path6.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 { files: [...result.values()].flat(), run };
+}
+async function regenerateArtifacts(options, deps = {}) {
+  return (await regenerateRun(options, deps)).files;
+}
+function startWatch(options, deps = {}) {
+  const log = deps.log ?? ((message) => console.log(message));
+  const regenerate = deps.regenerate ?? ((input) => regenerateArtifacts({ ...options, input }, deps));
+  const watchFn = deps.watch ?? ((filePath, listener) => fs5.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(path6.resolve(options.input), trigger);
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
+// src/index.ts
+import { advanceState, initialRunState } from "executable-stories-core";
+import { toStoryReport as toStoryReport6 } from "executable-stories-core/converters/story-report";
+
+// src/publishers/confluence.ts
+function parseAdf(adf) {
+  let parsed;
+  try {
+    parsed = JSON.parse(adf);
+  } catch (err) {
+    throw new Error(
+      `ADF payload is not valid JSON: ${err.message}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.type !== "doc" || !Array.isArray(parsed.content)) {
+    throw new Error(
+      `ADF payload must be an object with { version, type: "doc", content: [...] }`
+    );
+  }
+  return parsed;
+}
+function basicAuthHeader(auth) {
+  const raw = `${auth.email}:${auth.token}`;
+  const encoded = typeof Buffer !== "undefined" ? Buffer.from(raw, "utf8").toString("base64") : btoa(raw);
+  return `Basic ${encoded}`;
+}
+async function parseErrorBody(response) {
+  try {
+    const body = await response.text();
+    return body ? body.slice(0, 800) : "";
+  } catch {
+    return "";
+  }
+}
+async function publishConfluencePage(args, deps) {
+  parseAdf(args.adf);
+  if (!args.pageId && !args.spaceId) {
+    throw new Error(
+      "publishConfluencePage requires either pageId (update) or spaceId (create)"
+    );
+  }
+  if (!args.pageId && !args.title) {
+    throw new Error("Creating a new page requires a title");
+  }
+  const base = args.baseUrl.replace(/\/$/, "");
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  if (!fetchFn) {
+    throw new Error("No fetch implementation available (Node >= 22 expected)");
+  }
+  const headers = {
+    Authorization: basicAuthHeader(deps.auth),
+    Accept: "application/json",
+    "Content-Type": "application/json"
+  };
+  if (args.pageId) {
+    return updatePage(args, base, headers, fetchFn);
+  }
+  return createPage(args, base, headers, fetchFn);
+}
+async function updatePage(args, base, headers, fetchFn) {
+  const getUrl = `${base}/api/v2/pages/${encodeURIComponent(args.pageId)}`;
+  const getResp = await fetchFn(getUrl, { method: "GET", headers });
+  if (!getResp.ok) {
+    const body = await parseErrorBody(getResp);
+    throw new Error(
+      `GET ${getUrl} failed with ${getResp.status} ${getResp.statusText}${body ? `: ${body}` : ""}`
+    );
+  }
+  const current = await getResp.json();
+  const nextVersion = current.version.number + 1;
+  const title = args.title ?? current.title;
+  const putUrl = `${base}/api/v2/pages/${encodeURIComponent(args.pageId)}`;
+  const putResp = await fetchFn(putUrl, {
+    method: "PUT",
+    headers,
+    body: JSON.stringify({
+      id: args.pageId,
+      status: "current",
+      title,
+      body: {
+        representation: "atlas_doc_format",
+        value: args.adf
+      },
+      version: { number: nextVersion }
+    })
+  });
+  if (!putResp.ok) {
+    const body = await parseErrorBody(putResp);
+    throw new Error(
+      `PUT ${putUrl} failed with ${putResp.status} ${putResp.statusText}${body ? `: ${body}` : ""}`
+    );
+  }
+  const updated = await putResp.json();
+  return {
+    id: updated.id,
+    title: updated.title,
+    version: updated.version.number,
+    url: buildPageUrl(base, updated._links?.webui, updated.id),
+    action: "updated"
+  };
+}
+async function createPage(args, base, headers, fetchFn) {
+  const body = {
+    spaceId: args.spaceId,
+    status: "current",
+    title: args.title,
+    body: {
+      representation: "atlas_doc_format",
+      value: args.adf
+    }
+  };
+  if (args.parentId) body.parentId = args.parentId;
+  const postUrl = `${base}/api/v2/pages`;
+  const resp = await fetchFn(postUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  if (!resp.ok) {
+    const errBody = await parseErrorBody(resp);
+    throw new Error(
+      `POST ${postUrl} failed with ${resp.status} ${resp.statusText}${errBody ? `: ${errBody}` : ""}`
+    );
+  }
+  const created = await resp.json();
+  return {
+    id: created.id,
+    title: created.title,
+    version: created.version.number,
+    url: buildPageUrl(base, created._links?.webui, created.id),
+    action: "created"
+  };
+}
+function buildPageUrl(base, webui, id) {
+  if (webui) {
+    return webui.startsWith("http") ? webui : `${base}${webui}`;
+  }
+  return `${base}/pages/${id}`;
 }
 
 // src/publishers/jira.ts
@@ -7513,7 +8894,7 @@ function statusIcon2(status) {
       return "\u2022";
   }
 }
-function escapeCell2(value) {
+function escapeCell3(value) {
   return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 function intentSummary(intent) {
@@ -7542,7 +8923,7 @@ function renderWeakBand(lines, files) {
   lines.push(`## \u{1F7E1} Changed code with weak evidence (${weak.length})`);
   lines.push("");
   for (const file of weak) {
-    const covered = file.claims.map((c) => `${escapeCell2(c.scenario)} (${c.strength})`).join(", ");
+    const covered = file.claims.map((c) => `${escapeCell3(c.scenario)} (${c.strength})`).join(", ");
     lines.push(`- \`${file.path}\` _(${file.changeKind})_ \u2014 only: ${covered}`);
   }
   lines.push("");
@@ -7567,7 +8948,7 @@ function renderClaim(lines, claim) {
     );
   }
   if (claim.intent) {
-    lines.push(`- Why: ${escapeCell2(intentSummary(claim.intent))}`);
+    lines.push(`- Why: ${escapeCell3(intentSummary(claim.intent))}`);
   }
   lines.push("");
 }
@@ -7624,7 +9005,7 @@ function renderCodeDiff(lines, evidence) {
     } else {
       for (const ref of annotation.scenarios) {
         lines.push(
-          ref.resolved && ref.status ? `- ${statusIcon2(ref.status)} ${escapeCell2(ref.scenario ?? ref.id)} (\`${ref.id}\`)` : `- \u26A0\uFE0F \`${ref.id}\` \u2014 unverified reference (scenario not in this run)`
+          ref.resolved && ref.status ? `- ${statusIcon2(ref.status)} ${escapeCell3(ref.scenario ?? ref.id)} (\`${ref.id}\`)` : `- \u26A0\uFE0F \`${ref.id}\` \u2014 unverified reference (scenario not in this run)`
         );
       }
     }
@@ -7843,9 +9224,9 @@ function renderDiffHunk(file, hunk, anchoredStart, anchoredCount) {
     const sign = line.kind === "add" ? "+" : line.kind === "del" ? "-" : " ";
     return `<tr class="${cls}"><td class="diff-ln">${o}</td><td class="diff-ln">${n}</td><td class="diff-sign">${sign}</td><td class="diff-code">${escapeHtml3(line.text)}</td></tr>`;
   });
-  const path18 = file.newPath ?? file.oldPath ?? "";
+  const path20 = file.newPath ?? file.oldPath ?? "";
   return `<div class="diff-hunk">
-    <div class="diff-file-header"><code>${escapeHtml3(path18)}</code> <span class="subtle">@@ -${hunk.oldStart} +${hunk.newStart} @@ ${escapeHtml3(hunk.header)}</span></div>
+    <div class="diff-file-header"><code>${escapeHtml3(path20)}</code> <span class="subtle">@@ -${hunk.oldStart} +${hunk.newStart} @@ ${escapeHtml3(hunk.header)}</span></div>
     <table class="diff-table"><tbody>${rows.join("")}</tbody></table>
   </div>`;
 }
@@ -8080,8 +9461,8 @@ applyTheme(getEffectiveTheme());` : "";
 };
 
 // src/deploy/ledger.ts
-import * as fs5 from "fs";
-import * as path6 from "path";
+import * as fs6 from "fs";
+import * as path7 from "path";
 function createEmptyLedger() {
   return {
     deployments: [],
@@ -8089,12 +9470,12 @@ function createEmptyLedger() {
   };
 }
 function loadLedger(ledgerPath) {
-  const resolved = path6.resolve(ledgerPath);
-  if (!fs5.existsSync(resolved)) {
+  const resolved = path7.resolve(ledgerPath);
+  if (!fs6.existsSync(resolved)) {
     return createEmptyLedger();
   }
   try {
-    const raw = JSON.parse(fs5.readFileSync(resolved, "utf8"));
+    const raw = JSON.parse(fs6.readFileSync(resolved, "utf8"));
     if (raw.schemaVersion !== 1) {
       throw new Error(`Unsupported ledger schemaVersion: ${raw.schemaVersion}`);
     }
@@ -8105,10 +9486,10 @@ function loadLedger(ledgerPath) {
   }
 }
 function saveLedger(ledger, ledgerPath) {
-  const resolved = path6.resolve(ledgerPath);
-  const dir = path6.dirname(resolved);
-  fs5.mkdirSync(dir, { recursive: true });
-  fs5.writeFileSync(resolved, JSON.stringify(ledger, null, 2), "utf8");
+  const resolved = path7.resolve(ledgerPath);
+  const dir = path7.dirname(resolved);
+  fs6.mkdirSync(dir, { recursive: true });
+  fs6.writeFileSync(resolved, JSON.stringify(ledger, null, 2), "utf8");
 }
 function getLatestDeployment(ledger, environment) {
   return [...ledger.deployments].reverse().find((d) => d.environment === environment);
@@ -8235,11 +9616,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, joinNameAndExt(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);
@@ -8248,12 +9629,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));
   }
   if (colocatedStyle === "flat") {
-    return toPosix(path7.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
+    return toPosix(path8.posix.join(baseOutputDir, `${cleanTestStem(normalizedSource)}${ext}`));
   }
-  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();
@@ -8473,8 +9854,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,
@@ -8522,16 +9903,16 @@ var ReportGenerator = class {
       bySourceFile.set(sourceFile, outputPath);
     }
     if (bySourceFile.size === 0) return void 0;
-    const indexPath = toPosix(path7.join(this.options.outputDir, "index.html"));
+    const indexPath = toPosix(path8.join(this.options.outputDir, "index.html"));
     if (htmlPaths.some((p) => toPosix(p) === indexPath)) {
       this.deps.logger.warn?.(
         `Skipping colocated index: a report already occupies ${indexPath}.`
       );
       return void 0;
     }
-    const entries = buildIndexEntries(run, bySourceFile, path7.dirname(indexPath));
+    const entries = buildIndexEntries(run, bySourceFile, path8.dirname(indexPath));
     const html = renderColocatedIndex(entries, this.options.html.title);
-    await fsPromises.mkdir(path7.dirname(indexPath), { recursive: true });
+    await fsPromises.mkdir(path8.dirname(indexPath), { recursive: true });
     await this.deps.writeFile(indexPath, html);
     return indexPath;
   }
@@ -8550,9 +9931,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, joinNameAndExt(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];
@@ -8564,7 +9945,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);
@@ -8752,7 +10133,7 @@ async function generateRunComparison(args) {
   await fsPromises.mkdir(outputDir, { recursive: true });
   for (const format of args.formats) {
     const ext = format === "html" ? ".html" : format === "changelog" ? ".changelog.md" : ".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) : format === "changelog" ? new RunDiffChangelogFormatter().format(diff) : new RunDiffMarkdownFormatter({ title: args.title }).format(diff);
     await fsPromises.writeFile(outputPath, content, "utf8");
     files.push(outputPath);
@@ -8765,8 +10146,8 @@ import { parseNdjson as parseNdjson2 } from "executable-stories-core/converters/
 import { toCIInfo as toCIInfo2 } from "executable-stories-core/types/ci";
 
 // src/artifacts-readme.ts
-import * as fs6 from "fs";
-import * as path8 from "path";
+import * as fs7 from "fs";
+import * as path9 from "path";
 var README = `# executable-stories artifacts
 
 Generated by your test reporter and the \`executable-stories\` CLI. Safe to
@@ -8792,10 +10173,10 @@ Useful commands (all take \`raw-run.json\`):
 `;
 function writeArtifactsReadme(outputDir) {
   try {
-    const target = path8.join(outputDir, "README.md");
-    if (fs6.existsSync(target)) return false;
-    fs6.mkdirSync(outputDir, { recursive: true });
-    fs6.writeFileSync(target, README, "utf8");
+    const target = path9.join(outputDir, "README.md");
+    if (fs7.existsSync(target)) return false;
+    fs7.mkdirSync(outputDir, { recursive: true });
+    fs7.writeFileSync(target, README, "utf8");
     return true;
   } catch {
     return false;
@@ -8803,8 +10184,8 @@ function writeArtifactsReadme(outputDir) {
 }
 
 // src/explainers.ts
-import * as fs8 from "fs";
-import * as path10 from "path";
+import * as fs9 from "fs";
+import * as path11 from "path";
 import Ajv2 from "ajv/dist/2020.js";
 import { parse as parseYaml } from "yaml";
 import {
@@ -8863,16 +10244,16 @@ var explainer_v1_default = {
 };
 
 // src/utils/markdown-files.ts
-import * as fs7 from "fs";
-import * as path9 from "path";
+import * as fs8 from "fs";
+import * as path10 from "path";
 function collectMarkdownFiles(target) {
-  if (!fs7.existsSync(target)) return [];
-  if (fs7.statSync(target).isFile()) return [target];
+  if (!fs8.existsSync(target)) return [];
+  if (fs8.statSync(target).isFile()) return [target];
   const out = [];
   const walk = (dir) => {
-    for (const entry of fs7.readdirSync(dir, { withFileTypes: true })) {
+    for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-      const full = path9.join(dir, entry.name);
+      const full = path10.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (/\.mdx?$/u.test(entry.name)) out.push(full);
     }
@@ -8924,9 +10305,9 @@ function buildExplainersReport(args, _deps = {}) {
   const scenarios = report.features.flatMap((feature) => feature.scenarios);
   const explainers = [];
   for (const file of collectMarkdownFiles(args.dir).sort()) {
-    const parsed = parseExplainerDoc(fs8.readFileSync(file, "utf8"));
+    const parsed = parseExplainerDoc(fs9.readFileSync(file, "utf8"));
     if (!parsed) continue;
-    const rel = path10.relative(args.dir, file);
+    const rel = path11.relative(args.dir, file);
     if (!parsed.explainer) {
       explainers.push({ file: rel, status: "invalid", errors: parsed.errors });
       continue;
@@ -8995,13 +10376,13 @@ function renderExplainersReport(report, format) {
 }
 
 // src/run-file.ts
-import fs9 from "fs";
-import path11 from "path";
+import fs10 from "fs";
+import path12 from "path";
 var DEFAULT_RUN_FILES = [".executable-stories/raw-run.json", "reports/raw-run.json"];
 var SUPPORTED_RAW_RUN_SCHEMA = 1;
 function findDefaultRunFile(cwd = process.cwd()) {
   for (const candidate of DEFAULT_RUN_FILES) {
-    if (fs9.existsSync(path11.resolve(cwd, candidate))) return candidate;
+    if (fs10.existsSync(path12.resolve(cwd, candidate))) return candidate;
   }
   return void 0;
 }
@@ -9027,8 +10408,8 @@ function diagnoseRunFile(file, cwd = process.cwd()) {
     });
     return { checks, healthy: false };
   }
-  const abs = path11.resolve(cwd, resolved);
-  if (!fs9.existsSync(abs)) {
+  const abs = path12.resolve(cwd, resolved);
+  if (!fs10.existsSync(abs)) {
     checks.push({
       label: "run file",
       status: "fail",
@@ -9037,7 +10418,7 @@ function diagnoseRunFile(file, cwd = process.cwd()) {
     });
     return { checks, healthy: false };
   }
-  const stat = fs9.statSync(abs);
+  const stat = fs10.statSync(abs);
   checks.push({
     label: "run file",
     status: "ok",
@@ -9045,7 +10426,7 @@ function diagnoseRunFile(file, cwd = process.cwd()) {
   });
   let parsed;
   try {
-    parsed = JSON.parse(fs9.readFileSync(abs, "utf8"));
+    parsed = JSON.parse(fs10.readFileSync(abs, "utf8"));
   } catch (err) {
     checks.push({
       label: "json",
@@ -9176,7 +10557,9 @@ var COMPLETION_SUBCOMMANDS = [
   ["init-astro", "Scaffold a thin Astro docs site"],
   ["new", "Scaffold a docs page from a template"],
   ["check-links", "Scan docs for broken links"],
-  ["push", "Send a run to Executable Stories Cloud"],
+  ["push", "Send a run to a cloud ingest endpoint"],
+  ["coverage", "Compare stories against a test-management system (read-only)"],
+  ["sync", "Push cases, executions, and evidence to TestRail or Xray"],
   ["import-openapi", "Generate API doc pages from an OpenAPI spec"],
   ["publish-confluence", "Publish an ADF JSON file to Confluence"],
   ["publish-jira", "Publish an ADF JSON file to a Jira issue"],
@@ -9198,8 +10581,16 @@ var COMMON_FLAGS = [
   "--baseline",
   "--baseline-dir",
   "--emit-canonical",
+  "--apply",
+  "--attach",
+  "--report-url",
   "--help"
 ];
+var SUBCOMMAND_VALUES = {
+  completion: ["bash", "zsh", "fish"],
+  sync: [...PROVIDER_NAMES],
+  coverage: [...PROVIDER_NAMES]
+};
 var FLAG_VALUES = {
   "--format": [
     "html",
@@ -9221,12 +10612,13 @@ var FLAG_VALUES = {
   "--preset": ["agent", "ci", "docs"],
   "--input-type": ["raw", "canonical", "ndjson"],
   "--list-format": ["text", "json", "csv", "markdown-table"],
-  "--check-format": ["text", "json"]
+  "--check-format": ["text", "json"],
+  "--attach": ["failed", "all", "none"]
 };
 function bashScript() {
   const subcommands = COMPLETION_SUBCOMMANDS.map(([name]) => name).join(" ");
   const flags = COMMON_FLAGS.join(" ");
-  const valueCases = Object.entries(FLAG_VALUES).map(([flag, values]) => `    ${flag})
+  const valueCases = [...Object.entries(FLAG_VALUES), ...Object.entries(SUBCOMMAND_VALUES)].map(([word, values]) => `    ${word})
       COMPREPLY=( $(compgen -W "${values.join(" ")}" -- "$cur") ); return 0 ;;`).join("\n");
   return `# executable-stories bash completion
 _executable_stories() {
@@ -9236,8 +10628,6 @@ _executable_stories() {
 
   case "$prev" in
 ${valueCases}
-    completion)
-      COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ); return 0 ;;
   esac
 
   if [ "$COMP_CWORD" -eq 1 ]; then
@@ -9257,8 +10647,8 @@ function zshScript() {
   const subcommands = COMPLETION_SUBCOMMANDS.map(([name, desc]) => `    '${name}:${desc.replaceAll("'", "")}'`).join(
     "\n"
   );
-  const valueCases = Object.entries(FLAG_VALUES).map(([flag, values]) => `    ${flag})
-      _values '${flag.slice(2)}' ${values.join(" ")} ;;`).join("\n");
+  const valueCases = [...Object.entries(FLAG_VALUES), ...Object.entries(SUBCOMMAND_VALUES)].map(([word, values]) => `    ${word})
+      _values '${word.replace(/^--/, "")}' ${values.join(" ")} ;;`).join("\n");
   return `#compdef executable-stories
 # executable-stories zsh completion
 
@@ -9270,8 +10660,6 @@ ${subcommands}
 
   case "\${words[CURRENT-1]}" in
 ${valueCases}
-    completion)
-      _values 'shell' bash zsh fish ;;
     *)
       if (( CURRENT == 2 )); then
         _describe 'subcommand' subcommands
@@ -9300,6 +10688,11 @@ function fishScript() {
       `complete -c executable-stories -l ${flag.slice(2)} -x -a '${values.join(" ")}'`
     );
   }
+  for (const [subcommand, values] of Object.entries(SUBCOMMAND_VALUES)) {
+    lines.push(
+      `complete -c executable-stories -n '__fish_seen_subcommand_from ${subcommand}' -x -a '${values.join(" ")}'`
+    );
+  }
   lines.push("complete -c executable-stories -l open -d 'Open the HTML report when done'");
   lines.push("complete -c executable-stories -l help -d 'Show help'");
   return `# executable-stories fish completion
@@ -9334,7 +10727,7 @@ function runCompletion(args) {
 
 // src/open-report.ts
 import { spawn } from "child_process";
-import path12 from "path";
+import path13 from "path";
 function openCommand(platform) {
   if (platform === "darwin") return { command: "open", args: [] };
   if (platform === "win32") return { command: "cmd", args: ["/c", "start", ""] };
@@ -9350,7 +10743,7 @@ function openInBrowser(file, platform = process.platform) {
   }
   const { command, args } = openCommand(platform);
   try {
-    const child = spawn(command, [...args, path12.resolve(file)], { stdio: "ignore", detached: true });
+    const child = spawn(command, [...args, path13.resolve(file)], { stdio: "ignore", detached: true });
     child.on("error", (err) => {
       console.error(`--open: could not open ${file}: ${err.message}`);
     });
@@ -9378,14 +10771,14 @@ function summaryLine(counts, files, durationMs) {
 
 // src/init-astro.ts
 import { spawnSync } from "child_process";
-import * as fs10 from "fs";
-import * as path13 from "path";
+import * as fs11 from "fs";
+import * as path14 from "path";
 import { fileURLToPath } from "url";
-var __dirname = path13.dirname(fileURLToPath(import.meta.url));
+var __dirname = path14.dirname(fileURLToPath(import.meta.url));
 function detectPackageManager(cwd = process.cwd()) {
-  if (fs10.existsSync(path13.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs10.existsSync(path13.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs10.existsSync(path13.join(cwd, "bun.lock")) || fs10.existsSync(path13.join(cwd, "bun.lockb"))) {
+  if (fs11.existsSync(path14.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs11.existsSync(path14.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs11.existsSync(path14.join(cwd, "bun.lock")) || fs11.existsSync(path14.join(cwd, "bun.lockb"))) {
     return "bun";
   }
   return "npm";
@@ -9406,7 +10799,7 @@ function runDocsDev(siteDir) {
     return { kind: "not-scaffolded" };
   }
   const pm = detectPackageManager();
-  if (!fs10.existsSync(path13.join(siteDir, "node_modules"))) {
+  if (!fs11.existsSync(path14.join(siteDir, "node_modules"))) {
     console.log(`Installing docs site dependencies with ${pm}\u2026`);
     if (!installScaffoldDependencies(siteDir, pm)) {
       return { kind: "install-failed", pm };
@@ -9417,14 +10810,14 @@ function runDocsDev(siteDir) {
 }
 var SCAFFOLD_MARKER = "executable-stories.config.mjs";
 function isScaffoldedAstroSite(dir) {
-  return fs10.existsSync(path13.join(dir, SCAFFOLD_MARKER));
+  return fs11.existsSync(path14.join(dir, SCAFFOLD_MARKER));
 }
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
   const update = options.update ?? false;
-  const templateDir = path13.resolve(__dirname, "..", "templates", "astro-thin");
-  if (!fs10.existsSync(templateDir)) {
+  const templateDir = path14.resolve(__dirname, "..", "templates", "astro-thin");
+  if (!fs11.existsSync(templateDir)) {
     throw new Error(
       `Template directory not found at ${templateDir}. Ensure the package is installed correctly.`
     );
@@ -9432,8 +10825,8 @@ function initAstro(options = {}) {
   if (update) {
     return updateScaffoldDeps(templateDir, targetDir);
   }
-  if (fs10.existsSync(targetDir)) {
-    const entries = fs10.readdirSync(targetDir);
+  if (fs11.existsSync(targetDir)) {
+    const entries = fs11.readdirSync(targetDir);
     if (entries.length > 0 && !force) {
       throw new Error(
         `Directory "${targetDir}" already exists and is not empty. Use --force to overlay the template (existing files are kept; same-path template files are overwritten), or --update to refresh framework files only.`
@@ -9453,11 +10846,11 @@ function updateScaffoldDeps(templateDir, targetDir) {
   return { targetDir };
 }
 function mergeDependencies(templateDir, targetDir) {
-  const tmplPkgPath = path13.join(templateDir, "package.json");
-  const userPkgPath = path13.join(targetDir, "package.json");
-  if (!fs10.existsSync(tmplPkgPath) || !fs10.existsSync(userPkgPath)) return;
-  const tmpl = JSON.parse(fs10.readFileSync(tmplPkgPath, "utf8"));
-  const user = JSON.parse(fs10.readFileSync(userPkgPath, "utf8"));
+  const tmplPkgPath = path14.join(templateDir, "package.json");
+  const userPkgPath = path14.join(targetDir, "package.json");
+  if (!fs11.existsSync(tmplPkgPath) || !fs11.existsSync(userPkgPath)) return;
+  const tmpl = JSON.parse(fs11.readFileSync(tmplPkgPath, "utf8"));
+  const user = JSON.parse(fs11.readFileSync(userPkgPath, "utf8"));
   user.dependencies = user.dependencies ?? {};
   let changed = false;
   for (const [name, version] of Object.entries(tmpl.dependencies ?? {})) {
@@ -9467,28 +10860,28 @@ function mergeDependencies(templateDir, targetDir) {
     }
   }
   if (changed) {
-    fs10.writeFileSync(userPkgPath, `${JSON.stringify(user, null, 2)}
+    fs11.writeFileSync(userPkgPath, `${JSON.stringify(user, null, 2)}
 `, "utf8");
   }
 }
 function copyDirRecursive(src, dest) {
-  fs10.mkdirSync(dest, { recursive: true });
-  const entries = fs10.readdirSync(src, { withFileTypes: true });
+  fs11.mkdirSync(dest, { recursive: true });
+  const entries = fs11.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path13.join(src, entry.name);
+    const srcPath = path14.join(src, entry.name);
     const destName = entry.name === "gitignore" ? ".gitignore" : entry.name;
-    const destPath = path13.join(dest, destName);
+    const destPath = path14.join(dest, destName);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
-      fs10.copyFileSync(srcPath, destPath);
+      fs11.copyFileSync(srcPath, destPath);
     }
   }
 }
 
 // src/scaffold-doc.ts
-import * as fs11 from "fs";
-import * as path14 from "path";
+import * as fs12 from "fs";
+import * as path15 from "path";
 var TEMPLATES = [
   "adr",
   "runbook",
@@ -9505,7 +10898,7 @@ function isoDate(today) {
 function nextSeq(dir) {
   let max = 0;
   try {
-    for (const entry of fs11.readdirSync(dir)) {
+    for (const entry of fs12.readdirSync(dir)) {
       const match = /^(\d{1,4})-/.exec(entry);
       if (match) max = Math.max(max, Number.parseInt(match[1], 10));
     }
@@ -9662,12 +11055,12 @@ function scaffoldDoc(options) {
     );
   }
   const spec = TEMPLATE_SPECS[template];
-  const baseDir = options.baseDir ?? path14.join("src", "content", "docs");
+  const baseDir = options.baseDir ?? path15.join("src", "content", "docs");
   const today = options.today ?? /* @__PURE__ */ new Date();
   const name = (options.name ?? "").trim() || defaultName(template);
   const slug2 = slugify3(name);
   const scenarioId = normalizeScenarioId(options.scenarioId);
-  const dir = path14.join(baseDir, spec.subdir);
+  const dir = path15.join(baseDir, spec.subdir);
   if (template === "scenario-note" && !scenarioId) {
     throw new Error(`Template "scenario-note" requires --scenario-id.`);
   }
@@ -9679,14 +11072,14 @@ function scaffoldDoc(options) {
     seq: nextSeq(dir)
   };
   const filename = `${spec.filename(slug2, ctx)}.mdx`;
-  const filePath = path14.join(dir, filename);
-  if (fs11.existsSync(filePath) && !options.force) {
+  const filePath = path15.join(dir, filename);
+  if (fs12.existsSync(filePath) && !options.force) {
     throw new Error(
       `File "${filePath}" already exists. Use --force to overwrite.`
     );
   }
-  fs11.mkdirSync(dir, { recursive: true });
-  fs11.writeFileSync(filePath, spec.content(ctx), "utf8");
+  fs12.mkdirSync(dir, { recursive: true });
+  fs12.writeFileSync(filePath, spec.content(ctx), "utf8");
   return { template, path: filePath, title: titleFor2(template, ctx) };
 }
 function defaultName(template) {
@@ -9727,8 +11120,8 @@ function normalizeScenarioId(input) {
 }
 
 // src/check-links.ts
-import * as fs12 from "fs";
-import * as path15 from "path";
+import * as fs13 from "fs";
+import * as path16 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, "");
@@ -9742,8 +11135,8 @@ function extractLinks(markdown) {
   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) {
+  const attrRe = /\b(?:href|src)\s*=\s*["']([^"']+)["']/gi;
+  while ((match = attrRe.exec(stripped)) !== null) {
     found.push(match[1].trim());
   }
   return found.filter(Boolean);
@@ -9755,21 +11148,37 @@ function classifyLink(link2) {
   if (link2.startsWith("/")) return "root";
   return "internal";
 }
-function resolutionCandidates(fromFile, link2) {
-  const withoutAnchor = link2.split("#")[0];
-  if (!withoutAnchor) return [];
-  const base = path15.resolve(path15.dirname(fromFile), withoutAnchor);
+function resolutionCandidates(fromDir, linkPath) {
+  const base = path16.resolve(fromDir, linkPath);
   const candidates = [base];
-  if (!path15.extname(base)) {
+  if (!path16.extname(base)) {
     candidates.push(`${base}.md`, `${base}.mdx`);
-    candidates.push(path15.join(base, "index.md"), path15.join(base, "index.mdx"));
+    candidates.push(path16.join(base, "index.md"), path16.join(base, "index.mdx"));
   }
   return candidates;
 }
-function resolvesOnDisk(fromFile, link2) {
-  return resolutionCandidates(fromFile, link2).some(
-    (candidate) => fs12.existsSync(candidate) && fs12.statSync(candidate).isFile()
-  );
+function linkPathOf(link2) {
+  return link2.split("#")[0].split("?")[0];
+}
+function existsAsFile(candidate) {
+  return fs13.existsSync(candidate) && fs13.statSync(candidate).isFile();
+}
+function resolvesFrom(dirs, linkPath) {
+  return dirs.some((dir) => resolutionCandidates(dir, linkPath).some(existsAsFile));
+}
+function detectAssetRoots(target) {
+  let dir = fs13.existsSync(target) && fs13.statSync(target).isDirectory() ? path16.resolve(target) : path16.dirname(path16.resolve(target));
+  for (let depth = 0; depth < 6; depth++) {
+    const hasConfig = ["mjs", "js", "ts", "mts"].some(
+      (ext) => fs13.existsSync(path16.join(dir, `astro.config.${ext}`))
+    );
+    const publicDir = path16.join(dir, "public");
+    if (hasConfig && fs13.existsSync(publicDir)) return [publicDir];
+    const parent = path16.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return [];
 }
 async function isExternalAlive(url, timeoutMs) {
   const attempt = async (method) => {
@@ -9794,9 +11203,11 @@ async function isExternalAlive(url, timeoutMs) {
 }
 async function checkLinks(options) {
   const { target, checkExternal = false, externalTimeoutMs = 8e3 } = options;
-  if (!fs12.existsSync(target)) {
+  if (!fs13.existsSync(target)) {
     throw new Error(`Path not found: ${target}`);
   }
+  const siteRoot = path16.resolve(options.siteRoot ?? target);
+  const rootDirs = [siteRoot, ...(options.assetRoots ?? detectAssetRoots(target)).map((d) => path16.resolve(d))];
   const files = collectMarkdownFiles(target);
   const broken = [];
   let linksChecked = 0;
@@ -9804,13 +11215,25 @@ async function checkLinks(options) {
   let skipped = 0;
   const externalCache = /* @__PURE__ */ new Map();
   for (const file of files) {
-    const content = fs12.readFileSync(file, "utf8");
+    const content = fs13.readFileSync(file, "utf8");
     for (const link2 of extractLinks(content)) {
       const kind = classifyLink(link2);
-      if (kind === "anchor" || kind === "mail" || kind === "root") {
+      if (kind === "anchor" || kind === "mail") {
         skipped += 1;
         continue;
       }
+      if (kind === "root") {
+        const linkPath2 = linkPathOf(link2).replace(/^\/+/, "");
+        if (linkPath2 === "") {
+          skipped += 1;
+          continue;
+        }
+        linksChecked += 1;
+        if (!resolvesFrom(rootDirs, linkPath2)) {
+          broken.push({ file, link: link2, reason: "target file not found" });
+        }
+        continue;
+      }
       if (kind === "external") {
         if (!checkExternal) {
           skipped += 1;
@@ -9828,8 +11251,13 @@ async function checkLinks(options) {
         }
         continue;
       }
+      const linkPath = linkPathOf(link2);
+      if (linkPath === "") {
+        skipped += 1;
+        continue;
+      }
       linksChecked += 1;
-      if (!resolvesOnDisk(file, link2)) {
+      if (!resolvesFrom([path16.dirname(file)], linkPath)) {
         broken.push({ file, link: link2, reason: "target file not found" });
       }
     }
@@ -9861,7 +11289,7 @@ function formatLinkReport(report) {
 
 // src/push.ts
 import { execFileSync } from "child_process";
-import * as fs13 from "fs";
+import * as fs14 from "fs";
 import { parseArgs } from "util";
 import { canonicalizeRun as canonicalizeRun4 } from "executable-stories-core/converters/acl/index";
 import { toStoryReport as toStoryReport8 } from "executable-stories-core/converters/story-report";
@@ -9869,10 +11297,11 @@ import { synthesizeStories as synthesizeStories2 } from "executable-stories-core
 var EXIT_SUCCESS = 0;
 var EXIT_PUSH_FAILED = 1;
 var EXIT_USAGE = 4;
+var EXIT_GATE_BLOCKED = 5;
 var HELP = `Usage:
   executable-stories push <run.json> [options]
 
-Send a run to Executable Stories Cloud. <run.json> is either a StoryReport v1
+Send a run to a cloud ingest endpoint. <run.json> is either a StoryReport v1
 (e.g. reports/index.story-report.json) or a raw run JSON, which is converted
 through the standard pipeline first.
 
@@ -9886,12 +11315,20 @@ Options:
   --git-sha <sha>    Default: current git HEAD.
   --base <ref>       Send files changed since <ref> (e.g. origin/main) so the
                      cloud can recommend a test scope for the change.
+  --gate             After pushing, ask the cloud whether this commit is safe
+                     to release and exit 5 if it is blocked. The policy lives
+                     in your organization's settings, not in a file here.
   -h, --help         Show this help.
 
-Exit codes: 0 pushed, 1 push rejected/failed, 4 usage error.`;
+Under GitHub Actions, repo/branch/sha, the base commit, and PR metadata are
+read from the environment, the run URL and recommended scope are written to
+the job summary, and the run id is written to GITHUB_OUTPUT as ingest-run-id.
+
+Exit codes: 0 pushed, 1 push rejected/failed, 4 usage error, 5 gate blocked.`;
 function defaultDeps() {
   return {
-    readFile: (filePath) => fs13.readFileSync(filePath, "utf8"),
+    readFile: (filePath) => fs14.readFileSync(filePath, "utf8"),
+    appendFile: (filePath, text2) => fs14.appendFileSync(filePath, text2),
     fetchFn: fetch,
     git: (args) => {
       try {
@@ -9912,6 +11349,42 @@ function repoSlugFromRemote(remoteUrl) {
 function isStoryReport(data) {
   return typeof data.schemaVersion === "string";
 }
+function githubContext(deps) {
+  const env = deps.env;
+  const context = {
+    repo: env.GITHUB_REPOSITORY,
+    // GITHUB_HEAD_REF is the source branch on a pull_request event, where
+    // GITHUB_REF_NAME would be the synthetic "<n>/merge" ref.
+    branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+    gitSha: env.GITHUB_SHA
+  };
+  let event;
+  try {
+    event = JSON.parse(deps.readFile(env.GITHUB_EVENT_PATH ?? ""));
+  } catch {
+    return context;
+  }
+  context.prNumber = event.pull_request?.number;
+  context.prUrl = event.pull_request?.html_url;
+  const baseSha = event.pull_request?.base?.sha ?? event.before;
+  if (baseSha && !/^0+$/.test(baseSha)) {
+    if (deps.git(["cat-file", "-e", baseSha]) === void 0) {
+      deps.git(["fetch", "--depth=1", "origin", baseSha]);
+    }
+    context.baseSha = baseSha;
+  }
+  return context;
+}
+function summaryWriter(deps) {
+  const summaryPath = deps.env.GITHUB_STEP_SUMMARY;
+  return (markdown) => {
+    if (summaryPath) deps.appendFile(summaryPath, `${markdown}
+`);
+  };
+}
+function cell(text2) {
+  return text2.replaceAll("|", "\\|");
+}
 async function runPush(rawArgs, depsOverride = {}) {
   const deps = { ...defaultDeps(), ...depsOverride };
   let parsed;
@@ -9926,6 +11399,7 @@ async function runPush(rawArgs, depsOverride = {}) {
         branch: { type: "string" },
         "git-sha": { type: "string" },
         base: { type: "string" },
+        gate: { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -9947,7 +11421,7 @@ async function runPush(rawArgs, depsOverride = {}) {
   const key = parsed.values.key ?? deps.env.EXECUTABLE_STORIES_API_KEY;
   if (!key) {
     deps.error(
-      "push needs an API key: pass --key or set EXECUTABLE_STORIES_API_KEY. Create one in Executable Stories Cloud (Settings -> Ingest key)."
+      "push needs an API key: pass --key or set EXECUTABLE_STORIES_API_KEY. Create one in your cloud instance's settings (Ingest key)."
     );
     return EXIT_USAGE;
   }
@@ -9971,16 +11445,20 @@ async function runPush(rawArgs, depsOverride = {}) {
       return EXIT_USAGE;
     }
   }
-  const repo = parsed.values.repo ?? repoSlugFromRemote(deps.git(["config", "--get", "remote.origin.url"]) ?? "");
+  const onActions = deps.env.GITHUB_ACTIONS === "true";
+  const github = onActions ? githubContext(deps) : {};
+  const summary = summaryWriter(deps);
+  const repo = parsed.values.repo ?? github.repo ?? repoSlugFromRemote(deps.git(["config", "--get", "remote.origin.url"]) ?? "");
   if (!repo) {
     deps.error("Could not infer the repository slug from git. Pass --repo <org/name>.");
     return EXIT_USAGE;
   }
-  const branch = parsed.values.branch ?? deps.git(["rev-parse", "--abbrev-ref", "HEAD"]);
-  const gitSha = parsed.values["git-sha"] ?? deps.git(["rev-parse", "HEAD"]);
+  const branch = parsed.values.branch ?? github.branch ?? deps.git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const gitSha = parsed.values["git-sha"] ?? github.gitSha ?? deps.git(["rev-parse", "HEAD"]);
   const baseUrl = parsed.values.url ?? deps.env.EXECUTABLE_STORIES_URL ?? "https://app.executablestories.com";
   const base = parsed.values.base;
-  const changedFiles = base ? deps.git(["diff", "--name-only", `${base}...HEAD`])?.split("\n").filter(Boolean) ?? [] : [];
+  const baseSha = base ? deps.git(["rev-parse", base]) : github.baseSha;
+  const changedFiles = baseSha ? deps.git(["diff", "--name-only", `${baseSha}...HEAD`])?.split("\n").filter(Boolean) ?? [] : [];
   if (base && changedFiles.length === 0) {
     deps.error(`Warning: no changed files found against ${base}; pushing without change metadata.`);
   }
@@ -9996,9 +11474,13 @@ async function runPush(rawArgs, depsOverride = {}) {
         repo,
         branch,
         gitSha,
-        source: "serve",
+        // "serve" named a subcommand that no longer exists (ADR 0006). The
+        // cloud accepts both; "local" is what this is.
+        source: onActions ? "action" : "local",
         report,
-        ...changedFiles.length > 0 ? { changedFiles, baseSha: deps.git(["rev-parse", base]) } : {}
+        ...changedFiles.length > 0 ? { changedFiles, baseSha } : {},
+        ...github.prNumber ? { prNumber: github.prNumber } : {},
+        ...github.prUrl ? { prUrl: github.prUrl } : {}
       })
     });
   } catch (err) {
@@ -10011,18 +11493,428 @@ async function runPush(rawArgs, depsOverride = {}) {
     deps.error(`Push rejected: HTTP ${response.status}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${body.slice(0, 500)}`);
     return EXIT_PUSH_FAILED;
   }
-  let runId = "";
+  let result = {};
   try {
-    runId = String(JSON.parse(body).runId ?? "");
+    result = JSON.parse(body);
   } catch {
   }
+  const runId = String(result.runId ?? "");
   deps.log(runId ? `Pushed run ${runId} (${repo}${branch ? `@${branch}` : ""})` : "Pushed run.");
+  if (result.url) deps.log(result.url);
+  summary(
+    result.url ? `### Executable Stories
+
+[View this run](${result.url})` : "### Executable Stories\n\nRun pushed."
+  );
+  if (runId && deps.env.GITHUB_OUTPUT) {
+    deps.appendFile(deps.env.GITHUB_OUTPUT, `ingest-run-id=${runId}
+`);
+  }
+  const recommendations = result.recommendations ?? [];
+  if (recommendations.length > 0) {
+    deps.log(`
+Recommended scope for this change (${recommendations.length}):`);
+    for (const item of recommendations) {
+      deps.log(`  [${item.confidence}] ${item.title} \u2014 ${item.reason}`);
+    }
+    summary(`
+**Recommended scope for this change (${recommendations.length})**
+`);
+    summary("| Confidence | Case | Why |\n| --- | --- | --- |");
+    for (const item of recommendations) {
+      summary(`| ${cell(item.confidence)} | ${cell(item.title)} | ${cell(item.reason)} |`);
+    }
+  }
+  if (!parsed.values.gate) return EXIT_SUCCESS;
+  if (!gitSha) {
+    deps.error("--gate needs a commit sha: pass --git-sha or run inside a git repository.");
+    return EXIT_USAGE;
+  }
+  return await runGate({ baseUrl, key, repo, gitSha, onActions }, deps);
+}
+async function runGate({
+  baseUrl,
+  key,
+  repo,
+  gitSha,
+  onActions
+}, deps) {
+  const summary = summaryWriter(deps);
+  const query = `repo=${encodeURIComponent(repo)}&sha=${encodeURIComponent(gitSha)}`;
+  let response;
+  try {
+    response = await deps.fetchFn(new URL(`/api/v1/releases/gate?${query}`, baseUrl), {
+      headers: { Authorization: `Bearer ${key}` }
+    });
+  } catch (err) {
+    deps.error(`Could not reach the gate: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  const body = await response.text();
+  if (!response.ok) {
+    deps.error(`Gate check failed: HTTP ${response.status}: ${body.slice(0, 500)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  let gate = {};
+  try {
+    gate = JSON.parse(body);
+  } catch {
+    deps.error(`Gate returned a non-JSON body: ${body.slice(0, 200)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  for (const warning of gate.warnings ?? []) deps.log(`  warning: ${warning}`);
+  const commit = `${repo}@${gitSha.slice(0, 12)}`;
+  if (gate.status === "no-release") {
+    deps.log(`
+No release recorded for ${commit} \u2014 nothing to gate on.`);
+    summary("\n**Release gate: no release recorded for this commit**");
+    return EXIT_SUCCESS;
+  }
+  if (gate.status === "blocked") {
+    deps.error(`
+Release gate: BLOCKED for ${commit}`);
+    summary("\n**Release gate: blocked**\n");
+    for (const reason of gate.blocking ?? []) {
+      deps.error(`  - ${reason}`);
+      summary(`- ${reason}`);
+      if (onActions) deps.error(`::error::Release gate: ${reason}`);
+    }
+    return EXIT_GATE_BLOCKED;
+  }
+  deps.log(`
+Release gate: clear for ${commit}`);
+  summary("\n**Release gate: clear**");
   return EXIT_SUCCESS;
 }
 
+// src/sync/run.ts
+import * as fs15 from "fs";
+import * as path17 from "path";
+import { parseArgs as parseArgs2 } from "util";
+import { canonicalizeRun as canonicalizeRun5 } from "executable-stories-core/converters/acl/index";
+import { synthesizeStories as synthesizeStories3 } from "executable-stories-core/converters/synthesize";
+
+// src/config.ts
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { resolve as resolve9 } from "path";
+var CONFIG_CANDIDATES = [
+  "executable-stories.config.mjs",
+  "executable-stories.config.js",
+  "executable-stories.config.json"
+];
+async function loadConfig(configPath) {
+  let resolved;
+  if (configPath) {
+    resolved = resolve9(configPath);
+  } else {
+    const present = CONFIG_CANDIDATES.map((name) => resolve9(process.cwd(), name)).filter(existsSync11);
+    if (present.length > 1) {
+      throw new Error(
+        `Multiple config files found in this directory:
+` + present.map((p) => `  - ${p}`).join("\n") + `
+Keep only one, or pass --config <path> to choose which to load.`
+      );
+    }
+    resolved = present[0];
+  }
+  if (!resolved || !existsSync11(resolved)) return {};
+  const isJson = resolved.endsWith(".json");
+  let config;
+  if (isJson) {
+    try {
+      config = JSON.parse(readFileSync10(resolved, "utf8"));
+    } catch (err) {
+      throw new Error(`Config file at ${resolved} is not valid JSON: ${err.message}`);
+    }
+  } else {
+    config = (await import(resolved)).default;
+  }
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(
+      isJson ? `Config file at ${resolved} must contain a JSON object. Got: ${Array.isArray(config) ? "array" : typeof config}` : `Config file at ${resolved} must export a default object. Got: ${typeof config}`
+    );
+  }
+  const { formatters, sync } = config;
+  return {
+    ...formatters === void 0 ? {} : { formatters },
+    ...sync === void 0 ? {} : { sync }
+  };
+}
+
+// src/sync/run.ts
+var EXIT_SUCCESS2 = 0;
+var EXIT_FAILED = 1;
+var EXIT_USAGE2 = 4;
+var COVERAGE_HELP = `Usage:
+  executable-stories coverage <provider> <run.json> [options]
+
+Compares what your tests cover against what a test-management system holds.
+Read-only: needs nothing but a read-scoped API key, and writes nothing remote.
+
+Providers: ${PROVIDER_NAMES.join(", ")}
+
+Options:
+  --config <path>      Config file (default: executable-stories.config.mjs, .js, or .json)
+  --output-dir <dir>   Where the JSON and Markdown land (default: reports)
+  --report-url <url>   Published report URL, used for deep links
+  --lockfile <path>    Default: ${DEFAULT_LOCKFILE_PATH}
+  --quiet              Write the artifacts, skip the stdout summary
+  -h, --help           Show this help
+
+Credentials come from the environment:
+  TestRail  TESTRAIL_USERNAME, TESTRAIL_API_KEY
+  Xray      XRAY_CLIENT_ID, XRAY_CLIENT_SECRET (JIRA_EMAIL/JIRA_TOKEN to edit Jira fields)
+
+Exit codes: 0 report produced, 1 provider unreachable, 4 usage error.`;
+var SYNC_HELP = `Usage:
+  executable-stories sync <provider> <run.json> [options]
+
+Pushes stories into a test-management system: case bodies authored from the
+test, executions recorded against them, evidence attached.
+
+Prints the plan and changes nothing unless --apply is passed.
+
+Providers: ${PROVIDER_NAMES.join(", ")}
+
+Options:
+  --apply              Actually write. Without it, this is a dry run.
+  --attach <policy>    failed (default), all, or none
+  --config <path>      Config file (default: executable-stories.config.mjs, .js, or .json)
+  --lockfile <path>    Default: ${DEFAULT_LOCKFILE_PATH}
+  --report-url <url>   Published report URL, used for deep links
+  --output-dir <dir>   Where coverage artifacts land (default: reports)
+  --continue-on-error  Exit 0 even when some writes failed
+  --init               Print a config block for this provider and exit
+  -h, --help           Show this help
+
+The lockfile binds each story to its case. Commit it: the diff shows up in the
+pull request that created the case.
+
+Exit codes: 0 applied (or planned), 1 some writes failed, 4 usage error.`;
+function defaultDeps2() {
+  return {
+    readFile: (filePath) => fs15.readFileSync(filePath, "utf8"),
+    fileExists: (filePath) => fs15.existsSync(filePath),
+    writeFile: (filePath, contents) => {
+      fs15.mkdirSync(path17.dirname(path17.resolve(filePath)), { recursive: true });
+      fs15.writeFileSync(filePath, contents, "utf8");
+    },
+    fetchFn: globalThis.fetch,
+    env: process.env,
+    log: console.log,
+    error: console.error,
+    loadConfigFn: loadConfig
+  };
+}
+var CONFIG_TEMPLATES = {
+  testrail: `export default {
+  sync: {
+    testrail: {
+      url: "https://acme.testrail.io",
+      projectId: 1,
+      suiteId: 1,
+      // Section that newly created cases land in. Without it, creation is refused.
+      sectionId: 1,
+      // TestRail ships no "skipped" status; set one to record skipped tests.
+      // statusIds: { skipped: 6 },
+      // Only needed if this instance uses a customised case template.
+      // fields: { steps: "custom_steps_separated", description: "custom_preconds" },
+    },
+  },
+};
+
+// Environment: TESTRAIL_USERNAME (login email), TESTRAIL_API_KEY (My Settings -> API Keys)`,
+  xray: `export default {
+  sync: {
+    xray: {
+      jiraBaseUrl: "https://acme.atlassian.net",
+      projectKey: "PROJ",
+      // testPlanKey: "PROJ-100",
+    },
+  },
+};
+
+// Environment: XRAY_CLIENT_ID, XRAY_CLIENT_SECRET (Jira -> Apps -> Xray -> API Keys)
+// Optional:    JIRA_EMAIL, JIRA_TOKEN (needed to update an existing test's summary/description)`
+};
+var JSON_CONFIG_TEMPLATES = {
+  testrail: JSON.stringify(
+    { sync: { testrail: { url: "https://acme.testrail.io", projectId: 1, suiteId: 1, sectionId: 1 } } },
+    null,
+    2
+  ),
+  xray: JSON.stringify(
+    { sync: { xray: { jiraBaseUrl: "https://acme.atlassian.net", projectKey: "PROJ" } } },
+    null,
+    2
+  )
+};
+function isStoryReport2(data) {
+  return typeof data.schemaVersion === "string";
+}
+function loadRun(inputPath, deps) {
+  const data = JSON.parse(deps.readFile(inputPath));
+  if (isStoryReport2(data)) {
+    throw new Error(
+      `${inputPath} is a StoryReport, which has already dropped the attachment bodies and source paths this needs. Point at the raw run instead (e.g. reports/raw-run.json).`
+    );
+  }
+  return canonicalizeRun5(synthesizeStories3(data));
+}
+async function runSyncCommand(mode, rawArgs, depsOverride = {}) {
+  const deps = { ...defaultDeps2(), ...depsOverride };
+  const help = mode === "sync" ? SYNC_HELP : COVERAGE_HELP;
+  let parsed;
+  try {
+    parsed = parseArgs2({
+      args: rawArgs,
+      allowPositionals: true,
+      options: {
+        apply: { type: "boolean", default: false },
+        attach: { type: "string" },
+        config: { type: "string" },
+        lockfile: { type: "string" },
+        "report-url": { type: "string" },
+        "output-dir": { type: "string" },
+        "continue-on-error": { type: "boolean", default: false },
+        init: { type: "boolean", default: false },
+        quiet: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    });
+  } catch (err) {
+    deps.error(err instanceof Error ? err.message : String(err));
+    deps.error(help);
+    return EXIT_USAGE2;
+  }
+  if (parsed.values.help) {
+    deps.log(help);
+    return EXIT_SUCCESS2;
+  }
+  const providerName = parsed.positionals[0];
+  if (!providerName || !isProviderName(providerName)) {
+    deps.error(
+      providerName ? `Unknown provider "${providerName}". Available: ${PROVIDER_NAMES.join(", ")}.` : `${mode} needs a provider: executable-stories ${mode} <${PROVIDER_NAMES.join("|")}> <run.json>`
+    );
+    deps.error(help);
+    return EXIT_USAGE2;
+  }
+  if (parsed.values.init) {
+    deps.log(CONFIG_TEMPLATES[providerName]);
+    deps.log("");
+    deps.log(
+      `Save the block above as executable-stories.config.mjs (or merge the \`sync\` key into the one you have), then run:
+  executable-stories coverage ${providerName} reports/raw-run.json`
+    );
+    deps.log("");
+    deps.log(
+      `Not a JavaScript project? Put the same \`sync\` object in executable-stories.config.json instead:`
+    );
+    deps.log(JSON_CONFIG_TEMPLATES[providerName]);
+    return EXIT_SUCCESS2;
+  }
+  const inputPath = parsed.positionals[1];
+  if (!inputPath) {
+    deps.error(`${mode} needs a run file: executable-stories ${mode} ${providerName} <run.json>`);
+    deps.error(help);
+    return EXIT_USAGE2;
+  }
+  const attach = parsed.values.attach;
+  if (attach && !["failed", "all", "none"].includes(attach)) {
+    deps.error(`--attach must be one of: failed, all, none (got "${attach}")`);
+    return EXIT_USAGE2;
+  }
+  let run;
+  try {
+    run = loadRun(inputPath, deps);
+  } catch (err) {
+    deps.error(`Could not read ${inputPath}: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_USAGE2;
+  }
+  const logger = { warn: (message) => deps.error(`Warning: ${message}`) };
+  let targets;
+  try {
+    const config = await deps.loadConfigFn(parsed.values.config);
+    targets = config.sync ?? {};
+  } catch (err) {
+    deps.error(err instanceof Error ? err.message : String(err));
+    return EXIT_USAGE2;
+  }
+  let built;
+  try {
+    built = buildProvider(
+      { name: providerName, targets, env: deps.env },
+      { fetch: deps.fetchFn, logger }
+    );
+  } catch (err) {
+    deps.error(err instanceof Error ? err.message : String(err));
+    return EXIT_USAGE2;
+  }
+  const targetConfig = targets[providerName] ?? {};
+  const engineConfig = {
+    ...built.engineDefaults,
+    ...targetConfig,
+    ...parsed.values["report-url"] ? { reportUrl: parsed.values["report-url"] } : {},
+    ...attach ? { attach } : {}
+  };
+  const lockfilePath = parsed.values.lockfile ?? DEFAULT_LOCKFILE_PATH;
+  const outputDir = parsed.values["output-dir"] ?? "reports";
+  let lockfile;
+  try {
+    lockfile = deps.fileExists(lockfilePath) ? parseLockfile(deps.readFile(lockfilePath), lockfilePath) : emptyLockfile();
+  } catch (err) {
+    deps.error(err instanceof Error ? err.message : String(err));
+    return EXIT_USAGE2;
+  }
+  let analysis;
+  try {
+    analysis = await analyzeSync({
+      run,
+      provider: built.provider,
+      lockfile,
+      config: engineConfig
+    });
+  } catch (err) {
+    deps.error(`Could not read from ${providerName}: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_FAILED;
+  }
+  const jsonPath = path17.join(outputDir, `sync-coverage.${providerName}.json`);
+  const markdownPath = path17.join(outputDir, `sync-coverage.${providerName}.md`);
+  deps.writeFile(jsonPath, `${JSON.stringify(buildCoverageJson(analysis), null, 2)}
+`);
+  deps.writeFile(markdownPath, `${renderCoverageMarkdown(analysis)}
+`);
+  if (mode === "coverage") {
+    if (!parsed.values.quiet) {
+      deps.log(renderCoverageText(analysis));
+      deps.log("");
+    }
+    deps.log(`Wrote ${jsonPath} and ${markdownPath}`);
+    return EXIT_SUCCESS2;
+  }
+  const dryRun = !parsed.values.apply;
+  deps.log(renderPlan(analysis, { dryRun }));
+  if (dryRun) return EXIT_SUCCESS2;
+  const applied = await applySync(
+    { analysis, provider: built.provider, lockfile, config: engineConfig },
+    { logger }
+  );
+  deps.writeFile(lockfilePath, serializeLockfile(lockfile));
+  deps.log("");
+  deps.log(renderApplyResult(applied));
+  if (applied.errors.length > 0 && !parsed.values["continue-on-error"]) {
+    deps.error(
+      `
+${applied.errors.length} write(s) failed. A stale system of record is worse than a red build, so this exits non-zero. Pass --continue-on-error to treat it as advisory.`
+    );
+    return EXIT_FAILED;
+  }
+  return EXIT_SUCCESS2;
+}
+
 // src/import-openapi.ts
-import * as fs14 from "fs";
-import * as path16 from "path";
+import * as fs16 from "fs";
+import * as path18 from "path";
 import { parse as parseYamlString } from "yaml";
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
 function parseYaml2(raw, specPath) {
@@ -10035,9 +11927,9 @@ function parseYaml2(raw, specPath) {
   }
 }
 function parseSpec(specPath) {
-  if (!fs14.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
-  const raw = fs14.readFileSync(specPath, "utf8");
-  const ext = path16.extname(specPath).toLowerCase();
+  if (!fs16.existsSync(specPath)) throw new Error(`Spec not found: ${specPath}`);
+  const raw = fs16.readFileSync(specPath, "utf8");
+  const ext = path18.extname(specPath).toLowerCase();
   if (ext === ".json") return JSON.parse(raw);
   if (ext === ".yaml" || ext === ".yml") return parseYaml2(raw, specPath);
   try {
@@ -10068,8 +11960,8 @@ function extractEndpoints(spec) {
 }
 function loadScenarios(runFile) {
   if (!runFile) return [];
-  if (!fs14.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
-  const report = JSON.parse(fs14.readFileSync(runFile, "utf8"));
+  if (!fs16.existsSync(runFile)) throw new Error(`Run file not found: ${runFile}`);
+  const report = JSON.parse(fs16.readFileSync(runFile, "utf8"));
   return (report.features ?? []).flatMap((f) => f.scenarios ?? []);
 }
 function endpointRefs(endpoint) {
@@ -10176,25 +12068,25 @@ async function importOpenApi(options) {
     list.push(item);
     groups.set(item.endpoint.tag, list);
   }
-  const outputDir = options.outputDir ?? path16.join("src", "content", "docs", "api");
-  if (fs14.existsSync(outputDir) && !options.force) {
-    const entries = fs14.readdirSync(outputDir);
+  const outputDir = options.outputDir ?? path18.join("src", "content", "docs", "api");
+  if (fs16.existsSync(outputDir) && !options.force) {
+    const entries = fs16.readdirSync(outputDir);
     if (entries.length > 0) {
       throw new Error(`Output directory "${outputDir}" is not empty. Use --force to overwrite.`);
     }
   }
-  fs14.mkdirSync(outputDir, { recursive: true });
+  fs16.mkdirSync(outputDir, { recursive: true });
   const coveredCount = coverage.filter((c) => c.status === "covered").length;
   const uncoveredCount = coverage.filter((c) => c.status === "uncovered").length;
-  fs14.writeFileSync(
-    path16.join(outputDir, "index.mdx"),
+  fs16.writeFileSync(
+    path18.join(outputDir, "index.mdx"),
     renderIndex(groups, hasRun, { endpointCount: endpoints.length, coveredCount, uncoveredCount }),
     "utf8"
   );
   for (const [tag, rows] of groups) {
-    const dir = path16.join(outputDir, slug(tag));
-    fs14.mkdirSync(dir, { recursive: true });
-    fs14.writeFileSync(path16.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
+    const dir = path18.join(outputDir, slug(tag));
+    fs16.mkdirSync(dir, { recursive: true });
+    fs16.writeFileSync(path18.join(dir, "index.mdx"), renderTagPage(tag, rows, hasRun), "utf8");
   }
   return {
     outputDir,
@@ -10205,43 +12097,12 @@ async function importOpenApi(options) {
   };
 }
 
-// src/config.ts
-import { existsSync as existsSync11 } from "fs";
-import { resolve as resolve8 } from "path";
-var CONFIG_CANDIDATES = ["executable-stories.config.mjs", "executable-stories.config.js"];
-async function loadConfig(configPath) {
-  let resolved;
-  if (configPath) {
-    resolved = resolve8(configPath);
-  } else {
-    const present = CONFIG_CANDIDATES.map((name) => resolve8(process.cwd(), name)).filter(existsSync11);
-    if (present.length > 1) {
-      throw new Error(
-        `Multiple config files found in this directory:
-` + present.map((p) => `  - ${p}`).join("\n") + `
-Keep only one, or pass --config <path> to choose which to load.`
-      );
-    }
-    resolved = present[0];
-  }
-  if (!resolved || !existsSync11(resolved)) return {};
-  const mod = await import(resolved);
-  const config = mod.default;
-  if (!config || typeof config !== "object" || Array.isArray(config)) {
-    throw new Error(
-      `Config file at ${resolved} must export a default object. Got: ${typeof config}`
-    );
-  }
-  const { formatters } = config;
-  return formatters === void 0 ? {} : { formatters };
-}
-
 // src/cli.ts
-var EXIT_SUCCESS2 = 0;
+var EXIT_SUCCESS3 = 0;
 var EXIT_SCHEMA_VALIDATION = 1;
 var EXIT_CANONICAL_VALIDATION = 2;
 var EXIT_GENERATION = 3;
-var EXIT_USAGE2 = 4;
+var EXIT_USAGE3 = 4;
 var EXIT_COMPARE_GATE = 5;
 var EXIT_REVIEW_GATE = 5;
 var EXIT_AGENT_GATE = 5;
@@ -10270,6 +12131,8 @@ USAGE
   executable-stories new <template> "<name>" [options]
   executable-stories check-links <dir> [options]
   executable-stories push <run.json> [--key <es_...>] [--url <base>] [--repo <org/name>]
+  executable-stories coverage <testrail|xray> <run.json> [options]
+  executable-stories sync <testrail|xray> <run.json> [--apply] [options]
   executable-stories import-openapi <spec> [options]
   executable-stories publish-confluence <file.adf.json> [options]
   executable-stories publish-jira <file.adf.json> [options]
@@ -10294,7 +12157,9 @@ SUBCOMMANDS
   init-astro         Scaffold a thin Astro docs site (Starlight + executable-stories-astro; live stories at /stories)
   new                Scaffold a docs page from a template (adr, runbook, decision-log, incident, scenario-note)
   check-links        Scan docs for broken internal/external links (CI-friendly exit code)
-  push               Send a run (StoryReport or raw run JSON) to Executable Stories Cloud
+  push               Send a run (StoryReport or raw run JSON) to a cloud ingest endpoint
+  coverage           Compare your stories against a test-management system (read-only)
+  sync               Push cases, executions, and evidence to TestRail or Xray (dry run by default)
   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)
@@ -10487,18 +12352,19 @@ EXIT CODES
 function parseTextJsonFormat(flag, value) {
   if (value !== "text" && value !== "json") {
     console.error(`Error: ${flag} must be "text" or "json", got "${value}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   return value;
 }
 async function parseCliArgs(argv) {
   const args = argv.slice(2);
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  const SELF_DOCUMENTING = /* @__PURE__ */ new Set(["sync", "coverage"]);
+  if (args.length === 0 || (args.includes("--help") || args.includes("-h")) && !SELF_DOCUMENTING.has(args[0] ?? "")) {
     console.log(HELP_TEXT);
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   const subcommand = args[0];
-  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "check" && subcommand !== "check-explainers" && subcommand !== "goal" && subcommand !== "triage" && subcommand !== "validate" && subcommand !== "doctor" && subcommand !== "completion" && subcommand !== "dev" && subcommand !== "init-astro" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "push" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
+  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "check" && subcommand !== "check-explainers" && subcommand !== "goal" && subcommand !== "triage" && subcommand !== "validate" && subcommand !== "doctor" && subcommand !== "completion" && subcommand !== "dev" && subcommand !== "init-astro" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "push" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira" && subcommand !== "sync" && subcommand !== "coverage") {
     if (subcommand === "serve" || subcommand === "build-docs") {
       console.error(
         `The "${subcommand}" subcommand was removed. Living docs are now an Astro site, rendered live from the run JSON (no Markdown generation step):
@@ -10507,12 +12373,12 @@ async function parseCliArgs(argv) {
   3. run \`executable-stories dev\` in another \u2014 it hot-reloads the docs.
 See: https://github.com/jagreehal/executable-stories (executable-stories-astro).`
       );
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     console.error(
-      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "gate-release", "deploy", "review", "list", "check", "check-explainers", "goal", "triage", "validate", "doctor", "completion", "dev", "init-astro", "new", "check-links", "push", "import-openapi", "publish-confluence", or "publish-jira".`
+      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "gate-release", "deploy", "review", "list", "check", "check-explainers", "goal", "triage", "validate", "doctor", "completion", "dev", "init-astro", "new", "check-links", "push", "sync", "coverage", "import-openapi", "publish-confluence", or "publish-jira".`
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   if (subcommand === "completion") {
     process.exit(runCompletion(args.slice(1)));
@@ -10526,15 +12392,15 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
     } else {
       console.log(formatDoctorReport(report));
     }
-    process.exit(report.healthy ? EXIT_SUCCESS2 : EXIT_USAGE2);
+    process.exit(report.healthy ? EXIT_SUCCESS3 : EXIT_USAGE3);
   }
   if (subcommand === "publish-confluence") {
     await runPublishConfluence(args.slice(1));
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   if (subcommand === "publish-jira") {
     await runPublishJira(args.slice(1));
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   if (subcommand === "deploy") {
     process.exit(await runDeploy(args.slice(1)));
@@ -10548,7 +12414,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
         `No docs site found at ${siteDir}. Create one (scaffold + install) with:
   npx executable-stories init-astro --install`
       );
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     if (dev.kind === "install-failed") {
       console.error(`"${dev.pm} install" failed in ${siteDir} \u2014 run it manually, then retry.`);
@@ -10567,7 +12433,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
       if (update) {
         console.log(`Updated ${result.targetDir} (content + config left untouched)`);
         console.log("  Framework updates come via: pnpm update executable-stories-astro");
-        process.exit(EXIT_SUCCESS2);
+        process.exit(EXIT_SUCCESS3);
       }
       console.log(`Scaffolded Astro docs site at ${result.targetDir}`);
       const pm = detectPackageManager();
@@ -10594,17 +12460,19 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
       console.log("");
       console.log("Everything is configured in one file: executable-stories.config.mjs");
       console.log("  \u2014 sources, scenario selection (include/exclude), grouping (groupBy), docs, and theme.");
-      process.exit(EXIT_SUCCESS2);
+      process.exit(EXIT_SUCCESS3);
     } catch (err) {
       console.error(`Error: ${err.message}`);
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
   }
   if (subcommand === "new") process.exit(runNew(args.slice(1)));
   if (subcommand === "check-links") process.exit(await runCheckLinks(args.slice(1)));
   if (subcommand === "push") process.exit(await runPush(args.slice(1)));
+  if (subcommand === "sync") process.exit(await runSyncCommand("sync", args.slice(1)));
+  if (subcommand === "coverage") process.exit(await runSyncCommand("coverage", args.slice(1)));
   if (subcommand === "import-openapi") process.exit(await runImportOpenApi(args.slice(1)));
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: args.slice(1),
     options: {
       format: { type: "string", default: "html" },
@@ -10682,7 +12550,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   });
   if (values.help) {
     console.log(HELP_TEXT);
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   const userSetFormat = args.slice(1).some((a) => a === "--format" || a.startsWith("--format="));
   const preset = expandPreset(
@@ -10692,7 +12560,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   );
   if (preset.error) {
     console.error(`Error: ${preset.error}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const useStdin = values.stdin;
   const baselineValue = values.baseline;
@@ -10704,15 +12572,15 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   if (isCompareLike) {
     if (useStdin) {
       console.error(`Error: ${subcommand} does not support --stdin. Pass baseline and current files.`);
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     if (!currentFile) {
       console.error(`Error: ${subcommand} requires <current-file>, and either <baseline-file> or --baseline auto.`);
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     if (baselineMode === "explicit" && !baselineFile) {
       console.error(`Error: ${subcommand} requires <baseline-file> and <current-file>, or use --baseline auto.`);
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
   }
   let resolvedInputFile = inputFile;
@@ -10727,13 +12595,13 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   Pass a path, use --stdin, or run your tests first (non-JS adapters write
   ${DEFAULT_RUN_FILES[0]}; set rawRunPath in a JS reporter to write ${DEFAULT_RUN_FILES[1]}).`
       );
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
   }
   const inputType = values["input-type"];
   if (inputType !== "raw" && inputType !== "canonical" && inputType !== "ndjson") {
     console.error(`Error: --input-type must be "raw", "canonical", or "ndjson", got "${inputType}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const pluginConfig = await loadConfig(values["config"]);
   const customFormatterNames = new Set(Object.keys(pluginConfig.formatters ?? {}));
@@ -10752,7 +12620,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   if (unknownFormats.length > 0) {
     const knownCustom = customFormatterNames.size > 0 ? `, ${[...customFormatterNames].join(", ")}` : "";
     console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: agent-text, astro-markdown, behavior-manifest-json, confluence, html, markdown, release-manifest, traceability-matrix, traceability-csv, junit, cucumber-json, cucumber-messages, cucumber-html, scenario-index-json, story-report-json${knownCustom}.`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const formats = builtInRequested;
   const noSynthesize = values["no-synthesize-stories"];
@@ -10761,19 +12629,19 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   const validNotifyConditions = /* @__PURE__ */ new Set(["always", "on-failure", "never"]);
   if (!validNotifyConditions.has(notifyValue)) {
     console.error(`Error: --notify must be "always", "on-failure", or "never", got "${notifyValue}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const maxFailedTestsStr = values["max-failed-tests"];
   const maxFailedTests = maxFailedTestsStr ? parseInt(maxFailedTestsStr, 10) : 5;
   if (maxFailedTestsStr && (isNaN(maxFailedTests) || maxFailedTests < 0)) {
     console.error(`Error: --max-failed-tests must be a non-negative integer, got "${maxFailedTestsStr}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const htmlStaleAfterDaysStr = values["html-stale-after-days"];
   const htmlStaleAfterDays = htmlStaleAfterDaysStr ? parseInt(htmlStaleAfterDaysStr, 10) : 7;
   if (htmlStaleAfterDaysStr && (isNaN(htmlStaleAfterDays) || htmlStaleAfterDays < 0)) {
     console.error(`Error: --html-stale-after-days must be a non-negative integer, got "${htmlStaleAfterDaysStr}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const slackWebhook = values["slack-webhook"];
   const teamsWebhook = values["teams-webhook"];
@@ -10800,7 +12668,7 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
     const upper = webhookMethodRaw.toUpperCase();
     if (upper !== "POST" && upper !== "PUT") {
       console.error(`Error: --webhook-method must be "POST" or "PUT", got "${webhookMethodRaw}".`);
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     webhookMethod = upper;
   }
@@ -10808,36 +12676,36 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
   const maxHistoryRuns = maxHistoryRunsStr ? parseInt(maxHistoryRunsStr, 10) : 10;
   if (maxHistoryRunsStr && (isNaN(maxHistoryRuns) || maxHistoryRuns < 1)) {
     console.error(`Error: --max-history-runs must be a positive integer, got "${maxHistoryRunsStr}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const maxRegressionsStr = values["max-regressions"];
   const maxRegressions = maxRegressionsStr !== void 0 ? parseInt(maxRegressionsStr, 10) : void 0;
   if (maxRegressionsStr !== void 0 && (isNaN(maxRegressions) || maxRegressions < 0)) {
     console.error(`Error: --max-regressions must be a non-negative integer, got "${maxRegressionsStr}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const sortTestCasesRaw = values["sort-test-cases"];
   const validSortModes = /* @__PURE__ */ new Set(["id", "source", "none"]);
   if (!validSortModes.has(sortTestCasesRaw)) {
     console.error(`Error: --sort-test-cases must be id, source, or none, got "${sortTestCasesRaw}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const assetModeRaw = values["asset-mode"];
   const validAssetModes = /* @__PURE__ */ new Set(["none", "copy"]);
   if (!validAssetModes.has(assetModeRaw)) {
     console.error(`Error: --asset-mode must be "none" or "copy", got "${assetModeRaw}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const failOnRaw = values["fail-on"];
   if (failOnRaw !== void 0 && failOnRaw !== "uncovered" && failOnRaw !== "weak") {
     console.error(`Error: --fail-on must be "uncovered" or "weak", got "${failOnRaw}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const minEvidenceRaw = values["min-evidence"];
   const validMinEvidence = /* @__PURE__ */ new Set(["weak", "moderate", "strong"]);
   if (minEvidenceRaw !== void 0 && !validMinEvidence.has(minEvidenceRaw)) {
     console.error(`Error: --min-evidence must be "weak", "moderate", or "strong", got "${minEvidenceRaw}".`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const checkFormat = parseTextJsonFormat("--check-format", values["check-format"]);
   const goalFormat = parseTextJsonFormat("--goal-format", values["goal-format"]);
@@ -10921,27 +12789,27 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path17.resolve(args.inputFile);
-  if (!fs15.existsSync(filePath)) {
+  const filePath = path19.resolve(args.inputFile);
+  if (!fs17.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  return fs15.readFileSync(filePath, "utf8");
+  return fs17.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path17.resolve(filePath);
-  if (!fs15.existsSync(resolved)) {
+  const resolved = path19.resolve(filePath);
+  if (!fs17.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  return fs15.readFileSync(resolved, "utf8");
+  return fs17.readFileSync(resolved, "utf8");
 }
 function readStdin() {
-  return new Promise((resolve10, reject) => {
+  return new Promise((resolve12, reject) => {
     const chunks = [];
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve10(chunks.join("")));
+    process.stdin.on("end", () => resolve12(chunks.join("")));
     process.stdin.on("error", reject);
   });
 }
@@ -10951,7 +12819,7 @@ function parseJson(text2) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Error: Invalid JSON \u2014 ${msg}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
 }
 function tryParseJson(text2) {
@@ -10989,13 +12857,13 @@ ${msg}`);
   let raw = data;
   let droppedMissingStory = 0;
   if (args.synthesizeStories) {
-    raw = synthesizeStories3(raw);
+    raw = synthesizeStories4(raw);
   } else {
     const before = raw.testCases.length;
     const withStory = raw.testCases.filter((tc) => tc.story != null).length;
     droppedMissingStory = before - withStory;
   }
-  const canonical = canonicalizeRun5(raw);
+  const canonical = canonicalizeRun6(raw);
   try {
     assertValidRun2(canonical);
   } catch (err) {
@@ -11076,9 +12944,9 @@ function tryNormalizeRunFromText(text2, args) {
   if (!schemaResult.valid) return void 0;
   let raw = data;
   if (args.synthesizeStories) {
-    raw = synthesizeStories3(raw);
+    raw = synthesizeStories4(raw);
   }
-  const canonical = canonicalizeRun5(raw);
+  const canonical = canonicalizeRun6(raw);
   try {
     assertValidRun2(canonical);
     return canonical;
@@ -11087,14 +12955,14 @@ function tryNormalizeRunFromText(text2, args) {
   }
 }
 function listBaselineCandidates(currentFile, args) {
-  const baselineDir = path17.resolve(args.baselineDir ?? path17.dirname(currentFile));
-  const currentResolved = path17.resolve(currentFile);
-  if (!fs15.existsSync(baselineDir)) {
+  const baselineDir = path19.resolve(args.baselineDir ?? path19.dirname(currentFile));
+  const currentResolved = path19.resolve(currentFile);
+  if (!fs17.existsSync(baselineDir)) {
     console.error(`Error: baseline directory not found: ${baselineDir}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  const entries = fs15.readdirSync(baselineDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile()).map((entry) => path17.join(baselineDir, entry.name)).filter((candidate) => path17.resolve(candidate) !== currentResolved).filter(
+  const entries = fs17.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path19.join(baselineDir, entry.name)).filter((candidate) => path19.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -11102,21 +12970,21 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   const candidates = listBaselineCandidates(currentFile, args);
   const comparable = [];
   for (const candidate of candidates) {
-    const run = tryNormalizeRunFromText(fs15.readFileSync(candidate, "utf8"), args);
+    const run = tryNormalizeRunFromText(fs17.readFileSync(candidate, "utf8"), args);
     if (run) {
       comparable.push({ file: candidate, run });
     }
   }
   if (comparable.length === 0) {
     console.error(
-      `Error: no compatible baseline files found in ${path17.resolve(args.baselineDir ?? path17.dirname(currentFile))}.`
+      `Error: no compatible baseline files found in ${path19.resolve(args.baselineDir ?? path19.dirname(currentFile))}.`
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const picked = pickAutoBaseline(currentRun, comparable);
   if (!picked) {
     console.error("Error: unable to choose an automatic baseline.");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   return picked.file;
 }
@@ -11126,7 +12994,7 @@ function resolveBaselineRun(args, currentRun) {
   if (args.baselineArg === "auto") {
     if (!args.inputFile) {
       console.error("Error: --baseline auto requires a current input file (not --stdin).");
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     baselineFile = resolveBaselineAuto(args.inputFile, currentRun, args);
   } else {
@@ -11172,7 +13040,7 @@ async function runCompare(ctx) {
       }
       process.exit(EXIT_COMPARE_GATE);
     }
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Comparison failed: ${msg}`);
@@ -11217,7 +13085,7 @@ async function runGateRelease(ctx) {
       process.exit(EXIT_RELEASE_GATE);
     }
     console.error("Release gate passed: RC matches dev baseline.");
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Release gate check failed: ${msg}`);
@@ -11249,7 +13117,7 @@ async function runReview(ctx) {
       }
       process.exit(EXIT_REVIEW_GATE);
     }
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Review failed: ${msg}`);
@@ -11265,7 +13133,7 @@ async function runList(ctx) {
   const validListFormats = /* @__PURE__ */ new Set(["text", "json", "csv", "markdown-table"]);
   if (!validListFormats.has(resolvedFormat)) {
     console.error(`Error: Unknown list format "${resolvedFormat}". Valid: text, json, csv, markdown-table.`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const output = listScenarios(
     {
@@ -11276,7 +13144,7 @@ async function runList(ctx) {
     {}
   );
   console.log(output);
-  process.exit(EXIT_SUCCESS2);
+  process.exit(EXIT_SUCCESS3);
 }
 async function runCheck(ctx) {
   const { args } = ctx;
@@ -11291,17 +13159,17 @@ async function runCheck(ctx) {
   if (report.summary.failed > 0 && !args.noFail) {
     process.exit(EXIT_AGENT_GATE);
   }
-  process.exit(EXIT_SUCCESS2);
+  process.exit(EXIT_SUCCESS3);
 }
 async function runCheckExplainers(ctx) {
   const { args } = ctx;
   if (!args.explainersDir) {
     console.error("Error: check-explainers requires --explainers-dir <dir> (the folder of explainer markdown).");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  if (!fs15.existsSync(args.explainersDir) || !fs15.statSync(args.explainersDir).isDirectory()) {
+  if (!fs17.existsSync(args.explainersDir) || !fs17.statSync(args.explainersDir).isDirectory()) {
     console.error(`Error: --explainers-dir "${args.explainersDir}" is not a directory.`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const text2 = await readInput(args);
   const run = applySelection(normalizeRunFromText(text2, args).run, args);
@@ -11310,7 +13178,7 @@ async function runCheckExplainers(ctx) {
   if (explainersGateFailed(report) && !args.noFail) {
     process.exit(EXIT_AGENT_GATE);
   }
-  process.exit(EXIT_SUCCESS2);
+  process.exit(EXIT_SUCCESS3);
 }
 async function runGoal(ctx) {
   const { args } = ctx;
@@ -11331,7 +13199,7 @@ async function runGoal(ctx) {
     {}
   );
   console.log(renderGoal(report, args.goalFormat));
-  process.exit(report.met ? EXIT_SUCCESS2 : EXIT_AGENT_GATE);
+  process.exit(report.met ? EXIT_SUCCESS3 : EXIT_AGENT_GATE);
 }
 async function runTriage(ctx) {
   const { args } = ctx;
@@ -11343,13 +13211,13 @@ async function runTriage(ctx) {
     {}
   );
   console.log(renderTriage(report, args.triageFormat));
-  process.exit(EXIT_SUCCESS2);
+  process.exit(EXIT_SUCCESS3);
 }
 async function runWatch(ctx) {
   const { args } = ctx;
   if (!args.inputFile) {
     console.error("Error: watch requires an input file (the raw-run JSON the framework writes).");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   console.log(
     `Watching ${args.inputFile} \u2192 regenerating [${args.formats.join(", ")}] into ${args.outputDir}/ (Ctrl+C to stop)`
@@ -11398,7 +13266,7 @@ async function runFormatOrValidate(ctx) {
         }
       }
       console.log(`Valid NDJSON (${lines.length} envelopes).`);
-      process.exit(EXIT_SUCCESS2);
+      process.exit(EXIT_SUCCESS3);
     }
     let run;
     try {
@@ -11409,9 +13277,9 @@ async function runFormatOrValidate(ctx) {
       process.exit(EXIT_SCHEMA_VALIDATION);
     }
     if (args.emitCanonical) {
-      const outPath = path17.resolve(args.emitCanonical);
-      fs15.mkdirSync(path17.dirname(outPath), { recursive: true });
-      fs15.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path19.resolve(args.emitCanonical);
+      fs17.mkdirSync(path19.dirname(outPath), { recursive: true });
+      fs17.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const history = runHistoryPipeline(run, args);
@@ -11419,7 +13287,7 @@ async function runFormatOrValidate(ctx) {
       runCustomFormatters(run, customRequested, pluginConfig.formatters ?? {}, args);
       await dispatchNotifications(run, args);
       printResult(result, args, startMs);
-      process.exit(EXIT_SUCCESS2);
+      process.exit(EXIT_SUCCESS3);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`Generation failed: ${msg}`);
@@ -11433,7 +13301,7 @@ async function runFormatOrValidate(ctx) {
         assertValidRun2(data);
         warnLargeStateDocs(data.testCases);
         console.log("Valid canonical TestRunResult.");
-        process.exit(EXIT_SUCCESS2);
+        process.exit(EXIT_SUCCESS3);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(msg);
@@ -11457,7 +13325,7 @@ async function runFormatOrValidate(ctx) {
     }
     warnLargeStateDocs(data.testCases);
     console.log("Valid RawRun (schemaVersion 1).");
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   if (args.inputType === "canonical") {
     try {
@@ -11470,9 +13338,9 @@ ${msg}`);
     }
     const run = data;
     if (args.emitCanonical) {
-      const outPath = path17.resolve(args.emitCanonical);
-      fs15.mkdirSync(path17.dirname(outPath), { recursive: true });
-      fs15.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path19.resolve(args.emitCanonical);
+      fs17.mkdirSync(path19.dirname(outPath), { recursive: true });
+      fs17.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const history = runHistoryPipeline(run, args);
@@ -11480,7 +13348,7 @@ ${msg}`);
       runCustomFormatters(run, customRequested, pluginConfig.formatters ?? {}, args);
       await dispatchNotifications(run, args);
       printResult(result, args, startMs);
-      process.exit(EXIT_SUCCESS2);
+      process.exit(EXIT_SUCCESS3);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`Generation failed: ${msg}`);
@@ -11505,7 +13373,7 @@ ${msg}`);
   let raw = data;
   let droppedMissingStory = 0;
   if (args.synthesizeStories) {
-    raw = synthesizeStories3(raw);
+    raw = synthesizeStories4(raw);
   } else {
     const before = raw.testCases.length;
     const withStory = raw.testCases.filter(
@@ -11518,7 +13386,7 @@ ${msg}`);
       );
     }
   }
-  const canonical = canonicalizeRun5(raw);
+  const canonical = canonicalizeRun6(raw);
   try {
     assertValidRun2(canonical);
   } catch (err) {
@@ -11528,9 +13396,9 @@ ${msg}`);
     process.exit(EXIT_CANONICAL_VALIDATION);
   }
   if (args.emitCanonical) {
-    const outPath = path17.resolve(args.emitCanonical);
-    fs15.mkdirSync(path17.dirname(outPath), { recursive: true });
-    fs15.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
+    const outPath = path19.resolve(args.emitCanonical);
+    fs17.mkdirSync(path19.dirname(outPath), { recursive: true });
+    fs17.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const history = runHistoryPipeline(canonical, args);
@@ -11538,7 +13406,7 @@ ${msg}`);
     runCustomFormatters(canonical, customRequested, pluginConfig.formatters ?? {}, args);
     await dispatchNotifications(canonical, args);
     printResult(result, args, startMs, droppedMissingStory);
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Generation failed: ${msg}`);
@@ -11555,9 +13423,9 @@ function runCustomFormatters(run, customRequested, formatters, args) {
       const ext = formatter.fileExtension ?? formatName;
       const baseName = args.outputName ?? "report";
       const filename = args.outputNameTimestamp ? `${baseName}-${Math.floor(run.startedAtMs / 1e3)}.${ext}` : `${baseName}.${ext}`;
-      const filepath = path17.join(outputDir, filename);
-      fs15.mkdirSync(outputDir, { recursive: true });
-      fs15.writeFileSync(filepath, content, "utf8");
+      const filepath = path19.join(outputDir, filename);
+      fs17.mkdirSync(outputDir, { recursive: true });
+      fs17.writeFileSync(filepath, content, "utf8");
       console.log(`Generated: ${filepath}`);
     } catch (err) {
       console.error(`Error running custom formatter "${formatName}": ${err instanceof Error ? err.message : String(err)}`);
@@ -11607,13 +13475,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return void 0;
-  const historyPath = path17.resolve(args.historyFile);
+  const historyPath = path19.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs15.readFileSync(p, "utf8");
+          return fs17.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -11626,11 +13494,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path17.dirname(historyPath);
-  fs15.mkdirSync(dir, { recursive: true });
+  const dir = path19.dirname(historyPath);
+  fs17.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs15.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs17.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -11781,7 +13649,7 @@ function loadReviewContext(args) {
       console.error(
         "Error: --code-diff requires --patch <file> (generate it with: git diff --histogram > changes.patch)."
       );
-      process.exit(EXIT_USAGE2);
+      process.exit(EXIT_USAGE3);
     }
     const sidecar = JSON.parse(readFileInput(args.codeDiffPath));
     const patch = readFileInput(args.patchPath);
@@ -11801,11 +13669,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)}` : "";
-  fs15.mkdirSync(outputDir, { recursive: true });
-  const mdPath = path17.join(outputDir, `${baseName}${suffix}.md`);
-  const htmlPath = path17.join(outputDir, `${baseName}${suffix}.html`);
-  fs15.writeFileSync(mdPath, markdown, "utf8");
-  fs15.writeFileSync(htmlPath, html, "utf8");
+  fs17.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path19.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path19.join(outputDir, `${baseName}${suffix}.html`);
+  fs17.writeFileSync(mdPath, markdown, "utf8");
+  fs17.writeFileSync(htmlPath, html, "utf8");
   return [mdPath, htmlPath];
 }
 function evaluateReviewGate(review, args) {
@@ -11860,9 +13728,9 @@ function printResult(result, args, startMs, droppedMissingStory = 0) {
 function printCompareResult(result, args, startMs) {
   const durationMs = Date.now() - startMs;
   if (result.prSummary && args.prSummaryFile) {
-    const outputPath = path17.resolve(args.prSummaryFile);
-    fs15.mkdirSync(path17.dirname(outputPath), { recursive: true });
-    fs15.writeFileSync(outputPath, result.prSummary, "utf8");
+    const outputPath = path19.resolve(args.prSummaryFile);
+    fs17.mkdirSync(path19.dirname(outputPath), { recursive: true });
+    fs17.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -11896,13 +13764,13 @@ function printCompareResult(result, args, startMs) {
   }
 }
 function loadReleasePolicy(policyPath) {
-  const resolved = path17.resolve(policyPath);
-  if (!fs15.existsSync(resolved)) {
+  const resolved = path19.resolve(policyPath);
+  if (!fs17.existsSync(resolved)) {
     console.error(`Error: release policy file not found: ${resolved}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   try {
-    const raw = JSON.parse(fs15.readFileSync(resolved, "utf8"));
+    const raw = JSON.parse(fs17.readFileSync(resolved, "utf8"));
     return {
       allowedOmissions: Array.isArray(raw.allowedOmissions) ? raw.allowedOmissions : [],
       allowedRegressions: Array.isArray(raw.allowedRegressions) ? raw.allowedRegressions : [],
@@ -11911,7 +13779,7 @@ function loadReleasePolicy(policyPath) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Error reading release policy: ${msg}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
 }
 function applyReleasePolicy(result, policy) {
@@ -11963,7 +13831,7 @@ function evaluateCompareGate(result, args) {
   return failures;
 }
 async function runPublishConfluence(rawArgs) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs,
     options: {
       "page-id": { type: "string" },
@@ -11999,16 +13867,16 @@ Optional:
   --help                   Show this help
 
 Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens`);
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   const inputFile = positionals[0];
   if (!inputFile) {
     console.error("Error: missing ADF file argument. Run with --help for usage.");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  if (!fs15.existsSync(inputFile)) {
+  if (!fs17.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const baseUrl = values["base-url"] ?? process.env.CONFLUENCE_BASE_URL;
   const email = values.email ?? process.env.CONFLUENCE_EMAIL;
@@ -12022,19 +13890,19 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error(
       "Error: --base-url or CONFLUENCE_BASE_URL is required (e.g. https://acme.atlassian.net/wiki)"
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   if (!pageId && !spaceId) {
     console.error(
       "Error: specify either --page-id (to update) or --space-id (to create)"
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   if (!pageId && !title) {
     console.error("Error: --title is required when creating a new page");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  const adf = fs15.readFileSync(path17.resolve(inputFile), "utf8");
+  const adf = fs17.readFileSync(path19.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -12051,13 +13919,13 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
         2
       )
     );
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   if (!email || !token) {
     console.error(
       "Error: --email/CONFLUENCE_EMAIL and --token/CONFLUENCE_TOKEN are required unless --dry-run is set"
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   try {
     const result = await publishConfluencePage(
@@ -12067,14 +13935,14 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.log(
       `${result.action === "created" ? "Created" : "Updated"} "${result.title}" (v${result.version}) \u2192 ${result.url}`
     );
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(EXIT_GENERATION);
   }
 }
 async function runPublishJira(rawArgs) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs,
     options: {
       issue: { type: "string" },
@@ -12106,16 +13974,16 @@ Optional:
   --help                   Show this help
 
 Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens`);
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   const inputFile = positionals[0];
   if (!inputFile) {
     console.error("Error: missing ADF file argument. Run with --help for usage.");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
-  if (!fs15.existsSync(inputFile)) {
+  if (!fs17.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const baseUrl = values["base-url"] ?? process.env.JIRA_BASE_URL;
   const email = values.email ?? process.env.JIRA_EMAIL;
@@ -12127,20 +13995,20 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error(
       "Error: --base-url or JIRA_BASE_URL is required (e.g. https://acme.atlassian.net)"
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   if (!issueKey) {
     console.error("Error: --issue <KEY> is required (e.g. --issue PROJ-123)");
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   if (modeRaw !== "comment" && modeRaw !== "description") {
     console.error(
       `Error: --mode must be "comment" or "description" (got "${modeRaw}")`
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   const mode = modeRaw;
-  const adf = fs15.readFileSync(path17.resolve(inputFile), "utf8");
+  const adf = fs17.readFileSync(path19.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -12155,13 +14023,13 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
         2
       )
     );
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   }
   if (!email || !token) {
     console.error(
       "Error: --email/JIRA_EMAIL and --token/JIRA_TOKEN are required unless --dry-run is set"
     );
-    process.exit(EXIT_USAGE2);
+    process.exit(EXIT_USAGE3);
   }
   try {
     const result = await publishJiraIssue(
@@ -12175,14 +14043,14 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     } else {
       console.log(`Updated description for ${result.issueKey} \u2192 ${result.url}`);
     }
-    process.exit(EXIT_SUCCESS2);
+    process.exit(EXIT_SUCCESS3);
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(EXIT_GENERATION);
   }
 }
 function runNew(rawArgs) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs,
     options: {
       dir: { type: "string" },
@@ -12199,7 +14067,7 @@ function runNew(rawArgs) {
       `Usage: executable-stories new <template> "<name>" [--dir <docs-dir>] [--scenario-id <id>] [--force]`
     );
     console.error(`Templates: ${TEMPLATES.join(", ")}`);
-    return EXIT_USAGE2;
+    return EXIT_USAGE3;
   }
   try {
     const result = scaffoldDoc({
@@ -12213,36 +14081,41 @@ function runNew(rawArgs) {
     console.log(`  Title: ${result.title}`);
     console.log("");
     console.log("Next: fill in the content and link verifying stories in `verifiedBy`.");
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   } catch (err) {
     console.error(`Error: ${err.message}`);
-    return EXIT_USAGE2;
+    return EXIT_USAGE3;
   }
 }
 async function runCheckLinks(rawArgs) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs,
     options: {
       external: { type: "boolean", default: false },
-      json: { type: "boolean", default: false }
+      json: { type: "boolean", default: false },
+      "site-root": { type: "string" },
+      assets: { type: "string", multiple: true }
     },
     allowPositionals: true,
     strict: true
   });
   try {
+    const assets = values.assets;
     const report = await checkLinks({
       target: positionals[0] ?? ".",
-      checkExternal: values.external
+      checkExternal: values.external,
+      ...values["site-root"] ? { siteRoot: values["site-root"] } : {},
+      ...assets && assets.length > 0 ? { assetRoots: assets } : {}
     });
     console.log(values.json ? JSON.stringify(report, null, 2) : formatLinkReport(report));
-    return report.brokenCount > 0 ? EXIT_GENERATION : EXIT_SUCCESS2;
+    return report.brokenCount > 0 ? EXIT_GENERATION : EXIT_SUCCESS3;
   } catch (err) {
     console.error(`Error: ${err.message}`);
-    return EXIT_USAGE2;
+    return EXIT_USAGE3;
   }
 }
 async function runImportOpenApi(rawArgs) {
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs,
     options: {
       "output-dir": { type: "string" },
@@ -12255,7 +14128,7 @@ async function runImportOpenApi(rawArgs) {
   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_USAGE2;
+    return EXIT_USAGE3;
   }
   try {
     const result = await importOpenApi({
@@ -12269,10 +14142,10 @@ async function runImportOpenApi(rawArgs) {
     if (result.uncoveredCount > 0) {
       console.log(`  \u26A0 ${result.uncoveredCount} endpoint(s) have no verifying story`);
     }
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   } catch (err) {
     console.error(`Error: ${err.message}`);
-    return EXIT_USAGE2;
+    return EXIT_USAGE3;
   }
 }
 async function runDeploy(rawArgs) {
@@ -12282,9 +14155,9 @@ async function runDeploy(rawArgs) {
     console.error("  deploy record <file> --env <env> [--tag <tag>] [--ledger <path>]");
     console.error("  deploy status [--ledger <path>] [--json]");
     console.error("  deploy diff <env-a> <env-b> [--ledger <path>] [--json]");
-    return EXIT_USAGE2;
+    return EXIT_USAGE3;
   }
-  const { values, positionals } = parseArgs2({
+  const { values, positionals } = parseArgs3({
     args: rawArgs.slice(1),
     options: {
       env: { type: "string" },
@@ -12309,19 +14182,19 @@ OPTIONS
   --tag <tag>       Optional Git tag for this deployment (e.g. v1.2.3)
   --ledger <path>   Path to deployment ledger JSON (default: .executable-stories/deployments.json)
   --json            Output as JSON instead of text`);
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   }
   const ledgerPath = values.ledger;
   if (mode === "record") {
     const inputFile = positionals[0];
     if (!inputFile) {
       console.error("Error: deploy record requires an input file.");
-      return EXIT_USAGE2;
+      return EXIT_USAGE3;
     }
     const env = values.env;
     if (!env) {
       console.error("Error: deploy record requires --env <environment>.");
-      return EXIT_USAGE2;
+      return EXIT_USAGE3;
     }
     const text2 = readFileInput(inputFile);
     const { run } = normalizeRunFromText(text2, {
@@ -12347,14 +14220,14 @@ OPTIONS
       console.error(`  Tag: ${result.entry.tag}`);
     }
     console.error(`  Ledger: ${result.ledgerPath}`);
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   }
   if (mode === "status") {
     const status = getDeploymentStatus(ledgerPath);
     const envs = Object.keys(status.environments);
     if (envs.length === 0) {
       console.error("No deployments recorded yet.");
-      return EXIT_SUCCESS2;
+      return EXIT_SUCCESS3;
     }
     if (values.json) {
       console.log(JSON.stringify(status, null, 2));
@@ -12380,14 +14253,14 @@ OPTIONS
       }
       console.log(`Ledger: ${ledgerPath}`);
     }
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   }
   if (mode === "diff") {
     const envA = positionals[0];
     const envB = positionals[1];
     if (!envA || !envB) {
       console.error("Error: deploy diff requires two environment names.");
-      return EXIT_USAGE2;
+      return EXIT_USAGE3;
     }
     try {
       const drift = getEnvironmentDrift(ledgerPath, envA, envB);
@@ -12433,11 +14306,11 @@ OPTIONS
       }
     } catch (err) {
       console.error(`Error: ${err.message}`);
-      return EXIT_USAGE2;
+      return EXIT_USAGE3;
     }
-    return EXIT_SUCCESS2;
+    return EXIT_SUCCESS3;
   }
-  return EXIT_USAGE2;
+  return EXIT_USAGE3;
 }
 function createDefaultCliArgs() {
   return {
@@ -12493,6 +14366,6 @@ function createDefaultCliArgs() {
 }
 main().catch((err) => {
   console.error(err);
-  process.exit(EXIT_USAGE2);
+  process.exit(EXIT_USAGE3);
 });
 //# sourceMappingURL=cli.js.map