@withone/cli 1.47.8 → 1.47.10

package/dist/{flow-runner-7VRNSKWU.js → flow-runner-JNEFFR2U.js}

@@ -12,7 +12,7 @@ import {
   stripStepsAlias,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-KWGN3RJR.js";
+} from "./chunk-4AYHJFH3.js";
 import "./chunk-44CV5IMX.js";
 import "./chunk-K6MWE2ZH.js";
 export {

package/dist/index.js

@@ -29,8 +29,9 @@ import {
   saveFlow,
   searchCachePath,
   validateActionInput,
+  walkSteps,
   writeCache
-} from "./chunk-KWGN3RJR.js";
+} from "./chunk-4AYHJFH3.js";
 import {
   memSqlCommand
 } from "./chunk-QV3Y5N5G.js";
@@ -3597,7 +3598,7 @@ function validateOutputSchemas(flow2) {
       walkValue(v, `${pathPrefix}.${k}`);
     }
   }
-  function walkSteps(steps, pathPrefix) {
+  function walkSteps2(steps, pathPrefix) {
     steps.forEach((step, i) => {
       const stepPath = `${pathPrefix}[${i}]`;
       if (step.if) checkText(step.if, `${stepPath}.if`);
@@ -3612,13 +3613,13 @@ function validateOutputSchemas(flow2) {
         for (const { configKey, fieldName } of nestedKeys) {
           const c = step[configKey];
           if (c && Array.isArray(c[fieldName])) {
-            walkSteps(c[fieldName], `${stepPath}.${configKey}.${fieldName}`);
+            walkSteps2(c[fieldName], `${stepPath}.${configKey}.${fieldName}`);
           }
         }
       }
     });
   }
-  walkSteps(flow2.steps, "steps");
+  walkSteps2(flow2.steps, "steps");
   return errors;
 }
 function validateOutputSchemaShape(schema, location) {
@@ -3652,6 +3653,7 @@ function validateFlow(flow2, rootDir) {
     ...validateStepIds(f),
     ...validateSelectorReferences(f, rootDir),
     ...validateOutputSchemas(f),
+    ...validateFileReadSchemas(f),
     ...rootDir ? validateCodeModules(f, rootDir) : []
   ];
 }
@@ -3692,6 +3694,108 @@ function validateCodeModules(flow2, rootDir) {
   walk(flow2.steps, "steps");
   return errors;
 }
