@runcofactor/cli 0.10.0

package/dist/workflow-XYFH5LTP.js

@@ -0,0 +1,3708 @@
+import { createRequire as __cr } from "module"; const require = __cr(import.meta.url);
+import {
+  printGuide
+} from "./chunk-4NRDONSC.js";
+import {
+  workflowToSpec
+} from "./chunk-B2VISN2V.js";
+import {
+  applyWorkflowTagFlags
+} from "./chunk-XQXVG7RA.js";
+import {
+  alignSnapshotNodeIds
+} from "./chunk-JDBCZ3Z2.js";
+import {
+  apiRequest,
+  renderWorkflowUserError
+} from "./chunk-WOHL4FTB.js";
+import {
+  NODE_TYPE_LABEL,
+  USER_SETTABLE_WORKFLOW_STATUSES,
+  normalizeNodeType
+} from "./chunk-SJJW77WN.js";
+import {
+  apiFetch,
+  exitOnFailure,
+  fetchOrExit
+} from "./chunk-3CZU7XCS.js";
+import {
+  getArgValue,
+  hasFlag,
+  resolveAppUrl,
+  resolveConfig
+} from "./chunk-A4OFTUVV.js";
+import "./chunk-JWHYXEA2.js";
+import "./chunk-VKVL7WBN.js";
+
+// src/workflow.ts
+import fs5 from "fs/promises";
+import process9 from "process";
+
+// src/workflow-create.ts
+import fs from "fs/promises";
+import process2 from "process";
+import { createParser } from "eventsource-parser";
+async function readFromStdin() {
+  const chunks = [];
+  const stdin = process2.stdin;
+  if (stdin.isTTY) {
+    throw new Error("No input on stdin. Pipe workflow JSON or use --from-file.");
+  }
+  return new Promise((resolve, reject) => {
+    stdin.on("data", (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    stdin.on("error", reject);
+  });
+}
+async function readWorkflowInput(argv) {
+  let raw;
+  const fromFile = getArgValue(argv, "--from-file");
+  if (fromFile) {
+    try {
+      raw = await fs.readFile(fromFile, "utf-8");
+    } catch (err) {
+      throw new Error(`Failed to read file ${fromFile}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    raw = await readFromStdin();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid JSON input. Please provide valid workflow JSON.");
+  }
+  const input = parsed;
+  if (!input.name || typeof input.name !== "string") {
+    throw new Error('Workflow JSON must include a "name" string field.');
+  }
+  if (!Array.isArray(input.nodes) || input.nodes.length === 0) {
+    throw new Error('Workflow JSON must include a non-empty "nodes" array.');
+  }
+  const validNodeTypes = ["login", "navigate", "action", "assertion", "end", "setup", "seed", "wait", "condition", "api_sequence", "notification"];
+  for (const node of input.nodes) {
+    if (typeof node.nodeType === "string") {
+      node.nodeType = normalizeNodeType(node.nodeType);
+    }
+    if (!node.nodeType || !validNodeTypes.includes(node.nodeType)) {
+      throw new Error(
+        `Invalid nodeType "${node.nodeType}". Valid types: ${validNodeTypes.join(", ")}`
+      );
+    }
+  }
+  return input;
+}
+async function fetchOrgCredentials(apiUrl, token) {
+  const res = await fetch(`${apiUrl}/org/credentials`, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!res.ok) return [];
+  const data = await res.json();
+  return (data.items ?? []).filter((c) => !c.isEphemeral);
+}
+async function resolveCredential(apiUrl, token, credentialName) {
+  const credentials = await fetchOrgCredentials(apiUrl, token);
+  if (credentials.length === 0) {
+    throw new Error(
+      "No credentials found for this organization. Create one in the web app first."
+    );
+  }
+  if (credentialName) {
+    const match = credentials.find(
+      (c) => c.name.toLowerCase() === credentialName.toLowerCase()
+    );
+    if (match) {
+      const isLocal = /\blocal\b/i.test(match.name);
+      if (isLocal) {
+        console.warn(
+          `Warning: Credential "${match.name}" appears to be local-only. The workflow may fail in deployed environments. Consider using a non-local credential.`
+        );
+      }
+      return { credentialId: match.id, credentialName: match.name, propertyId: match.propertyId };
+    }
+    console.warn(`Warning: No credential matching name "${credentialName}". Trying other resolution strategies.`);
+  }
+  const defaults = credentials.filter((c) => c.isDefault);
+  if (defaults.length === 1) {
+    console.log(`Auto-selected default credential: ${defaults[0].name} (${defaults[0].id})`);
+    return { credentialId: defaults[0].id, credentialName: defaults[0].name, propertyId: defaults[0].propertyId };
+  }
+  const nonLocal = credentials.filter((c) => !/\blocal\b/i.test(c.name));
+  if (nonLocal.length === 1) {
+    console.log(`Auto-selected credential: ${nonLocal[0].name} (${nonLocal[0].id})`);
+    return { credentialId: nonLocal[0].id, credentialName: nonLocal[0].name, propertyId: nonLocal[0].propertyId };
+  }
+  const lines = credentials.map(
+    (c) => `  ${c.id}  ${c.name}${c.isDefault ? " (default)" : ""}${c.propertyName ? ` \u2014 ${c.propertyName}` : ""}`
+  );
+  throw new Error(
+    `Cannot auto-resolve credential. Specify credentialId in the login node configJson.
+
+Available credentials:
+${lines.join("\n")}`
+  );
+}
+async function fetchSuiteLiveState(apiUrl, token, suiteId) {
+  try {
+    const res = await fetch(`${apiUrl}/workflows/test-executions/${suiteId}/live-state`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+async function runAndPublish(opts) {
+  const { apiUrl, token, workflowId, workflowName, timeoutMs } = opts;
+  const body = {};
+  if (opts.propertyId) body.propertyId = opts.propertyId;
+  if (opts.environmentId) body.environmentId = opts.environmentId;
+  const triggerUrl = `${apiUrl}/workflows/test-runs?namePattern=${encodeURIComponent(workflowName)}`;
+  const triggerRes = await fetchOrExit(triggerUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    },
+    token,
+    body: JSON.stringify(body)
+  });
+  if (!triggerRes.ok) {
+    const errorText = await triggerRes.text();
+    console.error(`Failed to trigger test run: ${triggerRes.status} ${errorText}`);
+    return false;
+  }
+  const triggerData = await triggerRes.json();
+  if (!triggerData.ok || !triggerData.suiteId) {
+    console.error(`Failed to trigger test run: ${triggerData.error ?? "Unknown error"}`);
+    return false;
+  }
+  const { suiteId } = triggerData;
+  console.log(`Test run started (suite: ${suiteId})`);
+  console.log("Streaming results...\n");
+  const streamUrl = `${apiUrl}/workflows/test-runs/stream?suiteId=${suiteId}`;
+  const streamRes = await fetchOrExit(streamUrl, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "text/event-stream"
+    },
+    token,
+    // SSE connections stay open; don't let the default 30s timeout cut them off.
+    timeoutMs: 0
+  });
+  if (!streamRes.ok || !streamRes.body) {
+    console.error(`Failed to connect to event stream: ${streamRes.status}`);
+    return false;
+  }
+  let success = false;
+  let hasCompleted = false;
+  const parser = createParser({
+    onEvent: (event) => {
+      if (!event.data) return;
+      try {
+        const data = JSON.parse(event.data);
+        if (event.event === "workflow-test") {
+          const testEvent = data;
+          if (testEvent.status === "success") {
+            console.log(`  \u2713 ${workflowName}`);
+            success = true;
+          } else if (testEvent.status === "failed") {
+            console.log(`  \u2717 ${workflowName}`);
+            if (testEvent.errorMessage) {
+              console.log(`    Error: ${testEvent.errorMessage.slice(0, 200)}`);
+            }
+            success = false;
+          } else if (testEvent.status === "running") {
+            console.log(`  \u25B6 Running ${workflowName}...`);
+          }
+        }
+        if (event.event === "workflow-test-suite") {
+          const suiteEvent = data;
+          if (suiteEvent.status === "completed") {
+            hasCompleted = true;
+          }
+        }
+      } catch {
+      }
+    }
+  });
+  const reader = streamRes.body.getReader();
+  const decoder = new TextDecoder();
+  let timedOut = false;
+  const timeoutHandle = setTimeout(() => {
+    timedOut = true;
+    reader.cancel().catch(() => {
+    });
+  }, timeoutMs);
+  try {
+    while (!hasCompleted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parser.feed(decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    clearTimeout(timeoutHandle);
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+  if (!hasCompleted) {
+    const reason = timedOut ? `Timed out after ${Math.round(timeoutMs / 1e3)}s waiting for test completion` : "Event stream closed before completion";
+    console.warn(`
+\u26A0 ${reason}. Polling final state...`);
+    const live = await fetchSuiteLiveState(apiUrl, token, suiteId);
+    const exec = live?.execution;
+    if (exec && (exec.status === "completed" || exec.status === "completed_with_errors")) {
+      success = exec.failedWorkflows === 0;
+      const match = live?.runs?.find((r) => r.workflowId === workflowId);
+      if (match) {
+        console.log(
+          success ? `  \u2713 ${workflowName}` : `  \u2717 ${workflowName}`
+        );
+        if (!success && match.errorMessage) {
+          console.log(`    Error: ${match.errorMessage.slice(0, 200)}`);
+        }
+      }
+    } else {
+      console.error(
+        `Suite ${suiteId} is still ${exec?.status ?? "unknown"} on the server. Check it in the web app.`
+      );
+      return false;
+    }
+  }
+  if (success) {
+    try {
+      const publishRes = await fetchOrExit(`${apiUrl}/workflows/${workflowId}/publish`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        token
+      });
+      if (publishRes.ok) {
+        console.log(`
+\u2713 Workflow published successfully`);
+        return true;
+      } else {
+        console.error(`
+Failed to publish workflow: ${publishRes.status}`);
+        return false;
+      }
+    } catch (err) {
+      console.error(`
+Failed to publish workflow: ${err}`);
+      return false;
+    }
+  }
+  console.log(`
+\u2717 Test failed \u2014 workflow left in draft for manual review`);
+  return false;
+}
+async function readApiSequenceConfig(argv) {
+  const fromFile = getArgValue(argv, "--sequence-from-file");
+  const fromStdin = hasFlag(argv, "--sequence-from-stdin");
+  if (!fromFile && !fromStdin) {
+    return { steps: [] };
+  }
+  let raw;
+  if (fromFile) {
+    raw = await fs.readFile(fromFile, "utf-8");
+  } else {
+    raw = await readFromStdin();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid JSON for sequence config.");
+  }
+  const cfg = parsed;
+  if (!cfg || !Array.isArray(cfg.steps)) {
+    throw new Error('Sequence config must be { "steps": [...] }.');
+  }
+  return cfg;
+}
+async function handleApiOnlyCreate(argv, apiUrl, token) {
+  const name = getArgValue(argv, "--name");
+  if (!name) {
+    console.error("Error: --api-only requires --name <workflow name>.");
+    process2.exit(1);
+  }
+  const credentialId = getArgValue(argv, "--credential");
+  const guidance = getArgValue(argv, "--guidance");
+  let config;
+  try {
+    config = await readApiSequenceConfig(argv);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process2.exit(1);
+  }
+  const body = { name, config };
+  if (credentialId) body.credentialId = credentialId;
+  if (guidance) body.guidancePrompt = guidance;
+  const res = await fetchOrExit(`${apiUrl}/api-sequences/create-with-workflow`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    },
+    token,
+    body: JSON.stringify(body)
+  });
+  const raw = await res.json().catch(() => ({}));
+  if (!res.ok || !raw.ok || !raw.data) {
+    const jsonOutput = hasFlag(argv, "--json") || !process2.stdout.isTTY;
+    if (raw.code === "API_SEQUENCE_INVALID" && Array.isArray(raw.issues)) {
+      if (jsonOutput) {
+        console.log(
+          JSON.stringify(
+            {
+              ok: false,
+              error: raw.error ?? "API sequence configuration is invalid",
+              code: "API_SEQUENCE_INVALID",
+              issueCount: raw.issues.length,
+              issues: raw.issues
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.error(`Error: ${raw.error ?? "API sequence configuration is invalid"}`);
+        console.error(`Found ${raw.issues.length} issue${raw.issues.length === 1 ? "" : "s"}:`);
+        console.error("");
+        for (const issue of raw.issues) {
+          console.error(`  ${issue.path || "(root)"} [${issue.code}] :: ${issue.message}`);
+          if (issue.hint) console.error(`    hint: ${issue.hint}`);
+        }
+      }
+      process2.exit(1);
+    }
+    console.error(`Error: ${raw.error ?? `${res.status} ${res.statusText}`}`);
+    process2.exit(1);
+  }
+  if (hasFlag(argv, "--json") || !process2.stdout.isTTY) {
+    console.log(JSON.stringify({ ok: true, data: raw.data }, null, 2));
+    return;
+  }
+  const appUrl = resolveAppUrl(apiUrl);
+  console.log(`
+\u2713 API-only workflow created: ${name}`);
+  console.log(`  Workflow ID:     ${raw.data.workflowId}`);
+  console.log(`  API Sequence ID: ${raw.data.apiSequenceId}`);
+  if (raw.data.nodeId) console.log(`  Node ID:         ${raw.data.nodeId}`);
+  console.log(`  Steps:           ${config.steps.length}`);
+  console.log(`  URL:             ${appUrl}/flows/${raw.data.workflowId}`);
+  console.log(`
+  Next:`);
+  console.log(`    canary workflow api-sequence get ${raw.data.workflowId}`);
+  console.log(`    canary workflow api-sequence update ${raw.data.workflowId} --from-file seq.json`);
+  console.log(`    canary workflow api-sequence execute ${raw.data.workflowId}`);
+}
+async function handleWorkflowCreate(argv, apiUrl, token) {
+  if (hasFlag(argv, "--api-only")) {
+    await handleApiOnlyCreate(argv, apiUrl, token);
+    return;
+  }
+  const runAndPublishFlag = hasFlag(argv, "--run-and-publish");
+  const propertyArg = getArgValue(argv, "--property");
+  const environmentArg = getArgValue(argv, "--environment");
+  const timeoutArg = getArgValue(argv, "--publish-timeout");
+  const timeoutSec = timeoutArg ? Number.parseInt(timeoutArg, 10) : 900;
+  if (!Number.isFinite(timeoutSec) || timeoutSec <= 0) {
+    console.error(`Error: --publish-timeout must be a positive integer (seconds), got "${timeoutArg}"`);
+    process2.exit(1);
+  }
+  let input;
+  try {
+    input = await readWorkflowInput(argv);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process2.exit(1);
+  }
+  const loginNodes = input.nodes.filter((n) => n.nodeType === "login");
+  for (const loginNode of loginNodes) {
+    const config = loginNode.configJson ?? {};
+    if (!config.credentialId && !input.credentialId) {
+      try {
+        const resolved = await resolveCredential(
+          apiUrl,
+          token,
+          config.credentialName
+        );
+        config.credentialId = resolved.credentialId;
+        config.credentialName = resolved.credentialName;
+        loginNode.configJson = config;
+        if (resolved.propertyId && !input.propertyId) {
+          input.propertyId = resolved.propertyId;
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process2.exit(1);
+      }
+    }
+  }
+  input.createdVia = "cli";
+  const res = await fetchOrExit(`${apiUrl}/workflows/create-with-nodes`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    },
+    token,
+    body: JSON.stringify(input)
+  });
+  const result = await res.json();
+  if (!result.ok || !result.workflow) {
+    console.error(`Error: ${result.error ?? "Failed to create workflow"}`);
+    process2.exit(1);
+  }
+  const { workflow, nodes, edges } = result;
+  const { warnings } = result;
+  console.log(`
+\u2713 Workflow created: ${workflow.name}`);
+  console.log(`  ID: ${workflow.id}`);
+  console.log(`  Status: ${workflow.status}`);
+  console.log(`  Nodes: ${nodes?.length ?? 0}`);
+  console.log(`  Edges: ${edges?.length ?? 0}`);
+  if (warnings && warnings.length > 0) {
+    console.log(`
+  Warnings:`);
+    for (const w of warnings) {
+      console.log(`    \u26A0 ${w}`);
+    }
+  }
+  const appUrl = resolveAppUrl(apiUrl);
+  console.log(`  URL: ${appUrl}/flows/${workflow.id}`);
+  try {
+    const tagResult = await applyWorkflowTagFlags({
+      apiUrl,
+      token,
+      argv,
+      workflowId: workflow.id
+    });
+    if (tagResult) {
+      console.log(`  Tags: ${tagResult.tagIds.length} assigned`);
+    }
+  } catch (err) {
+    console.error(`
+Error applying tags:
+${err instanceof Error ? err.message : String(err)}`);
+    process2.exit(1);
+  }
+  if (runAndPublishFlag) {
+    console.log("\nTriggering test run...");
+    const passed = await runAndPublish({
+      apiUrl,
+      token,
+      workflowId: workflow.id,
+      workflowName: workflow.name,
+      propertyId: propertyArg ?? input.propertyId,
+      environmentId: environmentArg,
+      timeoutMs: timeoutSec * 1e3
+    });
+    if (!passed) {
+      process2.exit(1);
+    }
+  }
+}
+
+// src/workflow-run.ts
+import process3 from "process";
+
+// src/cli-format.ts
+var STATUS_ICONS = {
+  completed: "\u2705",
+  completed_with_errors: "\u26A0\uFE0F",
+  success: "\u2705",
+  passed: "\u2705",
+  failed: "\u274C",
+  running: "\u{1F535}",
+  queued: "\u23F3",
+  canceled: "\u{1F6AB}",
+  timeout: "\u23F0",
+  skipped: "\u23ED\uFE0F",
+  flaky_success: "\u{1F7E1}",
+  pending: "\u23F3"
+};
+function statusIcon(status) {
+  return STATUS_ICONS[status] ?? "\u2753";
+}
+function formatRelative(iso) {
+  if (!iso) return "\u2014";
+  const diffMs = Date.now() - new Date(iso).getTime();
+  if (diffMs < 0) return "just now";
+  const seconds = Math.floor(diffMs / 1e3);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+function computeDuration(startedAt, finishedAt) {
+  if (!startedAt || !finishedAt) return "\u2014";
+  const ms = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
+  if (ms < 0) return "\u2014";
+  const totalSeconds = Math.floor(ms / 1e3);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const remainMins = minutes % 60;
+  return remainMins > 0 ? `${hours}h ${remainMins}m` : `${hours}h`;
+}
+function pad(str, len) {
+  return str.padEnd(len);
+}
+function readFromStdin2() {
+  const stdin = process.stdin;
+  if (stdin.isTTY) {
+    return Promise.reject(
+      new Error("No input on stdin. Pipe JSON or use --from-file.")
+    );
+  }
+  const chunks = [];
+  return new Promise((resolve, reject) => {
+    stdin.on("data", (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    stdin.on("error", reject);
+  });
+}
+
+// src/workflow-run.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function handleWorkflowRun(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error(
+      "Usage: canary workflow run <workflowId> [--stream] [--json] [--validation | --no-validation]"
+    );
+    process3.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const stream = hasFlag(argv, "--stream");
+  const optInValidation = hasFlag(argv, "--validation");
+  const optOutValidation = hasFlag(argv, "--no-validation");
+  const validationMode = optInValidation ? true : optOutValidation ? false : void 0;
+  const requestBody = {
+    triggerSource: "cli_direct"
+  };
+  if (validationMode !== void 0) {
+    requestBody.validationMode = validationMode;
+  }
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/workflows/${workflowId}/execute`,
+    requestBody
+  );
+  if (!result.ok) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const rendered = renderWorkflowUserError(result);
+      console.error(rendered ?? `Error: ${result.error ?? "Unknown error"}`);
+    }
+    process3.exit(1);
+  }
+  const { runId } = result;
+  if (jsonOutput && !stream) {
+    console.log(JSON.stringify({ ok: true, runId, streamId: result.streamId }, null, 2));
+    return;
+  }
+  if (!stream) {
+    console.log(`Run triggered successfully.`);
+    console.log(`  Run ID: ${runId}`);
+    console.log(`
+Check status: canary workflow runs get ${workflowId} ${runId}`);
+    return;
+  }
+  console.log(`Run triggered (${runId}). Waiting for completion...
+`);
+  const terminalStatuses = /* @__PURE__ */ new Set([
+    "completed",
+    "success",
+    "passed",
+    "failed",
+    "canceled",
+    "timeout"
+  ]);
+  let lastStatus = "";
+  for (; ; ) {
+    await sleep(3e3);
+    const status = await apiRequest(
+      apiUrl,
+      token,
+      "GET",
+      `/workflows/${workflowId}/runs/${runId}`
+    );
+    if (!status.ok) {
+      console.error(`Error polling status: ${status.error ?? "Unknown error"}`);
+      process3.exit(1);
+    }
+    const run = status.data.run;
+    if (run.status !== lastStatus) {
+      console.log(`  ${statusIcon(run.status)} ${run.status}`);
+      lastStatus = run.status;
+    }
+    if (terminalStatuses.has(run.status)) {
+      if (run.errorMessage) {
+        console.log(`
+Error: ${run.errorMessage}`);
+      }
+      console.log(`
+Run finished: ${run.status}`);
+      console.log(`Details: canary workflow runs get ${workflowId} ${runId}`);
+      if (run.status === "failed" || run.status === "timeout" || run.status === "canceled") {
+        process3.exit(1);
+      }
+      return;
+    }
+  }
+}
+
+// src/workflow-runs.ts
+import process4 from "process";
+async function fetchBrowserRuns(apiUrl, token, workflowId, page, pageSize) {
+  const params = new URLSearchParams({ page, pageSize });
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/workflows/${workflowId}/runs?${params}`
+  );
+  if (!result.ok) return { error: result.error ?? "Unknown error" };
+  return { runs: result.data.runs, pagination: result.pagination };
+}
+async function fetchApiRuns(apiUrl, token, workflowId, page, pageSize) {
+  const seqRes = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/api-sequences/by-workflow/${workflowId}`
+  );
+  if (!seqRes.ok) {
+    return {
+      error: seqRes.error ?? "Unknown error",
+      ...seqRes.code ? { code: seqRes.code } : {}
+    };
+  }
+  if (!seqRes.data) return { runs: [], pagination: null };
+  const params = new URLSearchParams({ page, pageSize });
+  const runsRes = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/api-sequences/${seqRes.data.id}/runs?${params}`
+  );
+  if (!runsRes.ok) return { error: runsRes.error ?? "Unknown error" };
+  const runs = (runsRes.data ?? []).map((r) => ({
+    id: r.id,
+    status: r.status,
+    createdAt: r.createdAt ?? r.startedAt ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+    startedAt: r.startedAt,
+    finishedAt: r.finishedAt,
+    errorMessage: r.errorMessage,
+    browserMode: null,
+    stepTotals: null,
+    snapshotVersion: null
+  }));
+  return { runs, pagination: runsRes.pagination ?? null };
+}
+async function handleRunsList(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID. Usage: canary workflow runs list <workflowId>");
+    process4.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const page = getArgValue(argv, "--page") ?? "1";
+  const pageSize = getArgValue(argv, "--page-size") ?? "10";
+  const explicitSide = getArgValue(argv, "--side") ?? getArgValue(argv, "--mode");
+  const sideArg = (explicitSide ?? "all").toLowerCase();
+  if (!["all", "api", "browser"].includes(sideArg)) {
+    console.error(`Error: --side must be one of: all, api, browser (got "${sideArg}")`);
+    process4.exit(1);
+  }
+  const annotated = [];
+  let browserPagination = null;
+  let apiPagination = null;
+  if (sideArg === "browser" || sideArg === "all") {
+    const browser = await fetchBrowserRuns(apiUrl, token, workflowId, page, pageSize);
+    if ("error" in browser) {
+      console.error(`Error: ${browser.error}`);
+      process4.exit(1);
+    }
+    browserPagination = browser.pagination;
+    for (const r of browser.runs) annotated.push({ ...r, side: "browser" });
+  }
+  if (sideArg === "api" || sideArg === "all") {
+    const api = await fetchApiRuns(apiUrl, token, workflowId, page, pageSize);
+    if ("error" in api) {
+      const isMissingSequence = api.code === "API_SEQUENCE_NOT_FOUND";
+      if (!explicitSide && isMissingSequence) {
+        if (!jsonOutput) {
+          console.error("Note: workflow has no api-sequence \u2014 showing browser runs only.");
+        }
+      } else {
+        console.error(`Error: ${api.error}`);
+        process4.exit(1);
+      }
+    } else {
+      apiPagination = api.pagination;
+      for (const r of api.runs) annotated.push({ ...r, side: "api" });
+    }
+  }
+  annotated.sort((a, b) => {
+    const ta = new Date(a.startedAt ?? a.createdAt).getTime();
+    const tb = new Date(b.startedAt ?? b.createdAt).getTime();
+    return tb - ta;
+  });
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          data: { runs: annotated },
+          pagination: { browser: browserPagination, api: apiPagination }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  if (annotated.length === 0) {
+    console.log("No runs found.");
+    return;
+  }
+  console.log(`Runs (${annotated.length} shown, side=${sideArg})
+`);
+  const idW = 36;
+  const sideW = 8;
+  const statusW = 12;
+  const durationW = 10;
+  console.log(
+    [
+      "ID".padEnd(idW),
+      "Side".padEnd(sideW),
+      "Status".padEnd(statusW),
+      "Duration".padEnd(durationW),
+      "Started"
+    ].join("  ")
+  );
+  for (const run of annotated) {
+    const icon = statusIcon(run.status);
+    const dur = computeDuration(run.startedAt, run.finishedAt);
+    const time = formatRelative(run.startedAt ?? run.createdAt);
+    console.log(
+      [
+        run.id.padEnd(idW),
+        pad(run.side, sideW),
+        `${icon} ${pad(run.status, statusW - 3)}`,
+        pad(dur, durationW),
+        time
+      ].join("  ")
+    );
+  }
+  console.log("");
+}
+async function handleRunsGet(argv, apiUrl, token) {
+  const positional = argv.filter((a) => !a.startsWith("-"));
+  if (positional.length < 2) {
+    console.error(
+      "Error: Missing arguments. Usage: canary workflow runs get <workflowId> <runId>"
+    );
+    process4.exit(1);
+  }
+  const [workflowId, runId] = positional;
+  const jsonOutput = hasFlag(argv, "--json");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/workflows/${workflowId}/runs/${runId}`
+  );
+  if (!result.ok) {
+    console.error(`Error: ${result.error ?? "Unknown error"}`);
+    process4.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const { run } = result.data;
+  const duration = computeDuration(run.startedAt, run.finishedAt);
+  console.log(`Run:      ${run.id}`);
+  console.log(`Status:   ${statusIcon(run.status)} ${run.status}`);
+  console.log(`Duration: ${duration}`);
+  if (run.errorMessage) {
+    console.log(`Error:    ${run.errorMessage}`);
+  }
+  if (run.draftSnapshot) {
+    console.log(`Snapshot: v${run.draftSnapshot.version} (base: v${run.draftSnapshot.basePublishedVersion})`);
+  }
+  const steps = (run.steps ?? []).sort((a, b) => a.orderIndex - b.orderIndex);
+  if (steps.length === 0) {
+    console.log("\nNo steps recorded.");
+    return;
+  }
+  console.log(`
+Steps (${steps.length}):`);
+  for (const step of steps) {
+    const idx = String(step.orderIndex + 1).padStart(2);
+    const icon = statusIcon(step.status);
+    const nodeId = step.nodeId.slice(0, 8);
+    const dur = computeDuration(step.startedAt, step.finishedAt);
+    console.log(`  ${idx}. ${icon}  ${pad(nodeId, 10)} ${dur}`);
+    if (step.errorMessage) {
+      console.log(`       Error: ${step.errorMessage}`);
+    }
+  }
+  console.log("");
+}
+async function handleRunsDiagnostics(argv, apiUrl, token) {
+  const positional = argv.filter((a) => !a.startsWith("-"));
+  if (positional.length < 2) {
+    console.error(
+      "Error: Missing arguments. Usage: canary workflow runs diagnostics <workflowId> <runId>"
+    );
+    process4.exit(1);
+  }
+  const [workflowId, runId] = positional;
+  const jsonOutput = hasFlag(argv, "--json");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/workflows/${workflowId}/runs/${runId}/failure-diagnostic`
+  );
+  if (!result.ok) {
+    console.error(`Error: ${result.error ?? "Unknown error"}`);
+    process4.exit(1);
+  }
+  if (jsonOutput && result.data) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.data) {
+    const { status, diagnostic } = result.data;
+    if (status === "pending" || status === "running") {
+      console.log(`Diagnostic is still in progress (status: ${status}).`);
+      return;
+    }
+    if (status === "failed") {
+      console.log("Diagnostic analysis failed.");
+      return;
+    }
+    if (diagnostic) {
+      console.log("Failure Diagnostic");
+      console.log(`Status:     ${status}`);
+      if (diagnostic.category) {
+        const conf = diagnostic.confidence !== null && diagnostic.confidence !== void 0 ? ` (${diagnostic.confidence > 1 ? Math.round(diagnostic.confidence) : Math.round(diagnostic.confidence * 100)}% confidence)` : "";
+        console.log(`Category:   ${diagnostic.category}${conf}`);
+      }
+      if (diagnostic.title) {
+        console.log(`Title:      ${diagnostic.title}`);
+      }
+      if (diagnostic.analysis) {
+        console.log("");
+        console.log("Analysis:");
+        console.log(`  ${diagnostic.analysis}`);
+      }
+      if (diagnostic.recommendation) {
+        console.log("");
+        console.log("Recommendation:");
+        console.log(`  ${diagnostic.recommendation}`);
+      }
+      if (diagnostic.smokingGun) {
+        console.log("");
+        console.log("Smoking Gun:");
+        console.log(`  > ${diagnostic.smokingGun.description}`);
+        if (diagnostic.smokingGun.detail) {
+          console.log(`    ${diagnostic.smokingGun.detail}`);
+        }
+      }
+      console.log("");
+      return;
+    }
+  }
+  const rawResult = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/workflows/${workflowId}/runs/${runId}/diagnostics`
+  );
+  if (!rawResult.ok) {
+    console.log("No diagnostic available for this run.");
+    return;
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify(rawResult, null, 2));
+    return;
+  }
+  const hasConsole = rawResult.consoleLogs && rawResult.consoleLogs.length > 0;
+  const hasNetwork = rawResult.networkRequests && rawResult.networkRequests.length > 0;
+  if (!hasConsole && !hasNetwork) {
+    console.log("No diagnostic data available for this run.");
+    return;
+  }
+  if (hasConsole) {
+    console.log(`Console Logs (${rawResult.consoleLogs.length}):`);
+    for (const log of rawResult.consoleLogs.slice(0, 50)) {
+      const level = log.level.toUpperCase().padEnd(7);
+      console.log(`  [${level}] ${log.text}`);
+    }
+    if (rawResult.consoleLogs.length > 50) {
+      console.log(`  ... and ${rawResult.consoleLogs.length - 50} more`);
+    }
+    console.log("");
+  }
+  if (hasNetwork) {
+    console.log(`Network Requests (${rawResult.networkRequests.length}):`);
+    for (const req of rawResult.networkRequests.slice(0, 30)) {
+      const statusStr = req.status >= 400 ? `${req.status} !!!` : String(req.status);
+      console.log(`  ${req.method.padEnd(6)} ${statusStr.padEnd(8)} ${req.url}`);
+    }
+    if (rawResult.networkRequests.length > 30) {
+      console.log(`  ... and ${rawResult.networkRequests.length - 30} more`);
+    }
+    console.log("");
+  }
+}
+function printRunsHelp() {
+  console.log(
+    [
+      "Usage: canary workflow runs <sub-command> [options]",
+      "",
+      "Sub-commands:",
+      "  list <workflowId> [options]                    List runs for a workflow",
+      "  get <workflowId> <runId> [options]             Get run detail with steps",
+      "  diagnostics <workflowId> <runId> [options]     Get failure diagnostic",
+      "",
+      "List options:",
+      "  --page <n>            Page number (default: 1)",
+      "  --page-size <n>       Page size (default: 10)",
+      "  --side <side>         Filter: browser, api, all (default: all). Alias: --mode",
+      "",
+      "Output options:",
+      "  --json                Output raw JSON",
+      "",
+      "Common options:",
+      "  --env <env>           Target environment (prod, dev, local)",
+      "  --api-url <url>       API URL override",
+      "  --token <key>         API token override"
+    ].join("\n")
+  );
+}
+async function runWorkflowRuns(argv, apiUrl, token) {
+  const [subCommand, ...rest] = argv;
+  if (!subCommand || subCommand === "help" || hasFlag(argv, "--help", "-h")) {
+    printRunsHelp();
+    return;
+  }
+  switch (subCommand) {
+    case "list":
+      await handleRunsList(rest, apiUrl, token);
+      break;
+    case "get":
+      await handleRunsGet(rest, apiUrl, token);
+      break;
+    case "diagnostics":
+      await handleRunsDiagnostics(rest, apiUrl, token);
+      break;
+    default:
+      console.error(`Unknown sub-command: ${subCommand}`);
+      printRunsHelp();
+      process4.exit(1);
+  }
+}
+
+// src/workflow-sync.ts
+import crypto from "crypto";
+import fs2 from "fs/promises";
+import process5 from "process";
+function normalizeNodesAndEdges(rawNodes, rawEdges) {
+  const nodes = rawNodes.map((node, i) => ({
+    ...node,
+    id: node.id ?? crypto.randomUUID(),
+    orderIndex: node.orderIndex ?? i,
+    configJson: node.configJson ?? {}
+  }));
+  if (rawEdges && rawEdges.length > 0) {
+    const edges2 = rawEdges.map((edge) => ({
+      ...edge,
+      id: edge.id ?? crypto.randomUUID()
+    }));
+    return { nodes, edges: edges2 };
+  }
+  const edges = [];
+  for (let i = 0; i < nodes.length - 1; i++) {
+    edges.push({
+      id: crypto.randomUUID(),
+      sourceNodeId: nodes[i].id,
+      targetNodeId: nodes[i + 1].id,
+      edgeType: "default"
+    });
+  }
+  return { nodes, edges };
+}
+async function readSyncInput(argv) {
+  const filePath = getArgValue(argv, "--from-file");
+  const fromStdin = hasFlag(argv, "--from-stdin");
+  let raw;
+  if (filePath) {
+    try {
+      raw = await fs2.readFile(filePath, "utf-8");
+    } catch (err) {
+      console.error(`Error reading file: ${err instanceof Error ? err.message : String(err)}`);
+      process5.exit(1);
+    }
+  } else if (fromStdin) {
+    try {
+      raw = await readFromStdin2();
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process5.exit(1);
+    }
+  } else {
+    console.error("Error: Must provide --from-file <path> or --from-stdin");
+    process5.exit(1);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.error("Error: Invalid JSON input");
+    process5.exit(1);
+  }
+  const obj = parsed;
+  const normalizeNodes = (raw2) => {
+    return raw2.map((entry) => {
+      if (entry && typeof entry === "object" && "nodeType" in entry) {
+        const node = entry;
+        if (typeof node.nodeType === "string") {
+          node.nodeType = normalizeNodeType(node.nodeType);
+        }
+      }
+      return entry;
+    });
+  };
+  if (Array.isArray(obj.nodes)) {
+    return {
+      nodes: normalizeNodes(obj.nodes),
+      edges: Array.isArray(obj.edges) ? obj.edges : void 0
+    };
+  }
+  const workflow = obj.workflow;
+  if (workflow && Array.isArray(workflow.nodes)) {
+    return {
+      nodes: normalizeNodes(workflow.nodes),
+      edges: Array.isArray(workflow.edges) ? workflow.edges : void 0
+    };
+  }
+  console.error('Error: JSON must contain a "nodes" array.');
+  console.error("Accepted formats:");
+  console.error('  { "nodes": [{ "nodeType": "login", "configJson": {} }, ...] }');
+  console.error('  { "nodes": [...], "edges": [...] }');
+  console.error('  { "workflow": { "nodes": [...], "edges": [...] } }');
+  console.error("");
+  console.error("Edges, IDs, positions, and ordering are auto-generated when omitted.");
+  process5.exit(1);
+}
+async function alignWithCurrentWorkflow(apiUrl, token, workflowId, nodes, edges) {
+  let currentNodes = [];
+  try {
+    const current = await apiRequest(
+      apiUrl,
+      token,
+      "GET",
+      `/workflows/${workflowId}`
+    );
+    if (current.ok && current.workflow?.nodes) {
+      currentNodes = current.workflow.nodes.map((n) => ({
+        id: n.id,
+        nodeType: n.nodeType,
+        orderIndex: n.orderIndex,
+        configJson: n.configJson ?? {}
+      }));
+    }
+  } catch {
+  }
+  if (currentNodes.length === 0) {
+    return { nodes, edges };
+  }
+  const proposedSnapshot = {
+    nodes: nodes.map((n) => ({
+      id: String(n.id),
+      nodeType: String(n.nodeType ?? ""),
+      orderIndex: typeof n.orderIndex === "number" ? n.orderIndex : void 0,
+      configJson: n.configJson ?? {}
+    })),
+    edges: edges.map((e) => ({
+      id: String(e.id),
+      sourceNodeId: String(e.sourceNodeId),
+      targetNodeId: String(e.targetNodeId),
+      edgeType: e.edgeType ?? null
+    }))
+  };
+  const { snapshot } = alignSnapshotNodeIds(proposedSnapshot, currentNodes);
+  const alignedNodes = nodes.map((n, i) => ({
+    ...n,
+    id: snapshot.nodes[i].id
+  }));
+  const alignedEdges = edges.map((e, i) => ({
+    ...e,
+    sourceNodeId: snapshot.edges[i].sourceNodeId,
+    targetNodeId: snapshot.edges[i].targetNodeId
+  }));
+  return { nodes: alignedNodes, edges: alignedEdges };
+}
+async function handleWorkflowSync(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow sync <workflowId> --from-file <path>");
+    process5.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const noSnapshot = hasFlag(argv, "--no-snapshot");
+  const propose = hasFlag(argv, "--propose");
+  const proposalTitle = getArgValue(argv, "--title");
+  const proposalDescription = getArgValue(argv, "--description");
+  const raw = await readSyncInput(argv);
+  const { nodes, edges } = normalizeNodesAndEdges(raw.nodes, raw.edges);
+  if (propose) {
+    const title = proposalTitle ?? `CLI sync proposal (${nodes.length} nodes)`;
+    const aligned = await alignWithCurrentWorkflow(apiUrl, token, workflowId, nodes, edges);
+    const result2 = await apiRequest(
+      apiUrl,
+      token,
+      "POST",
+      `/workflows/${workflowId}/proposals`,
+      {
+        title,
+        description: proposalDescription ?? null,
+        snapshotJson: { nodes: aligned.nodes, edges: aligned.edges },
+        source: "api"
+      }
+    );
+    if (!result2.ok) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ ok: false, error: result2.error ?? "Unknown error" }, null, 2));
+      } else {
+        console.error(`Error: ${result2.error ?? "Unknown error"}`);
+      }
+      process5.exit(1);
+    }
+    if (jsonOutput) {
+      console.log(JSON.stringify(result2, null, 2));
+      return;
+    }
+    console.log(`Proposal created for workflow ${workflowId} (${nodes.length} nodes, ${edges.length} edges).`);
+    if (result2.data?.id) {
+      console.log(`Proposal ID: ${result2.data.id}`);
+    }
+    return;
+  }
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "PUT",
+    `/workflows/${workflowId}/draft-state`,
+    { nodes, edges, createSnapshot: !noSnapshot }
+  );
+  if (!result.ok) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({ ok: false, error: result.error ?? "Unknown error" }, null, 2));
+    } else {
+      console.error(`Error: ${result.error ?? "Unknown error"}`);
+    }
+    process5.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Workflow ${workflowId} synced (${nodes.length} nodes, ${edges.length} edges).`);
+  if (result.snapshotVersion) {
+    console.log(`Draft snapshot created: ${result.snapshotVersion}`);
+  }
+}
+
+// src/workflow-api-sequence.ts
+import process6 from "process";
+import { createParser as createParser2 } from "eventsource-parser";
+async function handleWorkflowGenerateApiSequence(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  const prompt = getArgValue(argv, "--prompt");
+  const guidance = getArgValue(argv, "--guidance");
+  const propertyId = getArgValue(argv, "--property");
+  const jsonOutput = hasFlag(argv, "--json");
+  const verbose = hasFlag(argv, "--verbose", "-v");
+  if (!workflowId && !prompt) {
+    console.error("Error: Provide a workflow ID or --prompt.");
+    console.error("");
+    console.error("Usage:");
+    console.error('  canary workflow generate-api-sequence <workflowId> [--guidance "text"]');
+    console.error('  canary workflow generate-api-sequence --prompt "Create user" [--property <id>]');
+    process6.exit(1);
+  }
+  let endpoint;
+  let body;
+  if (workflowId && !prompt) {
+    endpoint = "/api-sequence-agent/generate-from-run";
+    body = { workflowId };
+    if (guidance) body.guidancePrompt = guidance;
+    if (!jsonOutput) {
+      console.error(`Generating API sequence from latest run of workflow ${workflowId}...`);
+    }
+  } else {
+    endpoint = "/api-sequence-agent/generate";
+    body = { prompt };
+    if (propertyId) body.propertyId = propertyId;
+    if (workflowId) body.workflowId = workflowId;
+    if (!jsonOutput) {
+      console.error(`Generating API sequence from prompt...`);
+    }
+  }
+  let triggerRes;
+  try {
+    triggerRes = await fetch(`${apiUrl}${endpoint}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (err) {
+    console.error(`Failed to connect to API: ${err}`);
+    process6.exit(1);
+  }
+  if (triggerRes.status === 403) {
+    const data = await triggerRes.json().catch(() => ({}));
+    console.error(`Error: ${data.error ?? "This feature is not enabled for your organization."}`);
+    process6.exit(1);
+  }
+  if (!triggerRes.ok) {
+    const data = await triggerRes.json().catch(() => ({}));
+    console.error(`Error: ${data.error ?? `${triggerRes.status} ${triggerRes.statusText}`}`);
+    process6.exit(1);
+  }
+  const triggerData = await triggerRes.json();
+  if (!triggerData.ok || !triggerData.generationId) {
+    console.error(`Error: ${triggerData.error ?? "Failed to start generation"}`);
+    process6.exit(1);
+  }
+  const { generationId } = triggerData;
+  const streamUrl = `${apiUrl}/api-sequence-agent/stream?generationId=${generationId}`;
+  let streamRes;
+  try {
+    streamRes = await fetch(streamUrl, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "text/event-stream"
+      }
+    });
+  } catch (err) {
+    console.error(`Failed to connect to event stream: ${err}`);
+    process6.exit(1);
+  }
+  if (!streamRes.ok || !streamRes.body) {
+    console.error(`Failed to connect to event stream: ${streamRes.status}`);
+    process6.exit(1);
+  }
+  let resultConfig = null;
+  let resultSummary = "";
+  let hasCompleted = false;
+  let exitCode = 0;
+  const parser = createParser2({
+    onEvent: (event) => {
+      if (!event.data || event.event !== "api-sequence-generation") return;
+      try {
+        const data = JSON.parse(event.data);
+        switch (data.eventType) {
+          case "progress":
+            if (!jsonOutput) console.error(`  ${data.message}`);
+            break;
+          case "tool-call":
+            if (verbose) console.error(`  [tool] ${data.toolName}`);
+            break;
+          case "tool-result":
+            if (verbose) {
+              const icon = data.success ? "\u2713" : "\u2717";
+              console.error(`  [tool] ${icon} ${data.toolName}`);
+            }
+            break;
+          case "text":
+            if (verbose) process6.stderr.write(data.delta);
+            break;
+          case "complete":
+            resultConfig = data.config;
+            resultSummary = data.summary;
+            hasCompleted = true;
+            break;
+          case "error":
+            console.error(`
+Error: ${data.message}`);
+            exitCode = 1;
+            hasCompleted = true;
+            break;
+        }
+      } catch {
+      }
+    }
+  });
+  const reader = streamRes.body.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (!hasCompleted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parser.feed(decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (exitCode !== 0) {
+    process6.exit(exitCode);
+  }
+  if (!resultConfig) {
+    console.error("Generation completed but no config was returned.");
+    process6.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify({ ok: true, config: resultConfig, summary: resultSummary }, null, 2));
+  } else {
+    if (resultSummary) {
+      console.error("");
+      console.error(resultSummary);
+    }
+    console.error("");
+    console.log(JSON.stringify(resultConfig, null, 2));
+  }
+}
+
+// src/workflow-api-sequence-cmds.ts
+import fs3 from "fs/promises";
+import process7 from "process";
+function getArg(argv, key) {
+  const prefix = `${key}=`;
+  const eq = argv.find((a) => a.startsWith(prefix));
+  if (eq) return eq.slice(prefix.length);
+  return getArgValue(argv, key);
+}
+function wantsJson(argv) {
+  if (hasFlag(argv, "--json")) return true;
+  if (hasFlag(argv, "--text")) return false;
+  return !process7.stdout.isTTY;
+}
+function emit(argv, textFallback, json) {
+  if (wantsJson(argv)) {
+    console.log(JSON.stringify(json, null, 2));
+  } else {
+    console.log(textFallback);
+  }
+}
+async function readJsonInput(argv) {
+  const fromFile = getArg(argv, "--from-file");
+  let raw;
+  if (fromFile) {
+    raw = await fs3.readFile(fromFile, "utf-8");
+  } else if (hasFlag(argv, "--from-stdin") || !process7.stdin.isTTY) {
+    raw = await readStdin();
+  } else {
+    throw new Error("Provide --from-file <path> or pipe JSON on stdin.");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid JSON input.");
+  }
+}
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process7.stdin.on("data", (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    process7.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    process7.stdin.on("error", reject);
+  });
+}
+function reportAndMaybeExit(argv, result) {
+  if (result.ok) return;
+  if (result.code === "API_SEQUENCE_INVALID" && Array.isArray(result.issues)) {
+    if (wantsJson(argv)) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: false,
+            error: result.error ?? "API sequence configuration is invalid",
+            code: "API_SEQUENCE_INVALID",
+            issueCount: result.issues.length,
+            issues: result.issues
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`Error: ${result.error ?? "API sequence configuration is invalid"}`);
+      console.error(
+        `Found ${result.issues.length} issue${result.issues.length === 1 ? "" : "s"}:`
+      );
+      console.error("");
+      for (const issue of result.issues) {
+        console.error(`  ${issue.path || "(root)"} [${issue.code}] :: ${issue.message}`);
+        if (issue.hint) console.error(`    hint: ${issue.hint}`);
+      }
+      console.error("");
+      console.error(
+        "Re-run with --json for machine-readable output, or fix the listed fields and retry."
+      );
+    }
+    process7.exit(1);
+  }
+  return;
+}
+async function handleWorkflowApiSequence(argv, apiUrl, token) {
+  const [verb, ...rest] = argv;
+  switch (verb) {
+    case "get":
+      await handleGet(rest, apiUrl, token);
+      break;
+    case "update":
+      await handleUpdate(rest, apiUrl, token);
+      break;
+    case "execute":
+    case "run":
+      await handleExecute(rest, apiUrl, token);
+      break;
+    case "delete":
+      await handleDelete(rest, apiUrl, token);
+      break;
+    case "set-api-only":
+      await handleSetApiOnly(rest, apiUrl, token);
+      break;
+    case "generate":
+      await handleWorkflowGenerateApiSequence(rest, apiUrl, token);
+      break;
+    default:
+      printHelp();
+      process7.exit(verb ? 1 : 0);
+  }
+}
+function printHelp() {
+  console.error(
+    [
+      "Usage: canary workflow api-sequence <verb> <workflowId> [options]",
+      "",
+      "Verbs:",
+      "  get <wf>                     fetch the sequence attached to the workflow",
+      "  update <wf> --from-file <f>  replace config (steps, description, exports...)",
+      "  update <wf> --from-stdin     replace config from piped JSON",
+      "  execute <wf>                 run the sequence; returns { runId, status }",
+      "  delete <wf>                  delete the api-sequence record (keeps workflow)",
+      "  set-api-only <wf> [--off]    toggle the workflow's apiOnly flag",
+      "  generate <wf> [--prompt ...] AI-generate a config (streams progress)",
+      "",
+      "Global options:",
+      "  --json                       force JSON output",
+      "  --text                       force pretty-text output (default when stdout is a TTY)",
+      "",
+      "Config shape (for update): { steps: [...], description?, stopOnFailure?, exports? }",
+      'Run "canary workflow guide api-sequences" for step shape and template syntax.'
+    ].join("\n")
+  );
+}
+async function fetchSequenceByWorkflow(apiUrl, token, workflowId) {
+  const res = await apiRequest(
+    apiUrl,
+    token,
+    "GET",
+    `/api-sequences/by-workflow/${workflowId}`
+  );
+  if (!res.ok) {
+    console.error(`Error: ${res.error ?? "Failed to fetch sequence"}`);
+    process7.exit(1);
+  }
+  if (!res.data) {
+    console.error(`Error: Workflow ${workflowId} has no attached API sequence.`);
+    console.error("Create one with: canary workflow create --api-only --name <n> --sequence-from-file seq.json");
+    process7.exit(1);
+  }
+  return res.data;
+}
+async function handleGet(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    printHelp();
+    process7.exit(1);
+  }
+  const seq = await fetchSequenceByWorkflow(apiUrl, token, workflowId);
+  emit(argv, renderSequence(seq), seq);
+}
+async function handleUpdate(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    printHelp();
+    process7.exit(1);
+  }
+  let parsed;
+  try {
+    parsed = await readJsonInput(argv);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process7.exit(1);
+  }
+  const config = parsed;
+  if (!config || !Array.isArray(config.steps)) {
+    console.error('Error: Input must have a "steps" array. Got: ' + JSON.stringify(config));
+    process7.exit(1);
+  }
+  const seq = await fetchSequenceByWorkflow(apiUrl, token, workflowId);
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "PUT",
+    `/api-sequences/${seq.id}/config`,
+    { config }
+  );
+  reportAndMaybeExit(argv, result);
+  if (!result.ok) {
+    console.error(`Error: ${result.error ?? "Update failed"}`);
+    process7.exit(1);
+  }
+  emit(
+    argv,
+    `Updated api-sequence ${seq.id} (workflow ${workflowId}). Steps: ${config.steps.length}.`,
+    result
+  );
+}
+async function handleExecute(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    printHelp();
+    process7.exit(1);
+  }
+  const seq = await fetchSequenceByWorkflow(apiUrl, token, workflowId);
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/api-sequences/${seq.id}/execute`
+  );
+  if (!result.ok || !result.data) {
+    console.error(`Error: ${result.error ?? "Execute failed"}`);
+    process7.exit(1);
+  }
+  emit(
+    argv,
+    `Run started: ${result.data.runId} (status: ${result.data.status})
+Inspect: canary workflow runs get ${workflowId} ${result.data.runId}`,
+    result
+  );
+}
+async function handleDelete(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    printHelp();
+    process7.exit(1);
+  }
+  const seq = await fetchSequenceByWorkflow(apiUrl, token, workflowId);
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "DELETE",
+    `/api-sequences/${seq.id}`
+  );
+  if (!result.ok) {
+    console.error(`Error: ${result.error ?? "Delete failed"}`);
+    process7.exit(1);
+  }
+  emit(argv, `Deleted api-sequence ${seq.id} (workflow ${workflowId}).`, result);
+}
+async function handleSetApiOnly(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    printHelp();
+    process7.exit(1);
+  }
+  const apiOnly = !hasFlag(argv, "--off");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "PUT",
+    `/workflows/${workflowId}/api-only`,
+    { apiOnly }
+  );
+  if (!result.ok) {
+    console.error(`Error: ${result.error ?? "Update failed"}`);
+    process7.exit(1);
+  }
+  emit(argv, `Workflow ${workflowId} apiOnly=${apiOnly}.`, result);
+}
+function renderSequence(seq) {
+  const lines = [];
+  lines.push(`API Sequence ${seq.id}`);
+  lines.push(`  Workflow:    ${seq.workflowId}`);
+  lines.push(`  Status:      ${seq.status}`);
+  if (seq.credentialId) lines.push(`  Credential:  ${seq.credentialId}`);
+  if (seq.config.description) lines.push(`  Description: ${seq.config.description}`);
+  lines.push(`  stopOnFailure: ${seq.config.stopOnFailure ?? false}`);
+  lines.push("");
+  const steps = seq.config.steps ?? [];
+  if (steps.length === 0) {
+    lines.push("  (no steps \u2014 use `api-sequence update` to add)");
+  } else {
+    lines.push(`  Steps (${steps.length}):`);
+    steps.forEach((step, i) => {
+      const method = String(step.method ?? "??").toUpperCase().padEnd(6);
+      const path = step.path ?? "(no path)";
+      const id = step.id ? ` [${step.id}]` : "";
+      lines.push(`    ${String(i + 1).padStart(2)}. ${method} ${path}${id}`);
+      if (step.endpointId) lines.push(`        endpointId: ${step.endpointId}`);
+    });
+  }
+  const exports = seq.config.exports ?? [];
+  if (exports.length > 0) {
+    lines.push("");
+    lines.push(`  Exports: ${JSON.stringify(exports)}`);
+  }
+  return lines.join("\n");
+}
+
+// src/workflow-seed-create.ts
+import fs4 from "fs/promises";
+import process8 from "process";
+function getAllArgValues(argv, flag) {
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === flag && i + 1 < argv.length) {
+      values.push(argv[i + 1]);
+      i++;
+    }
+  }
+  return values;
+}
+function parseOutputFlag(value) {
+  const parts = value.split(":");
+  if (parts.length < 2) {
+    throw new Error(
+      `Invalid --output format: "${value}". Expected "dataKey:Name" or "dataKey:Name:Description".`
+    );
+  }
+  const [dataKey, name, ...descParts] = parts;
+  const description = descParts.length > 0 ? descParts.join(":") : void 0;
+  return {
+    dataKey: dataKey.trim(),
+    name: name.trim(),
+    displayLabel: name.trim(),
+    description: description?.trim() || void 0
+  };
+}
+async function readFromStdin3() {
+  const chunks = [];
+  const stdin = process8.stdin;
+  if (stdin.isTTY) {
+    throw new Error("No input on stdin. Pipe JSON or use --from-file.");
+  }
+  return new Promise((resolve, reject) => {
+    stdin.on("data", (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    stdin.on("error", reject);
+  });
+}
+async function readJsonInput2(argv) {
+  let raw;
+  const fromFile = getArgValue(argv, "--from-file");
+  if (fromFile) {
+    try {
+      raw = await fs4.readFile(fromFile, "utf-8");
+    } catch (err) {
+      throw new Error(`Failed to read file ${fromFile}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    raw = await readFromStdin3();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid JSON input.");
+  }
+  const input = parsed;
+  if (!input.name || typeof input.name !== "string") {
+    throw new Error('JSON input must include a "name" string field.');
+  }
+  if (Array.isArray(input.outputs)) {
+    for (const out of input.outputs) {
+      if (!out.dataKey || !out.name) {
+        throw new Error('Each output must have "dataKey" and "name" fields.');
+      }
+      if (!out.displayLabel) {
+        out.displayLabel = out.name;
+      }
+    }
+  }
+  return input;
+}
+function resolveInput(argv) {
+  const fromFile = getArgValue(argv, "--from-file");
+  const fromStdin = hasFlag(argv, "--from-stdin");
+  if (fromFile || fromStdin) {
+    return readJsonInput2(argv);
+  }
+  const name = getArgValue(argv, "--name");
+  if (!name) {
+    console.error("Error: --name is required (or use --from-stdin / --from-file for JSON input).");
+    console.error("Usage: canary workflow seed create --name <name> [--output key:name[:desc]] ...");
+    process8.exit(1);
+  }
+  const description = getArgValue(argv, "--description");
+  const status = getArgValue(argv, "--status");
+  const outputFlags = getAllArgValues(argv, "--output");
+  const outputs = outputFlags.map(parseOutputFlag);
+  const outputsJsonRaw = getArgValue(argv, "--outputs-json");
+  if (outputsJsonRaw) {
+    try {
+      const parsed = JSON.parse(outputsJsonRaw);
+      if (!Array.isArray(parsed)) throw new Error("not an array");
+      for (const out of parsed) {
+        if (!out.dataKey || !out.name) {
+          throw new Error('Each output must have "dataKey" and "name" fields.');
+        }
+        if (!out.displayLabel) out.displayLabel = out.name;
+      }
+      outputs.push(...parsed);
+    } catch (err) {
+      console.error(`Error: Invalid --outputs-json: ${err instanceof Error ? err.message : String(err)}`);
+      process8.exit(1);
+    }
+  }
+  return { name, description: description || void 0, status, outputs };
+}
+async function handleWorkflowSeedCreate(argv, apiUrl, token) {
+  if (hasFlag(argv, "--help", "-h")) {
+    printSeedCreateHelp();
+    return;
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const noTeardown = hasFlag(argv, "--no-teardown");
+  let input;
+  try {
+    input = await resolveInput(argv);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process8.exit(1);
+  }
+  const seedResult = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    "/workflows",
+    {
+      name: input.name,
+      description: input.description,
+      status: input.status ?? "draft",
+      flowType: "seed",
+      createdVia: "cli"
+    }
+  );
+  if (!seedResult.ok || !seedResult.workflow) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({ ok: false, error: seedResult.error ?? "Failed to create seed workflow" }, null, 2));
+    } else {
+      console.error(`Error: ${seedResult.error ?? "Failed to create seed workflow"}`);
+    }
+    process8.exit(1);
+  }
+  const seedId = seedResult.workflow.id;
+  const appUrl = resolveAppUrl(apiUrl);
+  let outputsSaved = false;
+  if (input.outputs && input.outputs.length > 0) {
+    const outputsResult = await apiRequest(
+      apiUrl,
+      token,
+      "PUT",
+      `/workflows/${seedId}`,
+      { seedOutputsJson: input.outputs }
+    );
+    if (outputsResult.ok) {
+      outputsSaved = true;
+    } else {
+      console.warn(`Warning: Seed created but failed to save outputs: ${outputsResult.error ?? "Unknown error"}`);
+    }
+  }
+  let teardownId;
+  let teardownName;
+  if (!noTeardown) {
+    const tdName = `Teardown: ${input.name}`;
+    const tdResult = await apiRequest(
+      apiUrl,
+      token,
+      "POST",
+      "/workflows",
+      {
+        name: tdName,
+        description: `Cleans up seed data from "${input.name}"`,
+        status: "draft",
+        flowType: "teardown",
+        createdVia: "cli"
+      }
+    );
+    if (tdResult.ok && tdResult.workflow) {
+      teardownId = tdResult.workflow.id;
+      teardownName = tdName;
+      const linkResult = await apiRequest(
+        apiUrl,
+        token,
+        "PUT",
+        `/workflows/${seedId}`,
+        { teardownWorkflowId: teardownId }
+      );
+      if (!linkResult.ok) {
+        console.warn(`Warning: Teardown created but failed to link to seed: ${linkResult.error ?? "Unknown error"}`);
+      }
+    } else {
+      console.warn(`Warning: Failed to create paired teardown: ${tdResult.error ?? "Unknown error"}`);
+    }
+  }
+  if (jsonOutput) {
+    const result = {
+      ok: true,
+      seed: {
+        id: seedId,
+        name: input.name,
+        status: input.status ?? "draft",
+        flowType: "seed",
+        outputs: outputsSaved ? input.outputs : [],
+        url: `${appUrl}/flows/${seedId}`
+      }
+    };
+    if (teardownId) {
+      result.teardown = {
+        id: teardownId,
+        name: teardownName,
+        status: "draft",
+        flowType: "teardown",
+        url: `${appUrl}/flows/${teardownId}`
+      };
+    }
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`
+\u2713 Seed workflow created: ${input.name}`);
+  console.log(`  ID: ${seedId}`);
+  console.log(`  Status: ${input.status ?? "draft"}`);
+  if (input.outputs && input.outputs.length > 0) {
+    const keys = input.outputs.map((o) => o.dataKey).join(", ");
+    console.log(`  Outputs: ${keys}${!outputsSaved ? " (save failed)" : ""}`);
+  }
+  console.log(`  URL: ${appUrl}/flows/${seedId}`);
+  if (teardownId) {
+    console.log(`
+\u2713 Teardown workflow created: ${teardownName}`);
+    console.log(`  ID: ${teardownId}`);
+    console.log(`  URL: ${appUrl}/flows/${teardownId}`);
+  }
+}
+function printSeedCreateHelp() {
+  console.log(
+    [
+      "Usage: canary workflow seed create [options]",
+      "",
+      "Create a seed workflow with declared outputs and an optional paired teardown.",
+      "",
+      "Flag-based input:",
+      "  --name <name>              Seed workflow name (required)",
+      "  --description <desc>       Description",
+      "  --output <key:name[:desc]> Declare an output (repeatable)",
+      "  --outputs-json <json>      Full outputs array as inline JSON (for credential configs)",
+      "  --no-teardown              Skip creating paired teardown workflow",
+      "  --status <status>          Initial status (default: draft)",
+      "  --json                     Output raw JSON",
+      "",
+      "JSON input:",
+      "  --from-stdin               Read full config from stdin",
+      "  --from-file <path>         Read full config from file",
+      "",
+      "Examples:",
+      '  canary workflow seed create --name "Create Project" --output "project_id:Project ID"',
+      "",
+      "  canary workflow seed create --from-stdin <<'EOF'",
+      "  {",
+      '    "name": "Create Test User",',
+      '    "outputs": [{',
+      '      "dataKey": "user_cred",',
+      '      "name": "Test User Credential",',
+      '      "credentialOutput": {',
+      '        "fieldMapping": { "username": "$generate.email", "password": "Test123!" },',
+      '        "emailPrefix": "testuser",',
+      '        "createInboxRecipient": true',
+      "      }",
+      "    }]",
+      "  }",
+      "  EOF"
+    ].join("\n")
+  );
+}
+
+// ../content/src/workflow-guide/overview.txt
+var overview_default = "Workflows are visual test sequences that model user journeys through your application. Each workflow is a directed graph of nodes \u2014 login, navigate, action, assertion, wait, condition, setup, and more \u2014 connected to form a testable path.\n\nWhen to use workflows:\n\n- Critical paths: signup, checkout, billing, onboarding\n- High-risk areas: features that regress often or have complex logic\n- Multi-step journeys: flows spanning multiple pages or user roles\n\nFLOW TYPES\n\n  standard    The default. Models a single user journey end-to-end.\n              Login \u2192 Navigate \u2192 Actions \u2192 Assertions \u2192 Cleanup.\n\n  setup       A prerequisite workflow that runs before other workflows.\n              Use for shared data creation or environment preparation.\n              Any published workflow can be referenced as a setup step.\n\n  seed        A data-seeding workflow that generates test data and exports\n              variables for downstream workflows. Seed outputs are declared\n              in the workflow definition and available as $var.{dataKey}\n              in any workflow that references the seed.\n\n  teardown    A cleanup workflow that runs after a seed workflow completes.\n              Automatically invoked to remove data the seed created.\n\nEXECUTION MODEL\n\n  1. Login node provisions an authenticated browser session\n  2. Nodes execute in sequence (or branch at condition nodes)\n  3. Each action node interacts with the live application\n  4. Assertions verify expected outcomes\n  5. Additional login nodes switch to a different user \u2014 each starts a\n     new segment with a fresh session (great for multi-role testing)\n  6. Wait nodes pause execution (minutes, hours, days) \u2014 also creating\n     segments. After a wait, a login re-establishes the session.\n  7. On completion, the run is marked success or failure\n\nVERSION HISTORY\n\n  Workflows maintain version history. Publishing creates a versioned\n  snapshot. Previous versions can be previewed or restored to draft.\n  Setup nodes reference a specific published version of another workflow.";
+
+// ../content/src/workflow-guide/node-types.txt
+var node_types_default = `Every workflow is built from nodes. Each node has a type, a title, a description,
+and type-specific configuration.
+
+STARTING NODE \u2014 pick the first node in this order
+  The first node of a flow follows a strict hierarchy. Getting this wrong is the
+  single most common authoring mistake (most often: opening with a navigate node).
+
+  1. SEED first \u2014 if the flow depends on pre-existing data, a \`seed\` node comes
+     first. It provisions data in its own isolated context and exports
+     $var.{dataKey} outputs the rest of the flow consumes.
+  2. Otherwise LOGIN first \u2014 for any authenticated flow, the first node is a
+     \`login\` node that declares the ACTOR (who the journey runs as). This is the
+     "acting as" step. Do NOT open an authenticated flow with a navigate node.
+  3. Navigate comes AFTER login \u2014 a navigate jumps to the test's entry point, but
+     it follows the login; it is never the opening node of an authenticated flow.
+
+  The only flows that may start with a navigate are UNauthenticated ones \u2014 signup,
+  password reset, a public/marketing page, or a test of the login experience
+  itself. For those, set the login node's \`performLogin: false\` (or omit the login
+  node) and author the steps as the journey.
+
+  LOGIN SUBSUMES LOGGING IN. A login node already provisions an authenticated
+  session \u2014 it IS the act of logging in. Never emit a login node and then a
+  "navigate to /login" \u2192 "enter email/password" \u2192 "click Sign in" sequence. Start
+  with the login node and go straight to the first real action. The one exception
+  is a flow whose explicit purpose is to test login (start logged out and make the
+  login steps the journey).
+
+LOGIN
+  Sets the user context. Select a credential to act as that user.
+  The login node provisions an authenticated browser session \u2014 subsequent
+  nodes start with the browser already logged in.
+
+  Config:
+    credentialId    UUID of the credential to log in as. REQUIRED for the
+                    node to bind to a real credential. Without it the
+                    Flow Designer shows a red "Select a credential"
+                    warning even if credentialName is set.
+    credentialName  Human-readable name, used as the node title. Optional
+                    but recommended alongside credentialId.
+    performLogin    When true, the browser is authenticated automatically.
+
+  Finding the credentialId:
+    canary credential list [--env prod|dev]
+    \u2192 prints "ID: <uuid>" under each credential name.
+    Pick the ID whose property matches the environment the flow runs in.
+
+  Ordering: login nodes should typically follow any seed nodes, not
+  precede them. Seeds export variables (e.g. $var.workflow_id) that
+  later nodes consume, so a seed-first / login-second order avoids
+  wasted browser segments and lets login/navigate URLs reference
+  seed outputs. See the SEED node type and the Node Ordering section
+  of best-practices.
+
+  - Workflows support multiple login nodes for multi-role testing.
+    Each login node starts a new segment with a fresh browser session.
+    Example: Login as Customer \u2192 place order \u2192 Login as Sales Rep \u2192 verify order.
+    Great for two-sided apps, permission checks (member vs admin), and
+    cross-role journeys.
+  - Login nodes also appear after Wait nodes to re-establish the session.
+  - A navigate node after login is optional but useful for jumping
+    directly to the test's entry point.
+
+NAVIGATE
+  Directs the browser to a specific path.
+
+  Prefer relative paths (e.g. "/flows", "/flows/$var.workflow_id")
+  over hard-coded absolute URLs. Relative paths let the same workflow
+  run unchanged across environments (prod, dev, local, preview) \u2014 the
+  base URL comes from the property/environment the run targets. A
+  workflow that hard-codes "https://app.dev.trycanary.ai/..." will
+  silently drive traffic against dev even when run against prod.
+
+  Use an absolute URL only when the destination is genuinely off the
+  application being tested (external identity provider, third-party
+  checkout, docs site, etc.).
+
+  - A navigate node after login is a great way to jump straight to the
+    page where the test begins.
+  - Select from discovered pages or enter a custom URL.
+
+ACTION
+  Performs a user interaction on the current page. Describe what the user
+  should do ("Create a new ticket") and optionally provide input data via
+  formFields.
+
+  Every action node must have a title (customActionTitle). The title shows
+  in the canvas, run timeline, failure reports, and issue tickets \u2014 an
+  untitled action is nearly impossible to reason about after the fact.
+  Keep titles short and intent-oriented, e.g. "Create a ticket" or
+  "Publish the flow" \u2014 not "Click the button".
+
+  Keep actions focused on a single user goal:
+    Good:  "Create a ticket with required fields"
+    Bad:   "Click the title field" (too granular)
+    Bad:   "Create a ticket, assign it, comment, upload, and verify" (too stuffed)
+
+  Rule of thumb: if an action crosses multiple screens or changes multiple
+  entities, split it. If it's a single user goal on a single screen, keep it.
+
+  Actions can include:
+  - customActionTitle: short intent-oriented title (required)
+  - formFields: input data the action needs (name, email, etc.)
+  - inlineAssertions: checks verified after the action completes (preferred
+    over standalone assertion nodes \u2014 see Assertions section)
+  - declaredOutputs: values to extract from the page for downstream use
+  - customInstructions: additional guidance for the agent executing the step
+
+ASSERTION
+  Verifies expected outcomes. Define a condition to check.
+  The run fails if the condition is not met.
+
+  Prefer inline assertions on action nodes over standalone assertion nodes.
+  Inline assertions keep the test on track and produce cleaner failure
+  reports. If verifying something requires significant interaction first,
+  that's better modeled as an action node with inline assertions.
+
+  Use standalone assertion nodes only when the check doesn't belong to
+  any action \u2014 e.g., verifying a page state after navigation, or
+  confirming data absence after a sequence of steps.
+
+  Severity levels:
+    fail    Critical \u2014 the test stops if this fails
+    warn    Non-critical \u2014 logged but doesn't fail the test
+
+  Agentic assertions: for visual/layout checks that can't be mechanically
+  validated, enable agent evaluation. These require the AI agent during
+  replay and cannot be cached. Use for:
+  - Timestamps or dates
+  - Real-time data feeds
+  - Content that changes between runs
+
+CONDITION
+  Branches the workflow based on a runtime condition. Define a condition
+  to evaluate, then connect separate paths for true and false outcomes.
+
+WAIT
+  Pauses execution for a specified duration (minutes, hours, or days).
+  Creates a segmented flow \u2014 execution pauses, then resumes automatically.
+  Add a Login node after the Wait to re-establish the browser session.
+
+SETUP
+  References another published workflow to run as a prerequisite.
+
+  Execution modes:
+    Inline (default)    Runs before each workflow
+    Suite-level         Runs once per suite, shared across workflows
+
+  When to use: creating users, projects, or records that multiple tests
+  depend on. Login is handled separately \u2014 setup nodes are for data creation.
+
+SEED
+  Injects outputs from a seed workflow as variables. Seed workflows
+  generate test data and export named values. Downstream workflows
+  access these as $var.{dataKey}.
+
+  Ordering: seed nodes should almost always come FIRST \u2014 before the
+  login node. Seeds run in their own isolated context (usually via
+  API sequence) and export variables into the workflow. Placing a
+  login before the seed wastes a browser session, and any
+  login/navigate node that references $var.{seed_output} must come
+  after the seed that produces it.
+
+  Typical pattern:
+    Seed \u2192 Login \u2192 Navigate \u2192 ... action/assertion nodes
+
+  Config:
+    seedWorkflowId    UUID of the seed workflow (required)
+    seedWorkflowName  Human-readable name (used as the node title)
+
+  Seed workflows are the preferred way to provision test data. See the
+  Seed Workflows section for details on building and using them.
+
+API SEQUENCE
+  Executes multiple API calls in sequence without a browser.
+  Use for backend-only operations, webhooks, or API testing.
+
+  API sequences are also used inside seed workflows \u2014 start with a
+  browser-based seed to discover the right API calls, then convert
+  to an API sequence for speed and reliability.
+
+NOTIFICATION
+  Sends notifications (Slack, email, etc.) at a point in the workflow.
+
+END
+  Explicitly terminates the workflow. Use when a condition branch
+  should stop execution rather than continue.`;
+
+// ../content/src/workflow-guide/playbook.txt
+var playbook_default = `A playbook is a sequence of human-readable steps that describe the actions
+taken during a workflow node's execution. Playbooks bridge the gap between
+high-level node descriptions ("Create a ticket") and the low-level browser
+interactions that fulfill them.
+
+WHAT A PLAYBOOK CONTAINS
+
+  Each playbook is an ordered list of PlaybookSteps:
+
+    order             Step sequence number
+    action            What to do: click, fill, fill_form, select, navigate,
+                      wait, scroll, hover, upload, verify, handle_native_dialog,
+                      toggle, press_key, focus, drag, resize, capture,
+                      extract_table, python_execute, verify_download,
+                      verify_download_content, screenshot, agent_loop
+    target            The element or area being acted on
+    params            Key-value parameters for the action
+    note              Human-readable description of the step
+
+  Example playbook for "Create a ticket":
+    1. click      "New Ticket" button
+    2. fill_form  Title: "QA Test \u2014 Billing Bug", Priority: "High"
+    3. click      "Submit" button
+    4. verify     Success toast appears
+
+HOW PLAYBOOKS ENABLE CACHE REPLAY
+
+  When a workflow runs for the first time, the AI agent explores the
+  application, performs actions, and generates a playbook for each node.
+  The raw browser actions (clicks, keystrokes, waits) are cached alongside
+  the playbook steps.
+
+  On subsequent runs, the system uses playbook-step-driven replay:
+
+    1. Load the playbook steps from the node config
+    2. For each step, look up the cached browser actions
+    3. Replay the cached actions directly (no AI agent needed)
+    4. If a step's cache misses or fails, the AI agent heals that step
+
+  This means most runs execute instantly via cache, with the agent only
+  invoked for steps that have changed or broken.
+
+COMPILED ENTRIES
+
+  The cache maps playbook steps to cached action indices:
+
+    cached    Playbook step has matching cached actions \u2014 replayed directly
+    gap       No cache for this step \u2014 agent performs it fresh
+
+  A fully cached node replays in seconds. A node with gaps falls back to
+  agent execution only for the missing steps.
+
+PLAYBOOK HEALTH
+
+  Each cached node tracks playbook health:
+
+    verified    Cache is working correctly across recent runs
+    degraded    Some steps have failures \u2014 cache still used but monitored
+    stale       Cache is no longer reliable \u2014 full agent re-execution needed
+
+  Step-level failure counts track which specific steps break most often,
+  guiding targeted cache healing.
+
+WHY PLAYBOOKS MATTER FOR AUTHORING
+
+  When you build a workflow, the quality of your node descriptions directly
+  affects playbook quality. Clear, intent-focused descriptions produce
+  better playbooks, which produce more reliable cache replay.
+
+  Good: "Create a ticket with title 'QA Test' and priority 'High'"
+    \u2192 Clean playbook: fill_form with clear fields, click submit
+
+  Bad: "Do the thing on the page"
+    \u2192 Vague playbook: agent guesses at actions, cache breaks easily
+
+  The playbook is the semantic contract between your intent and the
+  execution engine. Write nodes that describe what a human would do,
+  and the playbook will faithfully capture and replay it.
+`;
+
+// ../content/src/workflow-guide/best-practices.txt
+var best_practices_default = `SCOPE: ONE COHERENT USER JOURNEY
+
+  A workflow should test one job-to-be-done, not multiple unrelated tasks.
+  Many steps are fine if they're all part of the same flow (creating,
+  editing, verifying one entity). Stop when the goal is accomplished.
+
+  Good \u2014 coherent journey:
+    Login \u2192 Navigate to projects \u2192 Create project \u2192 Edit name \u2192
+    Assert name updated \u2192 Cleanup: delete project
+
+  Good \u2014 multi-role journey:
+    Login as Customer \u2192 Place an order \u2192
+    Login as Sales Rep \u2192 Verify the order appears in the queue
+
+  Good \u2014 read-only flow:
+    Login \u2192 Navigate to dashboard \u2192 Assert widgets visible
+
+  Bad \u2014 multiple unrelated journeys:
+    Dashboard \u2192 Create item \u2192 Manage users \u2192 Generate report
+    (These are separate jobs \u2014 create separate workflows)
+
+  Rule: "Is this step dependent on or naturally connected to the previous
+  steps?" If no, you're starting a new journey \u2014 stop.
+
+WRITE STEPS AS HUMAN INTENT
+
+  A workflow should read like instructions you'd explain to a teammate:
+    - "Create a ticket assigned to Support."
+    - "Submit the ticket and confirm it appears in the list."
+    - "Change the ticket status to Closed."
+
+  Capture the "why" and the "what" \u2014 not UI mechanics.
+
+CHOOSE THE RIGHT GRANULARITY
+
+  Too granular:
+    - "Click New"
+    - "Type title"
+    - "Type description"
+    - "Click Save"
+
+  Too stuffed:
+    - "Create a ticket, assign it, comment, upload, and verify in three views"
+
+  Good:
+    - "Create a ticket with required fields"
+    - "Assign the ticket to Support"
+    - "Verify the ticket appears in the queue"
+
+  If an action crosses multiple screens or changes multiple entities, split it.
+  If it's a single user goal on a single screen, keep it as one action.
+
+MAKE EACH TEST SELF-SUFFICIENT
+
+  Tests should not depend on what another test created or on long-lived
+  shared state. If a workflow needs data, provision it:
+
+  - Use a seed workflow (preferred) to generate data and export variables
+  - Use a setup node to reference a published workflow for shared data
+  - As a last resort, add data creation steps at the start of the workflow
+  - Always use macros ($EMAIL, $UUID, etc.) so reruns don't collide
+
+  This keeps runs deterministic and prevents cascading failures.
+
+VERIFY EVERY SIGNIFICANT ACTION
+
+  Before recording a step, verify it worked:
+
+  - Form submissions: confirm acceptance (success message, redirect, new item in list)
+  - Data creation: navigate to where the record should appear and confirm
+  - Data modification: reload and confirm the change persisted
+  - Deletions: confirm the item is gone (a toast alone is not enough)
+  - Navigation: confirm the expected page loaded
+
+  If verification fails, debug the issue \u2014 don't record and move on.
+
+KEEP DESCRIPTIONS CLEAR
+
+  Node titles should be short and action-oriented:
+    Good: "Create a support ticket"
+    Bad:  "Step 3 - ticket creation process"
+
+  Node descriptions should add detail the title can't carry:
+    Good: "Fill the form with a QA Test subject and High priority, then submit"
+    Bad:  "Do the thing"
+
+NODE ORDERING
+
+  The start-of-workflow order is a strict hierarchy (see "STARTING NODE"
+  in the Node Types guide):
+
+    Seed (if needed) \u2192 Login \u2192 Navigate \u2192 ...
+
+  The first node is the ACTOR, not a navigate: an authenticated flow opens
+  with a \`login\` node (or a \`seed\`, if it needs data first) \u2014 never with a
+  navigate node. A navigate jumps to the test's entry point AFTER login.
+  Only unauthenticated flows (signup, password reset, public pages, or a
+  login test) may start with a navigate.
+
+  Seed nodes should come first. Seeds run in their own isolated context
+  (usually via API sequence) and export variables the rest of the flow
+  consumes. Putting a login before the seed wastes a browser segment,
+  and any login/navigate that references $var.{seed_output} must come
+  after the seed that produced it.
+
+  Only skip the seed-first rule if the seed itself genuinely depends on
+  a browser session created earlier in the same workflow (rare \u2014 in
+  that case, prefer a separate browser-based seed workflow and reference
+  it here).
+
+LOGIN BEST PRACTICES
+
+  - Most workflows start with a login node. Workflows can also start
+    with a seed node or API sequence when no browser session is needed yet.
+  - Login SUBSUMES logging in. A login node already provisions an
+    authenticated session \u2014 it IS the act of logging in. Never follow a
+    login node with "navigate to /login" / "enter email + password" /
+    "click Sign in" steps. Start with the login node and go straight to
+    the first real action. (Only exception: a flow whose purpose is to
+    test login \u2014 start logged out and make the login steps the journey.)
+  - Login nodes require a credentialId (UUID), not just a credentialName.
+    Without a credentialId the Flow Designer flags the node as invalid.
+    Find credential IDs with:   canary credential list [--env prod|dev]
+  - Use multiple login nodes for multi-role testing \u2014 each login starts
+    a new segment with a fresh session as that user
+  - Don't test login itself (unless that's the explicit goal)
+  - A navigate node after login is a great way to jump directly to the
+    test's entry point
+
+PREFER INLINE ASSERTIONS
+
+  Attach assertions to action nodes using inlineAssertions rather than
+  adding standalone assertion nodes. Inline assertions keep the test
+  focused and produce clearer failure reports. See the Assertions section
+  for details.`;
+
+// ../content/src/workflow-guide/macros.txt
+var macros_default = `Macros generate fresh, unique data every time a workflow runs. Variables let
+you reference shared values across nodes. Both use the $ prefix.
+
+AVAILABLE MACROS
+
+  $EMAIL()              Unique test email        test-a1b2@example-test.com
+  $FIRST_NAME()         Random first name        Jordan
+  $LAST_NAME()          Random last name         Chen
+  $PHONE()              Random US phone          +1-555-382-7491
+  $UUID()               Random UUID v4           a1b2c3d4-e5f6-...
+  $NOW()                ISO 8601 timestamp       2026-02-19T14:30:00.000Z
+  $TODAY()              Current date             2026-02-19
+  $DATE(N)              Date offset by N days    $DATE(7) = next week
+  $TIMESTAMP()          Unix timestamp (ms)      1771520400000
+  $RANDOM_INT(min,max)  Random integer           $RANDOM_INT(1,100) = 42
+  $RANDOM_STRING(len)   Random alphanumeric      $RANDOM_STRING(6) = xK9mQ4
+  $SEQUENCE(name)       Auto-incrementing        $SEQUENCE(order) = 1, 2, 3...
+
+SYNTAX
+
+  Macros follow the format $MACRO_NAME() or $MACRO_NAME(args).
+  They can appear standalone or inline within a larger string:
+
+    Standalone:  $EMAIL()
+    Inline:      user-$UUID()@corp.com
+    Escaped:     \\$EMAIL() produces the literal text $EMAIL()
+
+  Each run resolves macros independently \u2014 every execution gets fresh values.
+
+VARIABLES
+
+  Variables reference values set during a workflow run. When an action has
+  input fields or extracts data, those become $var.{name} references.
+
+  Sources:
+    Input         A value entered in an action's field      $var.company
+    Macro         A macro expression in a field             $var.email
+    Extracted     Data extracted from the page              $var.order_id
+    Credential    Values from the login credential          $var.username
+
+  Use $var.{name} in subsequent step formFields and descriptions.
+  Don't re-hardcode values \u2014 reference the variable from the earlier step.
+
+HOW VARIABLES GET BOUND
+
+  Two distinct paths create $var.{name} bindings. Picking the wrong one is a
+  common foot-gun.
+
+  1. Typed input (auto-promote)
+
+     Add an entry to inputValues on an action node:
+
+       inputValues: { company: "$RANDOM_STRING(8)" }
+
+     The key "company" auto-promotes to $var.company for every downstream
+     node. Do NOT also list it in declaredOutputs \u2014 the input itself IS the
+     binding.
+
+  2. DOM capture (declaredOutputs + playbook capture)
+
+     For values that only exist after the page renders (URL fragment, badge
+     text, generated ID in the breadcrumb), declare them upfront and capture
+     them inside the playbook:
+
+       declaredOutputs: ["order_id"]
+       playbookSteps: [
+         { order: N, action: "capture", target: "<selector or rule>",
+           outputKey: "order_id" }
+       ]
+
+     The capture step writes into $var.order_id at runtime. Without
+     declaredOutputs the downstream resolver won't recognize the binding.
+
+  Rule of thumb: if you can type the value into a field before the run, it's
+  an input. If the value only exists after something happens in the browser,
+  it's a captured output.
+
+SEED VARIABLES
+
+  When seed workflows are configured, their outputs are available as
+  $var.{dataKey} references. If a seed provides data you need (a project ID,
+  a user record), use the seed variable \u2014 don't create that data again.
+
+COMMON PATTERNS
+
+  Unique user registration:
+    Email: $EMAIL()
+    Name: $FIRST_NAME() $LAST_NAME()
+
+  Numbered items:
+    $SEQUENCE("orders") \u2192 1, 2, 3... (resets each run, independent per name)
+
+  Date-relative testing:
+    $DATE(30) for 30 days out, $DATE(-7) for last week, $TODAY() for now
+
+  Unique identifiers:
+    $UUID() for globally unique, $RANDOM_STRING(8) for shorter strings
+    Combine with text: order-$RANDOM_STRING(6)
+
+BEST PRACTICES
+
+  - Use $EMAIL() instead of hardcoded addresses for uniqueness
+  - Use $SEQUENCE("name") when you need predictable ordering within a run
+  - Prefer $DATE(days) over fixed dates so tests stay valid over time
+  - Always include a value for every formField \u2014 don't leave fields empty`;
+
+// ../content/src/workflow-guide/seed-workflows.txt
+var seed_workflows_default = `Seed workflows are the preferred way to provision test data. A seed
+workflow creates data your test needs and exports named variables that
+downstream workflows can reference.
+
+WHY USE SEEDS
+
+  - Reusable: one seed can serve many test workflows
+  - Fast: seeds can use API sequences instead of slow browser interactions
+  - Clean: paired teardown workflows handle cleanup automatically
+  - Isolated: each run gets its own fresh data via macros
+
+HOW SEEDS WORK
+
+  1. Create a workflow with flowType "seed"
+  2. Define seedOutputs \u2014 the named values the seed exports
+     (e.g., project_id, user_email, order_number)
+  3. The seed creates data and captures those values during execution
+  4. Downstream workflows add a Seed node that references this seed
+  5. The seed's outputs are available as $var.{dataKey} in the test
+
+  Example:
+    Seed "Create Test Project" exports: project_id, project_name
+    Test workflow references the seed, then uses:
+      Navigate to $var.project_id
+      Assert page title contains $var.project_name
+
+CREATING SEEDS
+
+  A seed workflow shell needs a name, declared outputs, and usually a paired
+  teardown. Outputs are the contract downstream workflows depend on; define
+  them before building the seed body so every node captures the right values.
+
+  Simple data outputs need:
+    - dataKey: stable variable name, used as $var.{dataKey}
+    - name: human label
+    - description: optional context for builders and reviewers
+
+  Credential outputs additionally define credentialOutput, including provider
+  type, generated field mapping, inbox behavior, and loginUrl.
+
+  After creating the shell, add nodes through the Flow Designer, workflow sync,
+  or API, then publish once the seed and paired teardown both pass.
+
+  CLI users: see \`canary workflow guide cli-seeds\` for command usage.
+
+BUILDING A SEED: START WITH THE BROWSER
+
+  The easiest way to build a seed is to start with browser-based steps:
+
+  1. Create a seed workflow (flowType: seed)
+  2. Add a login node with credentials that have permission to create data
+  3. Add action nodes that create the data through the UI
+     - Use macros for all names and identifiers ($EMAIL, $RANDOM_STRING, etc.)
+  4. Add declaredOutputs on action nodes to capture generated values
+     (IDs, URLs, confirmation numbers)
+  5. Define seedOutputs on the workflow to export those captured values
+  6. Test and publish the seed
+
+  This approach lets you discover exactly what steps and data are needed
+  by interacting with the real application.
+
+CONVERTING TO API SEQUENCES
+
+  Once a browser-based seed works reliably, convert it to an API sequence
+  for speed and reliability. Canary can do this automatically.
+
+  Auto-conversion from a workflow run:
+    1. Open the seed workflow in the Flow Designer
+    2. Add an api_sequence node
+    3. In the node config, choose "Generate from workflow run"
+    4. Select a completed run of the browser-based seed
+    5. The AI agent analyzes the network requests captured during
+       that run and generates an equivalent API sequence automatically
+    6. The agent tests each step against the live API to verify it works
+    7. Review the generated sequence and publish
+
+  The AI agent has access to your application's API catalog and can:
+    - Search for endpoints by keyword
+    - Inspect request/response schemas
+    - Test individual API calls to verify they work
+    - Compose a multi-step sequence with variable passing between steps
+    - Validate the full sequence end-to-end before finalizing
+
+  You can also generate an API sequence from a prompt \u2014 describe what
+  data to create and the agent will find the right endpoints and build
+  the sequence.
+
+  API sequences support two kinds of dynamic values:
+    - Step references: {{stepId.response.path.to.value}} to pass data
+      between steps (e.g., use the project ID from step 1 in step 2)
+    - Macros: $EMAIL(), $UUID(), $RANDOM_STRING(), etc. for fresh
+      unique data each run
+
+  Exports map response fields to seed output variables:
+    - stepId: which step to extract from
+    - responsePath: dot notation path (e.g., "data.id")
+    - variableName: the $var.{name} downstream workflows will use
+
+EXECUTION MODES
+
+  Seeds automatically choose the best execution mode:
+
+    browser       Runs through the browser like a normal workflow
+    api           Runs the API sequence directly \u2014 no browser needed
+    recommended   Uses the API sequence if one exists, otherwise browser
+
+  Once you've added an API sequence to a seed, it will automatically
+  run via API \u2014 faster, cheaper, and more reliable than browser execution.
+
+  Not all seeds can be converted \u2014 some data creation flows require
+  browser interaction (file uploads, complex wizards, third-party
+  integrations). Keep those as browser-based seeds.
+
+API CALL TIMEOUT
+
+  When a seed runs in API mode (executionMode "api", or "recommended"
+  resolving to API), each HTTP call uses a 2-minute (120s) timeout by
+  default. Seeds/teardowns that hit slow provisioning endpoints can raise
+  this per seed node via apiTimeoutSeconds \u2014 it applies to both the seed
+  and its paired teardown. Ignored for browser-mode seeds.
+
+  Set it three equivalent ways:
+    - Flow Designer: the "API call timeout (seconds)" field on the Seed node
+    - .canary.md: a "- apiTimeoutSeconds: 300" bullet under the Seed node
+    - workflow JSON (create / sync): on the seed node's configJson, e.g.
+        { "nodeType": "seed",
+          "configJson": { "seedExecutionMode": "api", "apiTimeoutSeconds": 300 } }
+
+  Leave it unset to keep the 120s default; an invalid value falls back to
+  the default rather than erroring.
+
+TEARDOWN WORKFLOWS
+
+  Every seed can have a paired teardown workflow that cleans up the
+  data it created. Teardowns run automatically after the seed's
+  downstream workflows complete.
+
+  - Set flowType to "teardown" and link it to the seed
+  - The teardown receives the same $var.{dataKey} variables the seed exported
+  - Use those variables to find and delete the created data
+
+  Teardowns are the cleanest way to handle cleanup \u2014 they keep cleanup
+  logic separate from test logic and run automatically.
+
+SEED BEST PRACTICES
+
+  - Use macros in all created data ($EMAIL, $RANDOM_STRING, etc.)
+    so each run gets unique, non-conflicting data
+  - Keep seeds focused \u2014 one seed per logical dataset
+    (e.g., "Create Project with Members" not "Create Everything")
+  - Export only what downstream workflows need \u2014 don't over-export
+  - Start with browser-based seeds, then use auto-conversion to generate
+    an API sequence from a completed run
+  - Pair seeds with teardown workflows for automatic cleanup
+  - Use suite-level setup nodes to share seed data across multiple
+    workflows in the same test suite
+`;
+
+// ../content/src/workflow-guide/data-lifecycle.txt
+var data_lifecycle_default = `Test data discipline keeps workflows reliable and concurrent-safe.
+
+PREFER SEED WORKFLOWS FOR DATA
+
+  Seed workflows are the best way to provision test data. They run before
+  your test workflow, create the data it needs, and export variables that
+  downstream workflows can reference as $var.{dataKey}.
+
+  Benefits of seeds over inline data creation:
+  - Reusable across multiple workflows
+  - Faster \u2014 can use API sequences instead of browser interactions
+  - Cleaner separation of setup and test logic
+  - Paired teardown workflows handle cleanup automatically
+
+  See the Seed Workflows section for how to build and use them.
+
+THE DATA OWNERSHIP PRINCIPLE
+
+  Own your data:
+  - Data you create \u2192 clean it up when the workflow finishes
+  - Settings you modify \u2192 revert them when the workflow finishes
+  - Data that was already there \u2192 never delete it
+
+  It's fine to depend on pre-existing data (existing integrations, org
+  settings, reference data). Only create what doesn't already exist or
+  what the test specifically needs to own.
+
+CREATING TEST DATA
+
+  If the test operates on a record (edit, delete, archive), create that
+  record as an early step \u2014 unless it already exists and the test is meant
+  to operate on it.
+
+  Never reference "any" resource:
+    Bad:   "Pick a project from the list" (which one? may not exist)
+    Good:  "Create a project named 'QA Test \u2014 $RANDOM_STRING(6)'"
+    Good:  "Use the seed output $var.project_id"
+
+  Always use macros in names to ensure uniqueness across parallel runs:
+    Bad:   "Test Item" (generic, will collide with other runs)
+    Bad:   "QA Test Project" (still collides if two runs overlap)
+    Good:  "QA Test \u2014 $RANDOM_STRING(6)" (unique every run)
+    Good:  "QA Test $FIRST_NAME() $LAST_NAME()" (unique and readable)
+
+  After creating data, verify it exists before continuing.
+
+NAMING CONVENTION
+
+  All test data should follow this pattern:
+
+    Name/Title:    "QA Test $FIRST_NAME() $LAST_NAME()"
+    Email:         "$EMAIL()"
+    Phone:         "$PHONE()"
+    Project/Item:  "QA Test \u2014 $RANDOM_STRING(6)"
+    Unique ID:     "QA$TIMESTAMP()"
+
+  The "QA Test" prefix makes test data instantly recognizable. The macro
+  suffix ensures every run creates unique data that won't collide with
+  other runs or leftover data from previous executions.
+
+CLEANING UP (STRONGLY RECOMMENDED)
+
+  Workflows that create data should include cleanup steps at the end.
+  Workflows that modify settings should revert them.
+
+  This isn't strictly required, but it's strongly recommended:
+  - Cleanup prevents data accumulation over time
+  - It keeps the test environment clean for other workflows
+  - The "QA Test" naming convention makes orphaned data identifiable
+    even when cleanup is skipped or fails
+
+  Don't over-engineer cleanup \u2014 a simple "navigate to the item and
+  delete it" is sufficient. For seed workflows, use a paired teardown
+  workflow instead.
+
+WHAT NOT TO TOUCH
+
+  - Don't create users, roles, or org-level config unless that's the goal
+  - Don't modify shared resources (billing, integrations, API keys) as a side effect
+  - Don't delete or modify data not owned by this workflow
+
+AVOIDING COLLISIONS WITH MACROS
+
+  The best way to avoid data collisions is to use macros for every
+  name, email, and identifier. When every run generates unique values,
+  there's no risk of conflicting with parallel runs or leftover data:
+
+    $EMAIL()            Unique email every run
+    $RANDOM_STRING(6)   Short unique suffix for names
+    $UUID()             Globally unique identifier
+    $TIMESTAMP()        Unique-per-millisecond numeric ID
+
+  Combined with the "QA Test" prefix, this means you never need to
+  worry about whether data from a previous run still exists. Each run
+  creates its own isolated dataset.
+
+READ-ONLY FLOWS
+
+  Workflows that only read data (verify dashboard loads, check reports)
+  don't need creation or cleanup steps. Not every workflow needs to
+  create data \u2014 only create what the test specifically requires.`;
+
+// ../content/src/workflow-guide/assertions.txt
+var assertions_default = `Assertions verify that the application behaves as expected. There are two
+ways to add assertions: inline on action nodes, or as standalone assertion
+nodes. Inline assertions are strongly preferred.
+
+INLINE ASSERTIONS (PREFERRED)
+
+  Attach assertions directly to action nodes using the inlineAssertions
+  field. These are verified immediately after the action completes and
+  cached for fast replay.
+
+  Inline assertions are the best way to verify outcomes because they:
+  - Keep the test on track \u2014 verification happens right where the action is
+  - Produce clean failure reports \u2014 each assertion is tied to the step that caused it
+  - Are cacheable \u2014 fast replay on subsequent runs
+
+  Example \u2014 after submitting a form:
+    Action: "Submit the support ticket"
+    Inline assertions:
+      - "Success toast appears" (severity: warn)
+      - "Form is no longer visible" (severity: fail)
+
+  Severity levels:
+    fail    Critical \u2014 the test stops if this fails.
+            Use for: data saved, redirect happened, error absent.
+    warn    Non-critical \u2014 logged but doesn't fail the test.
+            Use for: toast appeared, animation completed.
+
+  If verifying something requires significant interaction (scrolling,
+  navigating, expanding sections), model that as an action node with
+  inline assertions \u2014 not a detailed standalone assertion node.
+
+STANDALONE ASSERTION NODES (USE SPARINGLY)
+
+  Use dedicated assertion nodes only when the check doesn't belong to
+  any action:
+
+  - Verifying a final page state after navigation (no action to attach to)
+  - Checking that data was NOT modified (absence checks after a sequence)
+  - Confirming a state visible only after a wait or page transition
+
+  A typical workflow has 0-1 standalone assertion nodes. If you find
+  yourself writing a complex assertion node that requires multiple steps
+  to verify, consider whether it should be an action node with inline
+  assertions instead.
+
+AGENTIC ASSERTIONS
+
+  For visual or layout checks that can't be mechanically validated,
+  enable agent evaluation. These require the AI agent during replay
+  and cannot be cached.
+
+  Use for:
+  - Screenshots that should "look correct"
+  - Charts or graphs rendering properly
+  - Dynamic content that changes between runs
+  - Timestamps or real-time data
+
+  Standard assertions are preferred \u2014 only use agentic when the
+  check is inherently subjective or dynamic.
+
+WRITING GOOD CONDITIONS
+
+  Assertions must be specific and observable:
+
+  Good:
+    - "The status badge shows 'Active'"
+    - "The table contains a row with name 'Test Record'"
+    - "Error message is not visible"
+    - "The page title is 'Dashboard'"
+
+  Bad:
+    - "The page looks correct"
+    - "The action was successful"
+    - "Everything works"
+
+  Start with what's observable: "The page displays...", "The table
+  contains...", "The field shows...". Include the specific value
+  you expect.
+
+ASSERTION PLACEMENT
+
+  Place assertions at critical verification points:
+
+  1. After data creation: verify the record exists (inline on the create action)
+  2. After data modification: verify the change persisted (inline on the edit action)
+  3. After deletion: verify the item is gone (inline on the delete action)
+  4. At the goal completion point: verify the journey succeeded
+
+  Don't assert everything \u2014 focus on the claims that matter.
+  A focused assertion that proves the test's core claim is better
+  than a dozen checks on every UI element.`;
+
+// ../content/src/workflow-guide/api-sequences.txt
+var api_sequences_default = 'API Sequences are the API-only counterpart to browser workflows. Instead of\ndriving a browser node-by-node, an API sequence is a single node\n(nodeType: "api_sequence") inside an api-only workflow that executes an\nordered list of HTTP calls, chaining outputs from one step into the inputs\nof the next.\n\nWHEN TO USE\n\n  - Exercise an API without a UI (integration tests, fixture setup).\n  - Seed or tear down state via API before/after a browser run.\n  - Fast, deterministic smoke test of a critical flow.\n\nCONFIG SHAPE (ApiSequenceConfig)\n\n  {\n    "steps":         [ ... ],       // ordered; required\n    "description":   "...",         // optional\n    "stopOnFailure": true,          // default: true\n    "exports":       [ ... ]        // optional; see below\n  }\n\nSTEP SHAPE (ApiSequenceStep)\n\n  The authoritative type is in packages/types/src/api-sequence.ts. Key fields:\n\n  {\n    "stepId":         "createProject",      // optional; defaults to "step{index}"\n    "apiRequestId":   "<catalog id>",       // required \u2014 points to api_requests row\n    "credentialId":   "<uuid>" | null,      // null = unauthenticated\n    "method":         "POST",               // optional; falls back to catalog default\n    "urlTemplate":    "/projects/{{createProject.response.id}}",\n    "queryParams":    [ { "key": "limit", "value": "10" } ],\n    "bodyTemplate":   "{\\"name\\": \\"$EMAIL()\\"}",   // STRING (JSON), not object\n    "headersTemplate": { "X-Trace": "$UUID()" },    // optional\n    "responseVariableName": "createProject",         // optional alias for stepId\n    "expectedStatusCodes":  [200, 201],             // step fails if status is outside\n    "description":    "...",                        // optional UI label\n    "validations":    [ ... ]                       // assertions against the response\n  }\n\n  CREDENTIAL ROLES \u2014 `credentialId` is overloaded; two distinct uses exist:\n\n    - Step-level `credentialId` (and a top-level/default credential on the\n      sequence) is AUTH: it\'s what the api-sequence runner uses to\n      authenticate each HTTP call. Editing this changes who is calling.\n\n    - `credentialId` appearing INSIDE a step\'s `bodyTemplate` JSON string is\n      DATA: it gets written into the request body and becomes part of the\n      provisioned resource (e.g. the credential a created workflow logs in\n      with). Editing this changes what the call creates.\n\n    The two are independent. Swapping the auth credential won\'t change what\n    the call provisions; swapping the body credential won\'t change auth.\n    Mixing them up silently produces confusing test failures.\n\n  `apiRequestId` references a row in the `api_requests` table. Discover IDs\n  from the API catalog for the target property. If `urlTemplate`, `method`,\n  or `bodyTemplate` are omitted, they are backfilled from the catalog entry\'s\n  defaults at execution time.\n\n  `bodyTemplate` is a JSON *string*, not a JSON object \u2014 templates and macros\n  are interpolated into it as raw text before parsing.\n\nTEMPLATE SYNTAX\n\n  Three ways to inject dynamic values. All three can appear in the same\n  string (urlTemplate, bodyTemplate, headersTemplate values, or queryParams\n  values).\n\n  1. STEP REFERENCES \u2014 outputs of prior steps.\n\n       {{stepId.response.path.to.value}}\n\n     The `.response.` segment is REQUIRED. This is the most common foot-gun:\n\n       \u2713 {{createProject.response.data.id}}\n       \u2717 {{createProject.data.id}}       \u2014 missing .response., will warn at\n                                           runtime and resolve to undefined\n       \u2717 {{projectId}}                   \u2014 no step reference at all\n\n     The executor logs a warning for malformed references but does NOT\n     block execution \u2014 a malformed template resolves to an empty string and\n     the request goes out anyway. Always run once and check the run log.\n\n  2. MACROS \u2014 dynamic data generated fresh per run.\n\n       $UUID()                 Random UUID v4\n       $NOW()                  ISO 8601 timestamp (UTC)\n       $TODAY()                YYYY-MM-DD\n       $DATE(N)                Date offset by N days\n       $TIMESTAMP()            Unix ms\n       $RANDOM_INT(min,max)    Random integer in range\n       $RANDOM_STRING(N)       Alphanumeric string of length N\n       $EMAIL()                test-<rand>@example-test.com\n       $FIRST_NAME()           Random first name\n       $LAST_NAME()            Random last name\n       $PHONE()                +1-555-...\n       $SEQUENCE("name")       Per-run auto-increment counter\n\n     Each run resolves macros independently. $SEQUENCE counters persist\n     across steps within a single run.\n\n  3. WORKFLOW VARIABLES \u2014 values injected by the workflow runtime.\n\n       $var.<name>\n\n     These come from two places:\n\n       a) Upstream credential variables \u2014 pre-provisioned before the\n          sequence runs. Typical names: `$var.credential.username`,\n          `$var.credential.password`, `$var.credential.email`. If the\n          workflow has a credential, USE these for the matching fields\n          instead of `$EMAIL()` / `$RANDOM_STRING()` \u2014 the values must\n          match the already-provisioned account.\n\n       b) Upstream exports \u2014 values exported by earlier nodes in the same\n          workflow (e.g. a seed step produced `$var.project_id`).\n\n     Naming convention for exported variables: `resource_field` with\n     underscores (e.g. `project_id`, `user_email`).\n\nEXPORTS\n\n  After all steps finish, the sequence can register values from the final\n  state into the workflow variable registry for downstream nodes:\n\n  {\n    "exports": [\n      {\n        "variableName": "project_id",        // appears as $var.project_id\n        "stepId":       "createProject",\n        "responsePath": "data.id",\n        "source":       "response",           // "response" (default) | "request"\n        "description":  "..."                 // optional UI label\n      }\n    ]\n  }\n\n  Only export fields downstream nodes actually need. Use the\n  `resource_field` naming convention.\n\nVALIDATIONS\n\n  Per-step assertions against the response. Each validation:\n\n  {\n    "left":     "createProject.response.data.status",  // "stepId.path" form\n    "operator": "equals",                              // see list\n    "right":    "active",                              // omit for is_set/is_not_set\n    "description": "..."\n  }\n\n  Operators: equals, not_equals, gt, lt, gte, lte, contains, not_contains,\n  is_set, is_not_set.\n\nWHAT IS VALIDATED AT COMMIT TIME\n\n  Very little. The save endpoint accepts anything matching\n  { steps: any[], description?, stopOnFailure?, exports? }. It does NOT\n  verify that apiRequestId exists in the catalog, that stepIds are unique,\n  that {{stepId.response.path}} references a real step, that exports\'\n  stepId resolves, or that macro names are known.\n\n  The only template sanity check is `validateStepTemplates()` in\n  apps/api/src/workflows/execution/api-sequence-executor.ts, which runs\n  at EXECUTE time, only flags `{{stepId.X}}` missing `.response.`, and only\n  LOGS A WARNING \u2014 the sequence still runs. Always smoke-test the sequence\n  before committing it to a workflow.\n\n  CLI users: see `canary workflow guide cli-api-sequences` for command usage.\n\nEXAMPLE (3-step sequence, correct shape)\n\n  {\n    "description": "Create an item, fetch it, delete it",\n    "stopOnFailure": true,\n    "steps": [\n      {\n        "stepId":       "create",\n        "apiRequestId": "<POST /items id>",\n        "credentialId": null,\n        "method":       "POST",\n        "bodyTemplate": "{\\"name\\": \\"item-$RANDOM_STRING(6)\\"}",\n        "expectedStatusCodes": [201]\n      },\n      {\n        "stepId":       "fetch",\n        "apiRequestId": "<GET /items/:id id>",\n        "credentialId": null,\n        "method":       "GET",\n        "urlTemplate":  "/items/{{create.response.id}}",\n        "expectedStatusCodes": [200],\n        "validations": [\n          { "left": "fetch.response.name", "operator": "is_set" }\n        ]\n      },\n      {\n        "stepId":       "remove",\n        "apiRequestId": "<DELETE /items/:id id>",\n        "credentialId": null,\n        "method":       "DELETE",\n        "urlTemplate":  "/items/{{create.response.id}}",\n        "expectedStatusCodes": [200, 204]\n      }\n    ],\n    "exports": [\n      { "variableName": "item_id", "stepId": "create", "responsePath": "id" }\n    ]\n  }\n\nTIPS\n\n  - Give every step a short, stable `stepId`. Later steps and exports\n    reference it; the default `stepN` label is brittle to reordering.\n  - Always include `.response.` in step references. The runtime won\'t\n    error out, but values will silently resolve to empty strings.\n  - Prefer `$EMAIL()`, `$UUID()`, `$RANDOM_STRING()` for fields that must\n    be unique per run \u2014 unless the workflow has an upstream credential,\n    in which case use `$var.credential.username` / `.password` / `.email`.\n  - Set `expectedStatusCodes` on every step so unexpected 4xx/5xx fails\n    the step instead of silently flowing into the next template.\n  - `bodyTemplate` is a JSON STRING. Escape inner quotes.\n  - `workflow api-sequence generate` can AI-draft a config from a prompt\n    or a prior browser run; refine with `update`. The generated output is\n    just JSON \u2014 review it before committing.\n';
+
+// ../content/src/workflow-guide/cli-seeds.txt
+var cli_seeds_default = 'Use this section when you need to create or inspect seed workflows from the\nCanary CLI. The conceptual model lives in `seed-workflows`; this section is\nonly command orientation. Prefer each command\'s `--help` output for the\ncurrent flag list.\n\nCREATE A SIMPLE SEED SHELL\n\n  For simple data outputs, create the seed shell with repeatable output\n  declarations:\n\n    canary workflow seed create \\\n      --name "Create Test Project" \\\n      --description "Provisions a test project with default settings" \\\n      --output "project_id:Project ID:The created project\'s UUID" \\\n      --output "project_name:Project Name"\n\n  This creates a draft seed workflow and, by default, a paired teardown\n  workflow linked to the seed.\n\nCREATE A COMPLEX SEED SHELL\n\n  For credential outputs or larger configs, put the full seed definition in a\n  JSON file and create from that file:\n\n    canary workflow seed create --from-file seed.json\n\n  Keep generated credential fields in credentialOutput, and keep exported data\n  fields in outputs. Downstream workflows consume both through $var.{dataKey}.\n\nAFTER CREATION\n\n  Add the seed body through the Flow Designer or workflow sync, test both the\n  seed and teardown, then publish. If the seed can be API-backed, generate or\n  attach an API sequence after the browser version is proven.\n\nREFERENCE\n\n  - Seed command help: `canary workflow seed --help`\n  - Workflow sync help: `canary workflow sync --help`\n';
+
+// ../content/src/workflow-guide/cli-api-sequences.txt
+var cli_api_sequences_default = 'Use this section when you need to drive API sequence authoring from the\nCanary CLI. The conceptual model lives in `api-sequences`; this section is\nonly command orientation. Prefer each command\'s `--help` output for the\ncurrent flag list.\n\nCOMMON FLOW\n\n  1. Inspect the API catalog for candidate endpoints.\n\n       canary api-catalog sources list\n       canary api-catalog endpoints list --search <keyword>\n       canary api-catalog endpoints get <apiRequestId>\n\n  2. Compose a sequence JSON file locally. Reference endpoints by\n     apiRequestId and chain steps with {{stepId.response.path}}.\n\n  3. Create an API-only workflow from the sequence file.\n\n       canary workflow create --api-only --name "smoke: create project" \\\n         --sequence-from-file seq.json\n\n     The command returns the workflow, sequence, and node IDs.\n\n  4. Execute immediately to surface template warnings and API failures.\n\n       canary workflow api-sequence execute <workflowId>\n\n  5. Inspect the run and iterate on the sequence file.\n\n       canary workflow runs list <workflowId> --side api\n       canary workflow runs get <workflowId> <runId>\n       canary workflow api-sequence update <workflowId> --from-file seq.json\n\nREFERENCE\n\n  - Command help: `canary workflow api-sequence --help`\n  - Workflow creation help: `canary workflow create --help`\n  - API catalog help: `canary api-catalog --help`\n';
+
+// ../content/src/workflow-guide/index.ts
+var WORKFLOW_GUIDE_CONCEPT_SECTIONS = [
+  { title: "Workflow Overview", slug: "overview", content: overview_default },
+  { title: "Node Types", slug: "node-types", content: node_types_default },
+  { title: "Playbooks & Cache", slug: "playbook", content: playbook_default },
+  { title: "Best Practices", slug: "best-practices", content: best_practices_default },
+  { title: "Macros & Variables", slug: "macros", content: macros_default },
+  { title: "Seed Workflows", slug: "seed-workflows", content: seed_workflows_default },
+  { title: "Test Data Lifecycle", slug: "data-lifecycle", content: data_lifecycle_default },
+  { title: "Assertions", slug: "assertions", content: assertions_default },
+  { title: "API Sequences", slug: "api-sequences", content: api_sequences_default }
+];
+var WORKFLOW_GUIDE_CLI_SECTIONS = [
+  { title: "CLI: Seed Workflows", slug: "cli-seeds", content: cli_seeds_default },
+  { title: "CLI: API Sequences", slug: "cli-api-sequences", content: cli_api_sequences_default }
+];
+var WORKFLOW_GUIDE_SECTIONS = [
+  ...WORKFLOW_GUIDE_CONCEPT_SECTIONS,
+  ...WORKFLOW_GUIDE_CLI_SECTIONS
+];
+
+// src/workflow.ts
+var WORKFLOW_STATUS_DESCRIPTIONS = {
+  draft: "editable, not run by suites",
+  published: "active, included in regression runs"
+};
+var formatWorkflowStatusList = () => USER_SETTABLE_WORKFLOW_STATUSES.map(
+  (s) => `${s} (${WORKFLOW_STATUS_DESCRIPTIONS[s]})`
+).join(", ");
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1) + "\u2026";
+}
+function getNodeTitle(node) {
+  const c = node.configJson ?? {};
+  switch (node.nodeType) {
+    case "login":
+      return c.credentialName || NODE_TYPE_LABEL.login;
+    case "navigate":
+      return c.pageTitle || truncate(c.pageUrl || "Navigate", 40);
+    case "action":
+      return c.customActionTitle || truncate(c.actionDescription || "Action", 50);
+    case "assertion":
+      return truncate(c.condition || "Assertion", 50);
+    case "setup":
+      return c.setupFlowName || "Setup";
+    case "seed":
+      return c.seedWorkflowName || "Seed";
+    case "wait":
+      return "Wait";
+    case "condition":
+      return truncate(c.conditionDescription || "Condition", 50);
+    case "end":
+      return "End";
+    case "api_sequence":
+      return "API Sequence";
+    default:
+      return node.nodeType;
+  }
+}
+function getCleanConfig(node) {
+  const c = node.configJson ?? {};
+  switch (node.nodeType) {
+    case "login":
+      return pick(c, ["credentialName", "performLogin"]);
+    case "navigate":
+      return {
+        ...pick(c, ["pageUrl", "pageTitle"]),
+        ...c.openInNewTab ? { openInNewTab: true } : {}
+      };
+    case "action":
+      return pick(c, [
+        "actionDescription",
+        "customActionInstructions",
+        "playbookSteps",
+        "inputValues",
+        "declaredOutputs",
+        "capturedVariableKeys",
+        "dataRequirements",
+        "alwaysUseAgent"
+      ]);
+    case "assertion":
+      return pick(c, ["condition", "expectedOutcome", "strict", "alwaysUseAgent"]);
+    case "setup":
+      return pick(c, ["setupFlowId", "setupFlowName"]);
+    case "seed":
+      return pick(c, ["seedWorkflowId", "seedWorkflowName", "snapshotVersion"]);
+    case "end":
+      return pick(c, ["outcome"]);
+    case "wait":
+    case "condition":
+    case "api_sequence":
+      return c;
+    default:
+      return c;
+  }
+}
+function pick(obj, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (obj[key] !== void 0 && obj[key] !== null) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+function formatWorkflowMarkdown(workflow) {
+  const seedOutputs = workflow.seedOutputsJson ?? workflow.seedOutputs;
+  return workflowToSpec({ ...workflow, seedOutputs });
+}
+function formatWorkflowJson(workflow) {
+  const sorted = [...workflow.nodes].sort((a, b) => a.orderIndex - b.orderIndex);
+  const seedOutputs = workflow.seedOutputsJson;
+  return {
+    workflow: {
+      id: workflow.id,
+      name: workflow.name,
+      description: workflow.description,
+      status: workflow.status,
+      flowType: workflow.flowType,
+      ...seedOutputs && seedOutputs.length > 0 ? { seedOutputs } : {}
+    },
+    steps: sorted.map((node, i) => ({
+      index: i + 1,
+      nodeId: node.id,
+      nodeType: node.nodeType,
+      title: getNodeTitle(node),
+      config: getCleanConfig(node)
+    }))
+  };
+}
+async function handleList(argv, apiUrl, token) {
+  const jsonOutput = hasFlag(argv, "--json");
+  const params = new URLSearchParams();
+  const search = getArgValue(argv, "--search");
+  const flowType = getArgValue(argv, "--flow-type");
+  const status = getArgValue(argv, "--status");
+  const page = getArgValue(argv, "--page");
+  const pageSize = getArgValue(argv, "--page-size");
+  if (search) params.set("search", search);
+  if (flowType) params.set("flowType", flowType);
+  if (status) params.set("status", status);
+  if (page) params.set("page", page);
+  if (pageSize) params.set("pageSize", pageSize);
+  const qs = params.toString();
+  const path = `/workflows${qs ? `?${qs}` : ""}`;
+  const result = await apiRequest(apiUrl, token, "GET", path);
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`);
+    process9.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify({ data: result.data, pagination: result.pagination }, null, 2));
+    return;
+  }
+  const { data, pagination } = result;
+  console.log(
+    `Workflows: ${pagination.totalItems} total (page ${pagination.page}/${pagination.totalPages})
+`
+  );
+  if (data.length === 0) {
+    console.log("No workflows found.");
+    return;
+  }
+  const idW = 36;
+  const nameW = 30;
+  const statusW = 12;
+  const typeW = 10;
+  const header = [
+    "ID".padEnd(idW),
+    "Name".padEnd(nameW),
+    "Status".padEnd(statusW),
+    "Type".padEnd(typeW)
+  ].join("  ");
+  console.log(header);
+  for (const w of data) {
+    const row = [
+      w.id.padEnd(idW),
+      truncate(w.name, nameW).padEnd(nameW),
+      w.status.padEnd(statusW),
+      w.flowType.padEnd(typeW)
+    ].join("  ");
+    console.log(row);
+  }
+}
+async function handleGet2(argv, apiUrl, token) {
+  const workflowId = argv[0];
+  if (!workflowId || workflowId.startsWith("--")) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow get <workflowId>");
+    process9.exit(1);
+  }
+  const _jsonOutput = hasFlag(argv, "--json") || getArgValue(argv, "--format") === "json";
+  const markdownOutput = hasFlag(argv, "--markdown") || getArgValue(argv, "--format") === "markdown" || getArgValue(argv, "--format") === "spec";
+  const outputFile = getArgValue(argv, "--output");
+  const apiRes = await apiFetch(`${apiUrl}/workflows/${workflowId}`, {
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    token
+  });
+  if (!apiRes.ok) exitOnFailure(apiRes.failure);
+  const result = await apiRes.response.json();
+  if (result.error === "WORKFLOW_NOT_FOUND") {
+    console.error("Error: Workflow not found.");
+    process9.exit(1);
+  }
+  if (result.error === "WORKFLOW_WRONG_ORG") {
+    console.error(
+      `Error: Workflow belongs to another org: ${result.targetOrgName ?? result.targetOrgId}`
+    );
+    process9.exit(1);
+  }
+  if (!result.workflow) {
+    console.error(`Error: ${result.error ?? "Unexpected response"}`);
+    process9.exit(1);
+  }
+  const workflow = result.workflow;
+  let output;
+  if (markdownOutput) {
+    output = formatWorkflowMarkdown(workflow);
+  } else {
+    output = JSON.stringify(formatWorkflowJson(workflow), null, 2);
+  }
+  if (outputFile) {
+    try {
+      await fs5.writeFile(outputFile, output, "utf-8");
+      console.log(`Written to ${outputFile}`);
+    } catch (err) {
+      console.error(
+        `Error writing to ${outputFile}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      process9.exit(1);
+    }
+    return;
+  }
+  console.log(output);
+  if (!markdownOutput) {
+    const appUrl = resolveAppUrl(apiUrl);
+    console.log(`
+URL: ${appUrl}/flows/${workflowId}`);
+  }
+}
+async function handlePatch(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow patch <workflowId> [--name ...] [--description ...] [--status ...] [--flow-type ...]");
+    process9.exit(1);
+  }
+  const name = getArgValue(argv, "--name");
+  const description = getArgValue(argv, "--description");
+  const status = getArgValue(argv, "--status");
+  const flowType = getArgValue(argv, "--flow-type");
+  const seedOutputsJsonRaw = getArgValue(argv, "--seed-outputs-json");
+  const seedOutputsFile = getArgValue(argv, "--seed-outputs-file");
+  const jsonOutput = hasFlag(argv, "--json");
+  const hasTagFlag = getArgValue(argv, "--tags") !== void 0 || getArgValue(argv, "--tags-add") !== void 0 || getArgValue(argv, "--tags-remove") !== void 0 || getArgValue(argv, "--tag-id") !== void 0;
+  if (!name && !description && !status && !flowType && !seedOutputsJsonRaw && !seedOutputsFile && !hasTagFlag) {
+    console.error(
+      "Error: No fields to update. Provide at least one of: --name, --description, --status, --flow-type, --seed-outputs-json, --seed-outputs-file, --tags, --tags-add, --tags-remove, --tag-id"
+    );
+    process9.exit(1);
+  }
+  if (status && !USER_SETTABLE_WORKFLOW_STATUSES.includes(status)) {
+    console.error(`Error: Invalid status "${status}". Valid: ${formatWorkflowStatusList()}`);
+    process9.exit(1);
+  }
+  const validFlowTypes = ["standard", "setup", "seed", "teardown"];
+  if (flowType && !validFlowTypes.includes(flowType)) {
+    console.error(`Error: Invalid flow type "${flowType}". Must be one of: ${validFlowTypes.join(", ")}`);
+    process9.exit(1);
+  }
+  const body = {};
+  if (name) body.name = name;
+  if (description) body.description = description;
+  if (status) body.status = status;
+  if (flowType) body.flowType = flowType;
+  if (seedOutputsJsonRaw || seedOutputsFile) {
+    let raw;
+    if (seedOutputsFile) {
+      try {
+        raw = await fs5.readFile(seedOutputsFile, "utf-8");
+      } catch (err) {
+        console.error(
+          `Error reading ${seedOutputsFile}: ${err instanceof Error ? err.message : String(err)}`
+        );
+        process9.exit(1);
+      }
+    } else {
+      raw = seedOutputsJsonRaw;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) {
+        throw new Error("seedOutputsJson must be a JSON array");
+      }
+      body.seedOutputsJson = parsed;
+    } catch (err) {
+      console.error(
+        `Error: Invalid --seed-outputs-json: ${err instanceof Error ? err.message : String(err)}`
+      );
+      process9.exit(1);
+    }
+  }
+  let tagResult = null;
+  if (Object.keys(body).length > 0) {
+    const result = await apiRequest(
+      apiUrl,
+      token,
+      "PUT",
+      `/workflows/${workflowId}`,
+      body
+    );
+    if (!result.ok) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ ok: false, error: result.error ?? "Unknown error" }, null, 2));
+      } else {
+        console.error(`Error: ${result.error ?? "Unknown error"}`);
+      }
+      process9.exit(1);
+    }
+  }
+  if (hasTagFlag) {
+    try {
+      tagResult = await applyWorkflowTagFlags({ apiUrl, token, argv, workflowId });
+    } catch (err) {
+      if (jsonOutput) {
+        console.log(
+          JSON.stringify(
+            { ok: false, error: err instanceof Error ? err.message : String(err) },
+            null,
+            2
+          )
+        );
+      } else {
+        console.error(`Error applying tags:
+${err instanceof Error ? err.message : String(err)}`);
+      }
+      process9.exit(1);
+    }
+  }
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify(
+        { ok: true, workflowId, updated: body, tags: tagResult?.tagIds ?? null },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const updatedKeys = Object.keys(body);
+  if (updatedKeys.length > 0) {
+    console.log(`Workflow ${workflowId} updated (${updatedKeys.join(", ")}).`);
+  }
+  if (tagResult) {
+    console.log(`Tags: ${tagResult.tagIds.length} assigned.`);
+  }
+}
+async function handleArchive(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow archive <workflowId> [--yes] [--json]");
+    process9.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const skipConfirm = hasFlag(argv, "--yes", "-y");
+  if (!skipConfirm) {
+    if (!process9.stdin.isTTY) {
+      console.error(
+        "Error: Archiving requires confirmation. Pass --yes (or -y) for non-interactive use."
+      );
+      process9.exit(1);
+    }
+    process9.stdout.write(
+      `Archive workflow ${workflowId}? It will be hidden from lists and skipped by test suites. [y/N] `
+    );
+    const answer = await new Promise((resolve) => {
+      process9.stdin.setEncoding("utf-8");
+      process9.stdin.once("data", (chunk) => resolve(String(chunk).trim().toLowerCase()));
+    });
+    if (answer !== "y" && answer !== "yes") {
+      console.error("Aborted.");
+      process9.exit(1);
+    }
+  }
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "DELETE",
+    `/workflows/${workflowId}`
+  );
+  if (result.error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      renderWorkflowUserError(result);
+    }
+    process9.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Archived workflow ${workflowId}. Use 'canary workflow unarchive ${workflowId}' to restore.`);
+  }
+}
+async function handleUnarchive(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow unarchive <workflowId> [--json]");
+    process9.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/workflows/${workflowId}/unarchive`,
+    {}
+  );
+  if (result.error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      renderWorkflowUserError(result);
+    }
+    process9.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Restored workflow ${workflowId}.`);
+  }
+}
+async function handlePublish(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow publish <workflowId> [--force] [--json]");
+    process9.exit(1);
+  }
+  const force = hasFlag(argv, "--force");
+  const jsonOutput = hasFlag(argv, "--json");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/workflows/${workflowId}/publish`,
+    force ? { force: true } : {}
+  );
+  if (result.error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const hint = result.code === "FLOW_NOT_READY_TO_PUBLISH" ? "\n  Trigger a successful run first (canary workflow run <id>), or pass --force." : "";
+      console.error(`Error: ${result.error}${hint}`);
+    }
+    process9.exit(1);
+  }
+  const version = result.workflow?.snapshotVersion;
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({ ok: true, workflowId, workflow: result.workflow ?? null }, null, 2)
+    );
+    return;
+  }
+  console.log(
+    `Workflow ${workflowId} published${version !== void 0 ? ` as snapshot v${version}` : ""}.`
+  );
+}
+function getAllArgValues2(argv, flag) {
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === flag && i + 1 < argv.length) {
+      values.push(argv[i + 1]);
+      i++;
+    }
+  }
+  return values;
+}
+async function handleNodePatch(argv, apiUrl, token) {
+  const positional = argv.filter((a) => !a.startsWith("-"));
+  const workflowId = positional[0];
+  const nodeId = positional[1];
+  if (!workflowId || !nodeId) {
+    console.error("Error: Missing workflow ID and/or node ID.");
+    console.error(
+      `Usage: canary workflow node patch <workflowId> <nodeId> --set-input key=value [--config '{"..."}'] [--json]`
+    );
+    process9.exit(1);
+  }
+  const configArg = getArgValue(argv, "--config");
+  const setInputArgs = getAllArgValues2(argv, "--set-input");
+  const jsonOutput = hasFlag(argv, "--json");
+  if (!configArg && setInputArgs.length === 0) {
+    console.error(`Error: No changes specified. Provide --set-input key=value and/or --config '{"..."}'`);
+    process9.exit(1);
+  }
+  let configJson = {};
+  if (configArg) {
+    try {
+      configJson = JSON.parse(configArg);
+    } catch (e) {
+      console.error(`Error: Invalid JSON in --config: ${e instanceof Error ? e.message : String(e)}`);
+      process9.exit(1);
+    }
+  }
+  if (setInputArgs.length > 0) {
+    const inputValues = configJson.inputValues ?? {};
+    for (const arg of setInputArgs) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(`Error: --set-input must be key=value, got: "${arg}"`);
+        process9.exit(1);
+      }
+      inputValues[arg.slice(0, eqIdx)] = arg.slice(eqIdx + 1);
+    }
+    configJson.inputValues = inputValues;
+  }
+  const getRes = await fetchOrExit(`${apiUrl}/workflows/${workflowId}`, {
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    token
+  });
+  const getResult = await getRes.json();
+  if (!getResult.workflow) {
+    console.error(`Error: Workflow not found.`);
+    process9.exit(1);
+  }
+  const existingNode = getResult.workflow.nodes.find((n) => n.id === nodeId);
+  if (!existingNode) {
+    console.error(`Error: Node ${nodeId} not found in workflow ${workflowId}.`);
+    console.error("\nAvailable nodes:");
+    for (const n of getResult.workflow.nodes.sort((a, b) => a.orderIndex - b.orderIndex)) {
+      console.error(`  ${n.id}  [${n.nodeType}] ${getNodeTitle(n)}`);
+    }
+    process9.exit(1);
+  }
+  const patchRes = await fetchOrExit(`${apiUrl}/workflows/${workflowId}/nodes/${nodeId}`, {
+    method: "PUT",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    token,
+    body: JSON.stringify({ configJson })
+  });
+  if (!patchRes.ok) {
+    const errBody = await patchRes.text();
+    if (jsonOutput) {
+      console.log(errBody || JSON.stringify({ ok: false, status: patchRes.status }, null, 2));
+    } else {
+      let rendered = null;
+      try {
+        const parsed = JSON.parse(errBody);
+        rendered = renderWorkflowUserError(parsed);
+      } catch {
+        rendered = null;
+      }
+      console.error(rendered ?? `Error (${patchRes.status}): ${errBody.slice(0, 500)}`);
+    }
+    process9.exit(1);
+  }
+  const patchResult = await patchRes.json();
+  if (jsonOutput) {
+    console.log(JSON.stringify({ ok: true, node: patchResult.node }, null, 2));
+    return;
+  }
+  const title = getNodeTitle(existingNode);
+  console.log(`Updated node [${existingNode.nodeType}] "${title}" (${nodeId}):
+`);
+  const oldConfig = existingNode.configJson ?? {};
+  for (const [key, newVal] of Object.entries(configJson)) {
+    if (typeof newVal === "object" && newVal !== null && typeof oldConfig[key] === "object" && oldConfig[key] !== null) {
+      const oldObj = oldConfig[key];
+      const newObj = newVal;
+      for (const [subKey, subVal] of Object.entries(newObj)) {
+        const oldVal = oldObj[subKey];
+        if (oldVal !== subVal) {
+          console.log(`  ${key}.${subKey}: ${JSON.stringify(oldVal ?? null)} -> ${JSON.stringify(subVal)}`);
+        }
+      }
+    } else {
+      const oldVal = oldConfig[key];
+      if (oldVal !== newVal) {
+        console.log(`  ${key}: ${JSON.stringify(oldVal ?? null)} -> ${JSON.stringify(newVal)}`);
+      }
+    }
+  }
+}
+function printWorkflowHelp() {
+  console.log(
+    [
+      "Usage: canary workflow <sub-command> [options]",
+      "",
+      '  Tip: Run "canary workflow guide" for the full authoring reference',
+      "       (node types, playbooks, macros, seeds, assertions, best practices)",
+      "",
+      "Sub-commands:",
+      "  guide [section] [--json]                    Authoring guide (node-types, macros, etc.)",
+      "  list [options]                              List workflows",
+      "  get <workflowId> [options]                  Get workflow definition with steps",
+      "  create [options]                            Create workflow from JSON",
+      "  sync <workflowId> [options]                 Replace all nodes (same format as create)",
+      "  patch <workflowId> [options]                Update workflow properties",
+      "  publish <workflowId> [--force] [--json]     Promote the current draft to a new published snapshot",
+      "  archive <workflowId> [--yes] [--json]       Soft-delete: hide from lists, skip in test suites (reversible)",
+      "  unarchive <workflowId> [--json]             Restore a previously archived workflow",
+      "  run <workflowId> [options]                  Trigger a workflow execution",
+      "  api-sequence <verb> <workflowId>            Manage the API sequence attached to a workflow",
+      "  generate-api-sequence <workflowId> [opts]   (deprecated alias for `api-sequence generate`)",
+      "  seed <sub-command>                          Create seed workflows",
+      "  node <sub-command>                          Manage individual nodes",
+      "  runs <sub-command>                          Query workflow run results",
+      "  debug <runId|sub-command>                   Debug a run (overview/steps/cache/thoughts/logs/trace)",
+      "",
+      "List options:",
+      "  --search <query>      Search by name",
+      "  --flow-type <type>    Filter: standard, setup, seed, teardown",
+      "  --status <status>     Filter: draft, published",
+      "  --page <n>            Page number (default: 1)",
+      "  --page-size <n>       Page size (default: 25)",
+      "  --json                Output raw JSON",
+      "",
+      "Get options:",
+      "  --format json|markdown|spec  Output format (default: json)",
+      "  --json                  Shorthand for --format json",
+      "  --markdown              Shorthand for editable .canary.md spec output",
+      "  --output <file>         Write output to file",
+      "",
+      "Create options:",
+      "  --from-stdin            Read workflow JSON from stdin (default)",
+      "  --from-file <path>      Read workflow JSON from file",
+      "  --api-only              Create an API-only workflow with a backing ApiSequence",
+      "                          Requires: --name <name>",
+      "                          Optional: --credential <id>, --guidance <text>,",
+      "                                    --sequence-from-file <path> or --sequence-from-stdin",
+      "                          Input shape: { steps, description?, stopOnFailure?, exports? }",
+      "                          Returns: { workflowId, apiSequenceId, nodeId }",
+      "  --run-and-publish       Run test first, publish on success",
+      "  --publish-timeout <sec> Timeout waiting for the test to finish (default: 900)",
+      "  --property <name|id>    Property for run-and-publish",
+      "  --environment <name|id> Environment for run-and-publish",
+      "  --tags <names>          Comma-separated tag names to assign (names, not IDs)",
+      "  --tag-id <ids>          Comma-separated raw tag IDs (escape hatch)",
+      "",
+      "  Input: { name, nodes: [{ nodeType, configJson }] }",
+      '  Run "canary workflow guide node-types" for available node types.',
+      '  Run "canary workflow guide macros" for dynamic test data ($EMAIL, $RANDOM_STRING, etc.)',
+      "",
+      "Sync options:",
+      "  --from-file <path>      Read nodes JSON from file",
+      "  --from-stdin            Read nodes JSON from stdin",
+      "  --no-snapshot           Skip creating a draft snapshot before sync",
+      "  --propose               Create a proposal instead of applying directly",
+      "  --title <title>         Proposal title (with --propose)",
+      "  --description <desc>    Proposal description (with --propose)",
+      "  --json                  Output raw JSON",
+      "",
+      "  Sync accepts the same minimal node format as create.",
+      "  Edges, IDs, positions, and ordering are auto-generated when omitted.",
+      "  Input: { nodes: [{ nodeType, configJson }] }",
+      "",
+      "  When using --propose on an existing workflow, run `canary workflow get",
+      "  <id>` first and reuse each node's existing `id` for steps you intend",
+      "  to keep. Only omit `id` for genuinely new steps. Without ID reuse the",
+      "  proposal will diff as a full remove-everything/add-everything rewrite.",
+      "",
+      "Patch options:",
+      "  --name <name>           Update workflow name",
+      "  --description <desc>    Update description",
+      "  --status <status>       Set status. Valid:",
+      "                            draft       \u2014 editable, not run by suites",
+      "                            published   \u2014 active, included in regression runs",
+      "                          (reliability is tracked automatically by health)",
+      "  --flow-type <type>      Set type: standard, setup, seed, teardown",
+      "  --seed-outputs-json <json>   Replace seedOutputsJson (array) \u2014 seed flows only",
+      "  --seed-outputs-file <path>   Replace seedOutputsJson from a JSON file",
+      "  --tags <names>          Replace tags with these names (comma-separated)",
+      "  --tags-add <names>      Add these tag names to the existing set",
+      "  --tags-remove <names>   Remove these tag names from the existing set",
+      "  --tag-id <ids>          Raw tag IDs (comma-separated)",
+      "  --json                  Output raw JSON",
+      "",
+      "Publish options:",
+      "  --force                 Publish without requiring a successful run (skips the",
+      "                          ready-to-publish gate; the new snapshot has no linked run)",
+      "  --json                  Output raw JSON",
+      "",
+      "  Publish snapshots the current workflow definition and promotes it",
+      "  into the suite. Without --force, the workflow must have a passing",
+      "  run (ready_to_publish=true). Different from --status=published which",
+      "  only sets a column and does NOT create a new snapshot.",
+      "",
+      "Run options:",
+      "  --stream                Follow execution until completion",
+      "  --json                  Output raw JSON",
+      "",
+      "API Sequence sub-commands:",
+      "  api-sequence get <wf>                       Show config + steps",
+      "  api-sequence update <wf> --from-file <f>    Replace config",
+      "  api-sequence execute <wf>                   Run the sequence",
+      "  api-sequence delete <wf>                    Delete the sequence",
+      "  api-sequence set-api-only <wf> [--off]     Toggle workflow apiOnly flag",
+      "  api-sequence generate <wf> [--prompt ...]   AI-generate a config (streams)",
+      "",
+      '  Run "canary workflow guide api-sequences" for step shape and template syntax.',
+      "",
+      "Seed sub-commands:",
+      "  seed create [options]                        Create a seed workflow with outputs",
+      "",
+      "Seed create options:",
+      "  --name <name>              Seed workflow name (required unless JSON input)",
+      "  --description <desc>       Description",
+      "  --output <key:name[:desc]> Declare an output (repeatable)",
+      "  --outputs-json <json>      Full outputs array as inline JSON",
+      "  --from-stdin               Read full config from stdin",
+      "  --from-file <path>         Read full config from file",
+      "  --no-teardown              Skip creating paired teardown workflow",
+      "  --status <status>          Initial status (default: draft)",
+      "  --json                     Output raw JSON",
+      "",
+      "Node sub-commands:",
+      "  node patch <workflowId> <nodeId> [options]  Update a node's config",
+      "",
+      "Node patch options:",
+      "  --set-input key=value   Set an inputValue (repeatable)",
+      `  --config '{"..."}'      Merge arbitrary configJson (partial update)`,
+      "  --json                  Output raw JSON",
+      "",
+      "Runs sub-commands:",
+      "  runs list <workflowId>                    List runs for a workflow",
+      "  runs get <workflowId> <runId>             Get run detail with steps",
+      "  runs diagnostics <workflowId> <runId>     Get failure diagnostic",
+      "",
+      "Cache sub-commands:",
+      "  cache status <workflowId>                                Show per-node cache version, health, recent failures",
+      "  cache clear <workflowId> [--node <id>] [--below-version <n>] [--stale-only] [--mode all]",
+      "                                                            Targeted cache invalidation (rows kept, isValid=false)",
+      "  cache clear <workflowId> --mode hard --yes               DESTRUCTIVE: delete cache rows, strip playbookSteps,",
+      '                                                            null lastRunId. Same as the UI "Reset flow" button',
+      "  cache optimize <workflowId>                              Enqueue a shadow-cache-writer heal run",
+      "",
+      "Common options:",
+      "  --env <env>           Target environment (prod, dev, local)",
+      "  --api-url <url>       API URL override",
+      "  --token <key>         API token override"
+    ].join("\n")
+  );
+}
+async function runWorkflow(argv) {
+  const [subCommand, ...rest] = argv;
+  if (!subCommand || subCommand === "help") {
+    printWorkflowHelp();
+    return;
+  }
+  if (subCommand === "debug" && hasFlag(rest, "--help", "-h")) {
+    const { handleWorkflowDebug } = await import("./workflow-debug-BGD4UIXU.js");
+    await handleWorkflowDebug(rest, "", "");
+    return;
+  }
+  if (hasFlag(argv, "--help", "-h")) {
+    printWorkflowHelp();
+    return;
+  }
+  if (subCommand === "guide") {
+    const sectionSlug = rest.find((a) => !a.startsWith("-"));
+    const jsonOutput = hasFlag(rest, "--json");
+    printGuide(WORKFLOW_GUIDE_SECTIONS, sectionSlug, jsonOutput);
+    return;
+  }
+  const { apiUrl, token } = await resolveConfig(argv);
+  switch (subCommand) {
+    case "list":
+      await handleList(rest, apiUrl, token);
+      break;
+    case "get":
+      await handleGet2(rest, apiUrl, token);
+      break;
+    case "create":
+      await handleWorkflowCreate(rest, apiUrl, token);
+      break;
+    case "patch":
+      await handlePatch(rest, apiUrl, token);
+      break;
+    case "publish":
+      await handlePublish(rest, apiUrl, token);
+      break;
+    case "archive":
+      await handleArchive(rest, apiUrl, token);
+      break;
+    case "unarchive":
+      await handleUnarchive(rest, apiUrl, token);
+      break;
+    case "run":
+      await handleWorkflowRun(rest, apiUrl, token);
+      break;
+    case "runs":
+      await runWorkflowRuns(rest, apiUrl, token);
+      break;
+    case "node": {
+      const [nodeSub, ...nodeRest] = rest;
+      if (nodeSub === "patch") {
+        await handleNodePatch(nodeRest, apiUrl, token);
+      } else {
+        console.error(`Unknown node sub-command: ${nodeSub ?? "(none)"}`);
+        printWorkflowHelp();
+        process9.exit(1);
+      }
+      break;
+    }
+    case "seed": {
+      const [seedSub, ...seedRest] = rest;
+      if (seedSub === "create") {
+        await handleWorkflowSeedCreate(seedRest, apiUrl, token);
+      } else {
+        console.error(`Unknown seed sub-command: ${seedSub ?? "(none)"}`);
+        printWorkflowHelp();
+        process9.exit(1);
+      }
+      break;
+    }
+    case "sync":
+      await handleWorkflowSync(rest, apiUrl, token);
+      break;
+    case "proposals": {
+      const { handleWorkflowProposals } = await import("./workflow-proposals-MTUDX46O.js");
+      await handleWorkflowProposals(rest, apiUrl, token);
+      break;
+    }
+    case "generate-api-sequence":
+      await handleWorkflowGenerateApiSequence(rest, apiUrl, token);
+      break;
+    case "api-sequence":
+      await handleWorkflowApiSequence(rest, apiUrl, token);
+      break;
+    case "cache": {
+      const { handleWorkflowCache } = await import("./workflow-cache-NQJQFWMV.js");
+      await handleWorkflowCache(rest, apiUrl, token);
+      break;
+    }
+    case "debug": {
+      const { handleWorkflowDebug } = await import("./workflow-debug-BGD4UIXU.js");
+      await handleWorkflowDebug(rest, apiUrl, token);
+      break;
+    }
+    default:
+      console.error(`Unknown sub-command: ${subCommand}`);
+      printWorkflowHelp();
+      process9.exit(1);
+  }
+}
+export {
+  runWorkflow
+};
+//# sourceMappingURL=workflow-XYFH5LTP.js.map