@withone/cli 1.15.0 → 1.17.1

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   loadFlow,
   resolveFlowPath,
   saveFlow
-} from "./chunk-SX2Y4HDW.js";
+} from "./chunk-QW4MBV4F.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -19,9 +19,10 @@ import { Command } from "commander";
 
 // src/commands/init.ts
 import * as p3 from "@clack/prompts";
-import pc3 from "picocolors";
+import pc2 from "picocolors";
+import fs3 from "fs";
 import path3 from "path";
-import { spawn } from "child_process";
+import os3 from "os";
 import { fileURLToPath } from "url";
 
 // src/lib/config.ts
@@ -530,122 +531,69 @@ function formatList(list) {
 
 // src/commands/init.ts
 import open2 from "open";
-
-// src/lib/table.ts
-import pc2 from "picocolors";
-function printTable(columns, rows) {
-  if (rows.length === 0) return;
-  const gap = "  ";
-  const indent = "  ";
-  const widths = columns.map((col) => {
-    const headerLen = col.label.length;
-    const maxValueLen = Math.max(...rows.map((row) => stripAnsi(row[col.key] || "").length));
-    return Math.max(headerLen, maxValueLen);
-  });
-  const header = columns.map((col, i) => {
-    const padded = col.align === "right" ? col.label.padStart(widths[i]) : col.label.padEnd(widths[i]);
-    return pc2.dim(padded);
-  }).join(gap);
-  console.log(`${indent}${header}`);
-  const separator = columns.map((_, i) => pc2.dim("\u2500".repeat(widths[i]))).join(gap);
-  console.log(`${indent}${separator}`);
-  for (const row of rows) {
-    const line = columns.map((col, i) => {
-      const raw = row[col.key] || "";
-      const rawLen = stripAnsi(raw).length;
-      const padding = widths[i] - rawLen;
-      const colored = col.color ? col.color(raw) : raw;
-      if (col.align === "right") {
-        return " ".repeat(Math.max(0, padding)) + colored;
-      }
-      return colored + " ".repeat(Math.max(0, padding));
-    }).join(gap);
-    console.log(`${indent}${line}`);
-  }
-}
-function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-
-// src/commands/init.ts
 async function initCommand(options) {
   if (isAgentMode()) {
     error("This command requires interactive input. Run without --agent.");
   }
   const existingConfig = readConfig();
+  printBanner();
   if (existingConfig) {
-    p3.intro(pc3.bgCyan(pc3.black(" One ")));
     await handleExistingConfig(existingConfig.apiKey, options);
     return;
   }
-  printBanner();
   await freshSetup(options);
 }
 async function handleExistingConfig(apiKey, options) {
   const statuses = getAgentStatuses();
   const masked = maskApiKey(apiKey);
+  const skillInstalled = isSkillInstalled();
   console.log();
-  console.log(`  ${pc3.bold("Current Setup")}`);
-  console.log(`  ${pc3.dim("\u2500".repeat(42))}`);
-  console.log(`  ${pc3.dim("API Key:")}  ${masked}`);
-  console.log(`  ${pc3.dim("Config:")}   ${getConfigPath()}`);
-  console.log();
-  printTable(
-    [
-      { key: "agent", label: "Agent" },
-      { key: "global", label: "Global" },
-      { key: "project", label: "Project" }
-    ],
-    statuses.map((s) => ({
-      agent: s.agent.name,
-      global: !s.detected ? pc3.dim("-") : s.globalMcp ? pc3.green("\u25CF yes") : pc3.yellow("\u25CB no"),
-      project: s.projectMcp === null ? pc3.dim("-") : s.projectMcp ? pc3.green("\u25CF yes") : pc3.yellow("\u25CB no")
-    }))
-  );
-  const notDetected = statuses.filter((s) => !s.detected);
-  if (notDetected.length > 0) {
-    console.log(`  ${pc3.dim("- = not detected on this machine")}`);
-  }
+  console.log(`  ${pc2.bold("Current Setup")}`);
+  console.log(`  ${pc2.dim("\u2500".repeat(42))}`);
+  console.log(`  ${pc2.dim("API Key:")}  ${masked}`);
+  console.log(`  ${pc2.dim("Skill:")}    ${skillInstalled ? pc2.green("installed") : pc2.yellow("not installed")}`);
+  console.log(`  ${pc2.dim("Config:")}   ${getConfigPath()}`);
   const ac = getAccessControl();
   if (Object.keys(ac).length > 0) {
-    console.log(`  ${pc3.bold("Access Control")}`);
-    console.log(`  ${pc3.dim("\u2500".repeat(42))}`);
-    if (ac.permissions) console.log(`  ${pc3.dim("Permissions:")}   ${ac.permissions}`);
-    if (ac.connectionKeys) console.log(`  ${pc3.dim("Connections:")}   ${ac.connectionKeys.join(", ")}`);
-    if (ac.actionIds) console.log(`  ${pc3.dim("Action IDs:")}    ${ac.actionIds.join(", ")}`);
-    if (ac.knowledgeAgent) console.log(`  ${pc3.dim("Knowledge only:")} yes`);
     console.log();
+    console.log(`  ${pc2.bold("Access Control")}`);
+    console.log(`  ${pc2.dim("\u2500".repeat(42))}`);
+    if (ac.permissions) console.log(`  ${pc2.dim("Permissions:")}   ${ac.permissions}`);
+    if (ac.connectionKeys) console.log(`  ${pc2.dim("Connections:")}   ${ac.connectionKeys.join(", ")}`);
+    if (ac.actionIds) console.log(`  ${pc2.dim("Action IDs:")}    ${ac.actionIds.join(", ")}`);
+    if (ac.knowledgeAgent) console.log(`  ${pc2.dim("Knowledge only:")} yes`);
   }
+  console.log();
   const actionOptions = [];
   actionOptions.push({
-    value: "update-key",
-    label: "Update API key"
+    value: "install-skills",
+    label: skillInstalled ? "Update skill" : "Install skill",
+    hint: skillInstalled ? "reinstall latest version" : "recommended"
   });
   actionOptions.push({
-    value: "install-skills",
-    label: "Install/update skills"
+    value: "show-prompt",
+    label: "Show agent onboarding prompt",
+    hint: "copy-paste to your AI agent"
+  });
+  actionOptions.push({
+    value: "add-connection",
+    label: "Connect a platform",
+    hint: "add Gmail, Slack, Shopify, etc."
+  });
+  actionOptions.push({
+    value: "update-key",
+    label: "Update API key"
   });
-  const agentsMissingGlobal = statuses.filter((s) => s.detected && !s.globalMcp);
-  if (agentsMissingGlobal.length > 0) {
-    actionOptions.push({
-      value: "install-more",
-      label: "Install MCP to more agents",
-      hint: `${agentsMissingGlobal.map((s) => s.agent.name).join(", ")} (not recommended)`
-    });
-  }
-  const agentsMissingProject = statuses.filter((s) => s.projectMcp === false);
-  if (agentsMissingProject.length > 0) {
-    actionOptions.push({
-      value: "install-project",
-      label: "Install MCP for this project",
-      hint: `${agentsMissingProject.map((s) => s.agent.name).join(", ")} (not recommended)`
-    });
-  }
   actionOptions.push({
     value: "access-control",
     label: "Configure access control",
     hint: "permissions, connections, actions"
   });
+  actionOptions.push({
+    value: "install-mcp",
+    label: "Install MCP server",
+    hint: "not recommended \u2014 use skills instead"
+  });
   actionOptions.push({
     value: "start-fresh",
     label: "Start fresh (reconfigure everything)"
@@ -659,30 +607,34 @@ async function handleExistingConfig(apiKey, options) {
     return;
   }
   switch (action) {
-    case "update-key":
-      await handleUpdateKey(statuses);
-      break;
     case "install-skills": {
-      const success = await runSkillsInstall();
+      const success = await promptSkillInstall();
       if (success) {
-        p3.outro("Skills installed successfully.");
+        printOnboardingPrompt();
+        p3.outro("Skill installed. Paste the prompt above to your AI agent.");
       } else {
-        const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-        const skillsDir = path3.resolve(__dirname2, "..", "skills");
-        p3.log.warn(`Skills installation failed. You can try manually: ${pc3.cyan(`npx skills add ${skillsDir}`)}`);
         p3.outro("Done.");
       }
       break;
     }
-    case "install-more":
-      await handleInstallMore(apiKey, agentsMissingGlobal);
+    case "show-prompt":
+      printOnboardingPrompt();
+      p3.outro("Paste the prompt above to your AI agent.");
       break;
-    case "install-project":
-      await handleInstallProject(apiKey, agentsMissingProject);
+    case "add-connection":
+      await promptConnectIntegrations(apiKey);
+      p3.outro("Done.");
+      break;
+    case "update-key":
+      await handleUpdateKey(statuses);
       break;
     case "access-control":
       await configCommand();
       break;
+    case "install-mcp":
+      await promptAndInstallMcp(apiKey, options);
+      p3.outro("Done.");
+      break;
     case "start-fresh":
       await freshSetup({ yes: true });
       break;
@@ -690,7 +642,7 @@ async function handleExistingConfig(apiKey, options) {
 }
 async function handleUpdateKey(statuses) {
   p3.note(`Get your API key at:
-${pc3.cyan(getApiKeyUrl())}`, "API Key");
+${pc2.cyan(getApiKeyUrl())}`, "API Key");
   const openBrowser = await p3.confirm({
     message: "Open browser to get API key?",
     initialValue: true
@@ -751,108 +703,161 @@ ${pc3.cyan(getApiKeyUrl())}`, "API Key");
   }
   p3.outro("API key updated.");
 }
-async function handleInstallMore(apiKey, missing) {
-  const ac = getAccessControl();
-  if (missing.length === 1) {
-    const agent = missing[0].agent;
-    const confirm3 = await p3.confirm({
-      message: `Install One MCP to ${agent.name}?`,
-      initialValue: true
-    });
-    if (p3.isCancel(confirm3) || !confirm3) {
-      p3.outro("No changes made.");
-      return;
+var SKILL_AGENTS = [
+  { id: "claude-code", name: "Claude Code", skillDir: ".claude/skills", primary: true },
+  { id: "claude-desktop", name: "Claude Desktop", skillDir: ".claude/skills", primary: true },
+  { id: "codex", name: "Codex", skillDir: ".codex/skills", primary: true },
+  { id: "cursor", name: "Cursor", skillDir: ".cursor/skills" },
+  { id: "windsurf", name: "Windsurf", skillDir: ".codeium/windsurf/skills" },
+  { id: "kiro", name: "Kiro", skillDir: ".kiro/skills" },
+  { id: "goose", name: "Goose", skillDir: ".config/goose/skills" },
+  { id: "amp", name: "Amp", skillDir: ".amp/skills" },
+  { id: "opencode", name: "OpenCode", skillDir: ".opencode/skills" },
+  { id: "roo", name: "Roo", skillDir: ".roo/skills" }
+];
+var CANONICAL_SKILL_DIR = ".agents/skills";
+function getSkillSourceDir() {
+  const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
+  return path3.resolve(__dirname2, "..", "skills", "one");
+}
+function getCanonicalSkillPath() {
+  return path3.join(os3.homedir(), CANONICAL_SKILL_DIR, "one");
+}
+function getAgentSkillPath(agent) {
+  return path3.join(os3.homedir(), agent.skillDir, "one");
+}
+function isSkillInstalled() {
+  return fs3.existsSync(path3.join(getCanonicalSkillPath(), "SKILL.md"));
+}
+function isSkillInstalledForAgent(agent) {
+  return fs3.existsSync(path3.join(getAgentSkillPath(agent), "SKILL.md"));
+}
+function copyDirSync(src, dest) {
+  fs3.mkdirSync(dest, { recursive: true });
+  for (const entry of fs3.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path3.join(src, entry.name);
+    const destPath = path3.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs3.copyFileSync(srcPath, destPath);
     }
-    installMcpConfig(agent, apiKey, "global", ac);
-    updateConfigAgents(agent.id);
-    p3.log.success(`${agent.name}: MCP installed`);
-    p3.outro("Done.");
-    return;
   }
-  const selected = await p3.multiselect({
-    message: "Select agents to install MCP:",
-    options: missing.map((s) => ({
-      value: s.agent.id,
-      label: s.agent.name
-    }))
-  });
-  if (p3.isCancel(selected)) {
-    p3.outro("No changes made.");
-    return;
+}
+function installSkillForAgents(agentIds) {
+  const source = getSkillSourceDir();
+  const canonical = getCanonicalSkillPath();
+  const installed = [];
+  const failed = [];
+  if (!fs3.existsSync(path3.join(source, "SKILL.md"))) {
+    return { installed: [], failed: ["skill source not found"] };
   }
-  const agents = missing.filter((s) => selected.includes(s.agent.id));
-  for (const s of agents) {
-    installMcpConfig(s.agent, apiKey, "global", ac);
-    updateConfigAgents(s.agent.id);
-    p3.log.success(`${s.agent.name}: MCP installed`);
+  try {
+    if (fs3.existsSync(canonical)) {
+      fs3.rmSync(canonical, { recursive: true });
+    }
+    copyDirSync(source, canonical);
+  } catch {
+    return { installed: [], failed: ["canonical copy"] };
   }
-  p3.outro("Done.");
+  const seen = /* @__PURE__ */ new Map();
+  for (const id of agentIds) {
+    const agent = SKILL_AGENTS.find((a) => a.id === id);
+    if (!agent) continue;
+    const agentPath = getAgentSkillPath(agent);
+    if (seen.has(agentPath)) {
+      (seen.get(agentPath) ? installed : failed).push(agent.name);
+      continue;
+    }
+    try {
+      const agentSkillsDir = path3.dirname(agentPath);
+      fs3.mkdirSync(agentSkillsDir, { recursive: true });
+      try {
+        fs3.lstatSync(agentPath);
+        fs3.rmSync(agentPath, { recursive: true });
+      } catch {
+      }
+      const relative = path3.relative(agentSkillsDir, canonical);
+      fs3.symlinkSync(relative, agentPath);
+      installed.push(agent.name);
+      seen.set(agentPath, true);
+    } catch {
+      failed.push(agent.name);
+      seen.set(agentPath, false);
+    }
+  }
+  return { installed, failed };
 }
-async function handleInstallProject(apiKey, missing) {
-  const ac = getAccessControl();
-  if (missing.length === 1) {
-    const agent = missing[0].agent;
-    const confirm3 = await p3.confirm({
-      message: `Install project-level MCP for ${agent.name}?`,
-      initialValue: true
+async function promptSkillInstall() {
+  const primaryAgents = SKILL_AGENTS.filter((a) => a.primary);
+  const otherAgents = SKILL_AGENTS.filter((a) => !a.primary);
+  const options = [
+    ...primaryAgents.map((a) => ({
+      value: a.id,
+      label: a.name,
+      hint: isSkillInstalledForAgent(a) ? pc2.green("installed") : void 0
+    })),
+    {
+      value: "_other",
+      label: "Other agents",
+      hint: otherAgents.map((a) => a.name).join(", ")
+    }
+  ];
+  const choice = await p3.multiselect({
+    message: "Install the One skill to:",
+    options,
+    initialValues: primaryAgents.map((a) => a.id)
+  });
+  if (p3.isCancel(choice)) {
+    return false;
+  }
+  let selectedIds = choice;
+  if (selectedIds.includes("_other")) {
+    selectedIds = selectedIds.filter((id) => id !== "_other");
+    const otherChoice = await p3.multiselect({
+      message: "Select additional agents:",
+      options: otherAgents.map((a) => ({
+        value: a.id,
+        label: a.name,
+        hint: isSkillInstalledForAgent(a) ? pc2.green("installed") : void 0
+      }))
     });
-    if (p3.isCancel(confirm3) || !confirm3) {
-      p3.outro("No changes made.");
-      return;
+    if (!p3.isCancel(otherChoice)) {
+      selectedIds.push(...otherChoice);
     }
-    installMcpConfig(agent, apiKey, "project", ac);
-    const configPath = getAgentConfigPath(agent, "project");
-    p3.log.success(`${agent.name}: ${configPath} created`);
-    p3.note(
-      pc3.yellow("Project config files can be committed to share with your team.\n") + pc3.yellow("Team members will need their own API key."),
-      "Tip"
-    );
-    p3.outro("Done.");
-    return;
   }
-  const selected = await p3.multiselect({
-    message: "Select agents for project-level MCP:",
-    options: missing.map((s) => ({
-      value: s.agent.id,
-      label: s.agent.name
-    }))
-  });
-  if (p3.isCancel(selected)) {
-    p3.outro("No changes made.");
-    return;
+  if (selectedIds.length === 0) {
+    p3.log.info("No agents selected.");
+    return false;
   }
-  const agents = missing.filter((s) => selected.includes(s.agent.id));
-  for (const s of agents) {
-    installMcpConfig(s.agent, apiKey, "project", ac);
-    const configPath = getAgentConfigPath(s.agent, "project");
-    p3.log.success(`${s.agent.name}: ${configPath} created`);
+  const spinner5 = p3.spinner();
+  spinner5.start("Installing skill...");
+  const { installed, failed } = installSkillForAgents(selectedIds);
+  spinner5.stop(installed.length > 0 ? "Skill installed" : "Installation failed");
+  for (const name of installed) {
+    p3.log.success(`${name}: ${pc2.green("\u2713")} skill installed`);
   }
-  p3.note(
-    pc3.yellow("Project config files can be committed to share with your team.\n") + pc3.yellow("Team members will need their own API key."),
-    "Tip"
-  );
-  p3.outro("Done.");
+  for (const name of failed) {
+    p3.log.warn(`${name}: failed to install`);
+  }
+  return installed.length > 0;
 }
-async function runSkillsInstall() {
-  const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-  const skillsDir = path3.resolve(__dirname2, "..", "skills");
-  return new Promise((resolve) => {
-    const handler = () => {
-    };
-    process.on("SIGINT", handler);
-    const child = spawn("npx", ["skills", "add", skillsDir], {
-      stdio: "inherit",
-      shell: true
-    });
-    child.on("close", (code) => {
-      process.removeListener("SIGINT", handler);
-      resolve(code === 0);
-    });
-    child.on("error", () => {
-      process.removeListener("SIGINT", handler);
-      resolve(false);
-    });
-  });
+function printOnboardingPrompt() {
+  console.log();
+  console.log(pc2.bold("  Copy-paste this to your AI agent:"));
+  console.log();
+  console.log(pc2.cyan("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(pc2.cyan("  \u2502"));
+  console.log(pc2.cyan("  \u2502  The One CLI (`one`) is now installed on this machine. It"));
+  console.log(pc2.cyan("  \u2502  lets you interact with 250+ third-party platforms (Gmail,"));
+  console.log(pc2.cyan("  \u2502  Slack, Shopify, HubSpot, Stripe, GitHub, etc.) through"));
+  console.log(pc2.cyan("  \u2502  their APIs. Whenever you need to interact with any"));
+  console.log(pc2.cyan("  \u2502  third-party platform or external service, use the `one`"));
+  console.log(pc2.cyan("  \u2502  skill. Please save this to your project instructions or"));
+  console.log(pc2.cyan("  \u2502  memory so you remember it in future conversations."));
+  console.log(pc2.cyan("  \u2502"));
+  console.log(pc2.cyan("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log();
 }
 async function promptAndInstallMcp(apiKey, options) {
   const allAgents = getAllAgents();
@@ -935,7 +940,7 @@ Project scope is supported by: ${supported}`,
     const allInstalled = [...projectAgents, ...nonProjectAgents];
     updateConfigAgentsList(allInstalled.map((a) => a.id));
     p3.note(
-      pc3.yellow("Project config files can be committed to share with your team.\n") + pc3.yellow("Team members will need their own API key."),
+      pc2.yellow("Project config files can be committed to share with your team.\n") + pc2.yellow("Team members will need their own API key."),
       "Tip"
     );
     return;
@@ -952,7 +957,7 @@ Project scope is supported by: ${supported}`,
 }
 async function freshSetup(options) {
   p3.note(`Get your API key at:
-${pc3.cyan(getApiKeyUrl())}`, "API Key");
+${pc2.cyan(getApiKeyUrl())}`, "API Key");
   const openBrowser = await p3.confirm({
     message: "Open browser to get API key?",
     initialValue: true
@@ -994,20 +999,7 @@ ${pc3.cyan(getApiKeyUrl())}`, "API Key");
     installedAgents: [],
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   });
-  const installSkills = await p3.confirm({
-    message: "Install One skills to your AI agents? (recommended)",
-    initialValue: true
-  });
-  if (!p3.isCancel(installSkills) && installSkills) {
-    const success = await runSkillsInstall();
-    if (success) {
-      p3.log.success("Skills installed successfully.");
-    } else {
-      const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-      const skillsDir = path3.resolve(__dirname2, "..", "skills");
-      p3.log.warn(`Skills installation failed. You can try manually: ${pc3.cyan(`npx skills add ${skillsDir}`)}`);
-    }
-  }
+  await promptSkillInstall();
   await promptConnectIntegrations(apiKey);
   const installMcp = await p3.confirm({
     message: "Install One MCP server to your AI agents? (not recommended)",
@@ -1017,29 +1009,26 @@ ${pc3.cyan(getApiKeyUrl())}`, "API Key");
     await promptAndInstallMcp(apiKey, options);
   }
   p3.note(
-    `Config saved to: ${pc3.dim(getConfigPath())}`,
+    `Config saved to: ${pc2.dim(getConfigPath())}`,
     "Setup Complete"
   );
-  p3.note(
-    `Tell your agent to run ${pc3.cyan("one onboard")} to learn what it can do.`,
-    "Next Step"
-  );
-  p3.outro("Your AI agents now have access to One integrations!");
+  printOnboardingPrompt();
+  p3.outro("Done! Paste the prompt above to your AI agent.");
 }
 function printBanner() {
   console.log();
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc3.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588      \u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(pc2.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588      \u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
   console.log();
-  console.log(pc3.dim("  U N I V E R S A L   I N T E G R A T I O N S   F O R   A I"));
+  console.log(pc2.dim("  I N F R A S T R U C T U R E   F O R   A G E N T S"));
   console.log();
 }
 var TOP_INTEGRATIONS = [
@@ -1084,13 +1073,13 @@ async function promptConnectIntegrations(apiKey) {
       } catch {
         p3.note("https://app.withone.ai/connections", "Open in browser");
       }
-      p3.log.info(`Connect from the dashboard, or use ${pc3.cyan("one add <platform>")}`);
+      p3.log.info(`Connect from the dashboard, or use ${pc2.cyan("one add <platform>")}`);
       break;
     }
     const platform = choice;
     const integration = TOP_INTEGRATIONS.find((i) => i.value === platform);
     const label = integration?.label ?? platform;
-    p3.log.info(`Opening browser to connect ${pc3.cyan(label)}...`);
+    p3.log.info(`Opening browser to connect ${pc2.cyan(label)}...`);
     try {
       await openConnectionPage(platform);
     } catch {
@@ -1103,13 +1092,13 @@ async function promptConnectIntegrations(apiKey) {
     try {
       await api.waitForConnection(platform, 5 * 60 * 1e3, 5e3);
       spinner5.stop(`${label} connected!`);
-      p3.log.success(`${pc3.green("\u2713")} ${label} is now available to your AI agents`);
+      p3.log.success(`${pc2.green("\u2713")} ${label} is now available to your AI agents`);
       connected.push(platform);
       first = false;
     } catch (error2) {
       spinner5.stop("Connection timed out");
       if (error2 instanceof TimeoutError) {
-        p3.log.warn(`No worries. Connect later with: ${pc3.cyan(`one add ${platform}`)}`);
+        p3.log.warn(`No worries. Connect later with: ${pc2.cyan(`one add ${platform}`)}`);
       }
       first = false;
     }
@@ -1123,14 +1112,6 @@ function maskApiKey(key) {
   if (key.length <= 12) return key.slice(0, 8) + "...";
   return key.slice(0, 8) + "..." + key.slice(-4);
 }
-function updateConfigAgents(agentId) {
-  const config = readConfig();
-  if (!config) return;
-  if (!config.installedAgents.includes(agentId)) {
-    config.installedAgents.push(agentId);
-    writeConfig(config);
-  }
-}
 function updateConfigAgentsList(agentIds) {
   const config = readConfig();
   if (!config) return;
@@ -1181,6 +1162,42 @@ function countMatchingChars(a, b) {
   return count;
 }
 
+// src/lib/table.ts
+import pc3 from "picocolors";
+function printTable(columns, rows) {
+  if (rows.length === 0) return;
+  const gap = "  ";
+  const indent = "  ";
+  const widths = columns.map((col) => {
+    const headerLen = col.label.length;
+    const maxValueLen = Math.max(...rows.map((row) => stripAnsi(row[col.key] || "").length));
+    return Math.max(headerLen, maxValueLen);
+  });
+  const header = columns.map((col, i) => {
+    const padded = col.align === "right" ? col.label.padStart(widths[i]) : col.label.padEnd(widths[i]);
+    return pc3.dim(padded);
+  }).join(gap);
+  console.log(`${indent}${header}`);
+  const separator = columns.map((_, i) => pc3.dim("\u2500".repeat(widths[i]))).join(gap);
+  console.log(`${indent}${separator}`);
+  for (const row of rows) {
+    const line = columns.map((col, i) => {
+      const raw = row[col.key] || "";
+      const rawLen = stripAnsi(raw).length;
+      const padding = widths[i] - rawLen;
+      const colored = col.color ? col.color(raw) : raw;
+      if (col.align === "right") {
+        return " ".repeat(Math.max(0, padding)) + colored;
+      }
+      return colored + " ".repeat(Math.max(0, padding));
+    }).join(gap);
+    console.log(`${indent}${line}`);
+  }
+}
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
 // src/commands/connection.ts
 async function connectionAddCommand(platformArg) {
   if (isAgentMode()) {
@@ -1680,57 +1697,576 @@ async function actionsExecuteCommand(platform, actionId, connectionKey, options)
         console.log(pc6.dim("Body:"));
         console.log(pc6.dim(JSON.stringify(result.requestConfig.data, null, 2)));
       }
-      console.log();
-      note2("Dry run \u2014 request was not sent", "Dry Run");
-    } else {
-      console.log();
-      console.log(pc6.bold("Response:"));
-      console.log(JSON.stringify(result.responseData, null, 2));
+      console.log();
+      note2("Dry run \u2014 request was not sent", "Dry Run");
+    } else {
+      console.log();
+      console.log(pc6.bold("Response:"));
+      console.log(JSON.stringify(result.responseData, null, 2));
+    }
+  } catch (error2) {
+    spinner5.stop("Execution failed");
+    error(
+      `Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`
+    );
+  }
+}
+function colorMethod(method) {
+  switch (method.toUpperCase()) {
+    case "GET":
+      return pc6.green(method);
+    case "POST":
+      return pc6.yellow(method);
+    case "PUT":
+      return pc6.blue(method);
+    case "PATCH":
+      return pc6.magenta(method);
+    case "DELETE":
+      return pc6.red(method);
+    default:
+      return method;
+  }
+}
+
+// src/commands/flow.ts
+import pc7 from "picocolors";
+
+// src/lib/flow-schema.ts
+var FLOW_SCHEMA = {
+  errorStrategies: ["fail", "continue", "retry", "fallback"],
+  validInputTypes: ["string", "number", "boolean", "object", "array"],
+  flowFields: {
+    key: { type: "string", required: true, description: "Unique kebab-case identifier", pattern: /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ },
+    name: { type: "string", required: true, description: "Human-readable flow name" },
+    description: { type: "string", required: false, description: "What this flow does" },
+    version: { type: "string", required: false, description: "Semver or arbitrary version string" },
+    inputs: { type: "object", required: true, description: "Input declarations (Record<string, InputDeclaration>)" },
+    steps: { type: "array", required: true, description: "Ordered array of steps", stepsArray: true }
+  },
+  inputFields: {
+    type: { type: "string", required: true, description: "Data type: string, number, boolean, object, array", enum: ["string", "number", "boolean", "object", "array"] },
+    required: { type: "boolean", required: false, description: "Whether this input must be provided" },
+    default: { type: "unknown", required: false, description: "Default value if not provided" },
+    description: { type: "string", required: false, description: "Human-readable description" },
+    connection: { type: "object", required: false, description: 'Connection metadata: { platform: "gmail" } \u2014 enables auto-resolution' }
+  },
+  stepCommonFields: {
+    id: { type: "string", required: true, description: "Unique step identifier (used in selectors)" },
+    name: { type: "string", required: true, description: "Human-readable step label" },
+    type: { type: "string", required: true, description: "Step type (determines which config object is required)" },
+    if: { type: "string", required: false, description: "JS expression \u2014 skip step if falsy" },
+    unless: { type: "string", required: false, description: "JS expression \u2014 skip step if truthy" }
+  },
+  stepTypes: [
+    {
+      type: "action",
+      configKey: "action",
+      description: "Execute a platform API action",
+      fields: {
+        platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
+        actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
+        connectionKey: { type: "string", required: true, description: "Connection key (use $.input selector)" },
+        data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
+        pathVars: { type: "object", required: false, description: "URL path variables" },
+        queryParams: { type: "object", required: false, description: "Query parameters" },
+        headers: { type: "object", required: false, description: "Additional headers" }
+      },
+      example: {
+        id: "findCustomer",
+        name: "Search Stripe customers",
+        type: "action",
+        action: {
+          platform: "stripe",
+          actionId: "conn_mod_def::xxx::yyy",
+          connectionKey: "$.input.stripeConnectionKey",
+          data: { query: "email:'{{$.input.customerEmail}}'" }
+        }
+      }
+    },
+    {
+      type: "transform",
+      configKey: "transform",
+      description: "Single JS expression with implicit return",
+      fields: {
+        expression: { type: "string", required: true, description: "JS expression evaluated with flow context as $" }
+      },
+      example: {
+        id: "extractNames",
+        name: "Extract customer names",
+        type: "transform",
+        transform: { expression: "$.steps.findCustomer.response.data.map(c => c.name)" }
+      }
+    },
+    {
+      type: "code",
+      configKey: "code",
+      description: "Multi-line async JS with explicit return",
+      fields: {
+        source: { type: "string", required: true, description: "JS function body (flow context as $, supports await)" }
+      },
+      example: {
+        id: "processData",
+        name: "Process and enrich data",
+        type: "code",
+        code: { source: "const items = $.steps.fetch.response.data;\nreturn items.filter(i => i.active);" }
+      }
+    },
+    {
+      type: "condition",
+      configKey: "condition",
+      description: "If/then/else branching",
+      fields: {
+        expression: { type: "string", required: true, description: "JS expression \u2014 truthy runs then, falsy runs else" },
+        then: { type: "array", required: true, description: "Steps to run when true", stepsArray: true },
+        else: { type: "array", required: false, description: "Steps to run when false", stepsArray: true }
+      },
+      example: {
+        id: "checkFound",
+        name: "Check if customer exists",
+        type: "condition",
+        condition: {
+          expression: "$.steps.search.response.data.length > 0",
+          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey", data: { text: "Found!" } } }],
+          else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
+        }
+      }
+    },
+    {
+      type: "loop",
+      configKey: "loop",
+      description: "Iterate over an array with optional concurrency",
+      fields: {
+        over: { type: "string", required: true, description: "Selector resolving to an array" },
+        as: { type: "string", required: true, description: "Variable name for current item ($.loop.<as>)" },
+        indexAs: { type: "string", required: false, description: "Variable name for index" },
+        steps: { type: "array", required: true, description: "Steps to run per iteration", stepsArray: true },
+        maxIterations: { type: "number", required: false, description: "Safety cap (default: no limit)" },
+        maxConcurrency: { type: "number", required: false, description: "Parallel batch size (default: 1 = sequential)" }
+      },
+      example: {
+        id: "processOrders",
+        name: "Process each order",
+        type: "loop",
+        loop: {
+          over: "$.steps.listOrders.response.data",
+          as: "order",
+          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey", data: { amount: "$.loop.order.total" } } }]
+        }
+      }
+    },
+    {
+      type: "parallel",
+      configKey: "parallel",
+      description: "Run steps concurrently",
+      fields: {
+        steps: { type: "array", required: true, description: "Steps to run in parallel", stepsArray: true },
+        maxConcurrency: { type: "number", required: false, description: "Max concurrent steps (default: 5)" }
+      },
+      example: {
+        id: "lookups",
+        name: "Parallel data lookups",
+        type: "parallel",
+        parallel: {
+          steps: [
+            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey" } },
+            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey" } }
+          ]
+        }
+      }
+    },
+    {
+      type: "file-read",
+      configKey: "fileRead",
+      description: "Read a file (optional JSON parse)",
+      fields: {
+        path: { type: "string", required: true, description: "File path to read" },
+        parseJson: { type: "boolean", required: false, description: "Parse contents as JSON (default: false)" }
+      },
+      example: {
+        id: "readConfig",
+        name: "Read config file",
+        type: "file-read",
+        fileRead: { path: "./data/config.json", parseJson: true }
+      }
+    },
+    {
+      type: "file-write",
+      configKey: "fileWrite",
+      description: "Write or append to a file",
+      fields: {
+        path: { type: "string", required: true, description: "File path to write" },
+        content: { type: "unknown", required: true, description: "Content to write (supports selectors)" },
+        append: { type: "boolean", required: false, description: "Append instead of overwrite (default: false)" }
+      },
+      example: {
+        id: "writeResults",
+        name: "Save results",
+        type: "file-write",
+        fileWrite: { path: "./output/results.json", content: "$.steps.transform.output" }
+      }
+    },
+    {
+      type: "while",
+      configKey: "while",
+      description: "Do-while loop with condition check",
+      fields: {
+        condition: { type: "string", required: true, description: "JS expression checked before each iteration (after first)" },
+        steps: { type: "array", required: true, description: "Steps to run each iteration", stepsArray: true },
+        maxIterations: { type: "number", required: false, description: "Safety cap (default: 100)" }
+      },
+      example: {
+        id: "paginate",
+        name: "Paginate through pages",
+        type: "while",
+        while: {
+          condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
+          maxIterations: 50,
+          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey" } }]
+        }
+      }
+    },
+    {
+      type: "flow",
+      configKey: "flow",
+      description: "Execute a sub-flow (supports composition)",
+      fields: {
+        key: { type: "string", required: true, description: "Flow key or path of the sub-flow" },
+        inputs: { type: "object", required: false, description: "Inputs to pass to the sub-flow (supports selectors)" }
+      },
+      example: {
+        id: "enrich",
+        name: "Run enrichment sub-flow",
+        type: "flow",
+        flow: { key: "enrich-customer", inputs: { email: "$.steps.getCustomer.response.email" } }
+      }
+    },
+    {
+      type: "paginate",
+      configKey: "paginate",
+      description: "Auto-paginate API results into a single array",
+      fields: {
+        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, connectionKey)" },
+        pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
+        resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
+        inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
+        maxPages: { type: "number", required: false, description: "Max pages to fetch (default: 10)" }
+      },
+      example: {
+        id: "allMessages",
+        name: "Fetch all Gmail messages",
+        type: "paginate",
+        paginate: {
+          action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey", queryParams: { maxResults: 100 } },
+          pageTokenField: "nextPageToken",
+          resultsField: "messages",
+          inputTokenParam: "queryParams.pageToken",
+          maxPages: 10
+        }
+      }
+    },
+    {
+      type: "bash",
+      configKey: "bash",
+      description: "Shell command (requires --allow-bash)",
+      fields: {
+        command: { type: "string", required: true, description: "Shell command to execute (supports selectors)" },
+        timeout: { type: "number", required: false, description: "Timeout in ms (default: 30000)" },
+        parseJson: { type: "boolean", required: false, description: "Parse stdout as JSON (default: false)" },
+        cwd: { type: "string", required: false, description: "Working directory (supports selectors)" },
+        env: { type: "object", required: false, description: "Additional environment variables" }
+      },
+      example: {
+        id: "analyze",
+        name: "Analyze with Claude",
+        type: "bash",
+        bash: {
+          command: "cat /tmp/data.json | claude --print 'Analyze this data' --output-format json",
+          timeout: 18e4,
+          parseJson: true
+        }
+      }
+    }
+  ]
+};
+var _coveredTypes = Object.fromEntries(
+  FLOW_SCHEMA.stepTypes.map((st) => [st.type, true])
+);
+var _stepTypeMap = new Map(
+  FLOW_SCHEMA.stepTypes.map((st) => [st.type, st])
+);
+function getStepTypeDescriptor(type) {
+  return _stepTypeMap.get(type);
+}
+function getValidStepTypes() {
+  return FLOW_SCHEMA.stepTypes.map((st) => st.type);
+}
+function getNestedStepsKeys() {
+  const result = [];
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    for (const [fieldName, fd] of Object.entries(st.fields)) {
+      if (fd.stepsArray) {
+        result.push({ configKey: st.configKey, fieldName });
+      }
+    }
+  }
+  return result;
+}
+function generateFlowGuide() {
+  const validTypes = getValidStepTypes();
+  const sections = [];
+  sections.push(`# One Flows \u2014 Reference
+
+## Overview
+
+Workflows are JSON files at \`.one/flows/<key>.flow.json\` that chain actions across platforms.
+
+## Commands
+
+\`\`\`bash
+one --agent flow create <key> --definition '<json>'   # Create (or --definition @file.json)
+one --agent flow create <key> --definition @flow.json  # Create from file
+one --agent flow list                                  # List
+one --agent flow validate <key>                        # Validate
+one --agent flow execute <key> -i name=value           # Execute
+one --agent flow execute <key> --dry-run --mock        # Test with mock data
+one --agent flow execute <key> --allow-bash            # Enable bash steps
+one --agent flow runs [flowKey]                        # List past runs
+one --agent flow resume <runId>                        # Resume failed run
+one --agent flow scaffold [template]                   # Generate a starter template
+\`\`\`
+
+You can also write the JSON file directly to \`.one/flows/<key>.flow.json\` \u2014 this is often easier than passing large JSON via --definition.
+
+## Building a Workflow
+
+1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
+2. **Discover connections** \u2014 \`one --agent connection list\`
+3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
+4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
+5. **Validate** \u2014 \`one --agent flow validate <key>\`
+6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\``);
+  sections.push(`## Flow JSON Schema
+
+\`\`\`json
+{
+  "key": "my-workflow",
+  "name": "My Workflow",
+  "description": "What this flow does",
+  "version": "1",
+  "inputs": {
+    "connectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Platform connection key",
+      "connection": { "platform": "stripe" }
+    },
+    "param": {
+      "type": "string",
+      "required": true,
+      "description": "A user parameter"
+    }
+  },
+  "steps": [
+    {
+      "id": "stepId",
+      "name": "Human-readable step name",
+      "type": "action",
+      "action": {
+        "platform": "stripe",
+        "actionId": "conn_mod_def::xxx::yyy",
+        "connectionKey": "$.input.connectionKey",
+        "data": { "query": "{{$.input.param}}" }
+      }
+    }
+  ]
+}
+\`\`\`
+
+### Top-level fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.flowFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
+  }
+  sections.push(`
+### Input declarations
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.inputFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
+  }
+  sections.push(`
+### Step fields (all steps)
+
+Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines which config object is required.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+  for (const [name, fd] of Object.entries(FLOW_SCHEMA.stepCommonFields)) {
+    sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
+  }
+  sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(" | ")}", "retries": 3, "retryDelayMs": 1000 }\` |`);
+  sections.push(`
+## Step Types
+
+**IMPORTANT:** Each step type requires a config object nested under a specific key. The type name and config key differ for some types (noted below).
+
+| Type | Config Key | Description |
+|------|-----------|-------------|`);
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    const keyNote = st.type !== st.configKey ? ` \u26A0\uFE0F` : "";
+    sections.push(`| \`${st.type}\` | \`${st.configKey}\`${keyNote} | ${st.description} |`);
+  }
+  sections.push(`
+## Step Type Reference`);
+  for (const st of FLOW_SCHEMA.stepTypes) {
+    sections.push(`
+### \`${st.type}\` \u2014 ${st.description}`);
+    if (st.type !== st.configKey) {
+      sections.push(`
+> **Note:** Type is \`"${st.type}"\` but config key is \`"${st.configKey}"\` (camelCase).`);
+    }
+    sections.push(`
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|`);
+    for (const [name, fd] of Object.entries(st.fields)) {
+      sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? "yes" : "no"} | ${fd.description} |`);
+    }
+    sections.push(`
+\`\`\`json
+${JSON.stringify(st.example, null, 2)}
+\`\`\``);
+  }
+  sections.push(`
+## Selectors
+
+| Pattern | Resolves To |
+|---------|-------------|
+| \`$.input.paramName\` | Input value |
+| \`$.steps.stepId.response\` | Full API response |
+| \`$.steps.stepId.response.data[0].email\` | Nested field |
+| \`$.steps.stepId.response.data[*].id\` | Wildcard array map |
+| \`$.env.MY_VAR\` | Environment variable |
+| \`$.loop.item\` / \`$.loop.i\` | Loop iteration |
+| \`"Hello {{$.steps.getUser.response.name}}"\` | String interpolation |
+
+### When to use bare selectors vs \`{{...}}\` interpolation
+
+- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
+- **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
+- **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
+
+### \`output\` vs \`response\` on step results
+
+Every completed step produces both \`output\` and \`response\`:
+- **Action steps**: \`response\` is the raw API response. \`output\` is the same as \`response\`.
+- **Code/transform steps**: \`output\` is the return value. \`response\` is an alias for \`output\`.
+- **In practice**: Use \`$.steps.stepId.response\` for action steps (API data) and \`$.steps.stepId.output\` for code/transform steps (computed data). Both work interchangeably, but using the semantically correct one makes flows easier to read.
+
+## Error Handling
+
+\`\`\`json
+{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
+\`\`\`
+
+Strategies: \`${FLOW_SCHEMA.errorStrategies.join("`, `")}\`
+
+Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
+
+## Input Connection Auto-Resolution
+
+When an input has \`"connection": { "platform": "stripe" }\`, the flow engine can automatically resolve the connection key at execution time. If the user has exactly one connection for that platform, the engine fills in the key without requiring \`-i connectionKey=...\`. If multiple connections exist, the user must specify which one. This is metadata for tooling \u2014 it does not affect the flow JSON structure, but it makes execution more convenient.
+
+## Complete Example: Fetch Data, Transform, Notify
+
+\`\`\`json
+{
+  "key": "contacts-to-slack",
+  "name": "CRM Contacts Summary to Slack",
+  "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
+  "version": "1",
+  "inputs": {
+    "crmConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "CRM platform connection key",
+      "connection": { "platform": "attio" }
+    },
+    "slackConnectionKey": {
+      "type": "string",
+      "required": true,
+      "description": "Slack connection key",
+      "connection": { "platform": "slack" }
+    },
+    "slackChannel": {
+      "type": "string",
+      "required": true,
+      "description": "Slack channel name or ID"
+    }
+  },
+  "steps": [
+    {
+      "id": "fetchContacts",
+      "name": "Fetch recent contacts",
+      "type": "action",
+      "action": {
+        "platform": "attio",
+        "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
+        "connectionKey": "$.input.crmConnectionKey",
+        "queryParams": { "limit": "10" }
+      }
+    },
+    {
+      "id": "buildSummary",
+      "name": "Build formatted summary",
+      "type": "code",
+      "code": {
+        "source": "const contacts = $.steps.fetchContacts.response.data || [];\\nconst lines = contacts.map((c, i) => \`\${i+1}. \${c.name || 'Unknown'} \u2014 \${c.email || 'no email'}\`);\\nreturn { summary: \`Found \${contacts.length} contacts:\\n\${lines.join('\\n')}\` };"
+      }
+    },
+    {
+      "id": "notifySlack",
+      "name": "Post summary to Slack",
+      "type": "action",
+      "action": {
+        "platform": "slack",
+        "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
+        "connectionKey": "$.input.slackConnectionKey",
+        "data": {
+          "channel": "$.input.slackChannel",
+          "text": "{{$.steps.buildSummary.output.summary}}"
+        }
+      }
     }
-  } catch (error2) {
-    spinner5.stop("Execution failed");
-    error(
-      `Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`
-    );
-  }
-}
-function colorMethod(method) {
-  switch (method.toUpperCase()) {
-    case "GET":
-      return pc6.green(method);
-    case "POST":
-      return pc6.yellow(method);
-    case "PUT":
-      return pc6.blue(method);
-    case "PATCH":
-      return pc6.magenta(method);
-    case "DELETE":
-      return pc6.red(method);
-    default:
-      return method;
-  }
+  ]
 }
+\`\`\`
 
-// src/commands/flow.ts
-import pc7 from "picocolors";
+Note: Action IDs above are placeholders. Always use \`one --agent actions search <platform> "<query>"\` to find real IDs.
+
+## AI-Augmented Pattern
+
+For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
+
+1. \`file-write\` \u2014 save data to temp file
+2. \`bash\` \u2014 \`claude --print\` analyzes it (\`parseJson: true\`, \`timeout: 180000\`)
+3. \`code\` \u2014 parse and structure the output
+
+Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
+
+## Notes
+
+- Connection keys are **inputs**, not hardcoded
+- Action IDs in examples are placeholders \u2014 always use \`actions search\`
+- Code steps allow \`crypto\`, \`buffer\`, \`url\`, \`path\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
+- Bash steps require \`--allow-bash\` flag
+- State is persisted after every step \u2014 resume picks up where it left off`);
+  return sections.join("\n");
+}
 
 // src/lib/flow-validator.ts
-var VALID_STEP_TYPES = [
-  "action",
-  "transform",
-  "code",
-  "condition",
-  "loop",
-  "parallel",
-  "file-read",
-  "file-write",
-  "while",
-  "flow",
-  "paginate",
-  "bash"
-];
-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") {
@@ -1740,7 +2276,7 @@ function validateFlowSchema(flow2) {
   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) {
+  } else if (FLOW_SCHEMA.flowFields.key.pattern && !FLOW_SCHEMA.flowFields.key.pattern.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") {
@@ -1763,8 +2299,8 @@ function validateFlowSchema(flow2) {
         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.type || !FLOW_SCHEMA.validInputTypes.includes(d.type)) {
+        errors.push({ path: `${prefix}.type`, message: `Input type must be one of: ${FLOW_SCHEMA.validInputTypes.join(", ")}` });
       }
       if (d.connection !== void 0) {
         if (!d.connection || typeof d.connection !== "object") {
@@ -1786,6 +2322,7 @@ function validateFlowSchema(flow2) {
   return errors;
 }
 function validateStepsArray(steps, pathPrefix, errors) {
+  const validTypes = FLOW_SCHEMA.stepTypes.map((st) => st.type);
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
     const path4 = `${pathPrefix}[${i}]`;
@@ -1800,189 +2337,79 @@ function validateStepsArray(steps, pathPrefix, errors) {
     if (!s.name || typeof s.name !== "string") {
       errors.push({ path: `${path4}.name`, message: 'Step must have a string "name"' });
     }
-    if (!s.type || !VALID_STEP_TYPES.includes(s.type)) {
-      errors.push({ path: `${path4}.type`, message: `Step type must be one of: ${VALID_STEP_TYPES.join(", ")}` });
+    if (!s.type || !validTypes.includes(s.type)) {
+      errors.push({ path: `${path4}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
+      continue;
     }
     if (s.onError && typeof s.onError === "object") {
       const oe = s.onError;
-      if (!VALID_ERROR_STRATEGIES.includes(oe.strategy)) {
-        errors.push({ path: `${path4}.onError.strategy`, message: `Error strategy must be one of: ${VALID_ERROR_STRATEGIES.join(", ")}` });
+      if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy)) {
+        errors.push({ path: `${path4}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(", ")}` });
       }
     }
-    const type = s.type;
-    if (type === "action") {
-      if (!s.action || typeof s.action !== "object") {
-        errors.push({ path: `${path4}.action`, message: 'Action step must have an "action" config object' });
-      } else {
-        const a = s.action;
-        if (!a.platform) errors.push({ path: `${path4}.action.platform`, message: 'Action must have "platform"' });
-        if (!a.actionId) errors.push({ path: `${path4}.action.actionId`, message: 'Action must have "actionId"' });
-        if (!a.connectionKey) errors.push({ path: `${path4}.action.connectionKey`, message: 'Action must have "connectionKey"' });
-      }
-    } else if (type === "transform") {
-      if (!s.transform || typeof s.transform !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.transform.expression`, message: 'Transform must have a string "expression"' });
-        }
-      }
-    } else if (type === "code") {
-      if (!s.code || typeof s.code !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.code.source`, message: 'Code must have a string "source"' });
-        }
-      }
-    } else if (type === "condition") {
-      if (!s.condition || typeof s.condition !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.condition.expression`, message: 'Condition must have a string "expression"' });
-        }
-        if (!Array.isArray(c.then)) {
-          errors.push({ path: `${path4}.condition.then`, message: 'Condition must have a "then" steps array' });
-        } else {
-          validateStepsArray(c.then, `${path4}.condition.then`, errors);
-        }
-        if (c.else !== void 0) {
-          if (!Array.isArray(c.else)) {
-            errors.push({ path: `${path4}.condition.else`, message: 'Condition "else" must be a steps array' });
-          } else {
-            validateStepsArray(c.else, `${path4}.condition.else`, errors);
-          }
-        }
-      }
-    } else if (type === "loop") {
-      if (!s.loop || typeof s.loop !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.loop.over`, message: 'Loop must have a string "over" selector' });
-        }
-        if (!l.as || typeof l.as !== "string") {
-          errors.push({ path: `${path4}.loop.as`, message: 'Loop must have a string "as" variable name' });
-        }
-        if (!Array.isArray(l.steps)) {
-          errors.push({ path: `${path4}.loop.steps`, message: 'Loop must have a "steps" array' });
-        } else {
-          validateStepsArray(l.steps, `${path4}.loop.steps`, errors);
-        }
-      }
-    } else if (type === "parallel") {
-      if (!s.parallel || typeof s.parallel !== "object") {
-        errors.push({ path: `${path4}.parallel`, message: 'Parallel step must have a "parallel" config object' });
-      } else {
-        const par = s.parallel;
-        if (!Array.isArray(par.steps)) {
-          errors.push({ path: `${path4}.parallel.steps`, message: 'Parallel must have a "steps" array' });
-        } else {
-          validateStepsArray(par.steps, `${path4}.parallel.steps`, errors);
-        }
-      }
-    } else if (type === "file-read") {
-      if (!s.fileRead || typeof s.fileRead !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.fileRead.path`, message: 'File-read must have a string "path"' });
-        }
+    const descriptor = getStepTypeDescriptor(s.type);
+    if (!descriptor) continue;
+    const configKey = descriptor.configKey;
+    const configObj = s[configKey];
+    if (!configObj || typeof configObj !== "object") {
+      const hint = detectFlatConfigHint(s, descriptor);
+      errors.push({
+        path: `${path4}.${configKey}`,
+        message: `${capitalize(descriptor.type)} step must have a "${configKey}" config object${hint}`
+      });
+      continue;
+    }
+    const config = configObj;
+    for (const [fieldName, fd] of Object.entries(descriptor.fields)) {
+      const fieldPath = `${path4}.${configKey}.${fieldName}`;
+      const value = config[fieldName];
+      if (fd.required && (value === void 0 || value === null || value === "")) {
+        errors.push({ path: fieldPath, message: `${capitalize(descriptor.type)} must have ${fd.type === "string" ? "a string" : fd.type === "array" ? "a" : "a"} "${fieldName}"` });
+        continue;
       }
-    } else if (type === "file-write") {
-      if (!s.fileWrite || typeof s.fileWrite !== "object") {
-        errors.push({ path: `${path4}.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: `${path4}.fileWrite.path`, message: 'File-write must have a string "path"' });
-        }
-        if (fw.content === void 0) {
-          errors.push({ path: `${path4}.fileWrite.content`, message: 'File-write must have "content"' });
-        }
+      if (value === void 0) continue;
+      if (fd.type === "string" && fd.required && typeof value !== "string") {
+        errors.push({ path: fieldPath, message: `"${fieldName}" must be a string` });
       }
-    } else if (type === "while") {
-      if (!s.while || typeof s.while !== "object") {
-        errors.push({ path: `${path4}.while`, message: 'While step must have a "while" config object' });
-      } else {
-        const w = s.while;
-        if (!w.condition || typeof w.condition !== "string") {
-          errors.push({ path: `${path4}.while.condition`, message: 'While must have a string "condition"' });
-        }
-        if (!Array.isArray(w.steps)) {
-          errors.push({ path: `${path4}.while.steps`, message: 'While must have a "steps" array' });
-        } else {
-          validateStepsArray(w.steps, `${path4}.while.steps`, errors);
-        }
-        if (w.maxIterations !== void 0 && (typeof w.maxIterations !== "number" || w.maxIterations <= 0)) {
-          errors.push({ path: `${path4}.while.maxIterations`, message: "maxIterations must be a positive number" });
-        }
+      if (fd.type === "number" && value !== void 0 && (typeof value !== "number" || value <= 0)) {
+        errors.push({ path: fieldPath, message: `${fieldName} must be a positive number` });
       }
-    } else if (type === "flow") {
-      if (!s.flow || typeof s.flow !== "object") {
-        errors.push({ path: `${path4}.flow`, message: 'Flow step must have a "flow" config object' });
-      } else {
-        const f = s.flow;
-        if (!f.key || typeof f.key !== "string") {
-          errors.push({ path: `${path4}.flow.key`, message: 'Flow must have a string "key"' });
-        }
-        if (f.inputs !== void 0 && (typeof f.inputs !== "object" || Array.isArray(f.inputs))) {
-          errors.push({ path: `${path4}.flow.inputs`, message: "Flow inputs must be an object" });
-        }
+      if (fd.type === "boolean" && value !== void 0 && typeof value !== "boolean") {
+        errors.push({ path: fieldPath, message: `${fieldName} must be a boolean` });
       }
-    } else if (type === "paginate") {
-      if (!s.paginate || typeof s.paginate !== "object") {
-        errors.push({ path: `${path4}.paginate`, message: 'Paginate step must have a "paginate" config object' });
-      } else {
-        const p7 = s.paginate;
-        if (!p7.action || typeof p7.action !== "object") {
-          errors.push({ path: `${path4}.paginate.action`, message: 'Paginate must have an "action" config object' });
+      if (fd.stepsArray) {
+        if (!Array.isArray(value)) {
+          errors.push({ path: fieldPath, message: `"${fieldName}" must be a steps array` });
         } else {
-          const a = p7.action;
-          if (!a.platform) errors.push({ path: `${path4}.paginate.action.platform`, message: 'Action must have "platform"' });
-          if (!a.actionId) errors.push({ path: `${path4}.paginate.action.actionId`, message: 'Action must have "actionId"' });
-          if (!a.connectionKey) errors.push({ path: `${path4}.paginate.action.connectionKey`, message: 'Action must have "connectionKey"' });
-        }
-        if (!p7.pageTokenField || typeof p7.pageTokenField !== "string") {
-          errors.push({ path: `${path4}.paginate.pageTokenField`, message: 'Paginate must have a string "pageTokenField"' });
-        }
-        if (!p7.resultsField || typeof p7.resultsField !== "string") {
-          errors.push({ path: `${path4}.paginate.resultsField`, message: 'Paginate must have a string "resultsField"' });
-        }
-        if (!p7.inputTokenParam || typeof p7.inputTokenParam !== "string") {
-          errors.push({ path: `${path4}.paginate.inputTokenParam`, message: 'Paginate must have a string "inputTokenParam"' });
-        }
-        if (p7.maxPages !== void 0 && (typeof p7.maxPages !== "number" || p7.maxPages <= 0)) {
-          errors.push({ path: `${path4}.paginate.maxPages`, message: "maxPages must be a positive number" });
+          validateStepsArray(value, fieldPath, errors);
         }
       }
-    } else if (type === "bash") {
-      if (!s.bash || typeof s.bash !== "object") {
-        errors.push({ path: `${path4}.bash`, message: 'Bash step must have a "bash" config object' });
-      } else {
-        const b = s.bash;
-        if (!b.command || typeof b.command !== "string") {
-          errors.push({ path: `${path4}.bash.command`, message: 'Bash must have a string "command"' });
-        }
-        if (b.timeout !== void 0 && (typeof b.timeout !== "number" || b.timeout <= 0)) {
-          errors.push({ path: `${path4}.bash.timeout`, message: "timeout must be a positive number" });
-        }
-        if (b.parseJson !== void 0 && typeof b.parseJson !== "boolean") {
-          errors.push({ path: `${path4}.bash.parseJson`, message: "parseJson must be a boolean" });
+      if (descriptor.type === "paginate" && fieldName === "action") {
+        if (typeof value === "object" && value !== null) {
+          const a = value;
+          if (!a.platform) errors.push({ path: `${fieldPath}.platform`, message: 'Action must have "platform"' });
+          if (!a.actionId) errors.push({ path: `${fieldPath}.actionId`, message: 'Action must have "actionId"' });
+          if (!a.connectionKey) errors.push({ path: `${fieldPath}.connectionKey`, message: 'Action must have "connectionKey"' });
         }
       }
     }
   }
 }
+function detectFlatConfigHint(step, descriptor) {
+  const requiredFields = Object.entries(descriptor.fields).filter(([, fd]) => fd.required).map(([name]) => name);
+  const flatFields = requiredFields.filter((f) => f in step);
+  if (flatFields.length > 0) {
+    return `. Hint: "${flatFields.join('", "')}" must be nested inside "${descriptor.configKey}": { ... }, not placed directly on the step`;
+  }
+  return "";
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 function validateStepIds(flow2) {
   const errors = [];
   const seen = /* @__PURE__ */ new Set();
+  const nestedKeys = getNestedStepsKeys();
   function collectIds(steps, pathPrefix) {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
@@ -1992,13 +2419,12 @@ function validateStepIds(flow2) {
       } else {
         seen.add(step.id);
       }
-      if (step.condition) {
-        if (step.condition.then) collectIds(step.condition.then, `${path4}.condition.then`);
-        if (step.condition.else) collectIds(step.condition.else, `${path4}.condition.else`);
+      for (const { configKey, fieldName } of nestedKeys) {
+        const config = step[configKey];
+        if (config && Array.isArray(config[fieldName])) {
+          collectIds(config[fieldName], `${path4}.${configKey}.${fieldName}`);
+        }
       }
-      if (step.loop?.steps) collectIds(step.loop.steps, `${path4}.loop.steps`);
-      if (step.parallel?.steps) collectIds(step.parallel.steps, `${path4}.parallel.steps`);
-      if (step.while?.steps) collectIds(step.while.steps, `${path4}.while.steps`);
     }
   }
   collectIds(flow2.steps, "steps");
@@ -2007,25 +2433,17 @@ function validateStepIds(flow2) {
 function validateSelectorReferences(flow2) {
   const errors = [];
   const inputNames = new Set(Object.keys(flow2.inputs));
+  const nestedKeys = getNestedStepsKeys();
   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);
+      for (const { configKey, fieldName } of nestedKeys) {
+        const config = step[configKey];
+        if (config && Array.isArray(config[fieldName])) {
+          for (const id of getAllStepIds(config[fieldName])) 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);
-      }
-      if (step.while?.steps) {
-        for (const id of getAllStepIds(step.while.steps)) ids.add(id);
-      }
     }
     return ids;
   }
@@ -2072,49 +2490,29 @@ function validateSelectorReferences(flow2) {
   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`);
-    }
-    if (step.while) {
-      step.while.steps.forEach((s, i) => checkStep(s, `${pathPrefix}.while.steps[${i}]`));
-    }
-    if (step.flow) {
-      checkSelectors(extractSelectors(step.flow.key), `${pathPrefix}.flow.key`);
-      if (step.flow.inputs) {
-        checkSelectors(extractSelectors(step.flow.inputs), `${pathPrefix}.flow.inputs`);
-      }
-    }
-    if (step.paginate) {
-      checkSelectors(extractSelectors(step.paginate.action), `${pathPrefix}.paginate.action`);
-    }
-    if (step.bash) {
-      checkSelectors(extractSelectors(step.bash.command), `${pathPrefix}.bash.command`);
-      if (step.bash.cwd) {
-        checkSelectors(extractSelectors(step.bash.cwd), `${pathPrefix}.bash.cwd`);
+    const descriptor = getStepTypeDescriptor(step.type);
+    if (descriptor) {
+      const config = step[descriptor.configKey];
+      if (config && typeof config === "object") {
+        if (step.type !== "transform" && step.type !== "code") {
+          for (const [fieldName, fd] of Object.entries(descriptor.fields)) {
+            if (fd.stepsArray) continue;
+            const value = config[fieldName];
+            if (value !== void 0) {
+              checkSelectors(extractSelectors(value), `${pathPrefix}.${descriptor.configKey}.${fieldName}`);
+            }
+          }
+        }
       }
-      if (step.bash.env) {
-        checkSelectors(extractSelectors(step.bash.env), `${pathPrefix}.bash.env`);
+      for (const { configKey, fieldName } of nestedKeys) {
+        if (configKey === descriptor.configKey) {
+          const c = step[configKey];
+          if (c && Array.isArray(c[fieldName])) {
+            c[fieldName].forEach(
+              (s, i) => checkStep(s, `${pathPrefix}.${configKey}.${fieldName}[${i}]`)
+            );
+          }
+        }
       }
     }
   }
@@ -2132,7 +2530,7 @@ function validateFlow(flow2) {
 }
 
 // src/commands/flow.ts
-import fs3 from "fs";
+import fs4 from "fs";
 function getConfig2() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -2186,10 +2584,19 @@ async function flowCreateCommand(key, options) {
   intro2(pc7.bgCyan(pc7.black(" One Workflow ")));
   let flow2;
   if (options.definition) {
+    let raw = options.definition;
+    if (raw.startsWith("@")) {
+      const filePath = raw.slice(1);
+      try {
+        raw = fs4.readFileSync(filePath, "utf-8");
+      } catch (err) {
+        error(`Cannot read file "${filePath}": ${err.message}`);
+      }
+    }
     try {
-      flow2 = JSON.parse(options.definition);
+      flow2 = JSON.parse(raw);
     } catch {
-      error("Invalid JSON in --definition");
+      error("Invalid JSON in --definition. If your JSON contains special characters (like :: in action IDs), try --definition @file.json instead.");
     }
   } else if (!process.stdin.isTTY) {
     const chunks = [];
@@ -2364,7 +2771,7 @@ async function flowValidateCommand(keyOrPath) {
   let flowData;
   try {
     const flowPath = resolveFlowPath(keyOrPath);
-    const content = fs3.readFileSync(flowPath, "utf-8");
+    const content = fs4.readFileSync(flowPath, "utf-8");
     flowData = JSON.parse(content);
   } catch (err) {
     spinner5.stop("Validation failed");
@@ -2496,6 +2903,205 @@ function colorStatus(status) {
       return status;
   }
 }
+var SCAFFOLD_TEMPLATES = {
+  basic: () => ({
+    key: "my-workflow",
+    name: "My Workflow",
+    description: "A basic workflow with a single action step",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key for the platform",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "step1",
+        name: "Execute action",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey",
+          data: {}
+        }
+      }
+    ]
+  }),
+  conditional: () => ({
+    key: "my-conditional-workflow",
+    name: "Conditional Workflow",
+    description: "Fetch data, then branch based on results",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetch",
+        name: "Fetch data",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "decide",
+        name: "Check results",
+        type: "condition",
+        condition: {
+          expression: "$.steps.fetch.response.data && $.steps.fetch.response.data.length > 0",
+          then: [
+            {
+              id: "handleFound",
+              name: "Handle found",
+              type: "transform",
+              transform: { expression: "$.steps.fetch.response.data[0]" }
+            }
+          ],
+          else: [
+            {
+              id: "handleNotFound",
+              name: "Handle not found",
+              type: "transform",
+              transform: { expression: "({ error: 'No results found' })" }
+            }
+          ]
+        }
+      }
+    ]
+  }),
+  loop: () => ({
+    key: "my-loop-workflow",
+    name: "Loop Workflow",
+    description: "Fetch a list, then process each item",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetchList",
+        name: "Fetch items",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "processItems",
+        name: "Process each item",
+        type: "loop",
+        loop: {
+          over: "$.steps.fetchList.response.data",
+          as: "item",
+          steps: [
+            {
+              id: "processItem",
+              name: "Process single item",
+              type: "transform",
+              transform: { expression: "({ id: $.loop.item.id, processed: true })" }
+            }
+          ]
+        }
+      },
+      {
+        id: "summary",
+        name: "Generate summary",
+        type: "transform",
+        transform: { expression: "({ total: $.steps.fetchList.response.data.length })" }
+      }
+    ]
+  }),
+  ai: () => ({
+    key: "my-ai-workflow",
+    name: "AI Analysis Workflow",
+    description: "Fetch data, analyze with Claude, and send results",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key for data source",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetchData",
+        name: "Fetch raw data",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "writeData",
+        name: "Write data for analysis",
+        type: "file-write",
+        fileWrite: {
+          path: "/tmp/workflow-data.json",
+          content: "$.steps.fetchData.response"
+        }
+      },
+      {
+        id: "analyze",
+        name: "Analyze with Claude",
+        type: "bash",
+        bash: {
+          command: `cat /tmp/workflow-data.json | claude --print 'Analyze this data and return JSON with: {"summary": "...", "insights": [...], "recommendations": [...]}. Return ONLY valid JSON.' --output-format json`,
+          timeout: 18e4,
+          parseJson: true
+        }
+      },
+      {
+        id: "formatResult",
+        name: "Format analysis output",
+        type: "code",
+        code: {
+          source: "const a = $.steps.analyze.output;\nreturn {\n  summary: a.summary,\n  insights: a.insights,\n  recommendations: a.recommendations\n};"
+        }
+      }
+    ]
+  })
+};
+async function flowScaffoldCommand(template) {
+  const templateName = template || "basic";
+  const templateFn = SCAFFOLD_TEMPLATES[templateName];
+  if (!templateFn) {
+    const available = Object.keys(SCAFFOLD_TEMPLATES).join(", ");
+    if (isAgentMode()) {
+      json({ error: `Unknown template "${templateName}". Available: ${available}` });
+      process.exit(1);
+    }
+    error(`Unknown template "${templateName}". Available: ${available}`);
+  }
+  const scaffold = templateFn();
+  if (isAgentMode()) {
+    json(scaffold);
+    return;
+  }
+  console.log(JSON.stringify(scaffold, null, 2));
+}
 
 // src/commands/relay.ts
 import pc8 from "picocolors";
@@ -2856,13 +3462,13 @@ one --agent <command>
 
 All commands return JSON. If an \`error\` key is present, the command failed.
 
-## IMPORTANT: Learn before you use
+## IMPORTANT: Read the guide before you act
 
-Before using any feature, you MUST read the corresponding skill documentation first. The skills are bundled with the CLI and teach you the correct workflow, required steps, template syntax, and common mistakes. Never guess \u2014 read the skill, then act.
+Before using any feature, read its guide section first: \`one guide actions\`, \`one guide flows\`, or \`one guide relay\`. The guide teaches you the correct workflow, required fields, and common mistakes. Never guess \u2014 read the guide, then act.
 
 ## Features
 
-### 1. Actions \u2014 Execute API calls on 200+ platforms
+### 1. Actions \u2014 Execute API calls on 250+ platforms
 Search for actions, read their docs, and execute them. This is the core workflow.
 
 **Quick start:**
@@ -2996,91 +3602,7 @@ All errors return JSON: \`{"error": "message"}\`. Check the \`error\` key.
 - If search returns no results, try broader queries
 - Access control settings from \`one config\` may restrict execution
 `;
-var GUIDE_FLOWS = `# One Flows \u2014 Reference
-
-## Overview
-
-Workflows are JSON files at \`.one/flows/<key>.flow.json\` that chain actions across platforms.
-
-## Commands
-
-\`\`\`bash
-one --agent flow create <key> --definition '<json>'   # Create
-one --agent flow list                                  # List
-one --agent flow validate <key>                        # Validate
-one --agent flow execute <key> -i name=value           # Execute
-one --agent flow execute <key> --dry-run --mock        # Test with mock data
-one --agent flow execute <key> --allow-bash            # Enable bash steps
-one --agent flow runs [flowKey]                        # List past runs
-one --agent flow resume <runId>                        # Resume failed run
-\`\`\`
-
-## Building a Workflow
-
-1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
-2. **Discover connections** \u2014 \`one --agent connection list\`
-3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
-4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
-5. **Validate** \u2014 \`one --agent flow validate <key>\`
-6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\`
-
-## Step Types
-
-| Type | Purpose |
-|------|---------|
-| \`action\` | Execute a platform API action |
-| \`transform\` | Single JS expression (implicit return) |
-| \`code\` | Multi-line async JS (explicit return) |
-| \`condition\` | If/then/else branching |
-| \`loop\` | Iterate over array with optional concurrency |
-| \`parallel\` | Run steps concurrently |
-| \`file-read\` | Read file (optional JSON parse) |
-| \`file-write\` | Write/append to file |
-| \`while\` | Do-while loop with condition |
-| \`flow\` | Execute a sub-flow |
-| \`paginate\` | Auto-paginate API results |
-| \`bash\` | Shell command (requires \`--allow-bash\`) |
-
-## Selectors
-
-| Pattern | Resolves To |
-|---------|-------------|
-| \`$.input.paramName\` | Input value |
-| \`$.steps.stepId.response\` | Full API response |
-| \`$.steps.stepId.response.data[0].email\` | Nested field |
-| \`$.steps.stepId.response.data[*].id\` | Wildcard array map |
-| \`$.env.MY_VAR\` | Environment variable |
-| \`$.loop.item\` / \`$.loop.i\` | Loop iteration |
-| \`"Hello {{$.steps.getUser.response.name}}"\` | String interpolation |
-
-## Error Handling
-
-\`\`\`json
-{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
-\`\`\`
-
-Strategies: \`fail\` (default), \`continue\`, \`retry\`, \`fallback\`
-
-Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
-
-## AI-Augmented Pattern
-
-For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
-
-1. \`file-write\` \u2014 save data to temp file
-2. \`bash\` \u2014 \`claude --print\` analyzes it (\`parseJson: true\`, \`timeout: 180000\`)
-3. \`code\` \u2014 parse and structure the output
-
-Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
-
-## Notes
-
-- Connection keys are **inputs**, not hardcoded
-- Action IDs in examples are placeholders \u2014 always use \`actions search\`
-- Code steps allow \`crypto\`, \`buffer\`, \`url\`, \`path\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
-- Bash steps require \`--allow-bash\` flag
-- State is persisted after every step \u2014 resume picks up where it left off
-`;
+var GUIDE_FLOWS = generateFlowGuide();
 var GUIDE_RELAY = `# One Relay \u2014 Reference
 
 ## Overview
@@ -3307,7 +3829,7 @@ function buildStep1() {
     nextCommand: "one onboard --step 2",
     message: `# One CLI \u2014 Agent Onboarding
 
-You now have access to the One CLI. It connects you to 200+ platforms
+You now have access to the One CLI. It connects you to 250+ platforms
 (Gmail, Slack, Stripe, Notion, etc.) \u2014 you'll learn the details shortly.
 
 IMPORTANT: Your only task right now is to send the message below to the
@@ -3317,7 +3839,7 @@ Do not offer demos yet. Just send this message and wait for their reply:
 ---
 
 I just got access to the One CLI \u2014 it connects me to your platforms like
-Gmail, Slack, Stripe, and 200+ others so I can work with them directly.
+Gmail, Slack, Stripe, and 250+ others so I can work with them directly.
 I'll show you what I can do in a moment.
 
 First, one quick setup step: right now only this conversation knows about
@@ -3346,7 +3868,7 @@ If they declined, skip this section.
 ## One CLI \u2014 Platform Integrations
 
 The One CLI (\`one\`) is installed and configured on this machine. It is a
-command-line tool that gives AI agents the ability to interact with 200+
+command-line tool that gives AI agents the ability to interact with 250+
 third-party platforms (Gmail, Slack, Shopify, HubSpot, Stripe, GitHub,
 Notion, Salesforce, etc.) through a single, unified interface.
 
@@ -3441,7 +3963,7 @@ function buildStep3(connections) {
 The user can connect any of these popular platforms:
 Gmail, Google Calendar, Slack, Notion, Shopify, Stripe, HubSpot, GitHub,
 Salesforce, QuickBooks, Asana, Jira, Linear, Intercom, Zendesk, Twilio,
-and 200+ more. Run \`one platforms\` for the full list.`);
+and 250+ more. Run \`one platforms\` for the full list.`);
   sections.push("## Onboarding complete!\n\nYou're all set. Use `one --agent guide` any time you need the full reference.");
   return {
     step: 3,
@@ -3472,7 +3994,7 @@ platform before you can start using actions. Suggest they run:
   one add slack
   one add <any-platform>
 
-Run \`one platforms\` to see all 200+ available platforms.`;
+Run \`one platforms\` to see all 250+ available platforms.`;
   }
   const header = `## Current State
 
@@ -3532,20 +4054,23 @@ function buildWorkflowIdeas(connections) {
 
 // src/commands/update.ts
 import { createRequire } from "module";
-import { spawn as spawn2 } from "child_process";
+import { spawn } from "child_process";
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 var require2 = createRequire(import.meta.url);
 var { version: currentVersion } = require2("../package.json");
 var CACHE_PATH = join(homedir(), ".one", "update-check.json");
-var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-async function fetchLatestVersion() {
+var CHECK_INTERVAL_MS = 4 * 60 * 60 * 1e3;
+var AGE_GATE_MS = 30 * 60 * 1e3;
+async function fetchLatestVersionInfo() {
   try {
-    const res = await fetch("https://registry.npmjs.org/@withone/cli/latest");
+    const res = await fetch("https://registry.npmjs.org/@withone/cli");
     if (!res.ok) return null;
     const data = await res.json();
-    return data.version;
+    const latest = data["dist-tags"]?.latest;
+    if (!latest) return null;
+    return { version: latest, publishedAt: data.time?.[latest] ?? null };
   } catch {
     return null;
   }
@@ -3557,24 +4082,26 @@ function readCache() {
     return null;
   }
 }
-function writeCache(latestVersion) {
+function writeCache(latestVersion, publishedAt) {
   try {
     mkdirSync(join(homedir(), ".one"), { recursive: true });
-    writeFileSync(CACHE_PATH, JSON.stringify({ lastCheck: Date.now(), latestVersion }));
+    writeFileSync(CACHE_PATH, JSON.stringify({ lastCheck: Date.now(), latestVersion, publishedAt }));
   } catch {
   }
 }
 async function checkLatestVersion() {
-  const version2 = await fetchLatestVersion();
-  if (version2) writeCache(version2);
-  return version2;
+  const info = await fetchLatestVersionInfo();
+  if (info) writeCache(info.version, info.publishedAt);
+  return info?.version ?? null;
 }
 async function checkLatestVersionCached() {
   const cache = readCache();
   if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
-    return cache.latestVersion;
+    return { version: cache.latestVersion, publishedAt: cache.publishedAt ?? null };
   }
-  return checkLatestVersion();
+  const info = await fetchLatestVersionInfo();
+  if (info) writeCache(info.version, info.publishedAt);
+  return info;
 }
 function getCurrentVersion() {
   return currentVersion;
@@ -3599,7 +4126,7 @@ async function updateCommand() {
   s.stop(`Update available: v${currentVersion} \u2192 v${latestVersion}`);
   console.log(`Updating @withone/cli: v${currentVersion} \u2192 v${latestVersion}...`);
   const code = await new Promise((resolve) => {
-    const child = spawn2("npm", ["install", "-g", "@withone/cli@latest", "--force"], {
+    const child = spawn("npm", ["install", "-g", "@withone/cli@latest", "--force"], {
       stdio: isAgentMode() ? "pipe" : "inherit",
       shell: true
     });
@@ -3616,12 +4143,24 @@ async function updateCommand() {
     error("Update failed \u2014 try running: npm install -g @withone/cli@latest");
   }
 }
+function autoUpdate(targetVersion, publishedAt) {
+  if (publishedAt) {
+    const age = Date.now() - new Date(publishedAt).getTime();
+    if (age < AGE_GATE_MS) return;
+  }
+  const child = spawn("npm", ["install", "-g", `@withone/cli@${targetVersion}`], {
+    detached: true,
+    stdio: "ignore",
+    shell: true
+  });
+  child.unref();
+}
 
 // src/index.ts
 var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
 var program = new Command();
-program.name("one").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`One CLI \u2014 Connect AI agents to 200+ platforms through one interface.
+program.name("one").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`One CLI \u2014 Connect AI agents to 250+ platforms through one interface.
 
   Setup:
     one init                              Set up API key and install MCP server
@@ -3665,7 +4204,7 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
         -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 'one platforms' to browse all 200+ available platforms.`).version(version);
+  Run 'one platforms' to browse all 250+ available platforms.`).version(version);
 var updateCheckPromise;
 program.hook("preAction", (thisCommand) => {
   const opts = program.opts();
@@ -3679,18 +4218,11 @@ program.hook("preAction", (thisCommand) => {
 });
 program.hook("postAction", async () => {
   if (!updateCheckPromise) return;
-  const latestVersion = await updateCheckPromise;
-  if (!latestVersion) return;
+  const info = await updateCheckPromise;
+  if (!info) return;
   const current = getCurrentVersion();
-  if (current === latestVersion) return;
-  if (isAgentMode()) {
-    process.stderr.write(`
-Update available: v${current} \u2192 v${latestVersion}. Run "one update" to upgrade.
-`);
-  } else {
-    console.log(`
-\x1B[33mUpdate available: v${current} \u2192 v${latestVersion}. Run \x1B[1mone update\x1B[22m to upgrade.\x1B[0m`);
-  }
+  if (current === info.version) return;
+  autoUpdate(info.version, info.publishedAt);
 });
 program.command("init").description("Set up One 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);
@@ -3745,6 +4277,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("scaffold [template]").description("Generate a workflow scaffold (templates: basic, conditional, loop, ai)").action(async (template) => {
+  await flowScaffoldCommand(template);
+});
 var relay = program.command("relay").alias("r").description("Receive webhooks from platforms and relay them via passthrough actions");
 relay.command("create").description("Create a new relay endpoint for a connection").requiredOption("--connection-key <key>", "Connection key for the source platform").option("--description <desc>", "Description of the relay endpoint").option("--event-filters <json>", `JSON array of event types to filter (e.g. '["customer.created"]')`).option("--tags <json>", "JSON array of tags").option("--create-webhook", "Automatically register the webhook with the source platform").action(async (options) => {
   await relayCreateCommand(options);