+var VALID_FILE_READ_SCHEMA_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "object", "array", "null", "unknown"]);
+function isPlainObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function validateFileReadFieldRule(raw, fieldPath, errors) {
+  if (typeof raw === "string") {
+    if (!VALID_FILE_READ_SCHEMA_TYPES.has(raw)) {
+      errors.push({ path: fieldPath, message: `unknown type "${raw}". Allowed: ${[...VALID_FILE_READ_SCHEMA_TYPES].join(", ")}.` });
+    }
+    return;
+  }
+  if (!isPlainObject(raw)) {
+    errors.push({ path: fieldPath, message: 'field rule must be a type string or an object (e.g. { "type": "string", "required": true })' });
+    return;
+  }
+  const rule = raw;
+  if (rule.type !== void 0 && (typeof rule.type !== "string" || !VALID_FILE_READ_SCHEMA_TYPES.has(rule.type))) {
+    errors.push({ path: `${fieldPath}.type`, message: `unknown type "${String(rule.type)}". Allowed: ${[...VALID_FILE_READ_SCHEMA_TYPES].join(", ")}.` });
+  }
+  if (rule.required !== void 0 && typeof rule.required !== "boolean") {
+    errors.push({ path: `${fieldPath}.required`, message: '"required" must be a boolean' });
+  }
+  if (rule.enum !== void 0) {
+    if (!Array.isArray(rule.enum) || rule.enum.length === 0) {
+      errors.push({ path: `${fieldPath}.enum`, message: '"enum" must be a non-empty array of allowed values' });
+    } else if (rule.enum.some((e) => e !== null && typeof e === "object")) {
+      errors.push({ path: `${fieldPath}.enum`, message: '"enum" entries must be primitives (string/number/boolean) or null' });
+    }
+  }
+  for (const k of ["minItems", "maxItems", "length"]) {
+    const n = rule[k];
+    if (n !== void 0 && (typeof n !== "number" || !Number.isInteger(n) || n < 0)) {
+      errors.push({ path: `${fieldPath}.${k}`, message: `"${k}" must be a non-negative integer` });
+    }
+  }
+  if (typeof rule.minItems === "number" && typeof rule.maxItems === "number" && rule.minItems > rule.maxItems) {
+    errors.push({ path: `${fieldPath}.minItems`, message: '"minItems" must be <= "maxItems"' });
+  }
+  if (rule.length !== void 0 && (rule.minItems !== void 0 || rule.maxItems !== void 0)) {
+    errors.push({ path: `${fieldPath}.length`, message: '"length" cannot be combined with "minItems"/"maxItems"' });
+  }
+  const hasArrayConstraint = rule.items !== void 0 || rule.minItems !== void 0 || rule.maxItems !== void 0 || rule.length !== void 0;
+  if (hasArrayConstraint && rule.type !== "array") {
+    errors.push({ path: `${fieldPath}.type`, message: '"items"/"minItems"/"maxItems"/"length" require "type": "array"' });
+  }
+  if (rule.items !== void 0) {
+    if (typeof rule.items === "string") {
+      if (!VALID_FILE_READ_SCHEMA_TYPES.has(rule.items)) {
+        errors.push({ path: `${fieldPath}.items`, message: `unknown item type "${rule.items}". Allowed: ${[...VALID_FILE_READ_SCHEMA_TYPES].join(", ")}.` });
+      }
+    } else if (isPlainObject(rule.items)) {
+      validateFileReadFieldRule(rule.items, `${fieldPath}.items`, errors);
+    } else {
+      errors.push({ path: `${fieldPath}.items`, message: '"items" must be a type string or a field rule object' });
+    }
+  }
+  if (rule.properties !== void 0) {
+    if (rule.type !== "object") {
+      errors.push({ path: `${fieldPath}.properties`, message: '"properties" requires "type": "object"' });
+    }
+    errors.push(...validateFileReadSchemaShape(rule.properties, `${fieldPath}.properties`));
+  }
+}
+function validateFileReadSchemaShape(schema, location) {
+  const errors = [];
+  if (!isPlainObject(schema)) {
+    errors.push({ path: location, message: '"schema" must be an object mapping field names to type/rules' });
+    return errors;
+  }
+  for (const [field, raw] of Object.entries(schema)) {
+    validateFileReadFieldRule(raw, `${location}.${field}`, errors);
+  }
+  return errors;
+}
+function validateFileReadSchemas(flow2) {
+  const errors = [];
+  const nestedKeys = getNestedStepsKeys();
+  function walk(steps, pathPrefix) {
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const stepPath = `${pathPrefix}[${i}]`;
+      if (step.type === "file-read" && step.fileRead && step.fileRead.schema !== void 0) {
+        const fr = step.fileRead;
+        if (fr.parseJson !== true) {
+          errors.push({
+            path: `${stepPath}.fileRead.schema`,
+            message: "fileRead.schema is only checked when parseJson:true \u2014 set parseJson:true or remove schema."
+          });
+        }
+        errors.push(...validateFileReadSchemaShape(fr.schema, `${stepPath}.fileRead.schema`));
+      }
+      for (const { configKey, fieldName } of nestedKeys) {
+        const config2 = step[configKey];
+        if (config2 && Array.isArray(config2[fieldName])) {
+          walk(config2[fieldName], `${stepPath}.${configKey}.${fieldName}`);
+        }
+      }
+    }
+  }
+  walk(flow2.steps, "steps");
+  return errors;
+}
 
 // src/commands/flow.ts
 import fs5 from "fs";
@@ -3716,6 +3820,49 @@ async function writeFlowResultFile(filePath, meta, steps) {
   await done;
   return abs;
 }
