@withone/cli 1.26.0 → 1.27.0

package/dist/{chunk-ZOIXA7MV.js → chunk-AZV4EGKT.js}

@@ -5,6 +5,7 @@ import crypto from "crypto";
 
 // src/lib/flow-engine.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { exec, spawn } from "child_process";
 import { promisify } from "util";
@@ -463,6 +464,27 @@ function withTimeout(promise, timeoutMs, stepId) {
     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;
@@ -509,27 +531,64 @@ function resolveSelector(selectorPath, context) {
 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*\}\}/g, (_match, qFlag, selector) => {
-    const value = resolveSelector(selector, context);
-    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;
+  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).`);
+        }
+        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;
+      }
+      const str2 = String(value);
+      return qFlag ? shellQuote(str2) : str2;
     }
-    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 (value.includes("{{$.") || /\{\{\s*q\s+\$\./.test(value)) {
+    if (/\{\{\s*(q\s+)?\$\./.test(value)) {
       return interpolateString(value, context);
     }
     return value;
@@ -914,7 +973,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-3DCROTPW.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-AK5W4GLF.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1006,6 +1065,39 @@ async function executePaginateStep(step, context, api, permissions, allowedActio
     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 = path.join(
+          os.tmpdir(),
+          `one-flow-${stepId}-${key}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`
+        );
+        fs.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");
@@ -1013,19 +1105,33 @@ async function executeBashStep(step, context, options) {
   const config = step.bash;
   const command = resolveValue(config.command, context);
   const cwd = config.cwd ? resolveValue(config.cwd, context) : process.cwd();
-  const env = config.env ? { ...process.env, ...resolveValue(config.env, context) } : process.env;
-  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 }
-  };
+  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 {
+        fs.unlinkSync(tmp);
+      } catch {
+      }
+    }
+  }
 }
 function describe(value) {
   if (value === null) return "null";
@@ -1155,6 +1261,18 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
       if (attempt === maxAttempts) {
         break;
       }
+      if (step.onError?.strategy === "retry" && (step.onError.retryOn || step.onError.failFastOn)) {
+        const decision = shouldRetryError(lastError, step.onError);
+        if (!decision.retry) {
+          options.onEvent?.({
+            event: "step:retry-skip",
+            stepId: step.id,
+            reason: decision.reason ?? "no-match",
+            error: lastError.message
+          });
+          break;
+        }
+      }
     }
   }
   const errorMessage = lastError?.message || "Unknown error";
@@ -1368,7 +1486,8 @@ var FLOW_SCHEMA = {
     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." }
+    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: [
     {
@@ -1808,7 +1927,7 @@ Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines whi
   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 }\` |`);
+  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
 
