@picahq/cli 1.9.3 → 1.10.0

package/dist/index.js

@@ -305,8 +305,8 @@ var PicaApi = class {
   constructor(apiKey) {
     this.apiKey = apiKey;
   }
-  async request(path3) {
-    return this.requestFull({ path: path3 });
+  async request(path5) {
+    return this.requestFull({ path: path5 });
   }
   async requestFull(opts) {
     let url = `${API_BASE}${opts.path}`;
@@ -488,7 +488,8 @@ var PicaApi = class {
       const text4 = await response.text();
       throw new ApiError(response.status, text4 || `HTTP ${response.status}`);
     }
-    const responseData = await response.json();
+    const responseText = await response.text();
+    const responseData = responseText ? JSON.parse(responseText) : {};
     return {
       requestConfig: sanitizedConfig,
       responseData
@@ -521,9 +522,9 @@ var TimeoutError = class extends Error {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function replacePathVariables(path3, variables) {
-  if (!path3) return path3;
-  let result = path3;
+function replacePathVariables(path5, variables) {
+  if (!path5) return path5;
+  let result = path5;
   result = result.replace(/\{\{([^}]+)\}\}/g, (_match, variable) => {
     const trimmedVariable = variable.trim();
     const value = variables[trimmedVariable];
@@ -629,6 +630,12 @@ function createSpinner() {
 function intro2(msg) {
   if (!isAgentMode()) p.intro(msg);
 }
+function outro2(msg) {
+  if (!isAgentMode()) p.outro(msg);
+}
+function note2(msg, title) {
+  if (!isAgentMode()) p.note(msg, title);
+}
 function json(data) {
   process.stdout.write(JSON.stringify(data) + "\n");
 }
@@ -1894,76 +1901,2220 @@ function colorMethod(method) {
   }
 }
 
-// src/index.ts
-var require2 = createRequire(import.meta.url);
-var { version } = require2("../package.json");
-var program = new Command();
-program.name("pica").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`Pica CLI \u2014 Connect AI agents to 200+ platforms through one interface.
-
-  Setup:
-    pica init                              Set up API key and install MCP server
-    pica add <platform>                    Connect a platform via OAuth (e.g. gmail, slack, shopify)
-    pica config                            Configure access control (permissions, scoping)
-
-  Workflow (use these in order):
-    1. pica list                           List your connected platforms and connection keys
-    2. pica actions search <platform> <q>  Search for actions using natural language
-    3. pica actions knowledge <plat> <id>  Get full docs for an action (ALWAYS do this before execute)
-    4. pica actions execute <p> <id> <key> Execute the action
-
-  Example \u2014 send an email through Gmail:
-    $ pica list
-    # Find: gmail  operational  live::gmail::default::abc123
-
-    $ pica actions search gmail "send email" -t execute
-    # Find: POST  Send Email  conn_mod_def::xxx::yyy
+// src/commands/flow.ts
+import pc7 from "picocolors";
 
-    $ pica actions knowledge gmail conn_mod_def::xxx::yyy
-    # Read the docs: required fields are to, subject, body, connectionKey
+// src/lib/flow-validator.ts
+var VALID_STEP_TYPES = [
+  "action",
+  "transform",
+  "code",
+  "condition",
+  "loop",
+  "parallel",
+  "file-read",
+  "file-write"
+];
+var VALID_INPUT_TYPES = ["string", "number", "boolean", "object", "array"];
+var VALID_ERROR_STRATEGIES = ["fail", "continue", "retry", "fallback"];
+function validateFlowSchema(flow2) {
+  const errors = [];
+  if (!flow2 || typeof flow2 !== "object") {
+    errors.push({ path: "", message: "Flow must be a JSON object" });
+    return errors;
+  }
+  const f = flow2;
+  if (!f.key || typeof f.key !== "string") {
+    errors.push({ path: "key", message: 'Flow must have a string "key"' });
+  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(f.key) && f.key.length > 1) {
+    errors.push({ path: "key", message: "Flow key must be kebab-case (lowercase letters, numbers, hyphens)" });
+  }
+  if (!f.name || typeof f.name !== "string") {
+    errors.push({ path: "name", message: 'Flow must have a string "name"' });
+  }
+  if (f.description !== void 0 && typeof f.description !== "string") {
+    errors.push({ path: "description", message: '"description" must be a string' });
+  }
+  if (f.version !== void 0 && typeof f.version !== "string") {
+    errors.push({ path: "version", message: '"version" must be a string' });
+  }
+  if (!f.inputs || typeof f.inputs !== "object" || Array.isArray(f.inputs)) {
+    errors.push({ path: "inputs", message: 'Flow must have an "inputs" object' });
+  } else {
+    const inputs = f.inputs;
+    for (const [name, decl] of Object.entries(inputs)) {
+      const prefix = `inputs.${name}`;
+      if (!decl || typeof decl !== "object" || Array.isArray(decl)) {
+        errors.push({ path: prefix, message: "Input declaration must be an object" });
+        continue;
+      }
+      const d = decl;
+      if (!d.type || !VALID_INPUT_TYPES.includes(d.type)) {
+        errors.push({ path: `${prefix}.type`, message: `Input type must be one of: ${VALID_INPUT_TYPES.join(", ")}` });
+      }
+      if (d.connection !== void 0) {
+        if (!d.connection || typeof d.connection !== "object") {
+          errors.push({ path: `${prefix}.connection`, message: "Connection metadata must be an object" });
+        } else {
+          const conn = d.connection;
+          if (!conn.platform || typeof conn.platform !== "string") {
+            errors.push({ path: `${prefix}.connection.platform`, message: 'Connection must have a string "platform"' });
+          }
+        }
+      }
+    }
+  }
+  if (!Array.isArray(f.steps)) {
+    errors.push({ path: "steps", message: 'Flow must have a "steps" array' });
+  } else {
+    validateStepsArray(f.steps, "steps", errors);
+  }
+  return errors;
+}
+function validateStepsArray(steps, pathPrefix, errors) {
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const path5 = `${pathPrefix}[${i}]`;
+    if (!step || typeof step !== "object" || Array.isArray(step)) {
+      errors.push({ path: path5, message: "Step must be an object" });
+      continue;
+    }
+    const s = step;
+    if (!s.id || typeof s.id !== "string") {
+      errors.push({ path: `${path5}.id`, message: 'Step must have a string "id"' });
+    }
+    if (!s.name || typeof s.name !== "string") {
+      errors.push({ path: `${path5}.name`, message: 'Step must have a string "name"' });
+    }
+    if (!s.type || !VALID_STEP_TYPES.includes(s.type)) {
+      errors.push({ path: `${path5}.type`, message: `Step type must be one of: ${VALID_STEP_TYPES.join(", ")}` });
+    }
+    if (s.onError && typeof s.onError === "object") {
+      const oe = s.onError;
+      if (!VALID_ERROR_STRATEGIES.includes(oe.strategy)) {
+        errors.push({ path: `${path5}.onError.strategy`, message: `Error strategy must be one of: ${VALID_ERROR_STRATEGIES.join(", ")}` });
+      }
+    }
+    const type = s.type;
+    if (type === "action") {
+      if (!s.action || typeof s.action !== "object") {
+        errors.push({ path: `${path5}.action`, message: 'Action step must have an "action" config object' });
+      } else {
+        const a = s.action;
+        if (!a.platform) errors.push({ path: `${path5}.action.platform`, message: 'Action must have "platform"' });
+        if (!a.actionId) errors.push({ path: `${path5}.action.actionId`, message: 'Action must have "actionId"' });
+        if (!a.connectionKey) errors.push({ path: `${path5}.action.connectionKey`, message: 'Action must have "connectionKey"' });
+      }
+    } else if (type === "transform") {
+      if (!s.transform || typeof s.transform !== "object") {
+        errors.push({ path: `${path5}.transform`, message: 'Transform step must have a "transform" config object' });
+      } else {
+        const t = s.transform;
+        if (!t.expression || typeof t.expression !== "string") {
+          errors.push({ path: `${path5}.transform.expression`, message: 'Transform must have a string "expression"' });
+        }
+      }
+    } else if (type === "code") {
+      if (!s.code || typeof s.code !== "object") {
+        errors.push({ path: `${path5}.code`, message: 'Code step must have a "code" config object' });
+      } else {
+        const c = s.code;
+        if (!c.source || typeof c.source !== "string") {
+          errors.push({ path: `${path5}.code.source`, message: 'Code must have a string "source"' });
+        }
+      }
+    } else if (type === "condition") {
+      if (!s.condition || typeof s.condition !== "object") {
+        errors.push({ path: `${path5}.condition`, message: 'Condition step must have a "condition" config object' });
+      } else {
+        const c = s.condition;
+        if (!c.expression || typeof c.expression !== "string") {
+          errors.push({ path: `${path5}.condition.expression`, message: 'Condition must have a string "expression"' });
+        }
+        if (!Array.isArray(c.then)) {
+          errors.push({ path: `${path5}.condition.then`, message: 'Condition must have a "then" steps array' });
+        } else {
+          validateStepsArray(c.then, `${path5}.condition.then`, errors);
+        }
+        if (c.else !== void 0) {
+          if (!Array.isArray(c.else)) {
+            errors.push({ path: `${path5}.condition.else`, message: 'Condition "else" must be a steps array' });
+          } else {
+            validateStepsArray(c.else, `${path5}.condition.else`, errors);
+          }
+        }
+      }
+    } else if (type === "loop") {
+      if (!s.loop || typeof s.loop !== "object") {
+        errors.push({ path: `${path5}.loop`, message: 'Loop step must have a "loop" config object' });
+      } else {
+        const l = s.loop;
+        if (!l.over || typeof l.over !== "string") {
+          errors.push({ path: `${path5}.loop.over`, message: 'Loop must have a string "over" selector' });
+        }
+        if (!l.as || typeof l.as !== "string") {
+          errors.push({ path: `${path5}.loop.as`, message: 'Loop must have a string "as" variable name' });
+        }
+        if (!Array.isArray(l.steps)) {
+          errors.push({ path: `${path5}.loop.steps`, message: 'Loop must have a "steps" array' });
+        } else {
+          validateStepsArray(l.steps, `${path5}.loop.steps`, errors);
+        }
+      }
+    } else if (type === "parallel") {
+      if (!s.parallel || typeof s.parallel !== "object") {
+        errors.push({ path: `${path5}.parallel`, message: 'Parallel step must have a "parallel" config object' });
+      } else {
+        const par = s.parallel;
+        if (!Array.isArray(par.steps)) {
+          errors.push({ path: `${path5}.parallel.steps`, message: 'Parallel must have a "steps" array' });
+        } else {
+          validateStepsArray(par.steps, `${path5}.parallel.steps`, errors);
+        }
+      }
+    } else if (type === "file-read") {
+      if (!s.fileRead || typeof s.fileRead !== "object") {
+        errors.push({ path: `${path5}.fileRead`, message: 'File-read step must have a "fileRead" config object' });
+      } else {
+        const fr = s.fileRead;
+        if (!fr.path || typeof fr.path !== "string") {
+          errors.push({ path: `${path5}.fileRead.path`, message: 'File-read must have a string "path"' });
+        }
+      }
+    } else if (type === "file-write") {
+      if (!s.fileWrite || typeof s.fileWrite !== "object") {
+        errors.push({ path: `${path5}.fileWrite`, message: 'File-write step must have a "fileWrite" config object' });
+      } else {
+        const fw = s.fileWrite;
+        if (!fw.path || typeof fw.path !== "string") {
+          errors.push({ path: `${path5}.fileWrite.path`, message: 'File-write must have a string "path"' });
+        }
+        if (fw.content === void 0) {
+          errors.push({ path: `${path5}.fileWrite.content`, message: 'File-write must have "content"' });
+        }
+      }
+    }
+  }
+}
+function validateStepIds(flow2) {
+  const errors = [];
+  const seen = /* @__PURE__ */ new Set();
+  function collectIds(steps, pathPrefix) {
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const path5 = `${pathPrefix}[${i}]`;
+      if (seen.has(step.id)) {
+        errors.push({ path: `${path5}.id`, message: `Duplicate step ID: "${step.id}"` });
+      } else {
+        seen.add(step.id);
+      }
+      if (step.condition) {
+        if (step.condition.then) collectIds(step.condition.then, `${path5}.condition.then`);
+        if (step.condition.else) collectIds(step.condition.else, `${path5}.condition.else`);
+      }
+      if (step.loop?.steps) collectIds(step.loop.steps, `${path5}.loop.steps`);
+      if (step.parallel?.steps) collectIds(step.parallel.steps, `${path5}.parallel.steps`);
+    }
+  }
+  collectIds(flow2.steps, "steps");
+  return errors;
+}
+function validateSelectorReferences(flow2) {
+  const errors = [];
+  const inputNames = new Set(Object.keys(flow2.inputs));
+  function getAllStepIds(steps) {
+    const ids = /* @__PURE__ */ new Set();
+    for (const step of steps) {
+      ids.add(step.id);
+      if (step.condition) {
+        for (const id of getAllStepIds(step.condition.then)) ids.add(id);
+        if (step.condition.else) {
+          for (const id of getAllStepIds(step.condition.else)) ids.add(id);
+        }
+      }
+      if (step.loop?.steps) {
+        for (const id of getAllStepIds(step.loop.steps)) ids.add(id);
+      }
+      if (step.parallel?.steps) {
+        for (const id of getAllStepIds(step.parallel.steps)) ids.add(id);
+      }
+    }
+    return ids;
+  }
+  const allStepIds = getAllStepIds(flow2.steps);
+  function extractSelectors(value) {
+    const selectors = [];
+    if (typeof value === "string") {
+      if (value.startsWith("$.")) {
+        selectors.push(value);
+      }
+      const interpolated = value.matchAll(/\{\{(\$\.[^}]+)\}\}/g);
+      for (const match of interpolated) {
+        selectors.push(match[1]);
+      }
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        selectors.push(...extractSelectors(item));
+      }
+    } else if (value && typeof value === "object") {
+      for (const v of Object.values(value)) {
+        selectors.push(...extractSelectors(v));
+      }
+    }
+    return selectors;
+  }
+  function checkSelectors(selectors, path5) {
+    for (const selector of selectors) {
+      const parts = selector.split(".");
+      if (parts.length < 3) continue;
+      const root = parts[1];
+      if (root === "input") {
+        const inputName = parts[2];
+        if (!inputNames.has(inputName)) {
+          errors.push({ path: path5, message: `Selector "${selector}" references undefined input "${inputName}"` });
+        }
+      } else if (root === "steps") {
+        const stepId = parts[2];
+        if (!allStepIds.has(stepId)) {
+          errors.push({ path: path5, message: `Selector "${selector}" references undefined step "${stepId}"` });
+        }
+      }
+    }
+  }
+  function checkStep(step, pathPrefix) {
+    if (step.if) checkSelectors(extractSelectors(step.if), `${pathPrefix}.if`);
+    if (step.unless) checkSelectors(extractSelectors(step.unless), `${pathPrefix}.unless`);
+    if (step.action) {
+      checkSelectors(extractSelectors(step.action), `${pathPrefix}.action`);
+    }
+    if (step.transform) {
+    }
+    if (step.condition) {
+      checkStep({ id: "__cond_expr", name: "", type: "transform", transform: { expression: "" } }, pathPrefix);
+      step.condition.then.forEach((s, i) => checkStep(s, `${pathPrefix}.condition.then[${i}]`));
+      step.condition.else?.forEach((s, i) => checkStep(s, `${pathPrefix}.condition.else[${i}]`));
+    }
+    if (step.loop) {
+      checkSelectors(extractSelectors(step.loop.over), `${pathPrefix}.loop.over`);
+      step.loop.steps.forEach((s, i) => checkStep(s, `${pathPrefix}.loop.steps[${i}]`));
+    }
+    if (step.parallel) {
+      step.parallel.steps.forEach((s, i) => checkStep(s, `${pathPrefix}.parallel.steps[${i}]`));
+    }
+    if (step.fileRead) {
+      checkSelectors(extractSelectors(step.fileRead.path), `${pathPrefix}.fileRead.path`);
+    }
+    if (step.fileWrite) {
+      checkSelectors(extractSelectors(step.fileWrite.path), `${pathPrefix}.fileWrite.path`);
+      checkSelectors(extractSelectors(step.fileWrite.content), `${pathPrefix}.fileWrite.content`);
+    }
+  }
+  flow2.steps.forEach((step, i) => checkStep(step, `steps[${i}]`));
+  return errors;
+}
+function validateFlow(flow2) {
+  const schemaErrors = validateFlowSchema(flow2);
+  if (schemaErrors.length > 0) return schemaErrors;
+  const f = flow2;
+  return [
+    ...validateStepIds(f),
+    ...validateSelectorReferences(f)
+  ];
+}
 
-    $ pica actions execute gmail conn_mod_def::xxx::yyy live::gmail::default::abc123 \\
-        -d '{"to":"j@example.com","subject":"Hello","body":"Hi!","connectionKey":"live::gmail::default::abc123"}'
+// src/lib/flow-runner.ts
+import fs4 from "fs";
+import path4 from "path";
+import crypto from "crypto";
 
-  Platform names are always kebab-case (e.g. hub-spot, ship-station, google-calendar).
-  Run 'pica platforms' to browse all 200+ available platforms.`).version(version);
-program.hook("preAction", (thisCommand) => {
-  const opts = program.opts();
-  if (opts.agent) {
-    setAgentMode(true);
+// src/lib/flow-engine.ts
+import fs3 from "fs";
+import path3 from "path";
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveSelector(selectorPath, context) {
+  if (!selectorPath.startsWith("$.")) return selectorPath;
+  const parts = selectorPath.slice(2).split(/\.|\[/).map((p7) => p7.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]);
+      }
+    } else if (typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
   }
-});
-program.command("init").description("Set up Pica and install MCP to your AI agents").option("-y, --yes", "Skip confirmations").option("-g, --global", "Install MCP globally (available in all projects)").option("-p, --project", "Install MCP for this project only (creates .mcp.json)").action(async (options) => {
-  await initCommand(options);
-});
-program.command("config").description("Configure MCP access control (permissions, connections, actions)").action(async () => {
-  await configCommand();
-});
-var connection = program.command("connection").description("Manage connections");
-connection.command("add [platform]").alias("a").description("Add a new connection").action(async (platform) => {
-  await connectionAddCommand(platform);
-});
-connection.command("list").alias("ls").description("List your connections").action(async () => {
-  await connectionListCommand();
-});
-program.command("platforms").alias("p").description("List available platforms").option("-c, --category <category>", "Filter by category").option("--json", "Output as JSON").action(async (options) => {
-  await platformsCommand(options);
-});
-var actions = program.command("actions").alias("a").description("Search, explore, and execute platform actions (workflow: search \u2192 knowledge \u2192 execute)");
-actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. pica actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). Default: knowledge").action(async (platform, query, options) => {
-  await actionsSearchCommand(platform, query, options);
-});
-actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").action(async (platform, actionId) => {
-  await actionsKnowledgeCommand(platform, actionId);
-});
-actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "pica list", actionId from "actions search"').option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").action(async (platform, actionId, connectionKey, options) => {
-  await actionsExecuteCommand(platform, actionId, connectionKey, {
-    data: options.data,
-    pathVars: options.pathVars,
-    queryParams: options.queryParams,
-    headers: options.headers,
-    formData: options.formData,
-    formUrlEncoded: options.formUrlEncoded
+  return current;
+}
+function interpolateString(str, context) {
+  return str.replace(/\{\{(\$\.[^}]+)\}\}/g, (_match, selector) => {
+    const value = resolveSelector(selector, context);
+    if (value === void 0 || value === null) return "";
+    if (typeof value === "object") return JSON.stringify(value);
+    return String(value);
+  });
+}
+function resolveValue(value, context) {
+  if (typeof value === "string") {
+    if (value.startsWith("$.") && !value.includes("{{")) {
+      return resolveSelector(value, context);
+    }
+    if (value.includes("{{$.")) {
+      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);
+}
+async function executeActionStep(step, context, api, permissions, allowedActionIds) {
+  const action = step.action;
+  const platform = resolveValue(action.platform, context);
+  const actionId = resolveValue(action.actionId, context);
+  const connectionKey = resolveValue(action.connectionKey, context);
+  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 actionDetails = await api.getActionDetails(actionId);
+  if (!isMethodAllowed(actionDetails.method, permissions)) {
+    throw new Error(`Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
+  }
+  const result = await api.executePassthroughRequest({
+    platform,
+    actionId,
+    connectionKey,
+    data,
+    pathVariables: pathVars,
+    queryParams,
+    headers
+  }, actionDetails);
+  return {
+    status: "success",
+    response: result.responseData,
+    output: result.responseData
+  };
+}
+function executeTransformStep(step, context) {
+  const output = evaluateExpression(step.transform.expression, context);
+  return { status: "success", output, response: output };
+}
+async function executeCodeStep(step, context) {
+  const source = step.code.source;
+  const AsyncFunction = Object.getPrototypeOf(async function() {
+  }).constructor;
+  const fn = new AsyncFunction("$", source);
+  const output = await fn(context);
+  return { status: "success", output, response: output };
+}
+async function executeConditionStep(step, context, api, permissions, allowedActionIds, options) {
+  const condition = step.condition;
+  const result = evaluateExpression(condition.expression, context);
+  const branch = result ? condition.then : condition.else || [];
+  const branchResults = await executeSteps(branch, context, api, permissions, allowedActionIds, options);
+  return {
+    status: "success",
+    output: { conditionResult: !!result, stepsExecuted: branchResults },
+    response: { conditionResult: !!result }
+  };
+}
+async function executeLoopStep(step, context, api, permissions, allowedActionIds, options) {
+  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 results = [];
+  const savedLoop = { ...context.loop };
+  for (let i = 0; i < Math.min(items.length, maxIterations); i++) {
+    context.loop = {
+      [loop.as]: items[i],
+      item: items[i],
+      i
+    };
+    if (loop.indexAs) {
+      context.loop[loop.indexAs] = i;
+    }
+    await executeSteps(loop.steps, context, api, permissions, allowedActionIds, options);
+    results.push(context.loop[loop.as]);
+  }
+  context.loop = savedLoop;
+  return { status: "success", output: results, response: results };
+}
+async function executeParallelStep(step, context, api, permissions, allowedActionIds, options) {
+  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))
+    );
+    results.push(...batchResults);
+  }
+  return { status: "success", output: results, response: results };
+}
+function executeFileReadStep(step, context) {
+  const config = step.fileRead;
+  const filePath = resolveValue(config.path, context);
+  const resolvedPath = path3.resolve(filePath);
+  const content = fs3.readFileSync(resolvedPath, "utf-8");
+  const output = config.parseJson ? JSON.parse(content) : content;
+  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 = path3.resolve(filePath);
+  const dir = path3.dirname(resolvedPath);
+  if (!fs3.existsSync(dir)) {
+    fs3.mkdirSync(dir, { recursive: true });
+  }
+  const stringContent = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+  if (config.append) {
+    fs3.appendFileSync(resolvedPath, stringContent);
+  } else {
+    fs3.writeFileSync(resolvedPath, stringContent);
+  }
+  return { status: "success", output: { path: resolvedPath, bytesWritten: stringContent.length }, response: { path: resolvedPath } };
+}
+async function executeSingleStep(step, context, api, permissions, allowedActionIds, options) {
+  if (step.if) {
+    const condResult = evaluateExpression(step.if, context);
+    if (!condResult) {
+      const result = { status: "skipped" };
+      context.steps[step.id] = result;
+      return result;
+    }
+  }
+  if (step.unless) {
+    const condResult = evaluateExpression(step.unless, context);
+    if (condResult) {
+      const result = { status: "skipped" };
+      context.steps[step.id] = result;
+      return result;
+    }
+  }
+  const startTime = Date.now();
+  let lastError;
+  const maxAttempts = step.onError?.strategy === "retry" && step.onError.retries ? step.onError.retries + 1 : 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      if (attempt > 1) {
+        options.onEvent?.({
+          event: "step:retry",
+          stepId: step.id,
+          attempt,
+          maxRetries: step.onError.retries
+        });
+        const delay = step.onError?.retryDelayMs || 1e3;
+        await sleep2(delay);
+      }
+      let result;
+      switch (step.type) {
+        case "action":
+          result = await executeActionStep(step, context, api, permissions, allowedActionIds);
+          break;
+        case "transform":
+          result = executeTransformStep(step, context);
+          break;
+        case "code":
+          result = await executeCodeStep(step, context);
+          break;
+        case "condition":
+          result = await executeConditionStep(step, context, api, permissions, allowedActionIds, options);
+          break;
+        case "loop":
+          result = await executeLoopStep(step, context, api, permissions, allowedActionIds, options);
+          break;
+        case "parallel":
+          result = await executeParallelStep(step, context, api, permissions, allowedActionIds, options);
+          break;
+        case "file-read":
+          result = executeFileReadStep(step, context);
+          break;
+        case "file-write":
+          result = executeFileWriteStep(step, context);
+          break;
+        default:
+          throw new Error(`Unknown step type: ${step.type}`);
+      }
+      result.durationMs = Date.now() - startTime;
+      if (attempt > 1) result.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;
+      }
+    }
+  }
+  const errorMessage = lastError?.message || "Unknown error";
+  const strategy = step.onError?.strategy || "fail";
+  if (strategy === "continue") {
+    const result = {
+      status: "failed",
+      error: errorMessage,
+      durationMs: Date.now() - startTime
+    };
+    context.steps[step.id] = result;
+    return result;
+  }
+  if (strategy === "fallback" && step.onError?.fallbackStepId) {
+    const result = {
+      status: "failed",
+      error: errorMessage,
+      durationMs: Date.now() - startTime
+    };
+    context.steps[step.id] = result;
+    return result;
+  }
+  throw lastError;
+}
+async function executeSteps(steps, context, api, permissions, allowedActionIds, options, completedStepIds) {
+  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);
+      results.push(result);
+      options.onEvent?.({
+        event: "step:complete",
+        stepId: step.id,
+        status: result.status,
+        durationMs: result.durationMs,
+        retries: result.retries
+      });
+    } catch (error2) {
+      const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+      options.onEvent?.({
+        event: "step:error",
+        stepId: step.id,
+        error: errorMsg,
+        strategy: step.onError?.strategy || "fail"
+      });
+      throw error2;
+    }
+  }
+  return results;
+}
+async function executeFlow(flow2, inputs, api, permissions, allowedActionIds, options = {}, resumeState) {
+  for (const [name, decl] of Object.entries(flow2.inputs)) {
+    if (decl.required !== false && inputs[name] === void 0 && decl.default === void 0) {
+      throw new Error(`Missing required input: "${name}" \u2014 ${decl.description || ""}`);
+    }
+  }
+  const resolvedInputs = {};
+  for (const [name, decl] of Object.entries(flow2.inputs)) {
+    if (inputs[name] !== void 0) {
+      resolvedInputs[name] = inputs[name];
+    } else if (decl.default !== void 0) {
+      resolvedInputs[name] = decl.default;
+    }
+  }
+  const context = resumeState?.context || {
+    input: resolvedInputs,
+    env: process.env,
+    steps: {},
+    loop: {}
+  };
+  const completedStepIds = resumeState ? new Set(resumeState.completedSteps) : void 0;
+  if (options.dryRun) {
+    options.onEvent?.({
+      event: "flow:dry-run",
+      flowKey: flow2.key,
+      resolvedInputs,
+      steps: flow2.steps.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return context;
+  }
+  options.onEvent?.({
+    event: "flow:start",
+    flowKey: flow2.key,
+    totalSteps: flow2.steps.length,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
+  const flowStart = Date.now();
+  try {
+    await executeSteps(flow2.steps, context, api, permissions, allowedActionIds, options, completedStepIds);
+    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: flow2.key,
+      status: "success",
+      durationMs: Date.now() - flowStart,
+      stepsCompleted: completed,
+      stepsFailed: failed,
+      stepsSkipped: skipped
+    });
+  } catch (error2) {
+    const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+    options.onEvent?.({
+      event: "flow:error",
+      flowKey: flow2.key,
+      status: "failed",
+      error: errorMsg,
+      durationMs: Date.now() - flowStart
+    });
+    throw error2;
+  }
+  return context;
+}
+
+// src/lib/flow-runner.ts
+var FLOWS_DIR = ".one/flows";
+var RUNS_DIR = ".one/flows/.runs";
+var LOGS_DIR = ".one/flows/.logs";
+function ensureDir(dir) {
+  if (!fs4.existsSync(dir)) {
+    fs4.mkdirSync(dir, { recursive: true });
+  }
+}
+function generateRunId() {
+  return crypto.randomBytes(6).toString("hex");
+}
+var FlowRunner = class _FlowRunner {
+  runId;
+  flowKey;
+  state;
+  logPath;
+  statePath;
+  paused = false;
+  constructor(flow2, inputs, runId) {
+    this.runId = runId || generateRunId();
+    this.flowKey = flow2.key;
+    ensureDir(RUNS_DIR);
+    ensureDir(LOGS_DIR);
+    this.statePath = path4.join(RUNS_DIR, `${flow2.key}-${this.runId}.state.json`);
+    this.logPath = path4.join(LOGS_DIR, `${flow2.key}-${this.runId}.log`);
+    this.state = {
+      runId: this.runId,
+      flowKey: flow2.key,
+      status: "running",
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      inputs,
+      completedSteps: [],
+      context: {
+        input: inputs,
+        env: {},
+        steps: {},
+        loop: {}
+      }
+    };
+  }
+  getRunId() {
+    return this.runId;
+  }
+  getLogPath() {
+    return this.logPath;
+  }
+  getStatePath() {
+    return this.statePath;
+  }
+  requestPause() {
+    this.paused = true;
+  }
+  log(level, msg, data) {
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      msg,
+      ...data
+    };
+    fs4.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+  }
+  saveState() {
+    fs4.writeFileSync(this.statePath, JSON.stringify(this.state, null, 2));
+  }
+  createEventHandler(externalHandler) {
+    return (event) => {
+      this.log(
+        event.event.includes("error") ? "warn" : "info",
+        event.event,
+        event
+      );
+      if (event.event === "step:complete" && event.stepId) {
+        this.state.completedSteps.push(event.stepId);
+        this.state.currentStepId = void 0;
+      }
+      if (event.event === "step:start" && event.stepId) {
+        this.state.currentStepId = event.stepId;
+      }
+      externalHandler?.(event);
+      if (this.paused && event.event === "step:complete") {
+        this.state.status = "paused";
+        this.state.pausedAt = (/* @__PURE__ */ new Date()).toISOString();
+        this.saveState();
+      }
+    };
+  }
+  async execute(flow2, api, permissions, allowedActionIds, options = {}) {
+    this.log("info", "Flow started", { flowKey: this.flowKey, runId: this.runId });
+    this.state.status = "running";
+    this.saveState();
+    const eventHandler = this.createEventHandler(options.onEvent);
+    try {
+      const context = await executeFlow(
+        flow2,
+        this.state.inputs,
+        api,
+        permissions,
+        allowedActionIds,
+        { ...options, onEvent: eventHandler }
+      );
+      this.state.status = "completed";
+      this.state.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.state.context = context;
+      this.saveState();
+      this.log("info", "Flow completed", { status: "success" });
+      return context;
+    } catch (error2) {
+      const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+      this.state.status = "failed";
+      this.state.context.steps = this.state.context.steps || {};
+      this.saveState();
+      this.log("error", "Flow failed", { error: errorMsg });
+      throw error2;
+    }
+  }
+  async resume(flow2, api, permissions, allowedActionIds, options = {}) {
+    this.log("info", "Flow resumed", { flowKey: this.flowKey, runId: this.runId });
+    this.state.status = "running";
+    this.state.pausedAt = void 0;
+    this.saveState();
+    const eventHandler = this.createEventHandler(options.onEvent);
+    try {
+      const context = await executeFlow(
+        flow2,
+        this.state.inputs,
+        api,
+        permissions,
+        allowedActionIds,
+        { ...options, onEvent: eventHandler },
+        {
+          context: this.state.context,
+          completedSteps: this.state.completedSteps
+        }
+      );
+      this.state.status = "completed";
+      this.state.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.state.context = context;
+      this.saveState();
+      this.log("info", "Flow completed after resume", { status: "success" });
+      return context;
+    } catch (error2) {
+      const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+      this.state.status = "failed";
+      this.saveState();
+      this.log("error", "Flow failed after resume", { error: errorMsg });
+      throw error2;
+    }
+  }
+  static loadRunState(runId) {
+    ensureDir(RUNS_DIR);
+    const files = fs4.readdirSync(RUNS_DIR).filter((f) => f.includes(runId) && f.endsWith(".state.json"));
+    if (files.length === 0) return null;
+    try {
+      const content = fs4.readFileSync(path4.join(RUNS_DIR, files[0]), "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+  static fromRunState(state) {
+    const runner = Object.create(_FlowRunner.prototype);
+    runner.runId = state.runId;
+    runner.flowKey = state.flowKey;
+    runner.state = state;
+    runner.paused = false;
+    runner.statePath = path4.join(RUNS_DIR, `${state.flowKey}-${state.runId}.state.json`);
+    runner.logPath = path4.join(LOGS_DIR, `${state.flowKey}-${state.runId}.log`);
+    return runner;
+  }
+  static listRuns(flowKey) {
+    ensureDir(RUNS_DIR);
+    const files = fs4.readdirSync(RUNS_DIR).filter((f) => f.endsWith(".state.json"));
+    const runs = [];
+    for (const file of files) {
+      try {
+        const content = fs4.readFileSync(path4.join(RUNS_DIR, file), "utf-8");
+        const state = JSON.parse(content);
+        if (!flowKey || state.flowKey === flowKey) {
+          runs.push(state);
+        }
+      } catch {
+      }
+    }
+    return runs.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+  }
+};
+function resolveFlowPath(keyOrPath) {
+  if (keyOrPath.includes("/") || keyOrPath.includes("\\") || keyOrPath.endsWith(".json")) {
+    return path4.resolve(keyOrPath);
+  }
+  return path4.resolve(FLOWS_DIR, `${keyOrPath}.flow.json`);
+}
+function loadFlow(keyOrPath) {
+  const flowPath = resolveFlowPath(keyOrPath);
+  if (!fs4.existsSync(flowPath)) {
+    throw new Error(`Flow not found: ${flowPath}`);
+  }
+  const content = fs4.readFileSync(flowPath, "utf-8");
+  return JSON.parse(content);
+}
+function listFlows() {
+  const flowsDir = path4.resolve(FLOWS_DIR);
+  if (!fs4.existsSync(flowsDir)) return [];
+  const files = fs4.readdirSync(flowsDir).filter((f) => f.endsWith(".flow.json"));
+  const flows = [];
+  for (const file of files) {
+    try {
+      const content = fs4.readFileSync(path4.join(flowsDir, file), "utf-8");
+      const flow2 = JSON.parse(content);
+      flows.push({
+        key: flow2.key,
+        name: flow2.name,
+        description: flow2.description,
+        inputCount: Object.keys(flow2.inputs).length,
+        stepCount: flow2.steps.length,
+        path: path4.join(flowsDir, file)
+      });
+    } catch {
+    }
+  }
+  return flows;
+}
+function saveFlow(flow2, outputPath) {
+  const flowPath = outputPath ? path4.resolve(outputPath) : path4.resolve(FLOWS_DIR, `${flow2.key}.flow.json`);
+  const dir = path4.dirname(flowPath);
+  ensureDir(dir);
+  fs4.writeFileSync(flowPath, JSON.stringify(flow2, null, 2) + "\n");
+  return flowPath;
+}
+
+// src/commands/flow.ts
+import fs5 from "fs";
+function getConfig2() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    error("Not configured. Run `pica init` first.");
+  }
+  const ac = getAccessControlFromAllSources();
+  const permissions = ac.permissions || "admin";
+  const connectionKeys = ac.connectionKeys || ["*"];
+  const actionIds = ac.actionIds || ["*"];
+  return { apiKey, permissions, connectionKeys, actionIds };
+}
+function parseInputs(inputArgs) {
+  const inputs = {};
+  for (const arg of inputArgs) {
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex === -1) {
+      error(`Invalid input format: "${arg}" \u2014 expected name=value`);
+    }
+    const key = arg.slice(0, eqIndex);
+    const value = arg.slice(eqIndex + 1);
+    try {
+      inputs[key] = JSON.parse(value);
+    } catch {
+      inputs[key] = value;
+    }
+  }
+  return inputs;
+}
+function collect(value, previous) {
+  return previous.concat([value]);
+}
+async function autoResolveConnectionInputs(flow2, inputs, api) {
+  const resolved = { ...inputs };
+  const connectionInputs = Object.entries(flow2.inputs).filter(
+    ([, decl]) => decl.connection && !resolved[decl.connection.platform]
+  );
+  if (connectionInputs.length === 0) return resolved;
+  const missing = connectionInputs.filter(([name]) => !resolved[name]);
+  if (missing.length === 0) return resolved;
+  const connections = await api.listConnections();
+  for (const [name, decl] of missing) {
+    const platform = decl.connection.platform;
+    const matching = connections.filter((c) => c.platform.toLowerCase() === platform.toLowerCase());
+    if (matching.length === 1) {
+      resolved[name] = matching[0].key;
+    }
+  }
+  return resolved;
+}
+async function flowCreateCommand(key, options) {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  let flow2;
+  if (options.definition) {
+    try {
+      flow2 = JSON.parse(options.definition);
+    } catch {
+      error("Invalid JSON in --definition");
+    }
+  } else if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8");
+    try {
+      flow2 = JSON.parse(raw);
+    } catch {
+      error("Invalid JSON from stdin");
+    }
+  } else {
+    error("Interactive flow creation not yet supported. Use --definition <json> or pipe JSON via stdin.");
+  }
+  if (key) {
+    flow2.key = key;
+  }
+  const errors = validateFlow(flow2);
+  if (errors.length > 0) {
+    if (isAgentMode()) {
+      json({ error: "Validation failed", errors });
+      process.exit(1);
+    }
+    error(`Validation failed:
+${errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
+  }
+  const flowPath = saveFlow(flow2, options.output);
+  if (isAgentMode()) {
+    json({ created: true, key: flow2.key, path: flowPath });
+    return;
+  }
+  note2(`Flow "${flow2.name}" saved to ${flowPath}`, "Created");
+  outro2(`Validate: ${pc7.cyan(`pica flow validate ${flow2.key}`)}
+Execute:  ${pc7.cyan(`pica flow execute ${flow2.key}`)}`);
+}
+async function flowExecuteCommand(keyOrPath, options) {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  const { apiKey, permissions, actionIds } = getConfig2();
+  const api = new PicaApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start(`Loading flow "${keyOrPath}"...`);
+  let flow2;
+  try {
+    flow2 = loadFlow(keyOrPath);
+  } catch (err) {
+    spinner5.stop("Flow not found");
+    error(err instanceof Error ? err.message : String(err));
+    return;
+  }
+  spinner5.stop(`Flow: ${flow2.name} (${flow2.steps.length} steps)`);
+  const inputs = parseInputs(options.input || []);
+  const resolvedInputs = await autoResolveConnectionInputs(flow2, inputs, api);
+  const runner = new FlowRunner(flow2, resolvedInputs);
+  const logPath = runner.getLogPath();
+  const runId = runner.getRunId();
+  const sigintHandler = () => {
+    runner.requestPause();
+    if (!isAgentMode()) {
+      console.log(`
+${pc7.yellow("Pausing after current step completes...")} (run ID: ${runId})`);
+    }
+  };
+  process.on("SIGINT", sigintHandler);
+  const onEvent = (event) => {
+    if (isAgentMode()) {
+      json(event);
+    } else if (options.verbose) {
+      const ts = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, 8);
+      if (event.event === "step:start") {
+        console.log(`  ${pc7.dim(ts)} ${pc7.cyan("\u25B6")} ${event.stepName} ${pc7.dim(`(${event.type})`)}`);
+      } else if (event.event === "step:complete") {
+        const status = event.status === "success" ? pc7.green("\u2713") : event.status === "skipped" ? pc7.dim("\u25CB") : pc7.red("\u2717");
+        console.log(`  ${pc7.dim(ts)} ${status} ${event.stepId} ${pc7.dim(`${event.durationMs}ms`)}`);
+      } else if (event.event === "step:error") {
+        console.log(`  ${pc7.dim(ts)} ${pc7.red("\u2717")} ${event.stepId}: ${event.error}`);
+      }
+    }
+  };
+  const execSpinner = createSpinner();
+  if (!options.verbose && !isAgentMode()) {
+    execSpinner.start("Executing flow...");
+  }
+  try {
+    const context = await runner.execute(flow2, api, permissions, actionIds, {
+      dryRun: options.dryRun,
+      verbose: options.verbose,
+      onEvent
+    });
+    process.off("SIGINT", sigintHandler);
+    if (!options.verbose && !isAgentMode()) {
+      execSpinner.stop("Flow completed");
+    }
+    if (isAgentMode()) {
+      json({
+        event: "flow:result",
+        runId,
+        logFile: logPath,
+        status: "success",
+        steps: context.steps
+      });
+      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;
+    const skipped = stepEntries.filter(([, r]) => r.status === "skipped").length;
+    console.log();
+    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) {
+      note2("Dry run \u2014 no steps were executed", "Dry Run");
+    }
+  } catch (error2) {
+    process.off("SIGINT", sigintHandler);
+    if (!options.verbose && !isAgentMode()) {
+      execSpinner.stop("Flow failed");
+    }
+    const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+    if (isAgentMode()) {
+      json({
+        event: "flow:result",
+        runId,
+        logFile: logPath,
+        status: "failed",
+        error: errorMsg
+      });
+      process.exit(1);
+    }
+    console.log(`  ${pc7.dim(`Run ID: ${runId}`)}`);
+    console.log(`  ${pc7.dim(`Log: ${logPath}`)}`);
+    error(`Flow failed: ${errorMsg}`);
+  }
+}
+async function flowListCommand() {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  const flows = listFlows();
+  if (isAgentMode()) {
+    json({ flows });
+    return;
+  }
+  if (flows.length === 0) {
+    note2("No flows found in .one/flows/\n\nCreate one with: pica flow create", "Flows");
+    return;
+  }
+  console.log();
+  printTable(
+    [
+      { key: "key", label: "Key" },
+      { key: "name", label: "Name" },
+      { key: "description", label: "Description" },
+      { key: "inputCount", label: "Inputs" },
+      { key: "stepCount", label: "Steps" }
+    ],
+    flows.map((f) => ({
+      key: f.key,
+      name: f.name,
+      description: f.description || "",
+      inputCount: String(f.inputCount),
+      stepCount: String(f.stepCount)
+    }))
+  );
+  console.log();
+}
+async function flowValidateCommand(keyOrPath) {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  const spinner5 = createSpinner();
+  spinner5.start(`Validating "${keyOrPath}"...`);
+  let flowData;
+  try {
+    const flowPath = resolveFlowPath(keyOrPath);
+    const content = fs5.readFileSync(flowPath, "utf-8");
+    flowData = JSON.parse(content);
+  } catch (err) {
+    spinner5.stop("Validation failed");
+    error(`Could not read flow: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const errors = validateFlow(flowData);
+  if (errors.length > 0) {
+    spinner5.stop("Validation failed");
+    if (isAgentMode()) {
+      json({ valid: false, errors });
+      process.exit(1);
+    }
+    console.log();
+    for (const e of errors) {
+      console.log(`  ${pc7.red("\u2717")} ${pc7.dim(e.path)}: ${e.message}`);
+    }
+    console.log();
+    error(`${errors.length} validation error(s) found`);
+  }
+  spinner5.stop("Flow is valid");
+  if (isAgentMode()) {
+    json({ valid: true, key: flowData.key });
+    return;
+  }
+  note2(`Flow "${flowData.key}" passed all validation checks`, "Valid");
+}
+async function flowResumeCommand(runId) {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  const state = FlowRunner.loadRunState(runId);
+  if (!state) {
+    error(`Run "${runId}" not found`);
+  }
+  if (state.status !== "paused" && state.status !== "failed") {
+    error(`Run "${runId}" is ${state.status} \u2014 can only resume paused or failed runs`);
+  }
+  const { apiKey, permissions, actionIds } = getConfig2();
+  const api = new PicaApi(apiKey);
+  let flow2;
+  try {
+    flow2 = loadFlow(state.flowKey);
+  } catch (err) {
+    error(`Could not load flow "${state.flowKey}": ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+  const runner = FlowRunner.fromRunState(state);
+  const onEvent = (event) => {
+    if (isAgentMode()) {
+      json(event);
+    }
+  };
+  const spinner5 = createSpinner();
+  spinner5.start(`Resuming run ${runId} (${state.completedSteps.length} steps already completed)...`);
+  try {
+    const context = await runner.resume(flow2, api, permissions, actionIds, { onEvent });
+    spinner5.stop("Flow completed");
+    if (isAgentMode()) {
+      json({
+        event: "flow:result",
+        runId,
+        logFile: runner.getLogPath(),
+        status: "success",
+        steps: context.steps
+      });
+      return;
+    }
+    console.log(`  ${pc7.green("\u2713")} Resumed and completed successfully`);
+    console.log(`  ${pc7.dim(`Log: ${runner.getLogPath()}`)}`);
+  } catch (error2) {
+    spinner5.stop("Resume failed");
+    const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+    if (isAgentMode()) {
+      json({ event: "flow:result", runId, status: "failed", error: errorMsg });
+      process.exit(1);
+    }
+    error(`Resume failed: ${errorMsg}`);
+  }
+}
+async function flowRunsCommand(flowKey) {
+  intro2(pc7.bgCyan(pc7.black(" Pica Flow ")));
+  const runs = FlowRunner.listRuns(flowKey);
+  if (isAgentMode()) {
+    json({
+      runs: runs.map((r) => ({
+        runId: r.runId,
+        flowKey: r.flowKey,
+        status: r.status,
+        startedAt: r.startedAt,
+        completedAt: r.completedAt,
+        pausedAt: r.pausedAt,
+        completedSteps: r.completedSteps.length
+      }))
+    });
+    return;
+  }
+  if (runs.length === 0) {
+    note2(flowKey ? `No runs found for flow "${flowKey}"` : "No flow runs found", "Runs");
+    return;
+  }
+  console.log();
+  printTable(
+    [
+      { key: "runId", label: "Run ID" },
+      { key: "flowKey", label: "Flow" },
+      { key: "status", label: "Status" },
+      { key: "startedAt", label: "Started" },
+      { key: "steps", label: "Steps Done" }
+    ],
+    runs.map((r) => ({
+      runId: r.runId,
+      flowKey: r.flowKey,
+      status: colorStatus(r.status),
+      startedAt: r.startedAt,
+      steps: String(r.completedSteps.length)
+    }))
+  );
+  console.log();
+}
+function colorStatus(status) {
+  switch (status) {
+    case "completed":
+      return pc7.green(status);
+    case "running":
+      return pc7.cyan(status);
+    case "paused":
+      return pc7.yellow(status);
+    case "failed":
+      return pc7.red(status);
+    default:
+      return status;
+  }
+}
+
+// src/commands/guide.ts
+import pc8 from "picocolors";
+
+// src/lib/guide-content.ts
+var GUIDE_OVERVIEW = `# Pica CLI \u2014 Agent Guide
+
+## Setup
+
+1. Run \`pica init\` to configure your API key
+2. Run \`pica add <platform>\` to connect platforms via OAuth
+3. Run \`pica --agent connection list\` to verify connections
+
+## The --agent Flag
+
+Always use \`--agent\` for machine-readable JSON output. It disables colors, spinners, and interactive prompts.
+
+\`\`\`bash
+pica --agent <command>
+\`\`\`
+
+All commands return JSON. If an \`error\` key is present, the command failed.
+
+## Topics
+
+This guide has three sections you can request individually:
+
+- **overview** \u2014 This section. Setup, flag usage, and discovery workflow.
+- **actions** \u2014 Full workflow for searching, reading docs, and executing platform actions.
+- **flows** \u2014 Building and executing multi-step API workflows (JSON-based).
+
+## Discovery Workflow
+
+1. \`pica --agent connection list\` \u2014 See connected platforms and connection keys
+2. \`pica --agent actions search <platform> <query>\` \u2014 Find actions
+3. \`pica --agent actions knowledge <platform> <actionId>\` \u2014 Read full docs (REQUIRED before execute)
+4. \`pica --agent actions execute <platform> <actionId> <connectionKey>\` \u2014 Execute the action
+
+For multi-step workflows, use flows:
+1. Discover actions with the workflow above
+2. Build a flow JSON definition
+3. \`pica --agent flow create <key> --definition '<json>'\`
+4. \`pica --agent flow execute <key> -i param=value\`
+
+Platform names are always kebab-case (e.g., \`hub-spot\`, \`google-calendar\`).
+Run \`pica platforms\` to browse all 200+ available platforms.
+`;
+var GUIDE_ACTIONS = `# Pica Actions CLI Workflow
+
+You have access to the Pica CLI which lets you interact with 200+ third-party platforms through their APIs. The CLI handles authentication, request building, and execution through Pica's passthrough proxy.
+
+## The Workflow
+
+Always follow this sequence \u2014 each step builds on the previous one:
+
+1. **List connections** to see what platforms the user has connected
+2. **Search actions** to find the right API action for what the user wants to do
+3. **Get knowledge** to understand the action's parameters, requirements, and structure
+4. **Execute** the action with the correct parameters
+
+Never skip the knowledge step before executing \u2014 it contains critical information about required parameters, validation rules, and request structure that you need to build a correct request.
+
+## Commands
+
+### 1. List Connections
+
+\`\`\`bash
+pica --agent connection list
+\`\`\`
+
+Returns JSON with all connected platforms, their status, and connection keys. You need the **connection key** for executing actions, and the **platform name** (kebab-case) for searching actions.
+
+Output format:
+\`\`\`json
+{"connections": [{"platform": "gmail", "state": "active", "key": "conn_abc123"}, ...]}
+\`\`\`
+
+### 2. Search Actions
+
+\`\`\`bash
+pica --agent actions search <platform> <query>
+\`\`\`
+
+Search for actions on a specific platform using natural language. Returns JSON with up to 5 matching actions including their action IDs, HTTP methods, and paths.
+
+- \`<platform>\` \u2014 Platform name in kebab-case exactly as shown in the connections list (e.g., \`gmail\`, \`shopify\`, \`hub-spot\`)
+- \`<query>\` \u2014 Natural language description of what you want to do (e.g., \`"send email"\`, \`"list contacts"\`, \`"create order"\`)
+
+Options:
+- \`-t, --type <execute|knowledge>\` \u2014 Use \`execute\` when the user wants to perform an action, \`knowledge\` when they want documentation or want to write code. Defaults to \`knowledge\`.
+
+Example:
+\`\`\`bash
+pica --agent actions search gmail "send email" -t execute
+\`\`\`
+
+Output format:
+\`\`\`json
+{"actions": [{"_id": "abc123", "title": "Send Email", "tags": [...], "method": "POST", "path": "/messages/send"}, ...]}
+\`\`\`
+
+### 3. Get Action Knowledge
+
+\`\`\`bash
+pica --agent actions knowledge <platform> <actionId>
+\`\`\`
+
+Get comprehensive documentation for an action including parameters, requirements, validation rules, request/response structure, and examples. Returns JSON with the full API knowledge and HTTP method.
+
+Always call this before executing \u2014 it tells you exactly what parameters are required and how to structure the request.
+
+Example:
+\`\`\`bash
+pica --agent actions knowledge gmail 67890abcdef
+\`\`\`
+
+Output format:
+\`\`\`json
+{"knowledge": "...full API documentation and guidance...", "method": "POST"}
+\`\`\`
+
+### 4. Execute Action
+
+\`\`\`bash
+pica --agent actions execute <platform> <actionId> <connectionKey> [options]
+\`\`\`
+
+Execute an action on a connected platform. Returns JSON with the request details and response data. You must have retrieved the knowledge for this action first.
+
+- \`<platform>\` \u2014 Platform name in kebab-case
+- \`<actionId>\` \u2014 Action ID from the search results
+- \`<connectionKey>\` \u2014 Connection key from \`pica connection list\`
+
+Options:
+- \`-d, --data <json>\` \u2014 Request body as JSON string (for POST, PUT, PATCH)
+- \`--path-vars <json>\` \u2014 Path variables as JSON (for URLs with \`{id}\` placeholders)
+- \`--query-params <json>\` \u2014 Query parameters as JSON
+- \`--headers <json>\` \u2014 Additional headers as JSON
+- \`--form-data\` \u2014 Send as multipart/form-data instead of JSON
+- \`--form-url-encoded\` \u2014 Send as application/x-www-form-urlencoded
+
+Examples:
+\`\`\`bash
+# Simple GET request
+pica --agent actions execute shopify <actionId> <connectionKey>
+
+# POST with data
+pica --agent actions execute hub-spot <actionId> <connectionKey> \\
+  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
+
+# With path variables and query params
+pica --agent actions execute shopify <actionId> <connectionKey> \\
+  --path-vars '{"order_id": "12345"}' \\
+  --query-params '{"limit": "10"}'
+\`\`\`
+
+Output format:
+\`\`\`json
+{"request": {"method": "POST", "url": "https://..."}, "response": {...}}
+\`\`\`
+
+## Error Handling
+
+All errors return JSON in agent mode:
+\`\`\`json
+{"error": "Error message here"}
+\`\`\`
+
+Parse the output as JSON. If the \`error\` key is present, the command failed \u2014 report the error message to the user.
+
+## Important Notes
+
+- **Always use \`--agent\` flag** \u2014 it produces structured JSON output without spinners, colors, or interactive prompts
+- Platform names are always **kebab-case** (e.g., \`hub-spot\` not \`HubSpot\`, \`ship-station\` not \`ShipStation\`)
+- Always use the **exact action ID** from search results \u2014 don't guess or construct them
+- Always read the knowledge output carefully \u2014 it tells you which parameters are required vs optional, what format they need to be in, and any caveats specific to that API
+- JSON values passed to \`-d\`, \`--path-vars\`, \`--query-params\`, and \`--headers\` must be valid JSON strings (use single quotes around the JSON to avoid shell escaping issues)
+- If search returns no results, try broader queries (e.g., \`"list"\` instead of \`"list active premium customers"\`)
+- The execute command respects access control settings configured via \`pica config\` \u2014 if execution is blocked, the user may need to adjust their permissions
+`;
+var GUIDE_FLOWS = `# Pica Flow \u2014 Multi-Step API Workflows
+
+You have access to the Pica CLI's flow engine, which lets you create and execute multi-step API workflows as JSON files. Flows chain actions across platforms \u2014 e.g., look up a Stripe customer, then send them a welcome email via Gmail.
+
+## 1. Overview
+
+- Flows are JSON files stored at \`.one/flows/<key>.flow.json\`
+- All dynamic values (including connection keys) are declared as **inputs**
+- Each flow has a unique **key** used to reference and execute it
+- Executed via \`pica --agent flow execute <key> -i name=value\`
+
+## 2. Building a Flow \u2014 Step-by-Step Process
+
+**You MUST follow this process to build a correct flow:**
+
+### Step 1: Discover connections
+
+\`\`\`bash
+pica --agent connection list
+\`\`\`
+
+Find out which platforms are connected and get their connection keys.
+
+### Step 2: For EACH API action needed, get the knowledge
+
+\`\`\`bash
+# Find the action ID
+pica --agent actions search <platform> "<query>" -t execute
+
+# Read the full docs \u2014 REQUIRED before adding to a flow
+pica --agent actions knowledge <platform> <actionId>
+\`\`\`
+
+**CRITICAL:** You MUST call \`pica actions knowledge\` for every action you include in the flow. The knowledge output tells you the exact request body structure, required fields, path variables, and query parameters. Without this, your flow JSON will have incorrect data shapes.
+
+### Step 3: Construct the flow JSON
+
+Using the knowledge gathered, build the flow JSON with:
+- All inputs declared (connection keys + user parameters)
+- Each step with the correct actionId, platform, and data structure (from knowledge)
+- Data wired between steps using \`$.input.*\` and \`$.steps.*\` selectors
+
+### Step 4: Write the flow file
+
+\`\`\`bash
+pica --agent flow create <key> --definition '<json>'
+\`\`\`
+
+Or write directly to \`.one/flows/<key>.flow.json\`.
+
+### Step 5: Validate
+
+\`\`\`bash
+pica --agent flow validate <key>
+\`\`\`
+
+### Step 6: Execute
+
+\`\`\`bash
+pica --agent flow execute <key> -i connectionKey=xxx -i param=value
+\`\`\`
+
+## 3. Flow JSON Schema Reference
+
+\`\`\`json
+{
+  "key": "welcome-customer",
+  "name": "Welcome New Customer",
+  "description": "Look up a Stripe customer and send them a welcome email via Gmail",
+  "version": "1",
+  "inputs": {
+    "stripeConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Stripe connection key from pica connection list",
+      "connection": { "platform": "stripe" }
+    },
+    "gmailConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Gmail connection key from pica connection list",
+      "connection": { "platform": "gmail" }
+    },
+    "customerEmail": {
+      "type": "string",
+      "required": true,
+      "description": "Customer email to look up"
+    }
+  },
+  "steps": [
+    {
+      "id": "stepId",
+      "name": "Human-readable label",
+      "type": "action",
+      "action": {
+        "platform": "stripe",
+        "actionId": "the-action-id-from-search",
+        "connectionKey": "$.input.stripeConnectionKey",
+        "data": {},
+        "pathVars": {},
+        "queryParams": {},
+        "headers": {}
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Input declarations
+
+| Field | Type | Description |
+|---|---|---|
+| \`type\` | string | \`string\`, \`number\`, \`boolean\`, \`object\`, \`array\` |
+| \`required\` | boolean | Whether this input must be provided (default: true) |
+| \`default\` | any | Default value if not provided |
+| \`description\` | string | Human-readable description |
+| \`connection\` | object | Connection metadata: \`{ "platform": "gmail" }\` \u2014 enables auto-resolution |
+
+**Connection inputs** have a \`connection\` field. If the user has exactly one connection for that platform, the engine auto-resolves it.
+
+## 4. Selector Syntax Reference
+
+| Pattern | Resolves To |
+|---|---|
+| \`$.input.gmailConnectionKey\` | Input value (including connection keys) |
+| \`$.input.customerEmail\` | Any input parameter |
+| \`$.steps.stepId.response\` | Full API response from a step |
+| \`$.steps.stepId.response.data[0].email\` | Nested field with array index |
+| \`$.steps.stepId.response.data[*].id\` | Wildcard \u2014 maps array to field |
+| \`$.env.MY_VAR\` | Environment variable |
+| \`$.loop.item\` | Current loop item |
+| \`$.loop.i\` | Current loop index |
+| \`"Hello {{$.steps.getUser.response.data.name}}"\` | String interpolation |
+
+**Rules:**
+- A value that is purely \`$.xxx\` resolves to the raw type (object, array, number)
+- A string containing \`{{$.xxx}}\` does string interpolation (stringifies objects)
+- Selectors inside objects/arrays are resolved recursively
+
+## 5. Step Types Reference
+
+### \`action\` \u2014 Execute a Pica API action
+
+\`\`\`json
+{
+  "id": "findCustomer",
+  "name": "Search Stripe customers",
+  "type": "action",
+  "action": {
+    "platform": "stripe",
+    "actionId": "conn_mod_def::xxx::yyy",
+    "connectionKey": "$.input.stripeConnectionKey",
+    "data": {
+      "query": "email:'{{$.input.customerEmail}}'"
+    }
+  }
+}
+\`\`\`
+
+### \`transform\` \u2014 Transform data with a JS expression
+
+\`\`\`json
+{
+  "id": "extractNames",
+  "name": "Extract customer names",
+  "type": "transform",
+  "transform": {
+    "expression": "$.steps.findCustomer.response.data.map(c => c.name)"
+  }
+}
+\`\`\`
+
+The expression is evaluated with the full flow context as \`$\`.
+
+### \`code\` \u2014 Run multi-line JavaScript
+
+Unlike \`transform\` (single expression, implicit return), \`code\` runs a full function body with explicit \`return\`. Use it when you need variables, loops, try/catch, or \`await\`.
+
+\`\`\`json
+{
+  "id": "processData",
+  "name": "Process and enrich data",
+  "type": "code",
+  "code": {
+    "source": "const customers = $.steps.listCustomers.response.data;\\nconst enriched = customers.map(c => ({\\n  ...c,\\n  tier: c.spend > 1000 ? 'gold' : 'silver'\\n}));\\nreturn enriched;"
+  }
+}
+\`\`\`
+
+The \`source\` field contains a JS function body. The flow context is available as \`$\`. The function is async, so you can use \`await\`. The return value is stored as the step result.
+
+### \`condition\` \u2014 If/then/else branching
+
+\`\`\`json
+{
+  "id": "checkFound",
+  "name": "Check if customer was found",
+  "type": "condition",
+  "condition": {
+    "expression": "$.steps.findCustomer.response.data.length > 0",
+    "then": [
+      { "id": "sendEmail", "name": "Send welcome email", "type": "action", "action": { "..." : "..." } }
+    ],
+    "else": [
+      { "id": "logNotFound", "name": "Log not found", "type": "transform", "transform": { "expression": "'Customer not found'" } }
+    ]
+  }
+}
+\`\`\`
+
+### \`loop\` \u2014 Iterate over an array
+
+\`\`\`json
+{
+  "id": "processOrders",
+  "name": "Process each order",
+  "type": "loop",
+  "loop": {
+    "over": "$.steps.listOrders.response.data",
+    "as": "order",
+    "indexAs": "i",
+    "maxIterations": 1000,
+    "steps": [
+      {
+        "id": "createInvoice",
+        "name": "Create invoice for order",
+        "type": "action",
+        "action": {
+          "platform": "quickbooks",
+          "actionId": "...",
+          "connectionKey": "$.input.qbConnectionKey",
+          "data": { "amount": "$.loop.order.total" }
+        }
+      }
+    ]
+  }
+}
+\`\`\`
+
+### \`parallel\` \u2014 Run steps concurrently
+
+\`\`\`json
+{
+  "id": "parallelLookups",
+  "name": "Look up in parallel",
+  "type": "parallel",
+  "parallel": {
+    "maxConcurrency": 5,
+    "steps": [
+      { "id": "getStripe", "name": "Get Stripe data", "type": "action", "action": { "...": "..." } },
+      { "id": "getHubspot", "name": "Get HubSpot data", "type": "action", "action": { "...": "..." } }
+    ]
+  }
+}
+\`\`\`
+
+### \`file-read\` \u2014 Read from filesystem
+
+\`\`\`json
+{
+  "id": "readConfig",
+  "name": "Read config file",
+  "type": "file-read",
+  "fileRead": { "path": "./data/config.json", "parseJson": true }
+}
+\`\`\`
+
+### \`file-write\` \u2014 Write to filesystem
+
+\`\`\`json
+{
+  "id": "writeResults",
+  "name": "Save results",
+  "type": "file-write",
+  "fileWrite": {
+    "path": "./output/results.json",
+    "content": "$.steps.transform.output",
+    "append": false
+  }
+}
+\`\`\`
+
+## 6. Error Handling
+
+### \`onError\` strategies
+
+\`\`\`json
+{
+  "id": "riskyStep",
+  "name": "Might fail",
+  "type": "action",
+  "onError": {
+    "strategy": "retry",
+    "retries": 3,
+    "retryDelayMs": 1000
+  },
+  "action": { "...": "..." }
+}
+\`\`\`
+
+| Strategy | Behavior |
+|---|---|
+| \`fail\` | Stop the flow immediately (default) |
+| \`continue\` | Mark step as failed, continue to next step |
+| \`retry\` | Retry up to N times with delay |
+| \`fallback\` | On failure, execute a different step |
+
+### Conditional execution
+
+Skip a step based on previous results:
+
+\`\`\`json
+{
+  "id": "sendEmail",
+  "name": "Send email only if customer found",
+  "type": "action",
+  "if": "$.steps.findCustomer.response.data.length > 0",
+  "action": { "...": "..." }
+}
+\`\`\`
+
+## 7. Updating Existing Flows
+
+To modify an existing flow:
+
+1. Read the flow JSON file at \`.one/flows/<key>.flow.json\`
+2. Understand its current structure
+3. Use \`pica --agent actions knowledge <platform> <actionId>\` for any new actions
+4. Modify the JSON (add/remove/update steps, change data mappings, add inputs)
+5. Write back the updated flow file
+6. Validate: \`pica --agent flow validate <key>\`
+
+## 8. Complete Examples
+
+### Example 1: Simple 2-step \u2014 Search Stripe customer, send Gmail email
+
+\`\`\`json
+{
+  "key": "welcome-customer",
+  "name": "Welcome New Customer",
+  "description": "Look up a Stripe customer and send them a welcome email",
+  "version": "1",
+  "inputs": {
+    "stripeConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Stripe connection key",
+      "connection": { "platform": "stripe" }
+    },
+    "gmailConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Gmail connection key",
+      "connection": { "platform": "gmail" }
+    },
+    "customerEmail": {
+      "type": "string",
+      "required": true,
+      "description": "Customer email to look up"
+    }
+  },
+  "steps": [
+    {
+      "id": "findCustomer",
+      "name": "Search for customer in Stripe",
+      "type": "action",
+      "action": {
+        "platform": "stripe",
+        "actionId": "STRIPE_SEARCH_CUSTOMERS_ACTION_ID",
+        "connectionKey": "$.input.stripeConnectionKey",
+        "data": {
+          "query": "email:'{{$.input.customerEmail}}'"
+        }
+      }
+    },
+    {
+      "id": "sendWelcome",
+      "name": "Send welcome email via Gmail",
+      "type": "action",
+      "if": "$.steps.findCustomer.response.data && $.steps.findCustomer.response.data.length > 0",
+      "action": {
+        "platform": "gmail",
+        "actionId": "GMAIL_SEND_EMAIL_ACTION_ID",
+        "connectionKey": "$.input.gmailConnectionKey",
+        "data": {
+          "to": "{{$.input.customerEmail}}",
+          "subject": "Welcome, {{$.steps.findCustomer.response.data[0].name}}!",
+          "body": "Thank you for being a customer. We're glad to have you!"
+        }
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Example 2: Conditional \u2014 Check if HubSpot contact exists, create or update
+
+\`\`\`json
+{
+  "key": "sync-hubspot-contact",
+  "name": "Sync Contact to HubSpot",
+  "description": "Check if a contact exists in HubSpot, create if new or update if existing",
+  "version": "1",
+  "inputs": {
+    "hubspotConnectionKey": {
+      "type": "string",
+      "required": true,
+      "connection": { "platform": "hub-spot" }
+    },
+    "email": { "type": "string", "required": true },
+    "firstName": { "type": "string", "required": true },
+    "lastName": { "type": "string", "required": true }
+  },
+  "steps": [
+    {
+      "id": "searchContact",
+      "name": "Search for existing contact",
+      "type": "action",
+      "action": {
+        "platform": "hub-spot",
+        "actionId": "HUBSPOT_SEARCH_CONTACTS_ACTION_ID",
+        "connectionKey": "$.input.hubspotConnectionKey",
+        "data": {
+          "filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "EQ", "value": "$.input.email" }] }]
+        }
+      }
+    },
+    {
+      "id": "createOrUpdate",
+      "name": "Create or update contact",
+      "type": "condition",
+      "condition": {
+        "expression": "$.steps.searchContact.response.total > 0",
+        "then": [
+          {
+            "id": "updateContact",
+            "name": "Update existing contact",
+            "type": "action",
+            "action": {
+              "platform": "hub-spot",
+              "actionId": "HUBSPOT_UPDATE_CONTACT_ACTION_ID",
+              "connectionKey": "$.input.hubspotConnectionKey",
+              "pathVars": { "contactId": "$.steps.searchContact.response.results[0].id" },
+              "data": {
+                "properties": { "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
+              }
+            }
+          }
+        ],
+        "else": [
+          {
+            "id": "createContact",
+            "name": "Create new contact",
+            "type": "action",
+            "action": {
+              "platform": "hub-spot",
+              "actionId": "HUBSPOT_CREATE_CONTACT_ACTION_ID",
+              "connectionKey": "$.input.hubspotConnectionKey",
+              "data": {
+                "properties": { "email": "$.input.email", "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Example 3: Loop \u2014 Iterate over Shopify orders, create invoices
+
+\`\`\`json
+{
+  "key": "shopify-to-invoices",
+  "name": "Shopify Orders to Invoices",
+  "description": "Fetch recent Shopify orders and create an invoice for each",
+  "version": "1",
+  "inputs": {
+    "shopifyConnectionKey": {
+      "type": "string",
+      "required": true,
+      "connection": { "platform": "shopify" }
+    },
+    "qbConnectionKey": {
+      "type": "string",
+      "required": true,
+      "connection": { "platform": "quick-books" }
+    }
+  },
+  "steps": [
+    {
+      "id": "listOrders",
+      "name": "List recent Shopify orders",
+      "type": "action",
+      "action": {
+        "platform": "shopify",
+        "actionId": "SHOPIFY_LIST_ORDERS_ACTION_ID",
+        "connectionKey": "$.input.shopifyConnectionKey",
+        "queryParams": { "status": "any", "limit": "50" }
+      }
+    },
+    {
+      "id": "createInvoices",
+      "name": "Create invoice for each order",
+      "type": "loop",
+      "loop": {
+        "over": "$.steps.listOrders.response.orders",
+        "as": "order",
+        "indexAs": "i",
+        "steps": [
+          {
+            "id": "createInvoice",
+            "name": "Create QuickBooks invoice",
+            "type": "action",
+            "onError": { "strategy": "continue" },
+            "action": {
+              "platform": "quick-books",
+              "actionId": "QB_CREATE_INVOICE_ACTION_ID",
+              "connectionKey": "$.input.qbConnectionKey",
+              "data": {
+                "Line": [
+                  {
+                    "Amount": "$.loop.order.total_price",
+                    "Description": "Shopify Order #{{$.loop.order.order_number}}"
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "id": "summary",
+      "name": "Generate summary",
+      "type": "transform",
+      "transform": {
+        "expression": "({ totalOrders: $.steps.listOrders.response.orders.length, processed: $.steps.createInvoices.output.length })"
+      }
+    }
+  ]
+}
+\`\`\`
+
+## CLI Commands Reference
+
+\`\`\`bash
+# Create a flow
+pica --agent flow create <key> --definition '<json>'
+
+# List all flows
+pica --agent flow list
+
+# Validate a flow
+pica --agent flow validate <key>
+
+# Execute a flow
+pica --agent flow execute <key> -i connectionKey=value -i param=value
+
+# Execute with dry run (validate only)
+pica --agent flow execute <key> --dry-run -i connectionKey=value
+
+# Execute with verbose output
+pica --agent flow execute <key> -v -i connectionKey=value
+
+# List flow runs
+pica --agent flow runs [flowKey]
+
+# Resume a paused/failed run
+pica --agent flow resume <runId>
+\`\`\`
+
+## Important Notes
+
+- **Always use \`--agent\` flag** for structured JSON output
+- **Always call \`pica actions knowledge\`** before adding an action step to a flow
+- Platform names are **kebab-case** (e.g., \`hub-spot\`, not \`HubSpot\`)
+- Connection keys are **inputs**, not hardcoded \u2014 makes flows portable and shareable
+- Use \`$.input.*\` for input values, \`$.steps.*\` for step results
+- Action IDs in examples (like \`STRIPE_SEARCH_CUSTOMERS_ACTION_ID\`) are placeholders \u2014 always use \`pica actions search\` to find the real IDs
+`;
+var TOPICS = [
+  { topic: "overview", description: "Setup, --agent flag, discovery workflow" },
+  { topic: "actions", description: "Search, read docs, and execute platform actions" },
+  { topic: "flows", description: "Build and execute multi-step API workflows" },
+  { topic: "all", description: "Complete guide (all topics combined)" }
+];
+function getGuideContent(topic) {
+  switch (topic) {
+    case "overview":
+      return { title: "Pica CLI \u2014 Agent Guide: Overview", content: GUIDE_OVERVIEW };
+    case "actions":
+      return { title: "Pica CLI \u2014 Agent Guide: Actions", content: GUIDE_ACTIONS };
+    case "flows":
+      return { title: "Pica CLI \u2014 Agent Guide: Flows", content: GUIDE_FLOWS };
+    case "all":
+      return {
+        title: "Pica CLI \u2014 Agent Guide: Complete",
+        content: [GUIDE_OVERVIEW, GUIDE_ACTIONS, GUIDE_FLOWS].join("\n---\n\n")
+      };
+  }
+}
+function getAvailableTopics() {
+  return TOPICS;
+}
+
+// src/commands/guide.ts
+var VALID_TOPICS = ["overview", "actions", "flows", "all"];
+async function guideCommand(topic = "all") {
+  if (!VALID_TOPICS.includes(topic)) {
+    error(
+      `Unknown topic "${topic}". Available topics: ${VALID_TOPICS.join(", ")}`
+    );
+  }
+  const { title, content } = getGuideContent(topic);
+  const availableTopics = getAvailableTopics();
+  if (isAgentMode()) {
+    json({ topic, title, content, availableTopics });
+    return;
+  }
+  intro2(pc8.bgCyan(pc8.black(" Pica Guide ")));
+  console.log();
+  console.log(content);
+  console.log(pc8.dim("\u2500".repeat(60)));
+  console.log(
+    pc8.dim("Available topics: ") + availableTopics.map((t) => pc8.cyan(t.topic)).join(", ")
+  );
+  console.log(pc8.dim(`Run ${pc8.cyan("pica guide <topic>")} for a specific section.`));
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var program = new Command();
+program.name("pica").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`Pica CLI \u2014 Connect AI agents to 200+ platforms through one interface.
+
+  Setup:
+    pica init                              Set up API key and install MCP server
+    pica add <platform>                    Connect a platform via OAuth (e.g. gmail, slack, shopify)
+    pica config                            Configure access control (permissions, scoping)
+
+  Workflow (use these in order):
+    1. pica list                           List your connected platforms and connection keys
+    2. pica actions search <platform> <q>  Search for actions using natural language
+    3. pica actions knowledge <plat> <id>  Get full docs for an action (ALWAYS do this before execute)
+    4. pica actions execute <p> <id> <key> Execute the action
+
+  Guide:
+    pica guide [topic]                     Full CLI guide (topics: overview, actions, flows, all)
+
+  Flows (multi-step workflows):
+    pica flow list                         List saved flows
+    pica flow create [key]                 Create a flow from JSON
+    pica flow execute <key>                Execute a flow
+    pica flow validate <key>               Validate a flow
+
+  Example \u2014 send an email through Gmail:
+    $ pica list
+    # Find: gmail  operational  live::gmail::default::abc123
+
+    $ pica actions search gmail "send email" -t execute
+    # Find: POST  Send Email  conn_mod_def::xxx::yyy
+
+    $ pica actions knowledge gmail conn_mod_def::xxx::yyy
+    # Read the docs: required fields are to, subject, body, connectionKey
+
+    $ pica actions execute gmail conn_mod_def::xxx::yyy live::gmail::default::abc123 \\
+        -d '{"to":"j@example.com","subject":"Hello","body":"Hi!","connectionKey":"live::gmail::default::abc123"}'
+
+  Platform names are always kebab-case (e.g. hub-spot, ship-station, google-calendar).
+  Run 'pica platforms' to browse all 200+ available platforms.`).version(version);
+program.hook("preAction", (thisCommand) => {
+  const opts = program.opts();
+  if (opts.agent) {
+    setAgentMode(true);
+  }
+});
+program.command("init").description("Set up Pica and install MCP to your AI agents").option("-y, --yes", "Skip confirmations").option("-g, --global", "Install MCP globally (available in all projects)").option("-p, --project", "Install MCP for this project only (creates .mcp.json)").action(async (options) => {
+  await initCommand(options);
+});
+program.command("config").description("Configure MCP access control (permissions, connections, actions)").action(async () => {
+  await configCommand();
+});
+var connection = program.command("connection").description("Manage connections");
+connection.command("add [platform]").alias("a").description("Add a new connection").action(async (platform) => {
+  await connectionAddCommand(platform);
+});
+connection.command("list").alias("ls").description("List your connections").action(async () => {
+  await connectionListCommand();
+});
+program.command("platforms").alias("p").description("List available platforms").option("-c, --category <category>", "Filter by category").option("--json", "Output as JSON").action(async (options) => {
+  await platformsCommand(options);
+});
+var actions = program.command("actions").alias("a").description("Search, explore, and execute platform actions (workflow: search \u2192 knowledge \u2192 execute)");
+actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. pica actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). Default: knowledge").action(async (platform, query, options) => {
+  await actionsSearchCommand(platform, query, options);
+});
+actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").action(async (platform, actionId) => {
+  await actionsKnowledgeCommand(platform, actionId);
+});
+actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "pica list", actionId from "actions search"').option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").action(async (platform, actionId, connectionKey, options) => {
+  await actionsExecuteCommand(platform, actionId, connectionKey, {
+    data: options.data,
+    pathVars: options.pathVars,
+    queryParams: options.queryParams,
+    headers: options.headers,
+    formData: options.formData,
+    formUrlEncoded: options.formUrlEncoded
+  });
+});
+var flow = program.command("flow").alias("f").description("Create, execute, and manage multi-step API workflows");
+flow.command("create [key]").description("Create a new flow from JSON definition").option("--definition <json>", "Flow 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 flow 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("-v, --verbose", "Show full request/response for each step").action(async (keyOrPath, options) => {
+  await flowExecuteCommand(keyOrPath, options);
+});
+flow.command("list").alias("ls").description("List all flows in .one/flows/").action(async () => {
+  await flowListCommand();
+});
+flow.command("validate <keyOrPath>").description("Validate a flow JSON file").action(async (keyOrPath) => {
+  await flowValidateCommand(keyOrPath);
+});
+flow.command("resume <runId>").description("Resume a paused or failed flow run").action(async (runId) => {
+  await flowResumeCommand(runId);
+});
+flow.command("runs [flowKey]").description("List flow runs (optionally filtered by flow key)").action(async (flowKey) => {
+  await flowRunsCommand(flowKey);
+});
+program.command("guide [topic]").description("Full CLI usage guide for agents (topics: overview, actions, flows, all)").action(async (topic) => {
+  await guideCommand(topic);
 });
 program.command("add [platform]").description("Shortcut for: connection add").action(async (platform) => {
   await connectionAddCommand(platform);