+function previewValue(value, max = 120) {
+  if (value === void 0) return "<undefined>";
+  let str;
+  try {
+    str = typeof value === "string" ? JSON.stringify(value) : JSON.stringify(value) ?? String(value);
+  } catch {
+    str = String(value);
+  }
+  if (str === void 0) str = String(value);
+  return str.length > max ? `${str.slice(0, max - 1)}\u2026` : str;
+}
+function renderDryRef(ref) {
+  if (ref.status === "resolved") {
+    return `${pc7.green("\u2713")} ${ref.selector} ${pc7.dim("\u2192")} ${previewValue(ref.value)}`;
+  }
+  if (ref.status === "deferred") {
+    return `${pc7.dim("\u25CB")} ${ref.selector} ${pc7.dim("\u2192 pending (produced by a later step)")}`;
+  }
+  return `${pc7.yellow("!")} ${ref.selector} ${pc7.yellow("\u2192 unresolved \u2014 check the input/env name")}`;
+}
+function renderDryResolution(steps) {
+  const isExpr = (t) => t === "transform" || t === "condition" || t === "while";
+  for (const s of steps) {
+    const label = s.name ? `${s.stepId} ${pc7.dim(`"${s.name}"`)}` : s.stepId;
+    console.log(`  ${pc7.cyan("\u25B8")} ${label} ${pc7.dim(`(${s.type})`)}`);
+    if (s.error !== void 0) {
+      console.log(`      ${pc7.red("error")} ${s.error}`);
+    } else if (isExpr(s.type) && s.deferred) {
+      const deps = s.references.map((r) => r.selector).join(", ");
+      console.log(`      ${pc7.dim("\u25CB pending \u2014 depends on")} ${deps} ${pc7.dim("(produced by a later step)")}`);
+    } else if (isExpr(s.type)) {
+      console.log(`      ${pc7.dim("=")} ${previewValue(s.resolved)}`);
+    }
+    if (!(isExpr(s.type) && s.deferred)) {
+      for (const ref of s.references) {
+        console.log(`      ${renderDryRef(ref)}`);
+      }
+    }
+    if (!isExpr(s.type) && s.references.length === 0 && s.error === void 0) {
+      console.log(`      ${pc7.dim("(no interpolations)")}`);
+    }
+  }
+}
 function getConfig2() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -3870,6 +4017,20 @@ ${preflightErrors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
     }
     error(msg);
   }
+  if (options.stopAfter) {
+    const ids = /* @__PURE__ */ new Set();
+    walkSteps(flow2.steps, (s) => {
+      ids.add(s.id);
+    });
+    if (!ids.has(options.stopAfter)) {
+      const msg = `--stop-after target "${options.stopAfter}" is not a step in workflow "${flow2.key}". Known step ids: ${[...ids].join(", ")}`;
+      if (isAgentMode()) {
+        json({ error: msg, unknownStopAfter: options.stopAfter, stepIds: [...ids] });
+        process.exit(1);
+      }
+      error(msg);
+    }
+  }
   const inputs = parseInputs(options.input || []);
   const resolvedInputs = await autoResolveConnectionInputs(flow2, inputs, api);
   const runner = new FlowRunner(flow2, resolvedInputs);
@@ -3883,7 +4044,17 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
     }
   };
   process.on("SIGINT", sigintHandler);
+  let dryRunSteps;
+  let dryResolveTarget;
+  let stoppedAfter;
   const onEvent = (event) => {
+    if (event.event === "flow:dry-run") {
+      dryRunSteps = event.steps;
+    } else if (event.event === "step:dry-resolve") {
+      dryResolveTarget = event;
+    } else if (event.event === "flow:stopped") {
+      stoppedAfter = event.stoppedAfter;
+    }
     if (isAgentMode()) {
       json(event);
     } else if (options.verbose) {
@@ -3909,23 +4080,46 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
       verbose: options.verbose,
       allowBash: options.allowBash,
       skipValidation: options.skipValidation,
+      stopAfter: options.stopAfter,
       rootDir,
       onEvent
     });
     process.off("SIGINT", sigintHandler);
     if (!options.verbose && !isAgentMode()) {
-      execSpinner.stop("Workflow completed");
+      execSpinner.stop(stoppedAfter ? "Workflow stopped" : dryRunSteps ? "Dry run complete" : "Workflow completed");
     }
     const resultFile = options.outputFile ? await writeFlowResultFile(options.outputFile, { runId, logFile: logPath, status: "success" }, context.steps) : void 0;
+    const finalStatus = stoppedAfter ? "stopped" : "success";
     if (isAgentMode()) {
-      json(
-        resultFile ? { event: "workflow:result", runId, logFile: logPath, status: "success", outputFile: resultFile } : { event: "workflow:result", runId, logFile: logPath, status: "success", steps: context.steps }
-      );
+      const envelope = {
+        event: "workflow:result",
+        runId,
+        logFile: logPath,
+        statePath: runner.getStatePath(),
+        status: finalStatus
+      };
+      if (resultFile) envelope.outputFile = resultFile;
+      else envelope.steps = context.steps;
+      if (options.dryRun) envelope.dryRun = true;
+      if (stoppedAfter) envelope.stoppedAfter = stoppedAfter;
+      json(envelope);
       return;
     }
     if (resultFile) {
       note(`Full result written to ${resultFile}`, "Output");
     }