@@ -1853,6 +1972,20 @@ ${JSON.stringify(st.example, null, 2)}
 | \`$.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\`, \`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).
@@ -1917,6 +2050,68 @@ If a sub-step id collides with a flattened field name, the flattened field wins
 
 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]
+  }
+}
+\`\`\`
+
+## 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" }
+  }
+}
+\`\`\`
+
+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\\""
+  }
+}
+\`\`\`
+
+- \`{ "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"\`
 
 ## Input Connection Auto-Resolution

package/dist/{flow-runner-3DCROTPW.js → flow-runner-AK5W4GLF.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-ZOIXA7MV.js";
+} from "./chunk-AZV4EGKT.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadFlowWithMeta,
   resolveFlowPath,
   saveFlow
-} from "./chunk-ZOIXA7MV.js";
+} from "./chunk-AZV4EGKT.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -2605,6 +2605,144 @@ function validateSelectorReferences(flow2) {
   });
   return errors;
 }
+var VALID_OUTPUT_SCHEMA_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "object", "array", "unknown"]);
+function isOutputSchemaObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function walkOutputSchema(schema, path8) {
+  let current = schema;
+  for (let i = 0; i < path8.length; i++) {
+    const seg = path8[i];
+    if (typeof current === "string") {
+      return current === "unknown" || current === "object" || current === "array" ? "opaque" : "opaque";
+    }
+    if (!(seg in current)) return "unknown-field";
+    const next = current[seg];
+    if (typeof next === "string") {
+      if (!VALID_OUTPUT_SCHEMA_TYPES.has(next)) return "unknown-field";
+      current = next;
+    } else if (isOutputSchemaObject(next)) {
+      current = next;
+    } else {
+      return "unknown-field";
+    }
+  }
+  return "ok";
+}
+function collectOutputSchemas(flow2) {
+  const out = /* @__PURE__ */ new Map();
+  const nestedKeys = getNestedStepsKeys();
+  function walk(steps) {
+    for (const step of steps) {
+      if (step.outputSchema && isOutputSchemaObject(step.outputSchema)) {
+        out.set(step.id, step.outputSchema);
+      }
+      for (const { configKey, fieldName } of nestedKeys) {
+        const config2 = step[configKey];
+        if (config2 && Array.isArray(config2[fieldName])) {
+          walk(config2[fieldName]);
+        }
+      }
+    }
+  }
+  walk(flow2.steps);
+  return out;
+}
+function validateOutputSchemas(flow2) {
+  const errors = [];
+  const schemas = collectOutputSchemas(flow2);
+  if (schemas.size === 0) return errors;
+  for (const [stepId, schema] of schemas) {
+    const schemaErrors = validateOutputSchemaShape(schema, `step "${stepId}".outputSchema`);
+    errors.push(...schemaErrors);
+  }
+  const SELECTOR_RE = /\$\.steps\.([a-zA-Z_][\w-]*)\.output((?:\.[a-zA-Z_][\w-]*)+)/g;
+  function checkText(text4, location) {
+    if (typeof text4 !== "string") return;
+    for (const m of text4.matchAll(SELECTOR_RE)) {
+      const stepId = m[1];
+      const tail = m[2].slice(1).split(".");
+      const schema = schemas.get(stepId);
+      if (!schema) continue;
+      const result = walkOutputSchema(schema, tail);
+      if (result === "unknown-field") {
+        errors.push({
+          path: location,
+          message: `Selector "${m[0]}" references field "${tail.join(".")}" which is not declared in step "${stepId}".outputSchema. Either fix the field name or update the outputSchema declaration.`
+        });
+      }
+    }
+  }
+  function walkValue(value, location) {
+    if (typeof value === "string") {
+      checkText(value, location);
+    } else if (Array.isArray(value)) {
+      value.forEach((v, i) => walkValue(v, `${location}[${i}]`));
+    } else if (value && typeof value === "object") {
+      for (const [k, v] of Object.entries(value)) {
+        walkValue(v, `${location}.${k}`);
+      }
+    }
+  }
+  const nestedKeys = getNestedStepsKeys();
+  const nestedFieldSet = new Set(nestedKeys.map((k) => `${k.configKey}.${k.fieldName}`));
+  function walkConfig(config2, configKey, pathPrefix) {
+    if (!config2 || typeof config2 !== "object" || Array.isArray(config2)) {
+      walkValue(config2, pathPrefix);
+      return;
+    }
+    for (const [k, v] of Object.entries(config2)) {
+      if (nestedFieldSet.has(`${configKey}.${k}`)) continue;
+      walkValue(v, `${pathPrefix}.${k}`);
+    }
+  }
+  function walkSteps(steps, pathPrefix) {
+    steps.forEach((step, i) => {
+      const stepPath = `${pathPrefix}[${i}]`;
+      if (step.if) checkText(step.if, `${stepPath}.if`);
+      if (step.unless) checkText(step.unless, `${stepPath}.unless`);
+      if (Array.isArray(step.requires)) {
+        step.requires.forEach((s, ri) => checkText(s, `${stepPath}.requires[${ri}]`));
+      }
+      const descriptor = getStepTypeDescriptor(step.type);
+      if (descriptor) {
+        const config2 = step[descriptor.configKey];
+        if (config2) walkConfig(config2, descriptor.configKey, `${stepPath}.${descriptor.configKey}`);
+        for (const { configKey, fieldName } of nestedKeys) {
+          const c = step[configKey];
+          if (c && Array.isArray(c[fieldName])) {
+            walkSteps(c[fieldName], `${stepPath}.${configKey}.${fieldName}`);
+          }
+        }
+      }
+    });
+  }
+  walkSteps(flow2.steps, "steps");
+  return errors;
+}
+function validateOutputSchemaShape(schema, location) {
+  const errors = [];
+  if (!isOutputSchemaObject(schema)) {
+    errors.push({ path: location, message: "outputSchema must be an object" });
+    return errors;
+  }
+  for (const [key, val] of Object.entries(schema)) {
+    const where = `${location}.${key}`;
+    if (typeof val === "string") {
+      if (!VALID_OUTPUT_SCHEMA_TYPES.has(val)) {
+        errors.push({
+          path: where,
+          message: `outputSchema field "${key}" has unknown type "${val}". Allowed: ${[...VALID_OUTPUT_SCHEMA_TYPES].join(", ")}.`
+        });
+      }
+    } else if (isOutputSchemaObject(val)) {
+      errors.push(...validateOutputSchemaShape(val, where));
+    } else {
+      errors.push({ path: where, message: `outputSchema field "${key}" must be a type string or a nested object` });
+    }
+  }
+  return errors;
+}
 function validateFlow(flow2, rootDir) {
   const schemaErrors = validateFlowSchema(flow2);
   if (schemaErrors.length > 0) return schemaErrors;
@@ -2612,6 +2750,7 @@ function validateFlow(flow2, rootDir) {
   return [
     ...validateStepIds(f),
     ...validateSelectorReferences(f),
+    ...validateOutputSchemas(f),
     ...rootDir ? validateCodeModules(f, rootDir) : []
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/references/flows.md

@@ -234,6 +234,29 @@ A pure `$.xxx` value resolves to the raw type. A string containing `{{$.xxx}}` d
 "files": "$.steps.extract.output.allFiles"
 ```
 
