@withone/cli 1.47.8 → 1.47.10

package/dist/{chunk-KWGN3RJR.js → chunk-4AYHJFH3.js}

@@ -746,1822 +746,2079 @@ function validateActionInput(action, args) {
   return { valid: false, missing };
 }
 
-// src/lib/flow-engine.ts
-var execAsync = promisify(exec);
-function sleep2(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-var StepTimeoutError = class extends Error {
-  errorCode = "TIMEOUT";
-  constructor(stepId, timeoutMs) {
-    super(`Step "${stepId}" exceeded timeout of ${timeoutMs}ms`);
-    this.name = "StepTimeoutError";
-  }
-};
-function withTimeout(promise, timeoutMs, stepId) {
-  let timer;
-  const timeoutPromise = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new StepTimeoutError(stepId, timeoutMs)), timeoutMs);
-  });
-  return Promise.race([promise, timeoutPromise]).finally(() => {
-    if (timer) clearTimeout(timer);
-  });
-}
-function shouldRetryError(err, onError) {
-  if (!onError) return { retry: false };
-  const message = err instanceof Error ? err.message : String(err);
-  const errorCode = err?.errorCode;
-  const matches = (entry) => {
-    if (typeof entry === "number") {
-      const re = new RegExp(`\\b${entry}\\b`);
-      return re.test(message);
-    }
-    if (errorCode && entry === errorCode) return true;
-    return message.toLowerCase().includes(entry.toLowerCase());
-  };
-  if (Array.isArray(onError.failFastOn) && onError.failFastOn.some(matches)) {
-    return { retry: false, reason: "failFastOn" };
-  }
-  if (Array.isArray(onError.retryOn)) {
-    if (onError.retryOn.some(matches)) return { retry: true, reason: "retryOn" };
-    return { retry: false, reason: "no-retryOn-match" };
-  }
-  return { retry: true };
-}
-function computeRetryDelay(onError, attempt) {
-  const base = onError.retryDelayMs ?? 1e3;
-  const max = onError.maxDelayMs ?? 3e4;
-  const backoff = onError.backoff ?? "fixed";
-  const retryIndex = attempt - 2;
-  let delay;
-  if (backoff === "exponential" || backoff === "exponential-jitter") {
-    delay = Math.min(base * Math.pow(2, retryIndex), max);
-    if (backoff === "exponential-jitter") {
-      delay = delay * (0.5 + Math.random() * 0.5);
-    }
-  } else {
-    delay = base;
-  }
-  return Math.round(delay);
-}
-function resolveSelector(selectorPath, context) {
-  if (!selectorPath.startsWith("$.")) return selectorPath;
-  const parts = selectorPath.slice(2).split(/\.|\[/).map((p) => p.replace(/\]$/, ""));
-  let current = context;
-  for (const part of parts) {
-    if (current === null || current === void 0) return void 0;
-    if (part === "*" && Array.isArray(current)) {
-      continue;
-    }
-    if (Array.isArray(current) && part === "*") {
-      continue;
-    }
-    if (Array.isArray(current)) {
-      const idx = Number(part);
-      if (!isNaN(idx)) {
-        current = current[idx];
-      } else {
-        current = current.map((item) => item?.[part]);
+// src/lib/flow-schema.ts
+var FLOW_SCHEMA = {
+  errorStrategies: ["fail", "continue", "retry", "fallback"],
+  validInputTypes: ["string", "number", "boolean", "object", "array"],
+  flowFields: {
+    key: { type: "string", required: true, description: "Unique kebab-case identifier", pattern: /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ },
+    name: { type: "string", required: true, description: "Human-readable flow name" },
+    description: { type: "string", required: false, description: "What this flow does" },
+    version: { type: "string", required: false, description: "Semver or arbitrary version string" },
+    inputs: { type: "object", required: true, description: "Input declarations (Record<string, InputDeclaration>)" },
+    steps: { type: "array", required: true, description: "Ordered array of steps", stepsArray: true },
+    defaultOnError: { type: "object", required: false, description: 'Default error strategy inherited by every step without its own `onError` (e.g. { "strategy": "continue" }). A step opts out with its own `onError`.' }
+  },
+  inputFields: {
+    type: { type: "string", required: true, description: "Data type: string, number, boolean, object, array", enum: ["string", "number", "boolean", "object", "array"] },
+    required: { type: "boolean", required: false, description: "Whether this input must be provided" },
+    default: { type: "unknown", required: false, description: "Default value if not provided" },
+    description: { type: "string", required: false, description: "Human-readable description" },
+    connection: { type: "object", required: false, description: 'Connection metadata: { platform: "gmail" } \u2014 enables auto-resolution' },
+    enum: { type: "array", required: false, description: "Allowed values. Resolved input must equal one of these (post-coercion)." }
+  },
+  stepCommonFields: {
+    id: { type: "string", required: true, description: "Unique step identifier (used in selectors)" },
+    name: { type: "string", required: true, description: "Human-readable step label" },
+    type: { type: "string", required: true, description: "Step type (determines which config object is required)" },
+    if: { type: "string", required: false, description: "JS expression \u2014 skip step if falsy" },
+    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" },
+    timeoutMs: { type: "number", required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout".' },
+    requires: { type: "array", required: false, description: "Presence preconditions: array of $.input.X or $.steps.X.output... selectors that must resolve to a non-empty value before the step runs. Failures honor onError." },
+    outputSchema: { type: "object", required: false, description: `Optional declaration of the shape this step's output produces. When set, the validator checks that downstream $.steps.<this.id>.output.<field> references point at declared fields. Format: { fieldName: "string"|"number"|"boolean"|"object"|"array"|"unknown" } \u2014 nested objects are supported.` }
+  },
+  stepTypes: [
+    {
+      type: "action",
+      configKey: "action",
+      description: "Execute a platform API action",
+      fields: {
+        platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
+        actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
+        connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
+        connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
+        data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
+        pathVars: { type: "object", required: false, description: "URL path variables" },
+        queryParams: { type: "object", required: false, description: "Query parameters" },
+        headers: { type: "object", required: false, description: "Additional headers" }
+      },
+      example: {
+        id: "findCustomer",
+        name: "Search Stripe customers",
+        type: "action",
+        action: {
+          platform: "stripe",
+          actionId: "conn_mod_def::xxx::yyy",
+          connection: { platform: "stripe" },
+          data: { query: "email:'{{$.input.customerEmail}}'" }
+        }
       }
-    } else if (typeof current === "object") {
-      current = current[part];
-    } else {
-      return void 0;
-    }
-  }
-  return current;
-}
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function applyHandlebarsPipe(value, pipe) {
-  switch (pipe) {
-    case "json":
-      return JSON.stringify(value ?? null);
-    case "shell": {
-      if (value === void 0 || value === null) return `''`;
-      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
-      return shellQuote(str);
-    }
-    case "url": {
-      if (value === void 0 || value === null) return "";
-      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
-      return encodeURIComponent(str);
-    }
-    case "md": {
-      if (value === void 0 || value === null) return "";
-      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
-      return str.replace(/([\\`*_{}\[\]()#+\-!|])/g, "\\$1");
-    }
-    case "html": {
-      if (value === void 0 || value === null) return "";
-      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
-      return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-    }
-    default:
-      throw new Error(`Unknown Handlebars pipe: "${pipe}". Supported: json, shell, url, md, html.`);
-  }
-}
-function interpolateString(str, context) {
-  return str.replace(
-    /\{\{\s*(q\s+)?(\$\.[^}\s|]+)(?:\s*\|\s*([a-zA-Z]+))?\s*\}\}/g,
-    (_match, qFlag, selector, pipe) => {
-      const value = resolveSelector(selector, context);
-      if (pipe) {
-        if (qFlag) {
-          throw new Error(`Handlebars expression "{{q ${selector} | ${pipe}}}" combines the legacy "q" prefix with a pipe \u2014 pick one (prefer the pipe form).`);
+    },
+    {
+      type: "transform",
+      configKey: "transform",
+      description: "Single JS expression with implicit return",
+      fields: {
+        expression: { type: "string", required: true, description: "JS expression evaluated with flow context as $" }
+      },
+      example: {
+        id: "extractNames",
+        name: "Extract customer names",
+        type: "transform",
+        transform: { expression: "$.steps.findCustomer.response.data.map(c => c.name)" }
+      }
+    },
+    {
+      type: "code",
+      configKey: "code",
+      description: "JS code \u2014 inline source or an external .mjs module under the flow's lib/ folder",
+      fields: {
+        source: { type: "string", required: false, description: 'Inline JS function body (flow context as $, supports await). Mutually exclusive with "module".' },
+        module: { type: "string", required: false, description: 'Relative path to a .mjs file under the flow folder (e.g. "lib/normalize.mjs"). Reads $ from stdin as JSON, writes result to stdout as JSON. Mutually exclusive with "source".' }
+      },
+      example: {
+        id: "processData",
+        name: "Process and enrich data",
+        type: "code",
+        code: { module: "lib/process-data.mjs" }
+      }
+    },
+    {
+      type: "condition",
+      configKey: "condition",
+      description: "If/then/else branching",
+      fields: {
+        expression: { type: "string", required: true, description: "JS expression \u2014 truthy runs then, falsy runs else" },
+        then: { type: "array", required: true, description: "Steps to run when true", stepsArray: true },
+        else: { type: "array", required: false, description: "Steps to run when false", stepsArray: true }
+      },
+      example: {
+        id: "checkFound",
+        name: "Check if customer exists",
+        type: "condition",
+        condition: {
+          expression: "$.steps.search.response.data.length > 0",
+          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" }, data: { text: "Found!" } } }],
+          else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
         }
-        return applyHandlebarsPipe(value, pipe);
       }
-      if (value === void 0 || value === null) return qFlag ? `''` : "";
-      if (typeof value === "object") {
-        console.warn(
-          `[flow] WARNING: Handlebars expression "{{${qFlag ? "q " : ""}${selector}}}" resolved to ${Array.isArray(value) ? "an array" : "an object"} and was stringified as JSON. To pass objects/arrays as native values, use a direct selector without {{ }}: "${selector}"`
-        );
-        const json = JSON.stringify(value);
-        return qFlag ? shellQuote(json) : json;
+    },
+    {
+      type: "loop",
+      configKey: "loop",
+      description: "Iterate over an array with optional concurrency",
+      fields: {
+        over: { type: "string", required: true, description: "Selector resolving to an array" },
+        as: { type: "string", required: true, description: "Variable name for current item ($.loop.<as>)" },
+        indexAs: { type: "string", required: false, description: "Variable name for index" },
+        steps: { type: "array", required: true, description: "Steps to run per iteration", stepsArray: true },
+        maxIterations: { type: "number", required: false, description: "Safety cap (default: no limit)" },
+        maxConcurrency: { type: "number", required: false, description: "Parallel batch size (default: 1 = sequential)" }
+      },
+      example: {
+        id: "processOrders",
+        name: "Process each order",
+        type: "loop",
+        loop: {
+          over: "$.steps.listOrders.response.data",
+          as: "order",
+          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" }, data: { amount: "$.loop.order.total" } } }]
+        }
+      }
+    },
+    {
+      type: "parallel",
+      configKey: "parallel",
+      description: "Run steps concurrently",
+      fields: {
+        steps: { type: "array", required: true, description: "Steps to run in parallel", stepsArray: true },
+        maxConcurrency: { type: "number", required: false, description: "Max concurrent steps (default: 5)" }
+      },
+      example: {
+        id: "lookups",
+        name: "Parallel data lookups",
+        type: "parallel",
+        parallel: {
+          steps: [
+            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" } } },
+            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" } } }
+          ]
+        }
+      }
+    },
+    {
+      type: "file-read",
+      configKey: "fileRead",
+      description: 'Read a file (optional JSON parse). With parseJson:true you may add an optional `schema` (field \u2192 type string, or { type, required, enum, items, minItems/maxItems/length, properties }) enforced at runtime \u2014 a mismatch throws (errorCode SCHEMA_VALIDATION) handled by the step\'s onError. Array constraints (items/minItems/maxItems/length) require type:"array" and properties requires type:"object". Unlike outputSchema (doc/wiring only), this checks the actual parsed value.',
+      fields: {
+        path: { type: "string", required: true, description: "File path to read" },
+        parseJson: { type: "boolean", required: false, description: "Parse contents as JSON (default: false)" }
+      },
+      example: {
+        id: "readConfig",
+        name: "Read config file",
+        type: "file-read",
+        fileRead: {
+          path: "./data/config.json",
+          parseJson: true,
+          schema: {
+            name: { type: "string", required: true },
+            mode: { type: "string", required: true, enum: ["dev", "staging", "prod"] },
+            tags: { type: "array", items: "string", minItems: 1, maxItems: 10 }
+          }
+        }
+      }
+    },
+    {
+      type: "file-write",
+      configKey: "fileWrite",
+      description: "Write or append to a file",
+      fields: {
+        path: { type: "string", required: true, description: "File path to write" },
+        content: { type: "unknown", required: true, description: "Content to write (supports selectors)" },
+        append: { type: "boolean", required: false, description: "Append instead of overwrite (default: false)" }
+      },
+      example: {
+        id: "writeResults",
+        name: "Save results",
+        type: "file-write",
+        fileWrite: { path: "./output/results.json", content: "$.steps.transform.output" }
+      }
+    },
+    {
+      type: "while",
+      configKey: "while",
+      description: "Do-while loop with condition check",
+      fields: {
+        condition: { type: "string", required: true, description: "JS expression checked before each iteration (after first)" },
+        steps: { type: "array", required: true, description: "Steps to run each iteration", stepsArray: true },
+        maxIterations: { type: "number", required: false, description: "Safety cap (default: 100)" }
+      },
+      example: {
+        id: "paginate",
+        name: "Paginate through pages",
+        type: "while",
+        while: {
+          condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
+          maxIterations: 50,
+          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" } } }]
+        }
+      }
+    },
+    {
+      type: "flow",
+      configKey: "flow",
+      description: "Execute a sub-flow (supports composition)",
+      fields: {
+        key: { type: "string", required: true, description: "Flow key or path of the sub-flow" },
+        inputs: { type: "object", required: false, description: "Inputs to pass to the sub-flow (supports selectors)" }
+      },
+      example: {
+        id: "enrich",
+        name: "Run enrichment sub-flow",
+        type: "flow",
+        flow: { key: "enrich-customer", inputs: { email: "$.steps.getCustomer.response.email" } }
+      }
+    },
+    {
+      type: "paginate",
+      configKey: "paginate",
+      description: "Auto-paginate API results into a single array",
+      fields: {
+        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, plus exactly one of `connection` or `connectionKey`)" },
+        pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
+        resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
+        inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
+        maxPages: { type: "number", required: false, description: "Max pages to fetch (default: 10)" }
+      },
+      example: {
+        id: "allMessages",
+        name: "Fetch all Gmail messages",
+        type: "paginate",
+        paginate: {
+          action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" }, queryParams: { maxResults: 100 } },
+          pageTokenField: "nextPageToken",
+          resultsField: "messages",
+          inputTokenParam: "queryParams.pageToken",
+          maxPages: 10
+        }
+      }
+    },
+    {
+      type: "bash",
+      configKey: "bash",
+      description: "Shell command (requires --allow-bash). Output shape: $.steps.<id>.output is the parsed JSON when parseJson:true, otherwise the trimmed stdout string. $.steps.<id>.response always exposes { stdout, stderr, exitCode }.",
+      fields: {
+        command: { type: "string", required: true, description: "Shell command to execute (supports selectors)" },
+        timeout: { type: "number", required: false, description: "Timeout in ms (default: 30000)" },
+        parseJson: { type: "boolean", required: false, description: "Parse stdout as JSON (default: false). When true, $.steps.<id>.output is the parsed object/array; when false, it is the trimmed stdout string." },
+        cwd: { type: "string", required: false, description: "Working directory (supports selectors)" },
+        env: { type: "object", required: false, description: "Additional environment variables" }
+      },
+      example: {
+        id: "analyze",
+        name: "Analyze with Claude",
+        type: "bash",
+        bash: {
+          command: "cat /tmp/data.json | claude --print 'Analyze this data' --output-format json",
+          timeout: 18e4,
+          parseJson: true
+        }
       }
-      const str2 = String(value);
-      return qFlag ? shellQuote(str2) : str2;
-    }
-  );
-}
-function resolveValue(value, context) {
-  if (typeof value === "string") {
-    if (value.startsWith("$.") && !value.includes("{{")) {
-      return resolveSelector(value, context);
-    }
-    if (/\{\{\s*(q\s+)?\$\./.test(value)) {
-      return interpolateString(value, context);
-    }
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => resolveValue(item, context));
-  }
-  if (value && typeof value === "object") {
-    const resolved = {};
-    for (const [k, v] of Object.entries(value)) {
-      resolved[k] = resolveValue(v, context);
     }
-    return resolved;
-  }
-  return value;
-}
-function evaluateExpression(expr, context) {
-  const fn = new Function("$", `return (${expr})`);
-  return fn(context);
-}
-function evaluateCondition(expr, context) {
-  try {
-    return Boolean(evaluateExpression(expr, context));
-  } catch (err) {
-    if (err instanceof TypeError) return false;
-    throw err;
-  }
-}
-var ALLOWED_MODULES = {
-  buffer: () => import("buffer"),
-  crypto: () => import("crypto"),
-  url: () => import("url"),
-  path: () => import("path")
+  ]
 };
-var BLOCKED_MODULES = /* @__PURE__ */ new Set([
-  "fs",
-  "http",
-  "https",
-  "net",
-  "child_process",
-  "process",
-  "os",
-  "cluster",
-  "dgram",
-  "tls",
-  "vm",
-  "worker_threads"
-]);
-function createSandboxedRequire() {
-  const cache = {};
-  return async (moduleName) => {
-    const clean = moduleName.replace(/^node:/, "");
-    if (BLOCKED_MODULES.has(clean)) {
-      throw new Error(`Module "${moduleName}" is blocked in code steps`);
-    }
-    if (!ALLOWED_MODULES[clean]) {
-      throw new Error(`Module "${moduleName}" not available. Allowed: ${Object.keys(ALLOWED_MODULES).join(", ")}`);
-    }
-    if (!cache[clean]) cache[clean] = await ALLOWED_MODULES[clean]();
-    return cache[clean];
-  };
+var _coveredTypes = Object.fromEntries(
+  FLOW_SCHEMA.stepTypes.map((st) => [st.type, true])
+);
+var _stepTypeMap = new Map(
+  FLOW_SCHEMA.stepTypes.map((st) => [st.type, st])
+);
+function getStepTypeDescriptor(type) {
+  return _stepTypeMap.get(type);
 }
-function stripCodeFences(text) {
-  const trimmed = text.trim();
-  const match = trimmed.match(/^```(?:\w*)\s*\n([\s\S]*?)\n\s*```\s*$/);
-  return match ? match[1].trim() : trimmed;
+function getValidStepTypes() {
+  return FLOW_SCHEMA.stepTypes.map((st) => st.type);
 }
-async function executeActionStep(step, context, api, permissions, allowedActionIds, options) {
-  const action = step.action;
-  const platform = resolveValue(action.platform, context);
-  const actionId = resolveValue(action.actionId, context);
-  const hasKey = action.connectionKey !== void 0 && action.connectionKey !== null && action.connectionKey !== "";
-  const hasRef = !!action.connection?.platform;
-  if (hasKey && hasRef) {
-    throw new Error(
-      `Action step "${step.id}" has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
-    );
-  }
-  if (!hasKey && !hasRef) {
-    throw new Error(
-      `Action step "${step.id}" must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").`
-    );
-  }
-  let connectionKey;
-  if (hasKey) {
-    connectionKey = resolveValue(action.connectionKey, context);
-  } else {
-    const ref = resolveValue(action.connection, context);
-    if (!context._connections) {
-      context._connections = await api.listConnections();
+function getNestedStepsKeys() {
+  const result = [];
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    for (const [fieldName, fd] of Object.entries(st.fields)) {
+      if (fd.stepsArray) {
+        result.push({ configKey: st.configKey, fieldName });
+      }
     }
-    const conn = await api.resolveConnection(ref, context._connections);
-    connectionKey = conn.key;
-  }
-  const data = action.data ? resolveValue(action.data, context) : void 0;
-  const pathVars = action.pathVars ? resolveValue(action.pathVars, context) : void 0;
-  const queryParams = action.queryParams ? resolveValue(action.queryParams, context) : void 0;
-  const headers = action.headers ? resolveValue(action.headers, context) : void 0;
-  if (!isActionAllowed(actionId, allowedActionIds)) {
-    throw new Error(`Action "${actionId}" is not in the allowed action list`);
   }
-  const { details: actionDetails } = await resolveActionDetails(api, actionId);
-  if (!isMethodAllowed(actionDetails.method, permissions)) {
-    throw new Error(`Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
-  }
-  if (!options.skipValidation) {
-    const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
-    if (!validation.valid) {
-      const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
-      throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
-    }
-  }
-  const result = await api.executePassthroughRequest({
-    platform,
-    actionId,
-    connectionKey,
-    data,
-    pathVariables: pathVars,
-    queryParams,
-    headers
-  }, actionDetails);
-  return {
-    status: "success",
-    response: result.responseData,
-    output: result.responseData
-  };
+  return result;
 }
-function executeTransformStep(step, context) {
-  const output = evaluateExpression(step.transform.expression, context);
-  return { status: "success", output, response: output };
+function generateFlowGuide() {
+  const validTypes = getValidStepTypes();
+  const sections = [];
+  sections.push(`# One Flows \u2014 Reference
+
+## Overview
+
+Workflows live in \`.one/flows/\` (relative to your current working directory \u2014 the CLI does NOT walk up parent directories or fall back to a global location) and chain actions across platforms. Two layouts are supported:
+
+- **Folder layout (REQUIRED for new flows)** \u2014 \`.one/flows/<key>/flow.json\`, with an optional \`lib/\` subfolder for JavaScript modules. This is like a skill: the folder groups the JSON spec with any JavaScript modules it needs, so the whole flow is shareable. **Always create new flows in this layout.**
+- **Single-file layout (DEPRECATED)** \u2014 \`.one/flows/<key>.flow.json\`. Still loads and runs for backward compatibility, but is deprecated. Do not create new flows in this layout. When editing an existing single-file flow, migrate it to the folder layout: move \`<key>.flow.json\` to \`<key>/flow.json\` and extract any non-trivial \`code.source\` blocks into \`<key>/lib/*.mjs\` modules.
+
+**Subdirectory groups** \u2014 Flows can be organized into subdirectories: \`.one/flows/<group>/<key>/flow.json\`. For example:
+\`\`\`
+.one/flows/
+  research/
+    company-research/flow.json
+    competitor-research/flow.json
+  deal-ops/
+    deal-log/flow.json
+\`\`\`
+Reference grouped flows with \`group/key\` (e.g. \`one flow execute research/company-research\`) or just the bare key if it's unique (e.g. \`one flow execute company-research\`). Create grouped flows with \`one flow create research/company-research --definition ...\`. \`flow list\` shows the group prefix.
+
+When resolving a flow by key, the CLI checks the folder layout first, then the deprecated legacy file, then scans group subdirectories. The \`loadFlow\` helper in agent integrations behaves the same.
+
+## Before you execute a flow you did NOT author \u2014 READ THIS
+
+**Agents: always inspect a flow before running it.** Nothing about a flow's runtime requirements is guessable from its name. Before \`flow execute\`, do one of these:
+
+1. Run \`one --agent flow list\` \u2014 the JSON output includes \`requiresBash\`, \`usesCodeModules\`, \`inputs\` (with \`autoResolvable\` flags), \`stepTypes\`, and the flow's \`description\`. This is the fastest path.
+2. Read the flow's \`description\` field directly from the JSON. Flow authors are required (see "Author conventions" below) to state any \`--allow-bash\` requirement and any non-auto-resolving inputs in the description.
+3. Run \`one --agent flow execute <key> --dry-run\` to see the resolved inputs and step plan without side effects.
+
+If you skip this step you will hit errors like *"Workflow X contains bash steps. Re-run with --allow-bash."* \u2014 the CLI now pre-flights and fails fast, so you won't waste a long run, but the error is still avoidable by reading first.
+
+## Author conventions \u2014 WRITE flows that are safe to execute blind
+
+When you create a flow, its \`description\` field is the contract with future executors (human or agent). It MUST state:
+
+- **\`--allow-bash\` if any step is type \`bash\`.** Example: *"Fetches recent Gmail threads and summarizes them with Claude Haiku. Requires \`--allow-bash\`."*
+- **Every input that does NOT have a \`connection\` hint.** Connection inputs auto-resolve when exactly one matching connection exists; everything else must be passed via \`-i name=value\` and the description must name it.
+- **Any files/directories the flow writes to** so operators know what will be modified on disk.
+
+A good description is one paragraph. If a flow's description doesn't tell you how to run it, treat that as a bug in the flow and fix it.
+
+## Commands
+
+\`\`\`bash
+one --agent flow create <key> --definition '<json>'              # Create (or --definition @file.json)
+one --agent flow create <key> --definition @flow.json            # Create from file
+one --agent flow create <group/key> --definition '<json>'        # Create in a subdirectory group
+one --agent flow list                                            # List (shows group prefixes)
+one --agent flow validate <key>                                  # Validate
+one --agent flow execute <key> -i name=value                     # Execute (bare key)
+one --agent flow execute <group/key> -i name=value               # Execute (namespaced key)
+one --agent flow execute <key> --dry-run --mock                  # Test with mock data
+one --agent flow execute <key> --allow-bash                      # Enable bash steps
+one --agent flow runs [flowKey]                                  # List past runs
+one --agent flow resume <runId>                                  # Resume failed run
+one --agent flow scaffold [template]                             # Generate a starter template
+\`\`\`
+
+You can also write the JSON file directly to \`.one/flows/<key>/flow.json\` (or \`.one/flows/<group>/<key>/flow.json\` for grouped flows) \u2014 often easier than passing large JSON via --definition. (The legacy \`.one/flows/<key>.flow.json\` single-file location is deprecated; don't use it for new flows.)
+
+## Code modules (flow \`lib/\` folder)
+
+A \`code\` step can either inline JS (\`code.source\`) or reference an external \`.mjs\` module (\`code.module\`). Modules live under the flow's \`lib/\` folder and run as a child \`node\` process:
+
+\`\`\`
+.one/flows/my-flow/
+\u251C\u2500\u2500 flow.json
+\u2514\u2500\u2500 lib/
+    \u2514\u2500\u2500 process-data.mjs
+\`\`\`
+
+**Module contract:** the flow context \`$\` is piped to stdin as JSON; the module writes its result to stdout as JSON. That's the whole interface \u2014 no framework imports, no magic.
+
+\`\`\`js
+// lib/process-data.mjs
+const $ = JSON.parse(await new Response(process.stdin).text());
+const items = $.steps.fetch.response.data ?? [];
+process.stdout.write(JSON.stringify(items.filter(i => i.active)));
+\`\`\`
+
+\`\`\`json
+{
+  "id": "processData",
+  "name": "Process and enrich data",
+  "type": "code",
+  "code": { "module": "lib/process-data.mjs" }
 }
-async function executeCodeStep(step, context, options) {
-  const config = step.code;
-  if (config.module) {
-    const output = await executeCodeModule(step.id, config.module, context, options);
-    return { status: "success", output, response: output };
+\`\`\`
+
+Modules are full Node processes \u2014 \`fs\`, \`https\`, any npm package installed in the host project, etc. are all available. Use this for anything non-trivial; keep \`code.source\` for one-liners.
+
+**Step output shape:** whatever JSON a module writes to stdout becomes both \`$.steps.<id>.output\` and \`$.steps.<id>.response\` (aliases). Downstream steps can reference either; convention is to use \`.output\` for code/transform step results and \`.response\` for action step API payloads.
+
+## Migrating a legacy single-file flow to the folder layout
+
+If you're editing an existing \`.one/flows/<key>.flow.json\`, migrate it \u2014 it takes a minute and the result is cleaner. Checklist:
+
+1. \`mkdir -p .one/flows/<key>/lib\`
+2. Move the file: \`mv .one/flows/<key>.flow.json .one/flows/<key>/flow.json\`
+3. For each non-trivial \`code\` step with inline \`source\`, extract it into \`lib/<step-id>.mjs\` (see translation pattern below) and swap the step config from \`{ "source": "..." }\` to \`{ "module": "lib/<step-id>.mjs" }\`. One-liners can stay inline.
+4. Validate: \`one --agent flow validate <key>\`.
+5. Run it and confirm behavior is unchanged.
+
+**Inline source \u2192 module translation pattern.** Inline \`code.source\` is an async function body where \`$\` is already in scope and you \`return\` the result. A module is a standalone script where you read \`$\` from stdin and write the result to stdout as JSON. The transform is mechanical:
+
+Before (inline \`code.source\`):
+\`\`\`js
+const items = $.steps.fetch.response.data;
+const active = items.filter(i => i.active);
+return { active, count: active.length };
+\`\`\`
+
+After (\`lib/<step-id>.mjs\`):
+\`\`\`js
+const $ = JSON.parse(await new Response(process.stdin).text());
+const items = $.steps.fetch.response.data;
+const active = items.filter(i => i.active);
+process.stdout.write(JSON.stringify({ active, count: active.length }));
+\`\`\`
+
+The only differences: (1) prepend the stdin-read line, (2) replace \`return X\` with \`process.stdout.write(JSON.stringify(X))\`. That's it.
+
+## Building a Workflow
+
+1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
+2. **Discover connections** \u2014 \`one --agent connection list\`
+3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
+4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
+5. **Validate** \u2014 \`one --agent flow validate <key>\`
+6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\``);
+  sections.push(`## Flow JSON Schema
+
+\`\`\`json
+{
+  "key": "my-workflow",
+  "name": "My Workflow",
+  "description": "What this flow does",
+  "version": "1",
+  "inputs": {
+    "param": {
+      "type": "string",
+      "required": true,
+      "description": "A user parameter"
+    }
+  },
+  "steps": [
+    {
+      "id": "stepId",
+      "name": "Human-readable step name",
+      "type": "action",
+      "action": {
+        "platform": "stripe",
+        "actionId": "conn_mod_def::xxx::yyy",
+        "connection": { "platform": "stripe" },
+        "data": { "query": "{{$.input.param}}" }
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Top-level fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.flowFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
   }
-  if (typeof config.source !== "string") {
-    throw new Error(`Code step "${step.id}" must define either "source" or "module"`);
+  sections.push(`
+### Input declarations
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.inputFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
   }
-  const AsyncFunction = Object.getPrototypeOf(async function() {
-  }).constructor;
-  const sandboxedRequire = createSandboxedRequire();
-  const sourceURL = `code:${step.id}`;
-  const taggedSource = `${config.source}
-//# sourceURL=${sourceURL}`;
-  const fn = new AsyncFunction("$", "require", taggedSource);
-  try {
-    const output = await fn(context, sandboxedRequire);
-    return { status: "success", output, response: output };
-  } catch (err) {
-    throw rewriteCodeStepError(err, step.id, config.source, sourceURL);
+  sections.push(`
+### Step fields (all steps)
+
+Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines which config object is required.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.stepCommonFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
   }
-}
-function rewriteCodeStepError(err, stepId, source, sourceURL) {
-  if (!(err instanceof Error)) return new Error(String(err));
-  const WRAPPER_LINE_OFFSET = 2;
-  const sourceLines = source.split("\n");
-  const stack = err.stack || "";
-  const re = new RegExp(`${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:(\\d+):(\\d+)`);
-  const match = stack.match(re);
-  if (!match) {
-    err.message = `Code step "${stepId}" failed: ${err.message}`;
-    return err;
+  sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(" | ")}", "retries": 3, "retryDelayMs": 1000, "backoff": "fixed \\| exponential \\| exponential-jitter", "maxDelayMs": 30000, "retryOn": [429, 502, "ETIMEDOUT"], "failFastOn": [401, 403, 404] }\`. \`retryOn\`/\`failFastOn\` (cli#53) make retries conditional on the error code/status \u2014 \`failFastOn\` matches skip the retry entirely. |`);
+  sections.push(`
+## Step Types
+
+**IMPORTANT:** Each step type requires a config object nested under a specific key. The type name and config key differ for some types (noted below).
+
+| Type | Config Key | Description |
+|------|-----------|-------------|`);
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    const keyNote = st.type !== st.configKey ? ` \u26A0\uFE0F` : "";
+    sections.push(`| \`${st.type}\` | \`${st.configKey}\`${keyNote} | ${st.description} |`);
   }
-  const wrappedLine = parseInt(match[1], 10);
-  const col = parseInt(match[2], 10);
-  const userLine = wrappedLine - WRAPPER_LINE_OFFSET;
-  const lineContent = sourceLines[userLine - 1] ?? "";
-  const trimmed = lineContent.trim();
-  err.message = `Code step "${stepId}" failed at line ${userLine}:${col}
-  ${trimmed}
-  ${err.message}`;
-  err.stack = stack.replace(
-    new RegExp(`(${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:)(\\d+)`, "g"),
-    (_m, prefix, l) => `${prefix}${parseInt(l, 10) - WRAPPER_LINE_OFFSET}`
-  );
-  return err;
-}
-async function executeCodeModule(stepId, modulePath, context, options) {
-  const rootDir = options.rootDir;
-  if (!rootDir) {
-    throw new Error(`Code step "${stepId}" uses module "${modulePath}" but no flow rootDir is available. Flows that use code modules must be loaded via loadFlowWithMeta.`);
-  }
-  if (path2.isAbsolute(modulePath)) {
-    throw new Error(`Code module path must be relative to the flow root, got absolute: "${modulePath}"`);
-  }
-  const absPath = path2.resolve(rootDir, modulePath);
-  const relFromRoot = path2.relative(rootDir, absPath);
-  if (relFromRoot.startsWith("..") || path2.isAbsolute(relFromRoot)) {
-    throw new Error(`Code module "${modulePath}" resolves outside the flow directory`);
+  sections.push(`
+## Step Type Reference`);
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    sections.push(`
+### \`${st.type}\` \u2014 ${st.description}`);
+    if (st.type !== st.configKey) {
+      sections.push(`
+> **Note:** Type is \`"${st.type}"\` but config key is \`"${st.configKey}"\` (camelCase).`);
+    }
+    sections.push(`
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+    for (const [name, fd] of Object.entries(st.fields)) {
+      sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
+    }
+    sections.push(`
+\`\`\`json
+${JSON.stringify(st.example, null, 2)}
+\`\`\``);
   }
-  if (!fs2.existsSync(absPath)) {
-    throw new Error(`Code module not found: ${absPath}`);
+  sections.push(`
+## Selectors
+
+| Pattern | Resolves To |
+|---------|-------------|
+| \`$.input.paramName\` | Input value |
+| \`$.steps.stepId.response\` | Full API response |
+| \`$.steps.stepId.response.data[0].email\` | Nested field |
+| \`$.steps.stepId.response.data[*].id\` | Wildcard array map |
+| \`$.env.MY_VAR\` | Environment variable |
+| \`$.loop.item\` / \`$.loop.i\` | Loop iteration |
+| \`"Hello {{$.steps.getUser.response.name}}"\` | String interpolation |
+
+### Context-aware escape pipes (cli#53)
+
+Handlebars interpolations support pipe-based escaping for safe embedding into shell commands, JSON, URLs, markdown, or HTML:
+
+| Pipe | Effect |
+|------|--------|
+| \`{{ $.x \\| json }}\`  | \`JSON.stringify\` (handles quotes, newlines, unicode) |
+| \`{{ $.x \\| shell }}\` | POSIX-shell-quote \u2014 safe inside bash arguments |
+| \`{{ $.x \\| url }}\`   | \`encodeURIComponent\` |
+| \`{{ $.x \\| md }}\`    | Escape markdown structural characters |
+| \`{{ $.x \\| html }}\`  | Entity-escape \`& < > " '\` |
+
+Pipes can be applied to any value (objects/arrays are JSON-stringified first for shell/url/md/html). An unknown pipe name throws at runtime. The legacy \`{{q $.x}}\` shell-quote helper still works but new flows should prefer \`{{$.x | shell}}\`.
+
+### When to use bare selectors vs \`{{...}}\` interpolation
+
+- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, the \`tag\` (or \`platform\`) inside \`connection\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
+- **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
+- **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
+
+### Selectors vs expressions
+
+Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`, \`connection.tag\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
+
+\`\`\`json
+{ "inputs": { "maxResults": { "type": "number", "default": 10 } } }
+\`\`\`
+
+The \`if\`, \`unless\`, \`condition.expression\`, \`while.condition\`, \`transform.expression\`, and \`code.source\` fields **do** support full JavaScript expressions (e.g., \`$.input.email && $.input.email.length > 0\`).
+
+### \`output\` vs \`response\` on step results
+
+Every completed step produces both \`output\` and \`response\`:
+- **Action steps**: \`response\` is the raw API response. \`output\` is the same as \`response\`.
+- **Code/transform steps**: \`output\` is the return value. \`response\` is an alias for \`output\`.
+- **In practice**: Use \`$.steps.stepId.response\` for action steps (API data) and \`$.steps.stepId.output\` for code/transform steps (computed data). Both work interchangeably, but using the semantically correct one makes flows easier to read.
+
+### Step result metadata (\`status\`, \`error\`, \`errorCode\`)
+
+Every step result also exposes execution metadata that downstream steps can inspect:
+
+| Field | Values | When set |
+|-------|--------|----------|
+| \`$.steps.X.status\` | \`"success"\` \\| \`"skipped"\` \\| \`"failed"\` \\| \`"timeout"\` | Always |
+| \`$.steps.X.error\` | error message string | When status is \`failed\` or \`timeout\` |
+| \`$.steps.X.errorCode\` | machine-readable code (e.g. \`"TIMEOUT"\`) | When the error has a code |
+| \`$.steps.X.durationMs\` | number | Always |
+| \`$.steps.X.retries\` | number | When the step was retried |
+
+This lets downstream steps distinguish \`skipped\` (\`if\` condition false) from \`failed\` (error, \`onError:continue\`) from \`timeout\` (exceeded \`timeoutMs\`) \u2014 e.g. \`"if": "$.steps.enrichment.status === 'timeout'"\` to retry with a longer window.
+
+### Sub-flow output (flattened)
+
+When a step has \`type: "flow"\`, the sub-flow's final step output is flattened onto the parent step's \`output\`:
+
+\`\`\`jsonc
+// Sub-flow "sub-consts" has a final step "load" that returns { CHART_URL, API_KEY }
+
+// Preferred (flattened):
+"{{$.steps.loadConfig.output.CHART_URL}}"
+
+// Legacy nested path (still works for backward compatibility):
+"{{$.steps.loadConfig.output.load.output.CHART_URL}}"
+
+// Escape hatch for programmatic access to the full sub-flow steps map:
+"{{$.steps.loadConfig.output._steps.load.output.CHART_URL}}"
+\`\`\`
+
+If a sub-step id collides with a flattened field name, the flattened field wins and the engine emits a \`flow:warning\` event.
+
+## Error Handling
+
+\`\`\`json
+{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
+\`\`\`
+
+Strategies: \`${FLOW_SCHEMA.errorStrategies.join("`, `")}\`
+
+**Conditional retry (cli#53):** add \`retryOn\` and/or \`failFastOn\` to discriminate transient errors from permanent ones. \`failFastOn\` takes precedence; \`retryOn\` (when set) requires a match for the retry to happen. Numbers match against any 3-digit substring of the error message (HTTP statuses); strings match against \`error.errorCode\` exactly OR as a case-insensitive substring of the message.
+
+\`\`\`json
+{
+  "onError": {
+    "strategy": "retry",
+    "retries": 4,
+    "backoff": "exponential",
+    "retryOn":    [429, 502, 503, "ETIMEDOUT", "ECONNRESET"],
+    "failFastOn": [401, 403, 404]
   }
-  const { env: _omitEnv, ...safeContext } = context;
-  void _omitEnv;
-  const stdinPayload = JSON.stringify(safeContext);
-  return await new Promise((resolve2, reject) => {
-    const child = spawn(process.execPath, [absPath], {
-      cwd: rootDir,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    child.stdout.on("data", (c) => stdoutChunks.push(c));
-    child.stderr.on("data", (c) => stderrChunks.push(c));
-    child.on("error", (err) => reject(err));
-    child.on("close", (code) => {
-      const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
-      const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-      if (code !== 0) {
-        reject(new Error(`Code module "${modulePath}" exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
-        return;
-      }
-      const trimmed = stdout.trim();
-      if (trimmed === "") {
-        resolve2(void 0);
-        return;
-      }
-      try {
-        resolve2(JSON.parse(stripCodeFences(trimmed)));
-      } catch (err) {
-        reject(new Error(`Code module "${modulePath}" did not print valid JSON to stdout: ${err.message}`));
-      }
-    });
-    child.stdin.write(stdinPayload);
-    child.stdin.end();
-  });
 }
-async function executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
-  const condition = step.condition;
-  const result = evaluateCondition(condition.expression, context);
-  const branch = result ? condition.then : condition.else || [];
-  const branchResults = await executeSteps(branch, context, api, permissions, allowedActionIds, options, void 0, flowStack);
-  return {
-    status: "success",
-    output: { conditionResult: !!result, stepsExecuted: branchResults },
-    response: { conditionResult: !!result }
-  };
+\`\`\`
+
+## Step Output Contracts (\`outputSchema\`, cli#59)
+
+Declare a step's output shape so the validator catches downstream field-name typos at flow load time:
+
+\`\`\`json
+{
+  "id": "research",
+  "type": "flow",
+  "flow": { "key": "company-research" },
+  "outputSchema": {
+    "company": "string",
+    "charCount": "number",
+    "quality": { "confidence": "string", "score": "number" }
+  }
 }
-async function executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
-  const loop = step.loop;
-  const items = resolveValue(loop.over, context);
-  if (!Array.isArray(items)) {
-    throw new Error(`Loop "over" must resolve to an array, got ${typeof items}`);
+\`\`\`
+
+Field types: \`string\`, \`number\`, \`boolean\`, \`object\`, \`array\`, \`unknown\`. Nested objects describe sub-fields. Any \`$.steps.<id>.output.<field>\` reference from a downstream step is checked against the schema; unknown fields fail validation. The runtime engine does not enforce the schema \u2014 it's a documentation / wiring-bug aid.
+
+## Bash structured env vars (cli#54)
+
+A \`bash\` step's \`env\` map accepts two structured forms in addition to plain strings:
+
+\`\`\`json
+{
+  "type": "bash",
+  "bash": {
+    "env": {
+      "PAYLOAD_FILE": { "json": "$.steps.buildConfig.output" },
+      "COMPANY":      { "shell": "$.input.companyName" }
+    },
+    "command": "curl -X POST $ENDPOINT -d @$PAYLOAD_FILE && echo \\"$COMPANY\\""
   }
-  const maxIterations = loop.maxIterations || 1e3;
-  const bounded = items.slice(0, maxIterations);
-  const savedLoop = { ...context.loop };
-  const iterationResults = [];
-  if (loop.maxConcurrency && loop.maxConcurrency > 1) {
-    const results2 = new Array(bounded.length);
-    for (let batchStart = 0; batchStart < bounded.length; batchStart += loop.maxConcurrency) {
-      const batch = bounded.slice(batchStart, batchStart + loop.maxConcurrency);
-      const batchResults = await Promise.all(
-        batch.map(async (item, batchIdx) => {
-          const i = batchStart + batchIdx;
-          const iterContext = {
-            ...context,
-            loop: {
-              [loop.as]: item,
-              item,
-              i,
-              ...loop.indexAs ? { [loop.indexAs]: i } : {}
-            },
-            steps: { ...context.steps }
-          };
-          const beforeKeys = new Set(Object.keys(iterContext.steps));
-          await executeSteps(loop.steps, iterContext, api, permissions, allowedActionIds, options, void 0, flowStack);
-          const iterResult = {};
-          for (const [key, val] of Object.entries(iterContext.steps)) {
-            if (!beforeKeys.has(key) || iterContext.steps[key] !== context.steps[key]) {
-              iterResult[key] = val;
-            }
-          }
-          iterationResults[i] = iterResult;
-          Object.assign(context.steps, iterContext.steps);
-          return iterContext.loop[loop.as];
-        })
-      );
-      for (let j = 0; j < batchResults.length; j++) {
-        results2[batchStart + j] = batchResults[j];
-      }
-    }
-    context.loop = savedLoop;
-    return {
-      status: "success",
-      output: results2,
-      response: { items: results2, iterations: iterationResults }
-    };
-  }
-  const results = [];
-  for (let i = 0; i < bounded.length; i++) {
-    context.loop = {
-      [loop.as]: bounded[i],
-      item: bounded[i],
-      i
-    };
-    if (loop.indexAs) {
-      context.loop[loop.indexAs] = i;
+}
+\`\`\`
+
+- \`{ "json": <selector|value> }\` \u2014 JSON-serialized to a temp file; the env var holds the temp file path. Auto-cleaned after the step runs (success or failure).
+- \`{ "shell": <selector|value> }\` \u2014 exposed as a plain string env var; reference inside bash double quotes (\`"$VAR"\`).
+- A plain string is the legacy form (interpolated as-is, caller is responsible for escaping).
+
+## Dynamic sub-flow dispatch (cli#61)
+
+A \`flow\` step's \`flow.key\` accepts selectors and Handlebars interpolations, so a single orchestrator can route to different sub-flows at runtime:
+
+\`\`\`json
+{ "type": "flow", "flow": { "key": "{{$.input.target}}", "inputs": { "company": "$.input.company" } } }
+\`\`\`
+
+Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
+
+## Connection Resolution \u2014 late-bound by default
+
+Action steps reference a platform connection in one of two forms:
+
+\`\`\`json
+// preferred \u2014 late-bound, survives re-auth
+"connection": { "platform": "gmail" }
+
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 works for backwards compat, breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The engine resolves the \`connection\` ref once per flow run (cached for the run's lifetime) by calling \`listConnections\` and matching on platform + optional tag. Resolution errors fail the step with a clear message \u2014 \`No connection found for platform "X"\`, \`Multiple "X" connections found (tags: ...). Add a "tag" field\`, or \`No "X" connection has tag "Y"\`.
+
+Both \`platform\` and \`tag\` accept \`$.input.x\` selectors so a flow can be parameterised per-execution (e.g. multi-tenant orchestrators that pass the user's email as the tag).
+
+The validator rejects any action that sets both forms or neither, at \`flow validate\` and \`flow execute\` time.
+
+### Optional input metadata: connection-key auto-resolve (legacy)
+
+For flows that still use literal \`connectionKey\` strings via inputs, an input declaration can carry a \`"connection": { "platform": "..." }\` hint so \`flow execute\` auto-fills a single matching connection's key. New flows don't need this \u2014 switch the action's connection form to \`{ platform, tag? }\` and skip the input entirely.
+
+## Complete Example: Fetch Data, Transform, Notify
+
+\`\`\`json
+{
+  "key": "contacts-to-slack",
+  "name": "CRM Contacts Summary to Slack",
+  "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
+  "version": "1",
+  "inputs": {
+    "slackChannel": {
+      "type": "string",
+      "required": true,
+      "description": "Slack channel name or ID"
     }
-    const beforeKeys = new Set(Object.keys(context.steps));
-    await executeSteps(loop.steps, context, api, permissions, allowedActionIds, options, void 0, flowStack);
-    const iterResult = {};
-    for (const [key, val] of Object.entries(context.steps)) {
-      if (!beforeKeys.has(key) || context.steps[key] !== (beforeKeys.has(key) ? void 0 : val)) {
-        iterResult[key] = val;
+  },
+  "steps": [
+    {
+      "id": "fetchContacts",
+      "name": "Fetch recent contacts",
+      "type": "action",
+      "action": {
+        "platform": "attio",
+        "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
+        "connection": { "platform": "attio" },
+        "queryParams": { "limit": "10" }
+      }
+    },
+    {
+      "id": "buildSummary",
+      "name": "Build formatted summary",
+      "type": "code",
+      "code": {
+        "source": "const contacts = $.steps.fetchContacts.response.data || [];\\nconst lines = contacts.map((c, i) => \`\${i+1}. \${c.name || 'Unknown'} \u2014 \${c.email || 'no email'}\`);\\nreturn { summary: \`Found \${contacts.length} contacts:\\n\${lines.join('\\n')}\` };"
+      }
+    },
+    {
+      "id": "notifySlack",
+      "name": "Post summary to Slack",
+      "type": "action",
+      "action": {
+        "platform": "slack",
+        "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
+        "connection": { "platform": "slack" },
+        "data": {
+          "channel": "$.input.slackChannel",
+          "text": "{{$.steps.buildSummary.output.summary}}"
+        }
       }
     }
-    iterationResults.push(iterResult);
-    results.push(context.loop[loop.as]);
+  ]
+}
+\`\`\`
+
+Note: Action IDs above are placeholders. Always use \`one --agent actions search <platform> "<query>"\` to find real IDs.
+
+## AI-Augmented Pattern
+
+For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
+
+1. \`file-write\` \u2014 save data to temp file
+2. \`bash\` \u2014 \`claude --print\` analyzes it (\`parseJson: true\`, \`timeout: 180000\`)
+3. \`code\` \u2014 parse and structure the output
+
+Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
+
+## Notes
+
+- Connection keys are **inputs**, not hardcoded
+- Action IDs in examples are placeholders \u2014 always use \`actions search\`
+- Inline \`code.source\` steps allow \`require('crypto' | 'buffer' | 'url' | 'path')\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
+- For anything beyond one-liners, use \`code.module\` to point at a \`.mjs\` file in the flow's \`lib/\` folder \u2014 runs as a child \`node\` process with full Node APIs, reads \`$\` from stdin, writes JSON to stdout
+- Bash steps require \`--allow-bash\` flag
+- State is persisted after every step \u2014 resume picks up where it left off`);
+  return sections.join("\n");
+}
+
+// src/lib/flow-engine.ts
+var execAsync = promisify(exec);
+function sleep2(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+var StepTimeoutError = class extends Error {
+  errorCode = "TIMEOUT";
+  constructor(stepId, timeoutMs) {
+    super(`Step "${stepId}" exceeded timeout of ${timeoutMs}ms`);
+    this.name = "StepTimeoutError";
   }
-  context.loop = savedLoop;
-  return {
-    status: "success",
-    output: results,
-    response: { items: results, iterations: iterationResults }
-  };
+};
+function withTimeout(promise, timeoutMs, stepId) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new StepTimeoutError(stepId, timeoutMs)), timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
 }
-async function executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
-  const parallel = step.parallel;
-  const maxConcurrency = parallel.maxConcurrency || 5;
-  const steps = parallel.steps;
-  const results = [];
-  for (let i = 0; i < steps.length; i += maxConcurrency) {
-    const batch = steps.slice(i, i + maxConcurrency);
-    const batchResults = await Promise.all(
-      batch.map((s) => executeSingleStep(s, context, api, permissions, allowedActionIds, options, flowStack))
-    );
-    for (let j = 0; j < batch.length; j++) {
-      context.steps[batch[j].id] = batchResults[j];
-    }
-    results.push(...batchResults);
+var FileReadSchemaError = class extends Error {
+  errorCode = "SCHEMA_VALIDATION";
+  constructor(stepId, violations) {
+    super(`Step "${stepId}" output failed schema validation: ${violations.join("; ")}`);
+    this.name = "FileReadSchemaError";
+  }
+};
+function asFieldSchema(node) {
+  return typeof node === "string" ? { type: node } : node;
+}
+function actualType(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}
+function matchesLeafType(v, t) {
+  switch (t) {
+    case "unknown":
+      return true;
+    case "null":
+      return v === null;
+    case "array":
+      return Array.isArray(v);
+    case "object":
+      return v !== null && typeof v === "object" && !Array.isArray(v);
+    default:
+      return typeof v === t;
   }
-  return { status: "success", output: results, response: results };
 }
-function executeFileReadStep(step, context) {
-  const config = step.fileRead;
-  const filePath = resolveValue(config.path, context);
-  const resolvedPath = path2.resolve(filePath);
-  const content = fs2.readFileSync(resolvedPath, "utf-8");
-  const output = config.parseJson ? JSON.parse(stripCodeFences(content)) : content;
-  return { status: "success", output, response: output };
+function isPlainObjectValue(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
 }
-function executeFileWriteStep(step, context) {
-  const config = step.fileWrite;
-  const filePath = resolveValue(config.path, context);
-  const content = resolveValue(config.content, context);
-  const resolvedPath = path2.resolve(filePath);
-  const dir = path2.dirname(resolvedPath);
-  if (!fs2.existsSync(dir)) {
-    fs2.mkdirSync(dir, { recursive: true });
+function collectFileReadViolations(value, schema, basePath, out) {
+  if (!isPlainObjectValue(value)) {
+    const where = basePath ? `at "${basePath.replace(/\.$/, "")}"` : "at the root";
+    out.push(`expected an object ${where} but got ${actualType(value)}`);
+    return;
   }
-  const stringContent = typeof content === "string" ? content : JSON.stringify(content, null, 2);
-  if (config.append) {
-    fs2.appendFileSync(resolvedPath, stringContent);
-  } else {
-    fs2.writeFileSync(resolvedPath, stringContent);
+  const obj = value;
+  for (const [field, raw] of Object.entries(schema)) {
+    const rule = asFieldSchema(raw);
+    const path4 = `${basePath}${field}`;
+    const present = Object.prototype.hasOwnProperty.call(obj, field) && obj[field] !== void 0;
+    if (!present) {
+      if (rule.required) out.push(`field "${path4}" is required but missing`);
+      continue;
+    }
+    checkFileReadRule(obj[field], rule, path4, out);
   }
-  return { status: "success", output: { path: resolvedPath, bytesWritten: stringContent.length }, response: { path: resolvedPath } };
 }
-async function executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
-  const config = step.while;
-  const maxIterations = config.maxIterations ?? 100;
-  const results = [];
-  context.steps[step.id] = {
-    status: "success",
-    output: { lastResult: void 0, iteration: 0, results: [] }
-  };
-  for (let iteration = 0; iteration < maxIterations; iteration++) {
-    if (iteration > 0) {
-      const conditionResult = evaluateCondition(config.condition, context);
-      if (!conditionResult) break;
+function checkFileReadRule(value, rule, path4, out) {
+  if (rule.type && !matchesLeafType(value, rule.type)) {
+    out.push(`field "${path4}" expected ${rule.type} but got ${actualType(value)}`);
+    return;
+  }
+  if (Array.isArray(rule.enum) && !rule.enum.some((e) => e === value)) {
+    out.push(`field "${path4}" value ${JSON.stringify(value)} is not one of [${rule.enum.map((e) => JSON.stringify(e)).join(", ")}]`);
+  }
+  const hasArrayConstraint = rule.items !== void 0 || rule.minItems !== void 0 || rule.maxItems !== void 0 || rule.length !== void 0;
+  if (hasArrayConstraint) {
+    if (!Array.isArray(value)) {
+      if (!rule.type) out.push(`field "${path4}" expected array but got ${actualType(value)}`);
+    } else {
+      if (rule.length !== void 0 && value.length !== rule.length) {
+        out.push(`field "${path4}" expected array of length ${rule.length} but got length ${value.length}`);
+      }
+      if (rule.minItems !== void 0 && value.length < rule.minItems) {
+        out.push(`field "${path4}" expected at least ${rule.minItems} item${rule.minItems === 1 ? "" : "s"} but got ${value.length}`);
+      }
+      if (rule.maxItems !== void 0 && value.length > rule.maxItems) {
+        out.push(`field "${path4}" expected at most ${rule.maxItems} item${rule.maxItems === 1 ? "" : "s"} but got ${value.length}`);
+      }
+      if (rule.items !== void 0) {
+        const itemRule = asFieldSchema(rule.items);
+        value.forEach((el, i) => checkFileReadRule(el, itemRule, `${path4}[${i}]`, out));
+      }
+    }
+  }
+  if (rule.properties) {
+    if (isPlainObjectValue(value)) {
+      collectFileReadViolations(value, rule.properties, `${path4}.`, out);
+    } else if (!rule.type) {
+      out.push(`field "${path4}" expected object but got ${actualType(value)}`);
     }
-    await executeSteps(config.steps, context, api, permissions, allowedActionIds, options, void 0, flowStack);
-    const lastStepId = config.steps[config.steps.length - 1]?.id;
-    const lastResult = lastStepId ? context.steps[lastStepId]?.output : void 0;
-    results.push(lastResult);
-    context.steps[step.id] = {
-      status: "success",
-      output: { lastResult, iteration, results }
-    };
   }
-  return {
-    status: "success",
-    output: { lastResult: results[results.length - 1], iteration: results.length, results },
-    response: { iterations: results.length, results }
-  };
 }
-async function executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
-  const config = step.flow;
-  const resolvedKey = resolveValue(config.key, context);
-  const resolvedInputs = config.inputs ? resolveValue(config.inputs, context) : {};
-  if (flowStack.includes(resolvedKey)) {
-    throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
-  }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-7VRNSKWU.js");
-  const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
-  const subContext = await executeFlow(
-    subFlow,
-    resolvedInputs,
-    api,
-    permissions,
-    allowedActionIds,
-    { ...options, rootDir: subRootDir },
-    void 0,
-    [...flowStack, resolvedKey]
-  );
-  const finalStep = subFlow.steps[subFlow.steps.length - 1];
-  const finalOutput = finalStep ? subContext.steps[finalStep.id]?.output : void 0;
-  let flattenedOutput;
-  if (finalOutput && typeof finalOutput === "object" && !Array.isArray(finalOutput)) {
-    const collisions = Object.keys(finalOutput).filter(
-      (k) => k in subContext.steps
-    );
-    if (collisions.length > 0) {
-      options.onEvent?.({
-        event: "flow:warning",
-        message: `Sub-flow "${resolvedKey}" final step output fields [${collisions.join(", ")}] collide with sub-step ids \u2014 flattened fields take precedence.`
-      });
+function assertMatchesFileReadSchema(value, schema, stepId) {
+  const violations = [];
+  collectFileReadViolations(value, schema, "", violations);
+  if (violations.length > 0) throw new FileReadSchemaError(stepId, violations);
+}
+function shouldRetryError(err, onError) {
+  if (!onError) return { retry: false };
+  const message = err instanceof Error ? err.message : String(err);
+  const errorCode = err?.errorCode;
+  const matches = (entry) => {
+    if (typeof entry === "number") {
+      const re = new RegExp(`\\b${entry}\\b`);
+      return re.test(message);
     }
-    flattenedOutput = {
-      ...subContext.steps,
-      ...finalOutput,
-      _steps: subContext.steps
-    };
-  } else {
-    flattenedOutput = {
-      ...subContext.steps,
-      _steps: subContext.steps,
-      ...finalOutput !== void 0 ? { _finalOutput: finalOutput } : {}
-    };
-  }
-  return {
-    status: "success",
-    output: flattenedOutput,
-    response: flattenedOutput
+    if (errorCode && entry === errorCode) return true;
+    return message.toLowerCase().includes(entry.toLowerCase());
   };
+  if (Array.isArray(onError.failFastOn) && onError.failFastOn.some(matches)) {
+    return { retry: false, reason: "failFastOn" };
+  }
+  if (Array.isArray(onError.retryOn)) {
+    if (onError.retryOn.some(matches)) return { retry: true, reason: "retryOn" };
+    return { retry: false, reason: "no-retryOn-match" };
+  }
+  return { retry: true };
 }
-async function executePaginateStep(step, context, api, permissions, allowedActionIds, options) {
-  const config = step.paginate;
-  const maxPages = config.maxPages ?? 10;
-  const allResults = [];
-  let pageToken = void 0;
-  let pages = 0;
-  for (let page = 0; page < maxPages; page++) {
-    const actionConfig = JSON.parse(JSON.stringify(config.action));
-    if (pageToken !== void 0 && pageToken !== null) {
-      const resolved = resolveValue(actionConfig, context);
-      setByDotPath(resolved, config.inputTokenParam, pageToken);
-      const syntheticStep = {
-        id: `${step.id}__page${page}`,
-        name: `${step.id} page ${page}`,
-        type: "action",
-        action: resolved
-      };
-      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
-      const response = result.response;
-      const pageResults = getByDotPath(response, config.resultsField);
-      if (Array.isArray(pageResults)) allResults.push(...pageResults);
-      pageToken = getByDotPath(response, config.pageTokenField);
-      pages++;
-      options.onEvent?.({ event: "step:page", stepId: step.id, page: pages });
-      if (pageToken === void 0 || pageToken === null) break;
-    } else if (page === 0) {
-      const resolvedAction = resolveValue(actionConfig, context);
-      const syntheticStep = {
-        id: `${step.id}__page0`,
-        name: `${step.id} page 0`,
-        type: "action",
-        action: resolvedAction
-      };
-      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
-      const response = result.response;
-      const pageResults = getByDotPath(response, config.resultsField);
-      if (Array.isArray(pageResults)) allResults.push(...pageResults);
-      pageToken = getByDotPath(response, config.pageTokenField);
-      pages++;
-      options.onEvent?.({ event: "step:page", stepId: step.id, page: pages });
-      if (pageToken === void 0 || pageToken === null) break;
+function computeRetryDelay(onError, attempt) {
+  const base = onError.retryDelayMs ?? 1e3;
+  const max = onError.maxDelayMs ?? 3e4;
+  const backoff = onError.backoff ?? "fixed";
+  const retryIndex = attempt - 2;
+  let delay;
+  if (backoff === "exponential" || backoff === "exponential-jitter") {
+    delay = Math.min(base * Math.pow(2, retryIndex), max);
+    if (backoff === "exponential-jitter") {
+      delay = delay * (0.5 + Math.random() * 0.5);
     }
+  } else {
+    delay = base;
   }
-  return {
-    status: "success",
-    output: allResults,
-    response: { pages, totalResults: allResults.length, results: allResults }
-  };
+  return Math.round(delay);
 }
-function resolveBashEnv(envConfig, context, stepId) {
-  const out = {};
-  const tempFiles = [];
-  if (!envConfig) return { env: out, tempFiles };
-  for (const [key, raw] of Object.entries(envConfig)) {
-    if (raw === void 0 || raw === null) continue;
-    if (typeof raw === "object" && !Array.isArray(raw)) {
-      const obj = raw;
-      if ("json" in obj) {
-        const resolved2 = resolveValue(obj.json, context);
-        const json = JSON.stringify(resolved2 ?? null);
-        const tmp = path2.join(
-          os2.tmpdir(),
-          `one-flow-${stepId}-${key}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`
-        );
-        fs2.writeFileSync(tmp, json, { encoding: "utf-8" });
-        tempFiles.push(tmp);
-        out[key] = tmp;
-        continue;
-      }
-      if ("shell" in obj) {
-        const resolved2 = resolveValue(obj.shell, context);
-        out[key] = resolved2 === void 0 || resolved2 === null ? "" : typeof resolved2 === "object" ? JSON.stringify(resolved2) : String(resolved2);
-        continue;
-      }
-      out[key] = JSON.stringify(resolveValue(raw, context));
+function resolveSelector(selectorPath, context) {
+  if (!selectorPath.startsWith("$.")) return selectorPath;
+  const parts = selectorPath.slice(2).split(/\.|\[/).map((p) => p.replace(/\]$/, ""));
+  let current = context;
+  for (const part of parts) {
+    if (current === null || current === void 0) return void 0;
+    if (part === "*" && Array.isArray(current)) {
       continue;
     }
-    const resolved = resolveValue(raw, context);
-    out[key] = resolved === void 0 || resolved === null ? "" : typeof resolved === "object" ? JSON.stringify(resolved) : String(resolved);
-  }
-  return { env: out, tempFiles };
-}
-async function executeBashStep(step, context, options) {
-  if (!options.allowBash) {
-    throw new Error("Bash steps require --allow-bash flag for security");
-  }
-  const config = step.bash;
-  const command = resolveValue(config.command, context);
-  const cwd = config.cwd ? resolveValue(config.cwd, context) : process.cwd();
-  const { env: resolvedEnv, tempFiles } = resolveBashEnv(
-    config.env,
-    context,
-    step.id
-  );
-  const env = config.env ? { ...process.env, ...resolvedEnv } : process.env;
-  try {
-    const { stdout, stderr } = await execAsync(command, {
-      timeout: config.timeout || 3e4,
-      cwd,
-      env,
-      maxBuffer: 10 * 1024 * 1024
-    });
-    const output = config.parseJson ? JSON.parse(stripCodeFences(stdout)) : stdout.trim();
-    return {
-      status: "success",
-      output,
-      response: { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }
-    };
-  } finally {
-    for (const tmp of tempFiles) {
-      try {
-        fs2.unlinkSync(tmp);
-      } catch {
+    if (Array.isArray(current) && part === "*") {
+      continue;
+    }
+    if (Array.isArray(current)) {
+      const idx = Number(part);
+      if (!isNaN(idx)) {
+        current = current[idx];
+      } else {
+        current = current.map((item) => item?.[part]);
       }
+    } else if (typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
     }
   }
+  return current;
 }
-function describe(value) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return `array (${JSON.stringify(value)})`;
-  if (typeof value === "object") return `object (${JSON.stringify(value)})`;
-  return `${typeof value} (${JSON.stringify(value)})`;
-}
-function isMissing(value) {
-  if (value === void 0 || value === null) return true;
-  if (typeof value === "string" && value.length === 0) return true;
-  if (Array.isArray(value) && value.length === 0) return true;
-  return false;
-}
-function explainMissing(selector, context) {
-  const parts = selector.slice(2).split(".");
-  if (parts[0] !== "steps" || parts.length < 2) return "";
-  const stepId = parts[1].replace(/\[.*$/, "");
-  const upstream = context.steps[stepId];
-  if (!upstream) return ` (upstream step "${stepId}" has not run)`;
-  if (upstream.status === "skipped") return ` (upstream step "${stepId}" was skipped)`;
-  if (upstream.status === "failed") return ` (upstream step "${stepId}" failed: ${upstream.error ?? "unknown error"})`;
-  if (upstream.status === "timeout") return ` (upstream step "${stepId}" timed out)`;
-  return "";
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function checkRequires(step, context) {
-  if (!step.requires || step.requires.length === 0) return;
-  for (const selector of step.requires) {
-    const value = resolveSelector(selector, context);
-    if (isMissing(value)) {
-      const why = explainMissing(selector, context);
-      throw new Error(
-        `Step "${step.id}" requires ${selector} but it resolved to ${value === void 0 ? "undefined" : value === null ? "null" : Array.isArray(value) ? "an empty array" : "an empty string"}${why}`
-      );
+function applyHandlebarsPipe(value, pipe) {
+  switch (pipe) {
+    case "json":
+      return JSON.stringify(value ?? null);
+    case "shell": {
+      if (value === void 0 || value === null) return `''`;
+      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
+      return shellQuote(str);
     }
-  }
-}
-async function executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack = []) {
-  if (step.if) {
-    const condResult = evaluateCondition(step.if, context);
-    if (!condResult) {
-      const result = { status: "skipped" };
-      context.steps[step.id] = result;
-      return result;
+    case "url": {
+      if (value === void 0 || value === null) return "";
+      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
+      return encodeURIComponent(str);
     }
-  }
-  if (step.unless) {
-    const condResult = evaluateCondition(step.unless, context);
-    if (condResult) {
-      const result = { status: "skipped" };
-      context.steps[step.id] = result;
-      return result;
+    case "md": {
+      if (value === void 0 || value === null) return "";
+      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
+      return str.replace(/([\\`*_{}\[\]()#+\-!|])/g, "\\$1");
+    }
+    case "html": {
+      if (value === void 0 || value === null) return "";
+      const str = typeof value === "object" ? JSON.stringify(value) : String(value);
+      return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
     }
+    default:
+      throw new Error(`Unknown Handlebars pipe: "${pipe}". Supported: json, shell, url, md, html.`);
   }
-  const startTime = Date.now();
-  let lastError;
-  const onError = step.onError ?? context._defaultOnError;
-  const maxAttempts = onError?.strategy === "retry" && onError.retries ? onError.retries + 1 : 1;
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      if (attempt > 1) {
-        const delay = computeRetryDelay(onError, attempt);
-        options.onEvent?.({
-          event: "step:retry",
-          stepId: step.id,
-          attempt,
-          maxRetries: onError.retries,
-          delayMs: delay
-        });
-        await sleep2(delay);
-      }
-      checkRequires(step, context);
-      if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
-        const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {};
-        let mockOutput = { _mock: true, ...resolvedConfig };
-        if (step.type === "action" && step.action) {
-          const actionId = resolveValue(step.action.actionId, context);
-          try {
-            const { details: actionDetails } = await resolveActionDetails(api, actionId);
-            if (!options.skipValidation) {
-              const data = step.action.data ? resolveValue(step.action.data, context) : void 0;
-              const pathVars = step.action.pathVars ? resolveValue(step.action.pathVars, context) : void 0;
-              const queryParams = step.action.queryParams ? resolveValue(step.action.queryParams, context) : void 0;
-              const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
-              if (!validation.valid) {
-                const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
-                throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
-              }
-            }
-            if (actionDetails.ioSchema?.ioExample?.output) {
-              mockOutput = actionDetails.ioSchema.ioExample.output;
-            }
-          } catch (e) {
-            if (e instanceof Error && e.message.startsWith("Validation failed")) throw e;
-          }
-        }
-        options.onEvent?.({ event: "step:mock", stepId: step.id, type: step.type, config: resolvedConfig });
-        const result2 = {
-          status: "success",
-          output: mockOutput,
-          response: { _mock: true },
-          durationMs: Date.now() - startTime
-        };
-        context.steps[step.id] = result2;
-        return result2;
-      }
-      const dispatch = async () => {
-        switch (step.type) {
-          case "action":
-            return await executeActionStep(step, context, api, permissions, allowedActionIds, options);
-          case "transform":
-            return executeTransformStep(step, context);
-          case "code":
-            return await executeCodeStep(step, context, options);
-          case "condition":
-            return await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          case "loop":
-            return await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          case "parallel":
-            return await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          case "file-read":
-            return executeFileReadStep(step, context);
-          case "file-write":
-            return executeFileWriteStep(step, context);
-          case "while":
-            return await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          case "flow":
-            return await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-          case "paginate":
-            return await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
-          case "bash":
-            return await executeBashStep(step, context, options);
-          default:
-            throw new Error(`Unknown step type: ${step.type}`);
+}
+function interpolateString(str, context) {
+  return str.replace(
+    /\{\{\s*(q\s+)?(\$\.[^}\s|]+)(?:\s*\|\s*([a-zA-Z]+))?\s*\}\}/g,
+    (_match, qFlag, selector, pipe) => {
+      const value = resolveSelector(selector, context);
+      if (pipe) {
+        if (qFlag) {
+          throw new Error(`Handlebars expression "{{q ${selector} | ${pipe}}}" combines the legacy "q" prefix with a pipe \u2014 pick one (prefer the pipe form).`);
         }
-      };
-      const result = step.timeoutMs ? await withTimeout(dispatch(), step.timeoutMs, step.id) : await dispatch();
-      result.durationMs = Date.now() - startTime;
-      if (attempt > 1) {
-        result.retries = attempt - 1;
-        options.onEvent?.({
-          event: "step:retry-success",
-          stepId: step.id,
-          retries: attempt - 1
-        });
-      }
-      context.steps[step.id] = result;
-      return result;
-    } catch (err) {
-      lastError = err instanceof Error ? err : new Error(String(err));
-      if (attempt === maxAttempts) {
-        break;
+        return applyHandlebarsPipe(value, pipe);
       }
-      if (onError?.strategy === "retry" && (onError.retryOn || onError.failFastOn)) {
-        const decision = shouldRetryError(lastError, onError);
-        if (!decision.retry) {
-          options.onEvent?.({
-            event: "step:retry-skip",
-            stepId: step.id,
-            reason: decision.reason ?? "no-match",
-            error: lastError.message
-          });
-          break;
-        }
+      if (value === void 0 || value === null) return qFlag ? `''` : "";
+      if (typeof value === "object") {
+        console.warn(
+          `[flow] WARNING: Handlebars expression "{{${qFlag ? "q " : ""}${selector}}}" resolved to ${Array.isArray(value) ? "an array" : "an object"} and was stringified as JSON. To pass objects/arrays as native values, use a direct selector without {{ }}: "${selector}"`
+        );
+        const json = JSON.stringify(value);
+        return qFlag ? shellQuote(json) : json;
       }
+      const str2 = String(value);
+      return qFlag ? shellQuote(str2) : str2;
+    }
+  );
+}
+function resolveValue(value, context) {
+  if (typeof value === "string") {
+    if (value.startsWith("$.") && !value.includes("{{")) {
+      return resolveSelector(value, context);
     }
+    if (/\{\{\s*(q\s+)?\$\./.test(value)) {
+      return interpolateString(value, context);
+    }
+    return value;
   }
-  const errorMessage = lastError?.message || "Unknown error";
-  const strategy = onError?.strategy || "fail";
-  const retriesUsed = Math.max(0, maxAttempts - 1);
-  const isTimeout = lastError instanceof StepTimeoutError;
-  const errorCode = lastError?.errorCode;
-  if (strategy === "continue") {
-    const result = {
-      status: isTimeout ? "timeout" : "failed",
-      error: errorMessage,
-      ...errorCode ? { errorCode } : {},
-      durationMs: Date.now() - startTime,
-      retries: retriesUsed
-    };
-    context.steps[step.id] = result;
-    return result;
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, context));
   }
-  if (strategy === "fallback" && onError?.fallbackStepId) {
-    const result = {
-      status: isTimeout ? "timeout" : "failed",
-      error: errorMessage,
-      ...errorCode ? { errorCode } : {},
-      durationMs: Date.now() - startTime,
-      retries: retriesUsed
-    };
-    context.steps[step.id] = result;
-    return result;
+  if (value && typeof value === "object") {
+    const resolved = {};
+    for (const [k, v] of Object.entries(value)) {
+      resolved[k] = resolveValue(v, context);
+    }
+    return resolved;
   }
-  throw lastError;
+  return value;
 }
-async function executeSteps(steps, context, api, permissions, allowedActionIds, options, completedStepIds, flowStack = []) {
-  const results = [];
-  for (const step of steps) {
-    if (completedStepIds?.has(step.id)) {
-      results.push(context.steps[step.id] || { status: "success" });
-      continue;
-    }
-    options.onEvent?.({
-      event: "step:start",
-      stepId: step.id,
-      stepName: step.name,
-      type: step.type,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    try {
-      const result = await executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack);
-      results.push(result);
-      options.onEvent?.({
-        event: "step:complete",
-        stepId: step.id,
-        status: result.status,
-        durationMs: result.durationMs,
-        retries: result.retries
-      });
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      options.onEvent?.({
-        event: "step:error",
-        stepId: step.id,
-        error: errorMsg,
-        strategy: step.onError?.strategy || "fail"
-      });
-      throw error;
+function evaluateExpression(expr, context) {
+  const fn = new Function("$", `return (${expr})`);
+  return fn(context);
+}
+function evaluateCondition(expr, context) {
+  try {
+    return Boolean(evaluateExpression(expr, context));
+  } catch (err) {
+    if (err instanceof TypeError) return false;
+    throw err;
+  }
+}
+var FlowStopSignal = class extends Error {
+  constructor(stepId) {
+    super(`Flow stopped after step "${stepId}"`);
+    this.stepId = stepId;
+    this.name = "FlowStopSignal";
+  }
+};
+var DRY_SELECTOR_TOKEN = /\$\.[A-Za-z0-9_$]+(?:[.[][A-Za-z0-9_$*\]]+)*/g;
+function extractSelectors(str) {
+  return str.match(DRY_SELECTOR_TOKEN) ?? [];
+}
+function walkConfigStrings(value, visit) {
+  if (typeof value === "string") {
+    visit(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) walkConfigStrings(v, visit);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) walkConfigStrings(v, visit);
+  }
+}
+function classifyDryRef(selector, value) {
+  if (value !== void 0) return "resolved";
+  if (selector.startsWith("$.steps.") || selector.startsWith("$.loop.")) return "deferred";
+  return "missing";
+}
+function expressionDeferredOn(expr, context) {
+  const deps = /* @__PURE__ */ new Set();
+  for (const selector of extractSelectors(expr)) {
+    if (!selector.startsWith("$.steps.") && !selector.startsWith("$.loop.")) continue;
+    const parts = selector.split(/[.[]/);
+    if (parts.length < 3) continue;
+    const root = `${parts[0]}.${parts[1]}.${parts[2]}`;
+    if (resolveSelector(root, context) === void 0) deps.add(root);
+  }
+  return [...deps];
+}
+function stepInterpolationSource(step) {
+  switch (step.type) {
+    case "action": {
+      const a = step.action;
+      if (!a) return {};
+      return {
+        platform: a.platform,
+        actionId: a.actionId,
+        connectionKey: a.connectionKey,
+        connection: a.connection,
+        pathVars: a.pathVars,
+        queryParams: a.queryParams,
+        headers: a.headers,
+        data: a.data
+      };
     }
+    case "paginate": {
+      const a = step.paginate?.action;
+      return a ? { platform: a.platform, actionId: a.actionId, connectionKey: a.connectionKey, connection: a.connection, pathVars: a.pathVars, queryParams: a.queryParams, headers: a.headers, data: a.data } : {};
+    }
+    case "file-read":
+      return { path: step.fileRead?.path };
+    case "file-write":
+      return { path: step.fileWrite?.path, content: step.fileWrite?.content };
+    case "loop":
+      return { over: step.loop?.over };
+    case "flow":
+      return { inputs: step.flow?.inputs };
+    case "bash":
+      return { command: step.bash?.command, cwd: step.bash?.cwd, env: step.bash?.env };
+    default:
+      return {};
   }
-  return results;
 }
-async function executeFlow(flow, inputs, api, permissions, allowedActionIds, options = {}, resumeState, flowStack = []) {
-  const resolvedInputs = {};
-  for (const [name, decl] of Object.entries(flow.inputs)) {
-    const provided = inputs[name];
-    const isMissing2 = provided === void 0 || provided === null;
-    if (isMissing2) {
-      if (decl.required !== false && decl.default === void 0) {
-        throw new Error(`Missing required input: "${name}"${decl.description ? ` \u2014 ${decl.description}` : ""}`);
+function dryResolveStep(step, context) {
+  const base = { stepId: step.id, name: step.name, type: step.type };
+  const expr = step.type === "transform" ? step.transform?.expression : step.type === "condition" ? step.condition?.expression : step.type === "while" ? step.while?.condition : void 0;
+  if (step.type === "transform" || step.type === "condition" || step.type === "while") {
+    if (!expr) return { ...base, references: [] };
+    try {
+      return { ...base, references: [], resolved: evaluateExpression(expr, context) };
+    } catch (err) {
+      if (err instanceof TypeError) {
+        const deps = expressionDeferredOn(expr, context);
+        if (deps.length > 0) {
+          return {
+            ...base,
+            references: deps.map((selector) => ({ selector, value: void 0, status: "deferred" })),
+            deferred: true
+          };
+        }
       }
-      if (decl.default !== void 0) {
-        resolvedInputs[name] = decl.default;
-      }
-      continue;
+      return { ...base, references: [], error: err instanceof Error ? err.message : String(err) };
     }
-    let value = provided;
-    switch (decl.type) {
-      case "string":
-        if (typeof value !== "string") value = String(value);
-        break;
-      case "number":
-        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
-          value = Number(value);
-        }
-        if (typeof value !== "number" || Number.isNaN(value)) {
-          throw new Error(`Input "${name}" must be a number, got ${describe(provided)}`);
-        }
-        break;
-      case "boolean":
-        if (value === "true" || value === "1" || value === 1) value = true;
-        else if (value === "false" || value === "0" || value === 0) value = false;
-        if (typeof value !== "boolean") {
-          throw new Error(`Input "${name}" must be a boolean, got ${describe(provided)}`);
-        }
-        break;
-      case "array":
-        if (typeof value === "string") {
-          try {
-            value = JSON.parse(value);
-          } catch {
-          }
-        }
-        if (!Array.isArray(value)) {
-          throw new Error(`Input "${name}" must be an array, got ${describe(provided)}`);
-        }
-        break;
-      case "object":
-        if (typeof value === "string") {
-          try {
-            value = JSON.parse(value);
-          } catch {
-          }
-        }
-        if (!value || typeof value !== "object" || Array.isArray(value)) {
-          throw new Error(`Input "${name}" must be an object, got ${describe(provided)}`);
-        }
-        break;
+  }
+  const src = stepInterpolationSource(step);
+  const references = [];
+  const seen = /* @__PURE__ */ new Set();
+  walkConfigStrings(src, (s) => {
+    for (const selector of extractSelectors(s)) {
+      if (seen.has(selector)) continue;
+      seen.add(selector);
+      const value = resolveSelector(selector, context);
+      references.push({ selector, value, status: classifyDryRef(selector, value) });
     }
-    if (Array.isArray(decl.enum) && decl.enum.length > 0) {
-      if (!decl.enum.some((allowed) => allowed === value)) {
-        throw new Error(`Input "${name}" must be one of ${JSON.stringify(decl.enum)}, got ${JSON.stringify(value)}`);
+  });
+  let resolved;
+  try {
+    resolved = resolveValue(src, context);
+  } catch {
+  }
+  return { ...base, references, resolved };
+}
+function dryResolveAllSteps(steps, context) {
+  const out = [];
+  const visit = (list) => {
+    for (const step of list) {
+      out.push(dryResolveStep(step, context));
+      const config = step;
+      for (const { configKey, fieldName } of getNestedStepsKeys()) {
+        const block = config[configKey];
+        if (block && Array.isArray(block[fieldName])) {
+          visit(block[fieldName]);
+        }
       }
     }
-    resolvedInputs[name] = value;
+  };
+  visit(steps);
+  return out;
+}
+var ALLOWED_MODULES = {
+  buffer: () => import("buffer"),
+  crypto: () => import("crypto"),
+  url: () => import("url"),
+  path: () => import("path")
+};
+var BLOCKED_MODULES = /* @__PURE__ */ new Set([
+  "fs",
+  "http",
+  "https",
+  "net",
+  "child_process",
+  "process",
+  "os",
+  "cluster",
+  "dgram",
+  "tls",
+  "vm",
+  "worker_threads"
+]);
+function createSandboxedRequire() {
+  const cache = {};
+  return async (moduleName) => {
+    const clean = moduleName.replace(/^node:/, "");
+    if (BLOCKED_MODULES.has(clean)) {
+      throw new Error(`Module "${moduleName}" is blocked in code steps`);
+    }
+    if (!ALLOWED_MODULES[clean]) {
+      throw new Error(`Module "${moduleName}" not available. Allowed: ${Object.keys(ALLOWED_MODULES).join(", ")}`);
+    }
+    if (!cache[clean]) cache[clean] = await ALLOWED_MODULES[clean]();
+    return cache[clean];
+  };
+}
+function stripCodeFences(text) {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^```(?:\w*)\s*\n([\s\S]*?)\n\s*```\s*$/);
+  return match ? match[1].trim() : trimmed;
+}
+async function executeActionStep(step, context, api, permissions, allowedActionIds, options) {
+  const action = step.action;
+  const platform = resolveValue(action.platform, context);
+  const actionId = resolveValue(action.actionId, context);
+  const hasKey = action.connectionKey !== void 0 && action.connectionKey !== null && action.connectionKey !== "";
+  const hasRef = !!action.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      `Action step "${step.id}" has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    );
   }
-  const context = resumeState?.context || {
-    input: resolvedInputs,
-    env: process.env,
-    steps: {},
-    loop: {}
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      `Action step "${step.id}" must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").`
+    );
+  }
+  let connectionKey;
+  if (hasKey) {
+    connectionKey = resolveValue(action.connectionKey, context);
+  } else {
+    const ref = resolveValue(action.connection, context);
+    if (!context._connections) {
+      context._connections = await api.listConnections();
+    }
+    const conn = await api.resolveConnection(ref, context._connections);
+    connectionKey = conn.key;
+  }
+  const data = action.data ? resolveValue(action.data, context) : void 0;
+  const pathVars = action.pathVars ? resolveValue(action.pathVars, context) : void 0;
+  const queryParams = action.queryParams ? resolveValue(action.queryParams, context) : void 0;
+  const headers = action.headers ? resolveValue(action.headers, context) : void 0;
+  if (!isActionAllowed(actionId, allowedActionIds)) {
+    throw new Error(`Action "${actionId}" is not in the allowed action list`);
+  }
+  const { details: actionDetails } = await resolveActionDetails(api, actionId);
+  if (!isMethodAllowed(actionDetails.method, permissions)) {
+    throw new Error(`Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
+  }
+  if (!options.skipValidation) {
+    const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
+    if (!validation.valid) {
+      const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
+      throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
+    }
+  }
+  const result = await api.executePassthroughRequest({
+    platform,
+    actionId,
+    connectionKey,
+    data,
+    pathVariables: pathVars,
+    queryParams,
+    headers
+  }, actionDetails);
+  return {
+    status: "success",
+    response: result.responseData,
+    output: result.responseData
   };
-  context.input = resolvedInputs;
-  context._defaultOnError = flow.defaultOnError;
-  const completedStepIds = resumeState ? new Set(resumeState.completedSteps) : void 0;
-  if (options.dryRun && !options.mock) {
-    options.onEvent?.({
-      event: "flow:dry-run",
-      flowKey: flow.key,
-      resolvedInputs,
-      steps: flow.steps.map((s) => ({ id: s.id, name: s.name, type: s.type })),
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    return context;
+}
+function executeTransformStep(step, context) {
+  const output = evaluateExpression(step.transform.expression, context);
+  return { status: "success", output, response: output };
+}
+async function executeCodeStep(step, context, options) {
+  const config = step.code;
+  if (config.module) {
+    const output = await executeCodeModule(step.id, config.module, context, options);
+    return { status: "success", output, response: output };
   }
-  options.onEvent?.({
-    event: options.mock ? "flow:mock-start" : "flow:start",
-    flowKey: flow.key,
-    totalSteps: flow.steps.length,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  const flowStart = Date.now();
+  if (typeof config.source !== "string") {
+    throw new Error(`Code step "${step.id}" must define either "source" or "module"`);
+  }
+  const AsyncFunction = Object.getPrototypeOf(async function() {
+  }).constructor;
+  const sandboxedRequire = createSandboxedRequire();
+  const sourceURL = `code:${step.id}`;
+  const taggedSource = `${config.source}
+//# sourceURL=${sourceURL}`;
+  const fn = new AsyncFunction("$", "require", taggedSource);
   try {
-    await executeSteps(flow.steps, context, api, permissions, allowedActionIds, options, completedStepIds, flowStack);
-    const stepEntries = Object.values(context.steps);
-    const completed = stepEntries.filter((s) => s.status === "success").length;
-    const failed = stepEntries.filter((s) => s.status === "failed").length;
-    const skipped = stepEntries.filter((s) => s.status === "skipped").length;
-    options.onEvent?.({
-      event: "flow:complete",
-      flowKey: flow.key,
-      status: "success",
-      durationMs: Date.now() - flowStart,
-      stepsCompleted: completed,
-      stepsFailed: failed,
-      stepsSkipped: skipped
-    });
-  } catch (error) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    options.onEvent?.({
-      event: "flow:error",
-      flowKey: flow.key,
-      status: "failed",
-      error: errorMsg,
-      durationMs: Date.now() - flowStart
-    });
-    throw error;
+    const output = await fn(context, sandboxedRequire);
+    return { status: "success", output, response: output };
+  } catch (err) {
+    throw rewriteCodeStepError(err, step.id, config.source, sourceURL);
   }
-  return context;
 }
-
-// src/lib/flow-schema.ts
-var FLOW_SCHEMA = {
-  errorStrategies: ["fail", "continue", "retry", "fallback"],
-  validInputTypes: ["string", "number", "boolean", "object", "array"],
-  flowFields: {
-    key: { type: "string", required: true, description: "Unique kebab-case identifier", pattern: /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ },
-    name: { type: "string", required: true, description: "Human-readable flow name" },
-    description: { type: "string", required: false, description: "What this flow does" },
-    version: { type: "string", required: false, description: "Semver or arbitrary version string" },
-    inputs: { type: "object", required: true, description: "Input declarations (Record<string, InputDeclaration>)" },
-    steps: { type: "array", required: true, description: "Ordered array of steps", stepsArray: true },
-    defaultOnError: { type: "object", required: false, description: 'Default error strategy inherited by every step without its own `onError` (e.g. { "strategy": "continue" }). A step opts out with its own `onError`.' }
-  },
-  inputFields: {
-    type: { type: "string", required: true, description: "Data type: string, number, boolean, object, array", enum: ["string", "number", "boolean", "object", "array"] },
-    required: { type: "boolean", required: false, description: "Whether this input must be provided" },
-    default: { type: "unknown", required: false, description: "Default value if not provided" },
-    description: { type: "string", required: false, description: "Human-readable description" },
-    connection: { type: "object", required: false, description: 'Connection metadata: { platform: "gmail" } \u2014 enables auto-resolution' },
-    enum: { type: "array", required: false, description: "Allowed values. Resolved input must equal one of these (post-coercion)." }
-  },
-  stepCommonFields: {
-    id: { type: "string", required: true, description: "Unique step identifier (used in selectors)" },
-    name: { type: "string", required: true, description: "Human-readable step label" },
-    type: { type: "string", required: true, description: "Step type (determines which config object is required)" },
-    if: { type: "string", required: false, description: "JS expression \u2014 skip step if falsy" },
-    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" },
-    timeoutMs: { type: "number", required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout".' },
-    requires: { type: "array", required: false, description: "Presence preconditions: array of $.input.X or $.steps.X.output... selectors that must resolve to a non-empty value before the step runs. Failures honor onError." },
-    outputSchema: { type: "object", required: false, description: `Optional declaration of the shape this step's output produces. When set, the validator checks that downstream $.steps.<this.id>.output.<field> references point at declared fields. Format: { fieldName: "string"|"number"|"boolean"|"object"|"array"|"unknown" } \u2014 nested objects are supported.` }
-  },
-  stepTypes: [
-    {
-      type: "action",
-      configKey: "action",
-      description: "Execute a platform API action",
-      fields: {
-        platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
-        actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
-        connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
-        connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
-        data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
-        pathVars: { type: "object", required: false, description: "URL path variables" },
-        queryParams: { type: "object", required: false, description: "Query parameters" },
-        headers: { type: "object", required: false, description: "Additional headers" }
-      },
-      example: {
-        id: "findCustomer",
-        name: "Search Stripe customers",
-        type: "action",
-        action: {
-          platform: "stripe",
-          actionId: "conn_mod_def::xxx::yyy",
-          connection: { platform: "stripe" },
-          data: { query: "email:'{{$.input.customerEmail}}'" }
-        }
+function rewriteCodeStepError(err, stepId, source, sourceURL) {
+  if (!(err instanceof Error)) return new Error(String(err));
+  const WRAPPER_LINE_OFFSET = 2;
+  const sourceLines = source.split("\n");
+  const stack = err.stack || "";
+  const re = new RegExp(`${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:(\\d+):(\\d+)`);
+  const match = stack.match(re);
+  if (!match) {
+    err.message = `Code step "${stepId}" failed: ${err.message}`;
+    return err;
+  }
+  const wrappedLine = parseInt(match[1], 10);
+  const col = parseInt(match[2], 10);
+  const userLine = wrappedLine - WRAPPER_LINE_OFFSET;
+  const lineContent = sourceLines[userLine - 1] ?? "";
+  const trimmed = lineContent.trim();
+  err.message = `Code step "${stepId}" failed at line ${userLine}:${col}
+  ${trimmed}
+  ${err.message}`;
+  err.stack = stack.replace(
+    new RegExp(`(${sourceURL.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}:)(\\d+)`, "g"),
+    (_m, prefix, l) => `${prefix}${parseInt(l, 10) - WRAPPER_LINE_OFFSET}`
+  );
+  return err;
+}
+async function executeCodeModule(stepId, modulePath, context, options) {
+  const rootDir = options.rootDir;
+  if (!rootDir) {
+    throw new Error(`Code step "${stepId}" uses module "${modulePath}" but no flow rootDir is available. Flows that use code modules must be loaded via loadFlowWithMeta.`);
+  }
+  if (path2.isAbsolute(modulePath)) {
+    throw new Error(`Code module path must be relative to the flow root, got absolute: "${modulePath}"`);
+  }
+  const absPath = path2.resolve(rootDir, modulePath);
+  const relFromRoot = path2.relative(rootDir, absPath);
+  if (relFromRoot.startsWith("..") || path2.isAbsolute(relFromRoot)) {
+    throw new Error(`Code module "${modulePath}" resolves outside the flow directory`);
+  }
+  if (!fs2.existsSync(absPath)) {
+    throw new Error(`Code module not found: ${absPath}`);
+  }
+  const { env: _omitEnv, ...safeContext } = context;
+  void _omitEnv;
+  const stdinPayload = JSON.stringify(safeContext);
+  return await new Promise((resolve2, reject) => {
+    const child = spawn(process.execPath, [absPath], {
+      cwd: rootDir,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    child.stdout.on("data", (c) => stdoutChunks.push(c));
+    child.stderr.on("data", (c) => stderrChunks.push(c));
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+      const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+      if (code !== 0) {
+        reject(new Error(`Code module "${modulePath}" exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
+        return;
       }
-    },
-    {
-      type: "transform",
-      configKey: "transform",
-      description: "Single JS expression with implicit return",
-      fields: {
-        expression: { type: "string", required: true, description: "JS expression evaluated with flow context as $" }
-      },
-      example: {
-        id: "extractNames",
-        name: "Extract customer names",
-        type: "transform",
-        transform: { expression: "$.steps.findCustomer.response.data.map(c => c.name)" }
+      const trimmed = stdout.trim();
+      if (trimmed === "") {
+        resolve2(void 0);
+        return;
       }
-    },
-    {
-      type: "code",
-      configKey: "code",
-      description: "JS code \u2014 inline source or an external .mjs module under the flow's lib/ folder",
-      fields: {
-        source: { type: "string", required: false, description: 'Inline JS function body (flow context as $, supports await). Mutually exclusive with "module".' },
-        module: { type: "string", required: false, description: 'Relative path to a .mjs file under the flow folder (e.g. "lib/normalize.mjs"). Reads $ from stdin as JSON, writes result to stdout as JSON. Mutually exclusive with "source".' }
-      },
-      example: {
-        id: "processData",
-        name: "Process and enrich data",
-        type: "code",
-        code: { module: "lib/process-data.mjs" }
+      try {
+        resolve2(JSON.parse(stripCodeFences(trimmed)));
+      } catch (err) {
+        reject(new Error(`Code module "${modulePath}" did not print valid JSON to stdout: ${err.message}`));
       }
-    },
-    {
-      type: "condition",
-      configKey: "condition",
-      description: "If/then/else branching",
-      fields: {
-        expression: { type: "string", required: true, description: "JS expression \u2014 truthy runs then, falsy runs else" },
-        then: { type: "array", required: true, description: "Steps to run when true", stepsArray: true },
-        else: { type: "array", required: false, description: "Steps to run when false", stepsArray: true }
-      },
-      example: {
-        id: "checkFound",
-        name: "Check if customer exists",
-        type: "condition",
-        condition: {
-          expression: "$.steps.search.response.data.length > 0",
-          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" }, data: { text: "Found!" } } }],
-          else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
-        }
+    });
+    child.stdin.write(stdinPayload);
+    child.stdin.end();
+  });
+}
+async function executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
+  const condition = step.condition;
+  const result = evaluateCondition(condition.expression, context);
+  const branch = result ? condition.then : condition.else || [];
+  const branchResults = await executeSteps(branch, context, api, permissions, allowedActionIds, options, void 0, flowStack);
+  return {
+    status: "success",
+    output: { conditionResult: !!result, stepsExecuted: branchResults },
+    response: { conditionResult: !!result }
+  };
+}
+async function executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
+  const loop = step.loop;
+  const items = resolveValue(loop.over, context);
+  if (!Array.isArray(items)) {
+    throw new Error(`Loop "over" must resolve to an array, got ${typeof items}`);
+  }
+  const maxIterations = loop.maxIterations || 1e3;
+  const bounded = items.slice(0, maxIterations);
+  const savedLoop = { ...context.loop };
+  const iterationResults = [];
+  if (loop.maxConcurrency && loop.maxConcurrency > 1) {
+    const results2 = new Array(bounded.length);
+    for (let batchStart = 0; batchStart < bounded.length; batchStart += loop.maxConcurrency) {
+      const batch = bounded.slice(batchStart, batchStart + loop.maxConcurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (item, batchIdx) => {
+          const i = batchStart + batchIdx;
+          const iterContext = {
+            ...context,
+            loop: {
+              [loop.as]: item,
+              item,
+              i,
+              ...loop.indexAs ? { [loop.indexAs]: i } : {}
+            },
+            steps: { ...context.steps }
+          };
+          const beforeKeys = new Set(Object.keys(iterContext.steps));
+          await executeSteps(loop.steps, iterContext, api, permissions, allowedActionIds, options, void 0, flowStack);
+          const iterResult = {};
+          for (const [key, val] of Object.entries(iterContext.steps)) {
+            if (!beforeKeys.has(key) || iterContext.steps[key] !== context.steps[key]) {
+              iterResult[key] = val;
+            }
+          }
+          iterationResults[i] = iterResult;
+          Object.assign(context.steps, iterContext.steps);
+          return iterContext.loop[loop.as];
+        })
+      );
+      for (let j = 0; j < batchResults.length; j++) {
+        results2[batchStart + j] = batchResults[j];
       }
-    },
-    {
-      type: "loop",
-      configKey: "loop",
-      description: "Iterate over an array with optional concurrency",
-      fields: {
-        over: { type: "string", required: true, description: "Selector resolving to an array" },
-        as: { type: "string", required: true, description: "Variable name for current item ($.loop.<as>)" },
-        indexAs: { type: "string", required: false, description: "Variable name for index" },
-        steps: { type: "array", required: true, description: "Steps to run per iteration", stepsArray: true },
-        maxIterations: { type: "number", required: false, description: "Safety cap (default: no limit)" },
-        maxConcurrency: { type: "number", required: false, description: "Parallel batch size (default: 1 = sequential)" }
-      },
-      example: {
-        id: "processOrders",
-        name: "Process each order",
-        type: "loop",
-        loop: {
-          over: "$.steps.listOrders.response.data",
-          as: "order",
-          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" }, data: { amount: "$.loop.order.total" } } }]
-        }
-      }
-    },
-    {
-      type: "parallel",
-      configKey: "parallel",
-      description: "Run steps concurrently",
-      fields: {
-        steps: { type: "array", required: true, description: "Steps to run in parallel", stepsArray: true },
-        maxConcurrency: { type: "number", required: false, description: "Max concurrent steps (default: 5)" }
-      },
-      example: {
-        id: "lookups",
-        name: "Parallel data lookups",
-        type: "parallel",
-        parallel: {
-          steps: [
-            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" } } },
-            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" } } }
-          ]
-        }
-      }
-    },
-    {
-      type: "file-read",
-      configKey: "fileRead",
-      description: "Read a file (optional JSON parse)",
-      fields: {
-        path: { type: "string", required: true, description: "File path to read" },
-        parseJson: { type: "boolean", required: false, description: "Parse contents as JSON (default: false)" }
-      },
-      example: {
-        id: "readConfig",
-        name: "Read config file",
-        type: "file-read",
-        fileRead: { path: "./data/config.json", parseJson: true }
-      }
-    },
-    {
-      type: "file-write",
-      configKey: "fileWrite",
-      description: "Write or append to a file",
-      fields: {
-        path: { type: "string", required: true, description: "File path to write" },
-        content: { type: "unknown", required: true, description: "Content to write (supports selectors)" },
-        append: { type: "boolean", required: false, description: "Append instead of overwrite (default: false)" }
-      },
-      example: {
-        id: "writeResults",
-        name: "Save results",
-        type: "file-write",
-        fileWrite: { path: "./output/results.json", content: "$.steps.transform.output" }
-      }
-    },
-    {
-      type: "while",
-      configKey: "while",
-      description: "Do-while loop with condition check",
-      fields: {
-        condition: { type: "string", required: true, description: "JS expression checked before each iteration (after first)" },
-        steps: { type: "array", required: true, description: "Steps to run each iteration", stepsArray: true },
-        maxIterations: { type: "number", required: false, description: "Safety cap (default: 100)" }
-      },
-      example: {
-        id: "paginate",
-        name: "Paginate through pages",
-        type: "while",
-        while: {
-          condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
-          maxIterations: 50,
-          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" } } }]
-        }
-      }
-    },
-    {
-      type: "flow",
-      configKey: "flow",
-      description: "Execute a sub-flow (supports composition)",
-      fields: {
-        key: { type: "string", required: true, description: "Flow key or path of the sub-flow" },
-        inputs: { type: "object", required: false, description: "Inputs to pass to the sub-flow (supports selectors)" }
-      },
-      example: {
-        id: "enrich",
-        name: "Run enrichment sub-flow",
-        type: "flow",
-        flow: { key: "enrich-customer", inputs: { email: "$.steps.getCustomer.response.email" } }
-      }
-    },
-    {
-      type: "paginate",
-      configKey: "paginate",
-      description: "Auto-paginate API results into a single array",
-      fields: {
-        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, plus exactly one of `connection` or `connectionKey`)" },
-        pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
-        resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
-        inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
-        maxPages: { type: "number", required: false, description: "Max pages to fetch (default: 10)" }
-      },
-      example: {
-        id: "allMessages",
-        name: "Fetch all Gmail messages",
-        type: "paginate",
-        paginate: {
-          action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" }, queryParams: { maxResults: 100 } },
-          pageTokenField: "nextPageToken",
-          resultsField: "messages",
-          inputTokenParam: "queryParams.pageToken",
-          maxPages: 10
-        }
-      }
-    },
-    {
-      type: "bash",
-      configKey: "bash",
-      description: "Shell command (requires --allow-bash). Output shape: $.steps.<id>.output is the parsed JSON when parseJson:true, otherwise the trimmed stdout string. $.steps.<id>.response always exposes { stdout, stderr, exitCode }.",
-      fields: {
-        command: { type: "string", required: true, description: "Shell command to execute (supports selectors)" },
-        timeout: { type: "number", required: false, description: "Timeout in ms (default: 30000)" },
-        parseJson: { type: "boolean", required: false, description: "Parse stdout as JSON (default: false). When true, $.steps.<id>.output is the parsed object/array; when false, it is the trimmed stdout string." },
-        cwd: { type: "string", required: false, description: "Working directory (supports selectors)" },
-        env: { type: "object", required: false, description: "Additional environment variables" }
-      },
-      example: {
-        id: "analyze",
-        name: "Analyze with Claude",
-        type: "bash",
-        bash: {
-          command: "cat /tmp/data.json | claude --print 'Analyze this data' --output-format json",
-          timeout: 18e4,
-          parseJson: true
-        }
+    }
+    context.loop = savedLoop;
+    return {
+      status: "success",
+      output: results2,
+      response: { items: results2, iterations: iterationResults }
+    };
+  }
+  const results = [];
+  for (let i = 0; i < bounded.length; i++) {
+    context.loop = {
+      [loop.as]: bounded[i],
+      item: bounded[i],
+      i
+    };
+    if (loop.indexAs) {
+      context.loop[loop.indexAs] = i;
+    }
+    const beforeKeys = new Set(Object.keys(context.steps));
+    await executeSteps(loop.steps, context, api, permissions, allowedActionIds, options, void 0, flowStack);
+    const iterResult = {};
+    for (const [key, val] of Object.entries(context.steps)) {
+      if (!beforeKeys.has(key) || context.steps[key] !== (beforeKeys.has(key) ? void 0 : val)) {
+        iterResult[key] = val;
       }
     }
-  ]
-};
-var _coveredTypes = Object.fromEntries(
-  FLOW_SCHEMA.stepTypes.map((st) => [st.type, true])
-);
-var _stepTypeMap = new Map(
-  FLOW_SCHEMA.stepTypes.map((st) => [st.type, st])
-);
-function getStepTypeDescriptor(type) {
-  return _stepTypeMap.get(type);
+    iterationResults.push(iterResult);
+    results.push(context.loop[loop.as]);
+  }
+  context.loop = savedLoop;
+  return {
+    status: "success",
+    output: results,
+    response: { items: results, iterations: iterationResults }
+  };
 }
-function getValidStepTypes() {
-  return FLOW_SCHEMA.stepTypes.map((st) => st.type);
+async function executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
+  const parallel = step.parallel;
+  const maxConcurrency = parallel.maxConcurrency || 5;
+  const steps = parallel.steps;
+  const results = [];
+  for (let i = 0; i < steps.length; i += maxConcurrency) {
+    const batch = steps.slice(i, i + maxConcurrency);
+    const batchResults = await Promise.all(
+      batch.map((s) => executeSingleStep(s, context, api, permissions, allowedActionIds, options, flowStack))
+    );
+    for (let j = 0; j < batch.length; j++) {
+      context.steps[batch[j].id] = batchResults[j];
+    }
+    results.push(...batchResults);
+  }
+  return { status: "success", output: results, response: results };
 }
-function getNestedStepsKeys() {
-  const result = [];
-  for (const st of FLOW_SCHEMA.stepTypes) {
-    for (const [fieldName, fd] of Object.entries(st.fields)) {
-      if (fd.stepsArray) {
-        result.push({ configKey: st.configKey, fieldName });
-      }
+function executeFileReadStep(step, context) {
+  const config = step.fileRead;
+  const filePath = resolveValue(config.path, context);
+  const resolvedPath = path2.resolve(filePath);
+  const content = fs2.readFileSync(resolvedPath, "utf-8");
+  const output = config.parseJson ? JSON.parse(stripCodeFences(content)) : content;
+  if (config.parseJson && config.schema) {
+    assertMatchesFileReadSchema(output, config.schema, step.id);
+  }
+  return { status: "success", output, response: output };
+}
+function executeFileWriteStep(step, context) {
+  const config = step.fileWrite;
+  const filePath = resolveValue(config.path, context);
+  const content = resolveValue(config.content, context);
+  const resolvedPath = path2.resolve(filePath);
+  const dir = path2.dirname(resolvedPath);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
+  }
+  const stringContent = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+  if (config.append) {
+    fs2.appendFileSync(resolvedPath, stringContent);
+  } else {
+    fs2.writeFileSync(resolvedPath, stringContent);
+  }
+  return { status: "success", output: { path: resolvedPath, bytesWritten: stringContent.length }, response: { path: resolvedPath } };
+}
+async function executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
+  const config = step.while;
+  const maxIterations = config.maxIterations ?? 100;
+  const results = [];
+  context.steps[step.id] = {
+    status: "success",
+    output: { lastResult: void 0, iteration: 0, results: [] }
+  };
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    if (iteration > 0) {
+      const conditionResult = evaluateCondition(config.condition, context);
+      if (!conditionResult) break;
     }
+    await executeSteps(config.steps, context, api, permissions, allowedActionIds, options, void 0, flowStack);
+    const lastStepId = config.steps[config.steps.length - 1]?.id;
+    const lastResult = lastStepId ? context.steps[lastStepId]?.output : void 0;
+    results.push(lastResult);
+    context.steps[step.id] = {
+      status: "success",
+      output: { lastResult, iteration, results }
+    };
   }
-  return result;
+  return {
+    status: "success",
+    output: { lastResult: results[results.length - 1], iteration: results.length, results },
+    response: { iterations: results.length, results }
+  };
 }
-function generateFlowGuide() {
-  const validTypes = getValidStepTypes();
-  const sections = [];
-  sections.push(`# One Flows \u2014 Reference
-
-## Overview
-
-Workflows live in \`.one/flows/\` (relative to your current working directory \u2014 the CLI does NOT walk up parent directories or fall back to a global location) and chain actions across platforms. Two layouts are supported:
-
-- **Folder layout (REQUIRED for new flows)** \u2014 \`.one/flows/<key>/flow.json\`, with an optional \`lib/\` subfolder for JavaScript modules. This is like a skill: the folder groups the JSON spec with any JavaScript modules it needs, so the whole flow is shareable. **Always create new flows in this layout.**
-- **Single-file layout (DEPRECATED)** \u2014 \`.one/flows/<key>.flow.json\`. Still loads and runs for backward compatibility, but is deprecated. Do not create new flows in this layout. When editing an existing single-file flow, migrate it to the folder layout: move \`<key>.flow.json\` to \`<key>/flow.json\` and extract any non-trivial \`code.source\` blocks into \`<key>/lib/*.mjs\` modules.
-
-**Subdirectory groups** \u2014 Flows can be organized into subdirectories: \`.one/flows/<group>/<key>/flow.json\`. For example:
-\`\`\`
-.one/flows/
-  research/
-    company-research/flow.json
-    competitor-research/flow.json
-  deal-ops/
-    deal-log/flow.json
-\`\`\`
-Reference grouped flows with \`group/key\` (e.g. \`one flow execute research/company-research\`) or just the bare key if it's unique (e.g. \`one flow execute company-research\`). Create grouped flows with \`one flow create research/company-research --definition ...\`. \`flow list\` shows the group prefix.
-
-When resolving a flow by key, the CLI checks the folder layout first, then the deprecated legacy file, then scans group subdirectories. The \`loadFlow\` helper in agent integrations behaves the same.
-
-## Before you execute a flow you did NOT author \u2014 READ THIS
-
-**Agents: always inspect a flow before running it.** Nothing about a flow's runtime requirements is guessable from its name. Before \`flow execute\`, do one of these:
-
-1. Run \`one --agent flow list\` \u2014 the JSON output includes \`requiresBash\`, \`usesCodeModules\`, \`inputs\` (with \`autoResolvable\` flags), \`stepTypes\`, and the flow's \`description\`. This is the fastest path.
-2. Read the flow's \`description\` field directly from the JSON. Flow authors are required (see "Author conventions" below) to state any \`--allow-bash\` requirement and any non-auto-resolving inputs in the description.
-3. Run \`one --agent flow execute <key> --dry-run\` to see the resolved inputs and step plan without side effects.
-
-If you skip this step you will hit errors like *"Workflow X contains bash steps. Re-run with --allow-bash."* \u2014 the CLI now pre-flights and fails fast, so you won't waste a long run, but the error is still avoidable by reading first.
-
-## Author conventions \u2014 WRITE flows that are safe to execute blind
-
-When you create a flow, its \`description\` field is the contract with future executors (human or agent). It MUST state:
-
-- **\`--allow-bash\` if any step is type \`bash\`.** Example: *"Fetches recent Gmail threads and summarizes them with Claude Haiku. Requires \`--allow-bash\`."*
-- **Every input that does NOT have a \`connection\` hint.** Connection inputs auto-resolve when exactly one matching connection exists; everything else must be passed via \`-i name=value\` and the description must name it.
-- **Any files/directories the flow writes to** so operators know what will be modified on disk.
-
-A good description is one paragraph. If a flow's description doesn't tell you how to run it, treat that as a bug in the flow and fix it.
-
-## Commands
-
-\`\`\`bash
-one --agent flow create <key> --definition '<json>'              # Create (or --definition @file.json)
-one --agent flow create <key> --definition @flow.json            # Create from file
-one --agent flow create <group/key> --definition '<json>'        # Create in a subdirectory group
-one --agent flow list                                            # List (shows group prefixes)
-one --agent flow validate <key>                                  # Validate
-one --agent flow execute <key> -i name=value                     # Execute (bare key)
-one --agent flow execute <group/key> -i name=value               # Execute (namespaced key)
-one --agent flow execute <key> --dry-run --mock                  # Test with mock data
-one --agent flow execute <key> --allow-bash                      # Enable bash steps
-one --agent flow runs [flowKey]                                  # List past runs
-one --agent flow resume <runId>                                  # Resume failed run
-one --agent flow scaffold [template]                             # Generate a starter template
-\`\`\`
-
-You can also write the JSON file directly to \`.one/flows/<key>/flow.json\` (or \`.one/flows/<group>/<key>/flow.json\` for grouped flows) \u2014 often easier than passing large JSON via --definition. (The legacy \`.one/flows/<key>.flow.json\` single-file location is deprecated; don't use it for new flows.)
-
-## Code modules (flow \`lib/\` folder)
-
-A \`code\` step can either inline JS (\`code.source\`) or reference an external \`.mjs\` module (\`code.module\`). Modules live under the flow's \`lib/\` folder and run as a child \`node\` process:
-
-\`\`\`
-.one/flows/my-flow/
-\u251C\u2500\u2500 flow.json
-\u2514\u2500\u2500 lib/
-    \u2514\u2500\u2500 process-data.mjs
-\`\`\`
-
-**Module contract:** the flow context \`$\` is piped to stdin as JSON; the module writes its result to stdout as JSON. That's the whole interface \u2014 no framework imports, no magic.
-
-\`\`\`js
-// lib/process-data.mjs
-const $ = JSON.parse(await new Response(process.stdin).text());
-const items = $.steps.fetch.response.data ?? [];
-process.stdout.write(JSON.stringify(items.filter(i => i.active)));
-\`\`\`
-
-\`\`\`json
-{
-  "id": "processData",
-  "name": "Process and enrich data",
-  "type": "code",
-  "code": { "module": "lib/process-data.mjs" }
+async function executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack) {
+  const config = step.flow;
+  const resolvedKey = resolveValue(config.key, context);
+  const resolvedInputs = config.inputs ? resolveValue(config.inputs, context) : {};
+  if (flowStack.includes(resolvedKey)) {
+    throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
+  }
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-JNEFFR2U.js");
+  const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
+  const subContext = await executeFlow(
+    subFlow,
+    resolvedInputs,
+    api,
+    permissions,
+    allowedActionIds,
+    { ...options, rootDir: subRootDir },
+    void 0,
+    [...flowStack, resolvedKey]
+  );
+  const finalStep = subFlow.steps[subFlow.steps.length - 1];
+  const finalOutput = finalStep ? subContext.steps[finalStep.id]?.output : void 0;
+  let flattenedOutput;
+  if (finalOutput && typeof finalOutput === "object" && !Array.isArray(finalOutput)) {
+    const collisions = Object.keys(finalOutput).filter(
+      (k) => k in subContext.steps
+    );
+    if (collisions.length > 0) {
+      options.onEvent?.({
+        event: "flow:warning",
+        message: `Sub-flow "${resolvedKey}" final step output fields [${collisions.join(", ")}] collide with sub-step ids \u2014 flattened fields take precedence.`
+      });
+    }
+    flattenedOutput = {
+      ...subContext.steps,
+      ...finalOutput,
+      _steps: subContext.steps
+    };
+  } else {
+    flattenedOutput = {
+      ...subContext.steps,
+      _steps: subContext.steps,
+      ...finalOutput !== void 0 ? { _finalOutput: finalOutput } : {}
+    };
+  }
+  return {
+    status: "success",
+    output: flattenedOutput,
+    response: flattenedOutput
+  };
 }
-\`\`\`
-
-Modules are full Node processes \u2014 \`fs\`, \`https\`, any npm package installed in the host project, etc. are all available. Use this for anything non-trivial; keep \`code.source\` for one-liners.
-
-**Step output shape:** whatever JSON a module writes to stdout becomes both \`$.steps.<id>.output\` and \`$.steps.<id>.response\` (aliases). Downstream steps can reference either; convention is to use \`.output\` for code/transform step results and \`.response\` for action step API payloads.
-
-## Migrating a legacy single-file flow to the folder layout
-
-If you're editing an existing \`.one/flows/<key>.flow.json\`, migrate it \u2014 it takes a minute and the result is cleaner. Checklist:
-
-1. \`mkdir -p .one/flows/<key>/lib\`
-2. Move the file: \`mv .one/flows/<key>.flow.json .one/flows/<key>/flow.json\`
-3. For each non-trivial \`code\` step with inline \`source\`, extract it into \`lib/<step-id>.mjs\` (see translation pattern below) and swap the step config from \`{ "source": "..." }\` to \`{ "module": "lib/<step-id>.mjs" }\`. One-liners can stay inline.
-4. Validate: \`one --agent flow validate <key>\`.
-5. Run it and confirm behavior is unchanged.
-
-**Inline source \u2192 module translation pattern.** Inline \`code.source\` is an async function body where \`$\` is already in scope and you \`return\` the result. A module is a standalone script where you read \`$\` from stdin and write the result to stdout as JSON. The transform is mechanical:
-
-Before (inline \`code.source\`):
-\`\`\`js
-const items = $.steps.fetch.response.data;
-const active = items.filter(i => i.active);
-return { active, count: active.length };
-\`\`\`
-
-After (\`lib/<step-id>.mjs\`):
-\`\`\`js
-const $ = JSON.parse(await new Response(process.stdin).text());
-const items = $.steps.fetch.response.data;
-const active = items.filter(i => i.active);
-process.stdout.write(JSON.stringify({ active, count: active.length }));
-\`\`\`
-
-The only differences: (1) prepend the stdin-read line, (2) replace \`return X\` with \`process.stdout.write(JSON.stringify(X))\`. That's it.
-
-## Building a Workflow
-
-1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
-2. **Discover connections** \u2014 \`one --agent connection list\`
-3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
-4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
-5. **Validate** \u2014 \`one --agent flow validate <key>\`
-6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\``);
-  sections.push(`## Flow JSON Schema
-
-\`\`\`json
-{
-  "key": "my-workflow",
-  "name": "My Workflow",
-  "description": "What this flow does",
-  "version": "1",
-  "inputs": {
-    "param": {
-      "type": "string",
-      "required": true,
-      "description": "A user parameter"
+async function executePaginateStep(step, context, api, permissions, allowedActionIds, options) {
+  const config = step.paginate;
+  const maxPages = config.maxPages ?? 10;
+  const allResults = [];
+  let pageToken = void 0;
+  let pages = 0;
+  for (let page = 0; page < maxPages; page++) {
+    const actionConfig = JSON.parse(JSON.stringify(config.action));
+    if (pageToken !== void 0 && pageToken !== null) {
+      const resolved = resolveValue(actionConfig, context);
+      setByDotPath(resolved, config.inputTokenParam, pageToken);
+      const syntheticStep = {
+        id: `${step.id}__page${page}`,
+        name: `${step.id} page ${page}`,
+        type: "action",
+        action: resolved
+      };
+      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
+      const response = result.response;
+      const pageResults = getByDotPath(response, config.resultsField);
+      if (Array.isArray(pageResults)) allResults.push(...pageResults);
+      pageToken = getByDotPath(response, config.pageTokenField);
+      pages++;
+      options.onEvent?.({ event: "step:page", stepId: step.id, page: pages });
+      if (pageToken === void 0 || pageToken === null) break;
+    } else if (page === 0) {
+      const resolvedAction = resolveValue(actionConfig, context);
+      const syntheticStep = {
+        id: `${step.id}__page0`,
+        name: `${step.id} page 0`,
+        type: "action",
+        action: resolvedAction
+      };
+      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
+      const response = result.response;
+      const pageResults = getByDotPath(response, config.resultsField);
+      if (Array.isArray(pageResults)) allResults.push(...pageResults);
+      pageToken = getByDotPath(response, config.pageTokenField);
+      pages++;
+      options.onEvent?.({ event: "step:page", stepId: step.id, page: pages });
+      if (pageToken === void 0 || pageToken === null) break;
     }
-  },
-  "steps": [
-    {
-      "id": "stepId",
-      "name": "Human-readable step name",
-      "type": "action",
-      "action": {
-        "platform": "stripe",
-        "actionId": "conn_mod_def::xxx::yyy",
-        "connection": { "platform": "stripe" },
-        "data": { "query": "{{$.input.param}}" }
+  }
+  return {
+    status: "success",
+    output: allResults,
+    response: { pages, totalResults: allResults.length, results: allResults }
+  };
+}
+function resolveBashEnv(envConfig, context, stepId) {
+  const out = {};
+  const tempFiles = [];
+  if (!envConfig) return { env: out, tempFiles };
+  for (const [key, raw] of Object.entries(envConfig)) {
+    if (raw === void 0 || raw === null) continue;
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+      const obj = raw;
+      if ("json" in obj) {
+        const resolved2 = resolveValue(obj.json, context);
+        const json = JSON.stringify(resolved2 ?? null);
+        const tmp = path2.join(
+          os2.tmpdir(),
+          `one-flow-${stepId}-${key}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`
+        );
+        fs2.writeFileSync(tmp, json, { encoding: "utf-8" });
+        tempFiles.push(tmp);
+        out[key] = tmp;
+        continue;
+      }
+      if ("shell" in obj) {
+        const resolved2 = resolveValue(obj.shell, context);
+        out[key] = resolved2 === void 0 || resolved2 === null ? "" : typeof resolved2 === "object" ? JSON.stringify(resolved2) : String(resolved2);
+        continue;
+      }
+      out[key] = JSON.stringify(resolveValue(raw, context));
+      continue;
+    }
+    const resolved = resolveValue(raw, context);
+    out[key] = resolved === void 0 || resolved === null ? "" : typeof resolved === "object" ? JSON.stringify(resolved) : String(resolved);
+  }
+  return { env: out, tempFiles };
+}
+async function executeBashStep(step, context, options) {
+  if (!options.allowBash) {
+    throw new Error("Bash steps require --allow-bash flag for security");
+  }
+  const config = step.bash;
+  const command = resolveValue(config.command, context);
+  const cwd = config.cwd ? resolveValue(config.cwd, context) : process.cwd();
+  const { env: resolvedEnv, tempFiles } = resolveBashEnv(
+    config.env,
+    context,
+    step.id
+  );
+  const env = config.env ? { ...process.env, ...resolvedEnv } : process.env;
+  try {
+    const { stdout, stderr } = await execAsync(command, {
+      timeout: config.timeout || 3e4,
+      cwd,
+      env,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    const output = config.parseJson ? JSON.parse(stripCodeFences(stdout)) : stdout.trim();
+    return {
+      status: "success",
+      output,
+      response: { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }
+    };
+  } finally {
+    for (const tmp of tempFiles) {
+      try {
+        fs2.unlinkSync(tmp);
+      } catch {
+      }
+    }
+  }
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `array (${JSON.stringify(value)})`;
+  if (typeof value === "object") return `object (${JSON.stringify(value)})`;
+  return `${typeof value} (${JSON.stringify(value)})`;
+}
+function isMissing(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string" && value.length === 0) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+function explainMissing(selector, context) {
+  const parts = selector.slice(2).split(".");
+  if (parts[0] !== "steps" || parts.length < 2) return "";
+  const stepId = parts[1].replace(/\[.*$/, "");
+  const upstream = context.steps[stepId];
+  if (!upstream) return ` (upstream step "${stepId}" has not run)`;
+  if (upstream.status === "skipped") return ` (upstream step "${stepId}" was skipped)`;
+  if (upstream.status === "failed") return ` (upstream step "${stepId}" failed: ${upstream.error ?? "unknown error"})`;
+  if (upstream.status === "timeout") return ` (upstream step "${stepId}" timed out)`;
+  return "";
+}
+function checkRequires(step, context) {
+  if (!step.requires || step.requires.length === 0) return;
+  for (const selector of step.requires) {
+    const value = resolveSelector(selector, context);
+    if (isMissing(value)) {
+      const why = explainMissing(selector, context);
+      throw new Error(
+        `Step "${step.id}" requires ${selector} but it resolved to ${value === void 0 ? "undefined" : value === null ? "null" : Array.isArray(value) ? "an empty array" : "an empty string"}${why}`
+      );
+    }
+  }
+}
+async function executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack = []) {
+  if (step.if) {
+    const condResult = evaluateCondition(step.if, context);
+    if (!condResult) {
+      const result = { status: "skipped" };
+      context.steps[step.id] = result;
+      return result;
+    }
+  }
+  if (step.unless) {
+    const condResult = evaluateCondition(step.unless, context);
+    if (condResult) {
+      const result = { status: "skipped" };
+      context.steps[step.id] = result;
+      return result;
+    }
+  }
+  const startTime = Date.now();
+  let lastError;
+  const onError = step.onError ?? context._defaultOnError;
+  const maxAttempts = onError?.strategy === "retry" && onError.retries ? onError.retries + 1 : 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      if (attempt > 1) {
+        const delay = computeRetryDelay(onError, attempt);
+        options.onEvent?.({
+          event: "step:retry",
+          stepId: step.id,
+          attempt,
+          maxRetries: onError.retries,
+          delayMs: delay
+        });
+        await sleep2(delay);
+      }
+      checkRequires(step, context);
+      if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
+        const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {};
+        let mockOutput = { _mock: true, ...resolvedConfig };
+        if (step.type === "action" && step.action) {
+          const actionId = resolveValue(step.action.actionId, context);
+          try {
+            const { details: actionDetails } = await resolveActionDetails(api, actionId);
+            if (!options.skipValidation) {
+              const data = step.action.data ? resolveValue(step.action.data, context) : void 0;
+              const pathVars = step.action.pathVars ? resolveValue(step.action.pathVars, context) : void 0;
+              const queryParams = step.action.queryParams ? resolveValue(step.action.queryParams, context) : void 0;
+              const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
+              if (!validation.valid) {
+                const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
+                throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
+              }
+            }
+            if (actionDetails.ioSchema?.ioExample?.output) {
+              mockOutput = actionDetails.ioSchema.ioExample.output;
+            }
+          } catch (e) {
+            if (e instanceof Error && e.message.startsWith("Validation failed")) throw e;
+          }
+        }
+        options.onEvent?.({ event: "step:mock", stepId: step.id, type: step.type, config: resolvedConfig });
+        const result2 = {
+          status: "success",
+          output: mockOutput,
+          response: { _mock: true },
+          durationMs: Date.now() - startTime
+        };
+        context.steps[step.id] = result2;
+        return result2;
+      }
+      const dispatch = async () => {
+        switch (step.type) {
+          case "action":
+            return await executeActionStep(step, context, api, permissions, allowedActionIds, options);
+          case "transform":
+            return executeTransformStep(step, context);
+          case "code":
+            return await executeCodeStep(step, context, options);
+          case "condition":
+            return await executeConditionStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "loop":
+            return await executeLoopStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "parallel":
+            return await executeParallelStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "file-read":
+            return executeFileReadStep(step, context);
+          case "file-write":
+            return executeFileWriteStep(step, context);
+          case "while":
+            return await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "flow":
+            return await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+          case "paginate":
+            return await executePaginateStep(step, context, api, permissions, allowedActionIds, options);
+          case "bash":
+            return await executeBashStep(step, context, options);
+          default:
+            throw new Error(`Unknown step type: ${step.type}`);
+        }
+      };
+      const result = step.timeoutMs ? await withTimeout(dispatch(), step.timeoutMs, step.id) : await dispatch();
+      result.durationMs = Date.now() - startTime;
+      if (attempt > 1) {
+        result.retries = attempt - 1;
+        options.onEvent?.({
+          event: "step:retry-success",
+          stepId: step.id,
+          retries: attempt - 1
+        });
+      }
+      context.steps[step.id] = result;
+      return result;
+    } catch (err) {
+      if (err instanceof FlowStopSignal) throw err;
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt === maxAttempts) {
+        break;
+      }
+      if (onError?.strategy === "retry" && (onError.retryOn || onError.failFastOn)) {
+        const decision = shouldRetryError(lastError, onError);
+        if (!decision.retry) {
+          options.onEvent?.({
+            event: "step:retry-skip",
+            stepId: step.id,
+            reason: decision.reason ?? "no-match",
+            error: lastError.message
+          });
+          break;
+        }
       }
     }
-  ]
-}
-\`\`\`
-
-### Top-level fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|`);
-  for (const [name, fd] of Object.entries(FLOW_SCHEMA.flowFields)) {
-    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
-  }
-  sections.push(`
-### Input declarations
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|`);
-  for (const [name, fd] of Object.entries(FLOW_SCHEMA.inputFields)) {
-    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
-  }
-  sections.push(`
-### Step fields (all steps)
-
-Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines which config object is required.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|`);
-  for (const [name, fd] of Object.entries(FLOW_SCHEMA.stepCommonFields)) {
-    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
-  }
-  sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(" | ")}", "retries": 3, "retryDelayMs": 1000, "backoff": "fixed \\| exponential \\| exponential-jitter", "maxDelayMs": 30000, "retryOn": [429, 502, "ETIMEDOUT"], "failFastOn": [401, 403, 404] }\`. \`retryOn\`/\`failFastOn\` (cli#53) make retries conditional on the error code/status \u2014 \`failFastOn\` matches skip the retry entirely. |`);
-  sections.push(`
-## Step Types
-
-**IMPORTANT:** Each step type requires a config object nested under a specific key. The type name and config key differ for some types (noted below).
-
-| Type | Config Key | Description |
-|------|-----------|-------------|`);
-  for (const st of FLOW_SCHEMA.stepTypes) {
-    const keyNote = st.type !== st.configKey ? ` \u26A0\uFE0F` : "";
-    sections.push(`| \`${st.type}\` | \`${st.configKey}\`${keyNote} | ${st.description} |`);
-  }
-  sections.push(`
-## Step Type Reference`);
-  for (const st of FLOW_SCHEMA.stepTypes) {
-    sections.push(`
-### \`${st.type}\` \u2014 ${st.description}`);
-    if (st.type !== st.configKey) {
-      sections.push(`
-> **Note:** Type is \`"${st.type}"\` but config key is \`"${st.configKey}"\` (camelCase).`);
-    }
-    sections.push(`
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|`);
-    for (const [name, fd] of Object.entries(st.fields)) {
-      sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
-    }
-    sections.push(`
-\`\`\`json
-${JSON.stringify(st.example, null, 2)}
-\`\`\``);
   }
-  sections.push(`
-## Selectors
-
-| Pattern | Resolves To |
-|---------|-------------|
-| \`$.input.paramName\` | Input value |
-| \`$.steps.stepId.response\` | Full API response |
-| \`$.steps.stepId.response.data[0].email\` | Nested field |
-| \`$.steps.stepId.response.data[*].id\` | Wildcard array map |
-| \`$.env.MY_VAR\` | Environment variable |
-| \`$.loop.item\` / \`$.loop.i\` | Loop iteration |
-| \`"Hello {{$.steps.getUser.response.name}}"\` | String interpolation |
-
-### Context-aware escape pipes (cli#53)
-
-Handlebars interpolations support pipe-based escaping for safe embedding into shell commands, JSON, URLs, markdown, or HTML:
-
-| Pipe | Effect |
-|------|--------|
-| \`{{ $.x \\| json }}\`  | \`JSON.stringify\` (handles quotes, newlines, unicode) |
-| \`{{ $.x \\| shell }}\` | POSIX-shell-quote \u2014 safe inside bash arguments |
-| \`{{ $.x \\| url }}\`   | \`encodeURIComponent\` |
-| \`{{ $.x \\| md }}\`    | Escape markdown structural characters |
-| \`{{ $.x \\| html }}\`  | Entity-escape \`& < > " '\` |
-
-Pipes can be applied to any value (objects/arrays are JSON-stringified first for shell/url/md/html). An unknown pipe name throws at runtime. The legacy \`{{q $.x}}\` shell-quote helper still works but new flows should prefer \`{{$.x | shell}}\`.
-
-### When to use bare selectors vs \`{{...}}\` interpolation
-
-- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, the \`tag\` (or \`platform\`) inside \`connection\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
-- **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
-- **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
-
-### Selectors vs expressions
-
-Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`, \`connection.tag\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
-
-\`\`\`json
-{ "inputs": { "maxResults": { "type": "number", "default": 10 } } }
-\`\`\`
-
-The \`if\`, \`unless\`, \`condition.expression\`, \`while.condition\`, \`transform.expression\`, and \`code.source\` fields **do** support full JavaScript expressions (e.g., \`$.input.email && $.input.email.length > 0\`).
-
-### \`output\` vs \`response\` on step results
-
-Every completed step produces both \`output\` and \`response\`:
-- **Action steps**: \`response\` is the raw API response. \`output\` is the same as \`response\`.
-- **Code/transform steps**: \`output\` is the return value. \`response\` is an alias for \`output\`.
-- **In practice**: Use \`$.steps.stepId.response\` for action steps (API data) and \`$.steps.stepId.output\` for code/transform steps (computed data). Both work interchangeably, but using the semantically correct one makes flows easier to read.
-
-### Step result metadata (\`status\`, \`error\`, \`errorCode\`)
-
-Every step result also exposes execution metadata that downstream steps can inspect:
-
-| Field | Values | When set |
-|-------|--------|----------|
-| \`$.steps.X.status\` | \`"success"\` \\| \`"skipped"\` \\| \`"failed"\` \\| \`"timeout"\` | Always |
-| \`$.steps.X.error\` | error message string | When status is \`failed\` or \`timeout\` |
-| \`$.steps.X.errorCode\` | machine-readable code (e.g. \`"TIMEOUT"\`) | When the error has a code |
-| \`$.steps.X.durationMs\` | number | Always |
-| \`$.steps.X.retries\` | number | When the step was retried |
-
-This lets downstream steps distinguish \`skipped\` (\`if\` condition false) from \`failed\` (error, \`onError:continue\`) from \`timeout\` (exceeded \`timeoutMs\`) \u2014 e.g. \`"if": "$.steps.enrichment.status === 'timeout'"\` to retry with a longer window.
-
-### Sub-flow output (flattened)
-
-When a step has \`type: "flow"\`, the sub-flow's final step output is flattened onto the parent step's \`output\`:
-
-\`\`\`jsonc
-// Sub-flow "sub-consts" has a final step "load" that returns { CHART_URL, API_KEY }
-
-// Preferred (flattened):
-"{{$.steps.loadConfig.output.CHART_URL}}"
-
-// Legacy nested path (still works for backward compatibility):
-"{{$.steps.loadConfig.output.load.output.CHART_URL}}"
-
-// Escape hatch for programmatic access to the full sub-flow steps map:
-"{{$.steps.loadConfig.output._steps.load.output.CHART_URL}}"
-\`\`\`
-
-If a sub-step id collides with a flattened field name, the flattened field wins and the engine emits a \`flow:warning\` event.
-
-## Error Handling
-
-\`\`\`json
-{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
-\`\`\`
-
-Strategies: \`${FLOW_SCHEMA.errorStrategies.join("`, `")}\`
-
-**Conditional retry (cli#53):** add \`retryOn\` and/or \`failFastOn\` to discriminate transient errors from permanent ones. \`failFastOn\` takes precedence; \`retryOn\` (when set) requires a match for the retry to happen. Numbers match against any 3-digit substring of the error message (HTTP statuses); strings match against \`error.errorCode\` exactly OR as a case-insensitive substring of the message.
-
-\`\`\`json
-{
-  "onError": {
-    "strategy": "retry",
-    "retries": 4,
-    "backoff": "exponential",
-    "retryOn":    [429, 502, 503, "ETIMEDOUT", "ECONNRESET"],
-    "failFastOn": [401, 403, 404]
+  const errorMessage = lastError?.message || "Unknown error";
+  const strategy = onError?.strategy || "fail";
+  const retriesUsed = Math.max(0, maxAttempts - 1);
+  const isTimeout = lastError instanceof StepTimeoutError;
+  const errorCode = lastError?.errorCode;
+  if (strategy === "continue") {
+    const result = {
+      status: isTimeout ? "timeout" : "failed",
+      error: errorMessage,
+      ...errorCode ? { errorCode } : {},
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
+    };
+    context.steps[step.id] = result;
+    return result;
   }
-}
-\`\`\`
-
-## Step Output Contracts (\`outputSchema\`, cli#59)
-
-Declare a step's output shape so the validator catches downstream field-name typos at flow load time:
-
-\`\`\`json
-{
-  "id": "research",
-  "type": "flow",
-  "flow": { "key": "company-research" },
-  "outputSchema": {
-    "company": "string",
-    "charCount": "number",
-    "quality": { "confidence": "string", "score": "number" }
+  if (strategy === "fallback" && onError?.fallbackStepId) {
+    const result = {
+      status: isTimeout ? "timeout" : "failed",
+      error: errorMessage,
+      ...errorCode ? { errorCode } : {},
+      durationMs: Date.now() - startTime,
+      retries: retriesUsed
+    };
+    context.steps[step.id] = result;
+    return result;
   }
+  throw lastError;
 }
-\`\`\`
-
-Field types: \`string\`, \`number\`, \`boolean\`, \`object\`, \`array\`, \`unknown\`. Nested objects describe sub-fields. Any \`$.steps.<id>.output.<field>\` reference from a downstream step is checked against the schema; unknown fields fail validation. The runtime engine does not enforce the schema \u2014 it's a documentation / wiring-bug aid.
-
-## Bash structured env vars (cli#54)
-
-A \`bash\` step's \`env\` map accepts two structured forms in addition to plain strings:
-
-\`\`\`json
-{
-  "type": "bash",
-  "bash": {
-    "env": {
-      "PAYLOAD_FILE": { "json": "$.steps.buildConfig.output" },
-      "COMPANY":      { "shell": "$.input.companyName" }
-    },
-    "command": "curl -X POST $ENDPOINT -d @$PAYLOAD_FILE && echo \\"$COMPANY\\""
+async function executeSteps(steps, context, api, permissions, allowedActionIds, options, completedStepIds, flowStack = []) {
+  const results = [];
+  const isDryResolve = !!options.dryRun && !options.mock;
+  for (const step of steps) {
+    if (completedStepIds?.has(step.id)) {
+      results.push(context.steps[step.id] || { status: "success" });
+      continue;
+    }
+    if (isDryResolve && options.stopAfter === step.id) {
+      options.onEvent?.({
+        event: "step:dry-resolve",
+        ...dryResolveStep(step, context),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      throw new FlowStopSignal(step.id);
+    }
+    options.onEvent?.({
+      event: "step:start",
+      stepId: step.id,
+      stepName: step.name,
+      type: step.type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    try {
+      const result = await executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack);
+      results.push(result);
+      options.onEvent?.({
+        event: "step:complete",
+        stepId: step.id,
+        status: result.status,
+        durationMs: result.durationMs,
+        retries: result.retries
+      });
+    } catch (error) {
+      if (error instanceof FlowStopSignal) throw error;
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      options.onEvent?.({
+        event: "step:error",
+        stepId: step.id,
+        error: errorMsg,
+        strategy: step.onError?.strategy || "fail"
+      });
+      throw error;
+    }
+    if (!isDryResolve && options.stopAfter === step.id) {
+      throw new FlowStopSignal(step.id);
+    }
   }
+  return results;
 }
-\`\`\`
-
-- \`{ "json": <selector|value> }\` \u2014 JSON-serialized to a temp file; the env var holds the temp file path. Auto-cleaned after the step runs (success or failure).
-- \`{ "shell": <selector|value> }\` \u2014 exposed as a plain string env var; reference inside bash double quotes (\`"$VAR"\`).
-- A plain string is the legacy form (interpolated as-is, caller is responsible for escaping).
-
-## Dynamic sub-flow dispatch (cli#61)
-
-A \`flow\` step's \`flow.key\` accepts selectors and Handlebars interpolations, so a single orchestrator can route to different sub-flows at runtime:
-
-\`\`\`json
-{ "type": "flow", "flow": { "key": "{{$.input.target}}", "inputs": { "company": "$.input.company" } } }
-\`\`\`
-
-Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
-
-## Connection Resolution \u2014 late-bound by default
-
-Action steps reference a platform connection in one of two forms:
-
-\`\`\`json
-// preferred \u2014 late-bound, survives re-auth
-"connection": { "platform": "gmail" }
-
-// multi-account: disambiguate with the connection's tag
-"connection": { "platform": "gmail", "tag": "work@example.com" }
-
-// legacy \u2014 works for backwards compat, breaks on re-auth
-"connectionKey": "live::gmail::default::abc123..."
-\`\`\`
-
-The engine resolves the \`connection\` ref once per flow run (cached for the run's lifetime) by calling \`listConnections\` and matching on platform + optional tag. Resolution errors fail the step with a clear message \u2014 \`No connection found for platform "X"\`, \`Multiple "X" connections found (tags: ...). Add a "tag" field\`, or \`No "X" connection has tag "Y"\`.
-
-Both \`platform\` and \`tag\` accept \`$.input.x\` selectors so a flow can be parameterised per-execution (e.g. multi-tenant orchestrators that pass the user's email as the tag).
-
-The validator rejects any action that sets both forms or neither, at \`flow validate\` and \`flow execute\` time.
-
-### Optional input metadata: connection-key auto-resolve (legacy)
-
-For flows that still use literal \`connectionKey\` strings via inputs, an input declaration can carry a \`"connection": { "platform": "..." }\` hint so \`flow execute\` auto-fills a single matching connection's key. New flows don't need this \u2014 switch the action's connection form to \`{ platform, tag? }\` and skip the input entirely.
-
-## Complete Example: Fetch Data, Transform, Notify
-
-\`\`\`json
-{
-  "key": "contacts-to-slack",
-  "name": "CRM Contacts Summary to Slack",
-  "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
-  "version": "1",
-  "inputs": {
-    "slackChannel": {
-      "type": "string",
-      "required": true,
-      "description": "Slack channel name or ID"
-    }
-  },
-  "steps": [
-    {
-      "id": "fetchContacts",
-      "name": "Fetch recent contacts",
-      "type": "action",
-      "action": {
-        "platform": "attio",
-        "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
-        "connection": { "platform": "attio" },
-        "queryParams": { "limit": "10" }
+async function executeFlow(flow, inputs, api, permissions, allowedActionIds, options = {}, resumeState, flowStack = []) {
+  const resolvedInputs = {};
+  for (const [name, decl] of Object.entries(flow.inputs)) {
+    const provided = inputs[name];
+    const isMissing2 = provided === void 0 || provided === null;
+    if (isMissing2) {
+      if (decl.required !== false && decl.default === void 0) {
+        throw new Error(`Missing required input: "${name}"${decl.description ? ` \u2014 ${decl.description}` : ""}`);
       }
-    },
-    {
-      "id": "buildSummary",
-      "name": "Build formatted summary",
-      "type": "code",
-      "code": {
-        "source": "const contacts = $.steps.fetchContacts.response.data || [];\\nconst lines = contacts.map((c, i) => \`\${i+1}. \${c.name || 'Unknown'} \u2014 \${c.email || 'no email'}\`);\\nreturn { summary: \`Found \${contacts.length} contacts:\\n\${lines.join('\\n')}\` };"
+      if (decl.default !== void 0) {
+        resolvedInputs[name] = decl.default;
       }
-    },
-    {
-      "id": "notifySlack",
-      "name": "Post summary to Slack",
-      "type": "action",
-      "action": {
-        "platform": "slack",
-        "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
-        "connection": { "platform": "slack" },
-        "data": {
-          "channel": "$.input.slackChannel",
-          "text": "{{$.steps.buildSummary.output.summary}}"
+      continue;
+    }
+    let value = provided;
+    switch (decl.type) {
+      case "string":
+        if (typeof value !== "string") value = String(value);
+        break;
+      case "number":
+        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+          value = Number(value);
+        }
+        if (typeof value !== "number" || Number.isNaN(value)) {
+          throw new Error(`Input "${name}" must be a number, got ${describe(provided)}`);
+        }
+        break;
+      case "boolean":
+        if (value === "true" || value === "1" || value === 1) value = true;
+        else if (value === "false" || value === "0" || value === 0) value = false;
+        if (typeof value !== "boolean") {
+          throw new Error(`Input "${name}" must be a boolean, got ${describe(provided)}`);
+        }
+        break;
+      case "array":
+        if (typeof value === "string") {
+          try {
+            value = JSON.parse(value);
+          } catch {
+          }
+        }
+        if (!Array.isArray(value)) {
+          throw new Error(`Input "${name}" must be an array, got ${describe(provided)}`);
+        }
+        break;
+      case "object":
+        if (typeof value === "string") {
+          try {
+            value = JSON.parse(value);
+          } catch {
+          }
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error(`Input "${name}" must be an object, got ${describe(provided)}`);
         }
+        break;
+    }
+    if (Array.isArray(decl.enum) && decl.enum.length > 0) {
+      if (!decl.enum.some((allowed) => allowed === value)) {
+        throw new Error(`Input "${name}" must be one of ${JSON.stringify(decl.enum)}, got ${JSON.stringify(value)}`);
       }
     }
-  ]
-}
-\`\`\`
-
-Note: Action IDs above are placeholders. Always use \`one --agent actions search <platform> "<query>"\` to find real IDs.
-
-## AI-Augmented Pattern
-
-For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
-
-1. \`file-write\` \u2014 save data to temp file
-2. \`bash\` \u2014 \`claude --print\` analyzes it (\`parseJson: true\`, \`timeout: 180000\`)
-3. \`code\` \u2014 parse and structure the output
-
-Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
-
-## Notes
-
-- Connection keys are **inputs**, not hardcoded
-- Action IDs in examples are placeholders \u2014 always use \`actions search\`
-- Inline \`code.source\` steps allow \`require('crypto' | 'buffer' | 'url' | 'path')\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
-- For anything beyond one-liners, use \`code.module\` to point at a \`.mjs\` file in the flow's \`lib/\` folder \u2014 runs as a child \`node\` process with full Node APIs, reads \`$\` from stdin, writes JSON to stdout
-- Bash steps require \`--allow-bash\` flag
-- State is persisted after every step \u2014 resume picks up where it left off`);
-  return sections.join("\n");
+    resolvedInputs[name] = value;
+  }
+  const context = resumeState?.context || {
+    input: resolvedInputs,
+    env: process.env,
+    steps: {},
+    loop: {}
+  };
+  context.input = resolvedInputs;
+  context._defaultOnError = flow.defaultOnError;
+  const completedStepIds = resumeState ? new Set(resumeState.completedSteps) : void 0;
+  if (options.dryRun && !options.mock && !options.stopAfter) {
+    options.onEvent?.({
+      event: "flow:dry-run",
+      flowKey: flow.key,
+      resolvedInputs,
+      steps: dryResolveAllSteps(flow.steps, context),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return context;
+  }
+  options.onEvent?.({
+    event: options.mock ? "flow:mock-start" : "flow:start",
+    flowKey: flow.key,
+    totalSteps: flow.steps.length,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const flowStart = Date.now();
+  try {
+    await executeSteps(flow.steps, context, api, permissions, allowedActionIds, options, completedStepIds, flowStack);
+    const stepEntries = Object.values(context.steps);
+    const completed = stepEntries.filter((s) => s.status === "success").length;
+    const failed = stepEntries.filter((s) => s.status === "failed").length;
+    const skipped = stepEntries.filter((s) => s.status === "skipped").length;
+    options.onEvent?.({
+      event: "flow:complete",
+      flowKey: flow.key,
+      status: "success",
+      durationMs: Date.now() - flowStart,
+      stepsCompleted: completed,
+      stepsFailed: failed,
+      stepsSkipped: skipped
+    });
+  } catch (error) {
+    if (error instanceof FlowStopSignal) {
+      const stepEntries = Object.values(context.steps);
+      options.onEvent?.({
+        event: "flow:stopped",
+        flowKey: flow.key,
+        stoppedAfter: error.stepId,
+        dryRun: !!options.dryRun && !options.mock,
+        durationMs: Date.now() - flowStart,
+        stepsCompleted: stepEntries.filter((s) => s.status === "success").length,
+        stepsFailed: stepEntries.filter((s) => s.status === "failed").length,
+        stepsSkipped: stepEntries.filter((s) => s.status === "skipped").length,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return context;
+    }
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    options.onEvent?.({
+      event: "flow:error",
+      flowKey: flow.key,
+      status: "failed",
+      error: errorMsg,
+      durationMs: Date.now() - flowStart
+    });
+    throw error;
+  }
+  return context;
 }
 
 // src/lib/flow-runner.ts
@@ -2732,6 +2989,10 @@ var FlowRunner = class _FlowRunner {
       throw error;
     }
   }
+  /** Path to a run's persisted state file. The post-mortem artifact surfaced by `one flow inspect`. */
+  static statePathFor(flowKey, runId) {
+    return path3.join(RUNS_DIR, `${flowKey}-${runId}.state.json`);
+  }
   static loadRunState(runId) {
     ensureDir(RUNS_DIR);
     const files = fs3.readdirSync(RUNS_DIR).filter((f) => f.includes(runId) && f.endsWith(".state.json"));