+    if (dryRunSteps && !stoppedAfter) {
+      console.log();
+      renderDryResolution(dryRunSteps);
+      console.log();
+      const missing = dryRunSteps.reduce((n, s) => n + s.references.filter((r) => r.status === "missing").length, 0);
+      note(
+        `Dry run \u2014 no steps executed. Resolved ${dryRunSteps.length} step(s)` + (missing > 0 ? `; ${pc7.yellow(`${missing} unresolved input/env reference(s)`)}` : "") + `.
+${pc7.dim("$.steps.* refs resolve at runtime \u2014 re-run with --stop-after=<stepId> to resolve them against real output.")}`,
+        "Dry Run"
+      );
+      return;
+    }
     const stepEntries = Object.entries(context.steps);
     const succeeded = stepEntries.filter(([, r]) => r.status === "success").length;
     const failed = stepEntries.filter(([, r]) => r.status === "failed").length;
@@ -3934,7 +4128,17 @@ ${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
     console.log(`  ${pc7.green("\u2713")} ${succeeded} succeeded  ${failed > 0 ? pc7.red(`\u2717 ${failed} failed`) : ""}  ${skipped > 0 ? pc7.dim(`\u25CB ${skipped} skipped`) : ""}`);
     console.log(`  ${pc7.dim(`Run ID: ${runId}`)}`);
     console.log(`  ${pc7.dim(`Log: ${logPath}`)}`);
-    if (options.dryRun) {
+    if (dryResolveTarget) {
+      console.log();
+      console.log(`  ${pc7.dim(`Resolved (not executed) "${dryResolveTarget.stepId}":`)}`);
+      renderDryResolution([dryResolveTarget]);
+    }
+    if (stoppedAfter) {
+      note(
+        `Stopped after step "${stoppedAfter}". Inspect step outputs with: ${pc7.cyan(`one flow inspect ${runId}`)}`,
+        "Stopped"
+      );
+    } else if (options.dryRun) {
       note("Dry run \u2014 no steps were executed", "Dry Run");
     }
   } catch (error2) {
@@ -4126,6 +4330,64 @@ async function flowRunsCommand(flowKey) {
   );
   console.log();
 }
+async function flowInspectCommand(runId, options = {}) {
+  intro(pc7.bgCyan(pc7.black(" One Workflow ")));
+  const state = FlowRunner.loadRunState(runId);
+  if (!state) {
+    const msg = `No run found for id "${runId}". List runs with: one flow runs`;
+    if (isAgentMode()) {
+      json({ error: msg, runId });
+      process.exit(1);
+    }
+    error(msg);
+    return;
+  }
+  const statePath = FlowRunner.statePathFor(state.flowKey, state.runId);
+  const stepEntries = Object.entries(state.context.steps || {});
+  if (isAgentMode()) {
+    json({
+      runId: state.runId,
+      flowKey: state.flowKey,
+      status: state.status,
+      startedAt: state.startedAt,
+      completedAt: state.completedAt,
+      pausedAt: state.pausedAt,
+      currentStepId: state.currentStepId,
+      inputs: state.inputs,
+      steps: state.context.steps,
+      statePath
+    });
+    return;
+  }
+  console.log();
+  console.log(`  ${pc7.bold(state.flowKey)} ${pc7.dim(`run ${state.runId}`)}  ${colorStatus(state.status)}`);
+  console.log(`  ${pc7.dim(`Started: ${state.startedAt}${state.completedAt ? `  \xB7  Ended: ${state.completedAt}` : ""}`)}`);
+  if (state.currentStepId) console.log(`  ${pc7.dim(`Current step: ${state.currentStepId}`)}`);
+  console.log();
+  if (stepEntries.length === 0) {
+    note("No step outputs recorded yet for this run.", "Steps");
+  } else {
+    for (const [id, result] of stepEntries) {
+      const icon = result.status === "success" ? pc7.green("\u2713") : result.status === "skipped" ? pc7.dim("\u25CB") : result.status === "timeout" ? pc7.yellow("\u29D6") : pc7.red("\u2717");
+      const dur = result.durationMs !== void 0 ? pc7.dim(` ${result.durationMs}ms`) : "";
+      const retries = result.retries ? pc7.dim(` (${result.retries} retr${result.retries === 1 ? "y" : "ies"})`) : "";
+      console.log(`  ${icon} ${id} ${pc7.dim(`[${result.status}]`)}${dur}${retries}`);
+      if (result.error) {
+        console.log(`      ${pc7.red("error")} ${result.error}${result.errorCode ? pc7.dim(` (${result.errorCode})`) : ""}`);
+      }
+      if (result.output !== void 0) {
+        const json2 = JSON.stringify(result.output, null, options.full ? 2 : 0) ?? String(result.output);
+        const shown = options.full || json2.length <= 240 ? json2 : `${json2.slice(0, 239)}\u2026  ${pc7.dim("(--full for all)")}`;
+        const indented = options.full ? shown.split("\n").map((l) => `        ${l}`).join("\n") : `      ${pc7.dim("output")} ${shown}`;
+        console.log(indented);
+      }
+    }
+  }
+  console.log();
+  console.log(`  ${pc7.dim(`State: ${statePath}`)}`);
+  console.log(`  ${pc7.dim(`Log:   ${path5.join(".one/flows/.logs", `${state.flowKey}-${state.runId}.log`)}`)}`);
+  console.log();
+}
 function colorStatus(status) {
   switch (status) {
     case "completed":
@@ -9452,6 +9714,9 @@ Chain actions across platforms as JSON workflow files with conditions, loops, pa
 one --agent flow create <key> --definition '<json>'   # Create a workflow
 one --agent flow validate <key>                       # Validate it
 one --agent flow execute <key> -i param=value         # Execute it
+one --agent flow execute <key> --dry-run -i ...       # Resolve interpolations, run nothing
+one --agent flow execute <key> --stop-after <stepId>  # Run up to a step, then stop
+one --agent flow inspect <runId>                      # Per-step outputs of a past run
 one --agent flow list                                 # List all workflows
 \`\`\`
 
@@ -9465,6 +9730,7 @@ one --agent flow list                                 # List all workflows
 - Use \`--skip-validation\` to bypass input validation on action steps
 - Use \`--output-file <path>\` to stream the full result to a file instead of stdout \u2014 for large results that would otherwise be truncated or hit the JSON string-size limit; stdout (and \`--agent\` output) then carries an \`outputFile\` pointer instead of inline \`steps\`
 - Step-level \`if\`/\`unless\` (and \`while\`/\`condition\` steps) are null-safe: a condition referencing a skipped or not-yet-run step's output (e.g. \`$.steps.maybeSkipped.output.x\`) evaluates to \`false\` instead of crashing the flow
+- Debugging: \`--dry-run\` resolves each step's interpolations and shows what they evaluate to without executing (\`$.steps.*\` refs are reported as deferred); \`--stop-after <stepId>\` runs up to a step then stops; \`--dry-run --stop-after <stepId>\` runs earlier steps for real then dry-resolves the target against their output; \`flow inspect <runId>\` shows a past run's per-step outputs (post-mortem, no re-run; \`--full\` for untruncated)
 
 ### 3. Relay \u2014 Webhook event forwarding between platforms
 Receive webhooks from platforms (Stripe, GitHub, Airtable, Attio, Google Calendar) and forward event data to any connected platform using passthrough actions with Handlebars templates. No middleware, no code.
@@ -11361,7 +11627,7 @@ var flow = program.command("flow").alias("f").description("Create, execute, and
 flow.command("create [key]").description("Create a new workflow from JSON definition").option("--definition <json>", "Workflow definition as JSON string").option("-o, --output <path>", "Custom output path (default .one/flows/<key>/flow.json)").action(async (key, options) => {
   await flowCreateCommand(key, options);
 });
-flow.command("execute <keyOrPath>").alias("x").description("Execute a workflow by key or file path").option("-i, --input <name=value>", "Input parameter (repeatable)", collect, []).option("--dry-run", "Validate and show execution plan without running").option("--mock", "With --dry-run: execute transforms/code with realistic mock API responses").option("--skip-validation", "Skip input validation against action schemas").option("--allow-bash", "Allow bash step execution (disabled by default for security)").option("-v, --verbose", "Show full request/response for each step").option("--output-file <path>", "Write the full result to a file (streamed) instead of stdout \u2014 avoids truncation/string-limit errors for large results; stdout/agent output then carries an outputFile pointer").action(async (keyOrPath, options) => {
+flow.command("execute <keyOrPath>").alias("x").description("Execute a workflow by key or file path").option("-i, --input <name=value>", "Input parameter (repeatable)", collect, []).option("--dry-run", "Resolve each step's interpolations and show what they evaluate to, without executing any step ($.steps.* refs resolve at runtime)").option("--mock", "With --dry-run: execute transforms/code with realistic mock API responses").option("--stop-after <stepId>", "Execute steps up to and including <stepId>, then stop (later steps are not run). With --dry-run, runs earlier steps for real and dry-resolves <stepId> against their output without executing it. See: one flow inspect").option("--skip-validation", "Skip input validation against action schemas").option("--allow-bash", "Allow bash step execution (disabled by default for security)").option("-v, --verbose", "Show full request/response for each step").option("--output-file <path>", "Write the full result to a file (streamed) instead of stdout \u2014 avoids truncation/string-limit errors for large results; stdout/agent output then carries an outputFile pointer").action(async (keyOrPath, options) => {
   await flowExecuteCommand(keyOrPath, options);
 });
 flow.command("list").alias("ls").description("List all workflows in .one/flows/").action(async () => {
@@ -11376,6 +11642,9 @@ flow.command("resume <runId>").description("Resume a paused or failed workflow r
 flow.command("runs [flowKey]").description("List workflow runs (optionally filtered by flow key)").action(async (flowKey) => {
   await flowRunsCommand(flowKey);
 });
+flow.command("inspect <runId>").description("Inspect a past run's per-step outputs (post-mortem, no re-run) from its saved state file").option("--full", "Show full step outputs (default truncates large values)").action(async (runId, options) => {
+  await flowInspectCommand(runId, options);
+});
 flow.command("scaffold [template]").description("Generate a workflow scaffold (templates: basic, conditional, loop, ai)").action(async (template) => {
   await flowScaffoldCommand(template);
 });

package/package.json

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

package/skills/one/SKILL.md

@@ -261,7 +261,7 @@ Without declared paths, the default walker concatenates every string in the reco
 One also supports more advanced patterns. Read the relevant reference file before using these:
 
 - **Webhook Relay** — Receive webhooks from a platform and forward to another (e.g., Stripe event -> Slack message). Read `references/relay.md` in this skill's directory for the full workflow.
-- **Multi-step Workflows** — Chain actions across platforms as JSON workflow files (like n8n/Zapier but file-based). Read `references/flows.md` in this skill's directory for the schema and examples.
+- **Multi-step Workflows** — Chain actions across platforms as JSON workflow files (like n8n/Zapier but file-based). Read `references/flows.md` in this skill's directory for the schema and examples. To debug: `flow execute <key> --dry-run` (resolve interpolations without running), `--stop-after <stepId>` (run up to a step then stop), and `flow inspect <runId>` (a past run's per-step outputs).
 
 ## Adding New Connections
 

package/skills/one/references/flows.md

@@ -8,7 +8,7 @@ Nothing about a flow's runtime requirements is guessable from its name. Before `
 
 1. **Recommended:** `one --agent flow list` — the JSON output includes `requiresBash`, `usesCodeModules`, `inputs` (with `autoResolvable`), `stepTypes`, and the flow's `description`. Fastest path to knowing what you need.
 2. Read the flow's `description` field from the JSON. Authors are required (see "Author conventions" below) to state `--allow-bash` requirements and non-auto-resolving inputs there.
-3. `one --agent flow execute <key> --dry-run` to see resolved inputs and step plan without side effects.
+3. `one --agent flow execute <key> --dry-run` to resolve every step's interpolations and see what they evaluate to — without side effects (see "Debugging a flow" below).
 
 If you skip this, you will hit errors like *"Workflow X contains bash steps. Re-run with --allow-bash."* — the CLI pre-flights and fails fast, but the error is entirely avoidable by reading first.
 
@@ -400,6 +400,28 @@ After a parallel step, access each substep's output by its `id`: `$.steps.fetchE
 { "id": "write", "type": "file-write", "fileWrite": { "path": "./output/results.json", "content": "$.steps.transform.output" } }
 ```
 
+**Validate a read config (`fileRead.schema`).** With `parseJson: true` you can add an optional `schema` that is **enforced at runtime** — a mismatch throws (`errorCode: "SCHEMA_VALIDATION"`) and is handled by the step's `onError`, so a bad config file fails fast with a clear message instead of producing garbage downstream. (This is distinct from `step.outputSchema`, which is documentation/wiring only and never checked at runtime.)
+
+```json
+{
+  "id": "read", "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"] },
+      "retries": { "type": "number" },
+      "tags": { "type": "array", "items": "string", "minItems": 1, "maxItems": 10 },
+      "coords": { "type": "array", "length": 2, "items": "number" },
+      "owner": { "type": "object", "required": true,
+                 "properties": { "id": "string", "email": { "type": "string", "required": true } } }
+    }
+  }
+}
+```
+
+Field rules (a richer field-rule format inspired by `outputSchema`): a value is a bare type string (`"string"`, optional) or `{ type, required, enum, items, minItems, maxItems, length, properties }`. Types: `string`/`number`/`boolean`/`object`/`array`/`null`/`unknown` (`unknown` passes anything). **Array constraints (`items`/`minItems`/`maxItems`/`length`) require `type: "array"`, and `properties` requires `type: "object"`** — `flow validate` rejects them otherwise (so they can't silently no-op). All violations are reported in one error; paths are dotted/indexed (`owner.email`, `tags[3]`); a non-object root reports `expected an object at the root but got <type>`. `flow validate` checks the schema's shape (and that `parseJson:true` is set). With `onError: { strategy: "continue" }` the step lands as `{ status: "failed", errorCode: "SCHEMA_VALIDATION" }` so downstream steps can branch on it; `retry`/`fallback` and `retryOn:["SCHEMA_VALIDATION"]` work too.
+
 ### `while` — Condition-driven loop (do-while)
 
 ```json