+### Context-aware escape pipes (cli#53)
+
+Handlebars interpolations support pipe-based escaping so user-controlled values are safe to embed in shell commands, JSON payloads, URLs, markdown, or HTML without writing per-call escapers:
+
+```json
+{
+  "command": "curl -d {{$.input.payload | json}} https://example.com/{{$.input.slug | url}}",
+  "env": { "GREETING": { "shell": "$.input.name" } }
+}
+```
+
+Available pipes:
+
+| Pipe | Effect | Example |
+|------|--------|---------|
+| `json` | `JSON.stringify` (handles quotes, newlines, unicode) | `{{$.x \| json}}` → `"O'Brien & Co."` |
+| `shell` | POSIX-shell-quote (apostrophes use the `'\''` close-reopen trick) | `{{$.x \| shell}}` → `'O'\''Brien & Co.'` |
+| `url` | `encodeURIComponent` | `{{$.x \| url}}` → `O'Brien%20%26%20Co.` |
+| `md` | Escape markdown structural characters (` ` ` * _ { } [ ] ( ) # + - ! \| `) | `{{x \| md}}` |
+| `html` | Entity-escape `& < > " '` | `{{x \| html}}` → `&lt;b&gt;` |
+
+Pipes can be applied to numbers, booleans, objects, and `null`/`undefined` (which become empty string for shell/url/md/html, `null` for json). An unknown pipe name throws a clear error at flow execution time. Pipes cannot be combined with the legacy `q` prefix — use the pipe form (`{{$.x | shell}}` instead of `{{q $.x}}`).
+
 ### Selectors vs expressions
 
 Selectors in data fields (`data`, `queryParams`, `pathVars`, `connectionKey`) are **dot-path lookups only** — they do not support JavaScript operators like `||` or `&&`. For default values, use the `default` field on the input definition:
@@ -390,6 +413,8 @@ After a parallel step, access each substep's output by its `id`: `$.steps.fetchE
 }
 ```
 
+**Dynamic dispatch (cli#61).** `flow.key` accepts a selector (`"$.input.target"`) or Handlebars interpolation (`"{{$.input.prefix}}-{{$.input.suffix}}"`). The resolved key is loaded at runtime, so you can write a single orchestrator that picks among multiple sub-flows based on inputs or upstream results — no bash workaround required. If the resolved key does not exist, the step fails with the standard "flow not found" error.
+
 A sub-flow step exposes the sub-flow's **step results map** at both `.output` and `.response` (they are aliases — pick whichever reads better). Access a specific sub-step's data with:
 
 ```