@@ -655,12 +677,24 @@ one --agent flow validate <key>
 one --agent flow execute <key> -i key=value
 one --agent flow execute <key> --dry-run -i key=value
 one --agent flow execute <key> --dry-run --mock -i key=value
+one --agent flow execute <key> --stop-after <stepId> -i key=value
+one --agent flow execute <key> --dry-run --stop-after <stepId> -i key=value
 one --agent flow execute <key> --skip-validation -i key=value
 one --agent flow execute <key> --allow-bash -i key=value
 one --agent flow runs [flowKey]
+one --agent flow inspect <runId>          # per-step outputs of a past run (add --full for untruncated)
 one --agent flow resume <runId>
 ```
 
+## Debugging a flow
+
+Three tools that turn "re-run the whole 40-step flow to debug step 30" into near-zero-cost inspection:
+
+- **`--dry-run`** — resolves every step's interpolations and shows what they evaluate to, *without executing any step*. `$.input.*` / `$.env.*` resolve immediately; `$.steps.*` references are reported as `deferred` (they're produced at runtime). Transform/condition/while steps show their *evaluated* result; if a transform can't evaluate yet because it reads a step that hasn't run, it's marked `deferred` (depends on a later step) rather than shown as an error — genuine problems (syntax errors, missing inputs, a missing field on a step that *did* run) still surface as errors. Catches wiring bugs (typo'd input names, wrong field paths) with zero API spend. In `--agent` mode this is the `flow:dry-run` event whose `steps[]` carry a `references` table (`{selector, value, status}` where status is `resolved` | `deferred` | `missing`), an evaluated `resolved` value, and a `deferred` / `error` flag for expression steps.
+- **`--stop-after <stepId>`** — executes steps up to and including `<stepId>`, then stops; later steps don't run. Isolates where a long flow breaks. Emits a `flow:stopped` event; the run's partial state is saved.
+- **`--dry-run --stop-after <stepId>`** — runs the steps *before* `<stepId>` for real, then dry-resolves `<stepId>` against that **real** accumulated context (so its `$.steps.*` references resolve to actual upstream output) and stops without executing it. The honest way to preview "what will step N actually receive". Emits a `step:dry-resolve` event for the target.
+- **`flow inspect <runId>`** — prints a past run's per-step status, durations, errors, and outputs from its persisted state file (post-mortem, no re-run). Use after `--stop-after`, or on any failed run, to see exactly what each step produced. `--full` disables output truncation.
+
 ## Important Notes
 
 - **Prefer passthrough actions over custom actions.** Custom actions add server-side fan-out that causes timeouts at scale. The flow runner handles pagination, retries, and rate limiting locally. Search with `-t knowledge` to find passthrough endpoints (e.g. GET `/gmail/v1/users/{userId}/threads` instead of POST `/gmail/get-threads`)