@@ -444,6 +469,27 @@ Alternatively, pass values as environment variables (also shell-safe) and refere
 }
 ```
 
+**Structured env vars (cli#54).** A bash step's `env` map also accepts two structured forms that handle JSON and shell escaping safely without writing temp files by hand:
+
+```json
+{
+  "type": "bash",
+  "bash": {
+    "env": {
+      "PAYLOAD_FILE": { "json": "$.steps.buildConfig.output" },
+      "COMPANY":      { "shell": "$.input.companyName" }
+    },
+    "command": "curl -X POST $ENDPOINT -H 'Content-Type: application/json' -d @$PAYLOAD_FILE && echo \"$COMPANY\""
+  }
+}
+```
+
+- `{ "json": <selector|value> }` — the resolved value is JSON-serialized, written to a temp file, and the env var is set to the temp file's path. Use it with `curl -d @$VAR` or `cat $VAR`. The temp file is cleaned up automatically after the step finishes (success OR failure).
+- `{ "shell": <selector|value> }` — the resolved value is exposed as a plain string env var. Reference it inside bash double quotes (`"$VAR"`) so bash itself handles word-splitting.
+- A plain string value (`"COMPANY": "$.input.companyName"`) is the legacy form — interpolated as-is.
+
+This is the recommended way to pass structured payloads to `curl`, `claude --print`, or any CLI that expects a JSON file. It eliminates the older `file-write → bash` two-step workaround.
+
 ## Step Input Contracts (`requires`)
 
 Declare the data a step depends on so the engine fails fast — with a useful error — when an upstream value is missing. Without `requires`, a skipped or failed upstream step silently leaves `undefined` in the context and the consumer either crashes deep in user code or burns an LLM call on empty input.
@@ -473,6 +519,34 @@ The "because…" suffix tells you exactly why — skipped, failed, or timed out
 
 Forward references are caught at flow load time: if `requires` points at a step declared after the current step, validation rejects the flow.
 
+## Step Output Contracts (`outputSchema`)
+
+Declare the shape of a step's `output` so the validator can catch field-name typos in downstream selectors at flow load time — long before a misspelled `$.steps.research.output.charCount` silently resolves to `undefined` at runtime:
+
+```json
+{
+  "id": "research",
+  "type": "flow",
+  "flow": { "key": "company-research" },
+  "outputSchema": {
+    "company": "string",
+    "research": "string",
+    "charCount": "number",
+    "quality": { "confidence": "string", "coverageScore": "number" }
+  }
+}
+```
+
+Field types: `"string"`, `"number"`, `"boolean"`, `"object"`, `"array"`, `"unknown"`. Nest objects to describe sub-fields (`quality.coverageScore` above). Anything not declared is rejected when referenced via `$.steps.<id>.output.<field>` from a downstream step:
+
+```
+Selector "$.steps.research.output.chars" references field "chars" which is not
+declared in step "research".outputSchema. Either fix the field name or update
+the outputSchema declaration.
+```
+
+`outputSchema` is purely a documentation / validation aid — the engine does **not** enforce the shape at runtime, so a code step that returns an unexpected field still works (it just won't be discoverable from typed selectors). Schemas declared on a step apply to all references from anywhere in the flow tree (including inside loops, conditions, parallel blocks, code, and transform expressions).
+
 ## Error Handling
 
 ```json
@@ -497,6 +571,26 @@ Strategies: `fail` (default), `continue`, `retry`, `fallback`.
 
 `exponential` waits `retryDelayMs * 2^(retryIndex)` (1s, 2s, 4s, 8s…) capped at `maxDelayMs`. `exponential-jitter` multiplies each wait by a random factor in [0.5, 1.0) so concurrent retries spread out.
 
+**Conditional retry (cli#53).** By default a `retry` strategy retries every error. To distinguish transient failures (rate-limits, timeouts) from permanent ones (auth errors, 404s) add `retryOn` and/or `failFastOn`:
+
+```json
+{
+  "onError": {
+    "strategy": "retry",
+    "retries": 4,
+    "backoff": "exponential",
+    "retryOn":    [429, 502, 503, "ETIMEDOUT", "ECONNRESET"],
+    "failFastOn": [401, 403, 404]
+  }
+}
+```
+
+- `failFastOn` takes precedence: if the error matches any entry, the step fails immediately without consuming retries.
+- `retryOn` (when set): the error must match an entry to be retried; non-matching errors fail immediately.
+- If neither is set the legacy "retry every error" behavior applies.
+
+Match rules: number entries are compared against any 3-digit token in the error message (covers `HTTP 429`, `status 502`, etc.); string entries match `error.errorCode` exactly OR appear as a case-insensitive substring of the message (covers Node error codes like `ETIMEDOUT` and our own `TIMEOUT`).
+
 **Inspecting retry outcomes.** Every retried step exposes how it ended on its `StepResult`:
 
 - `$.steps.<id>.status` — `"success"` or `"failed"`