@withone/cli 1.14.1 → 1.16.0

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   loadFlow,
   resolveFlowPath,
   saveFlow
-} from "./chunk-GEQRZGKM.js";
+} from "./chunk-SX2Y4HDW.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -1316,7 +1316,9 @@ async function connectionListCommand(options) {
         connections: limited.map((conn) => ({
           platform: conn.platform,
           state: conn.state,
-          key: conn.key
+          key: conn.key,
+          ...conn.name && { name: conn.name },
+          ...conn.tags?.length && { tags: conn.tags }
         })),
         ...limited.length < filtered.length && {
           hint: `Showing ${limited.length} of ${filtered.length} connections. Use --search <query> to filter by platform or --limit <n> to see more.`
@@ -1712,23 +1714,542 @@ function colorMethod(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}}"
+        }
+      }
+    }
+  ]
+}
+\`\`\`
+
+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") {
@@ -1738,7 +2259,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") {
@@ -1761,8 +2282,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") {
@@ -1784,6 +2305,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}]`;
@@ -1798,189 +2320,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];
@@ -1990,13 +2402,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");
@@ -2005,25 +2416,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;
   }
@@ -2070,49 +2473,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}]`)
+            );
+          }
+        }
       }
     }
   }
@@ -2184,10 +2567,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 = fs3.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 = [];
@@ -2494,909 +2886,791 @@ function colorStatus(status) {
       return status;
   }
 }
-
-// src/commands/guide.ts
-import pc8 from "picocolors";
-
-// src/lib/guide-content.ts
-var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
-
-## Setup
-
-1. Run \`one init\` to configure your API key
-2. Run \`one add <platform>\` to connect platforms via OAuth
-3. Run \`one --agent connection list\` to verify connections
-
-## The --agent Flag
-
-Always use \`--agent\` for machine-readable JSON output. It disables colors, spinners, and interactive prompts.
-
-\`\`\`bash
-one --agent <command>
-\`\`\`
-
-All commands return JSON. If an \`error\` key is present, the command failed.
-
-## Topics
-
-This guide has three sections you can request individually:
-
-- **overview** \u2014 This section. Setup, flag usage, and discovery workflow.
-- **actions** \u2014 Full workflow for searching, reading docs, and executing platform actions.
-- **workflows** \u2014 Building and executing multi-step API workflows (JSON-based).
-
-## Discovery Workflow
-
-1. \`one --agent connection list\` \u2014 See connected platforms and connection keys
-2. \`one --agent actions search <platform> <query>\` \u2014 Find actions
-3. \`one --agent actions knowledge <platform> <actionId>\` \u2014 Read full docs (REQUIRED before execute)
-4. \`one --agent actions execute <platform> <actionId> <connectionKey>\` \u2014 Execute the action
-
-For multi-step workflows:
-1. Discover actions with the workflow above
-2. Build a workflow JSON definition
-3. \`one --agent flow create <key> --definition '<json>'\`
-4. \`one --agent flow execute <key> -i param=value\`
-
-Platform names are always kebab-case (e.g., \`hub-spot\`, \`google-calendar\`).
-Run \`one platforms\` to browse all 200+ available platforms.
-`;
-var GUIDE_ACTIONS = `# One Actions CLI Workflow
-
-You have access to the One CLI which lets you interact with 200+ third-party platforms through their APIs. The CLI handles authentication, request building, and execution through One's passthrough proxy.
-
-## The Workflow
-
-Always follow this sequence \u2014 each step builds on the previous one:
-
-1. **List connections** to see what platforms the user has connected
-2. **Search actions** to find the right API action for what the user wants to do
-3. **Get knowledge** to understand the action's parameters, requirements, and structure
-4. **Execute** the action with the correct parameters
-
-Never skip the knowledge step before executing \u2014 it contains critical information about required parameters, validation rules, and request structure that you need to build a correct request.
-
-## Commands
-
-### 1. List Connections
-
-\`\`\`bash
-one --agent connection list
-\`\`\`
-
-Returns JSON with all connected platforms, their status, and connection keys. You need the **connection key** for executing actions, and the **platform name** (kebab-case) for searching actions.
-
-Output format:
-\`\`\`json
-{"connections": [{"platform": "gmail", "state": "active", "key": "conn_abc123"}, ...]}
-\`\`\`
-
-### 2. Search Actions
-
-\`\`\`bash
-one --agent actions search <platform> <query>
-\`\`\`
-
-Search for actions on a specific platform using natural language. Returns JSON with up to 5 matching actions including their action IDs, HTTP methods, and paths.
-
-- \`<platform>\` \u2014 Platform name in kebab-case exactly as shown in the connections list (e.g., \`gmail\`, \`shopify\`, \`hub-spot\`)
-- \`<query>\` \u2014 Natural language description of what you want to do (e.g., \`"send email"\`, \`"list contacts"\`, \`"create order"\`)
-
-Options:
-- \`-t, --type <execute|knowledge>\` \u2014 Use \`execute\` when the user wants to perform an action, \`knowledge\` when they want documentation or want to write code. Defaults to \`knowledge\`.
-
-Example:
-\`\`\`bash
-one --agent actions search gmail "send email" -t execute
-\`\`\`
-
-Output format:
-\`\`\`json
-{"actions": [{"_id": "abc123", "title": "Send Email", "tags": [...], "method": "POST", "path": "/messages/send"}, ...]}
-\`\`\`
-
-### 3. Get Action Knowledge
-
-\`\`\`bash
-one --agent actions knowledge <platform> <actionId>
-\`\`\`
-
-Get comprehensive documentation for an action including parameters, requirements, validation rules, request/response structure, and examples. Returns JSON with the full API knowledge and HTTP method.
-
-Always call this before executing \u2014 it tells you exactly what parameters are required and how to structure the request.
-
-Example:
-\`\`\`bash
-one --agent actions knowledge gmail 67890abcdef
-\`\`\`
-
-Output format:
-\`\`\`json
-{"knowledge": "...full API documentation and guidance...", "method": "POST"}
-\`\`\`
-
-### 4. Execute Action
-
-\`\`\`bash
-one --agent actions execute <platform> <actionId> <connectionKey> [options]
-\`\`\`
-
-Execute an action on a connected platform. Returns JSON with the request details and response data. You must have retrieved the knowledge for this action first.
-
-- \`<platform>\` \u2014 Platform name in kebab-case
-- \`<actionId>\` \u2014 Action ID from the search results
-- \`<connectionKey>\` \u2014 Connection key from \`one connection list\`
-
-Options:
-- \`-d, --data <json>\` \u2014 Request body as JSON string (for POST, PUT, PATCH)
-- \`--path-vars <json>\` \u2014 Path variables as JSON (for URLs with \`{id}\` placeholders)
-- \`--query-params <json>\` \u2014 Query parameters as JSON
-- \`--headers <json>\` \u2014 Additional headers as JSON
-- \`--form-data\` \u2014 Send as multipart/form-data instead of JSON
-- \`--form-url-encoded\` \u2014 Send as application/x-www-form-urlencoded
-- \`--dry-run\` \u2014 Show the request that would be sent without executing it
-
-Examples:
-\`\`\`bash
-# Simple GET request
-one --agent actions execute shopify <actionId> <connectionKey>
-
-# POST with data
-one --agent actions execute hub-spot <actionId> <connectionKey> \\
-  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
-
-# With path variables and query params
-one --agent actions execute shopify <actionId> <connectionKey> \\
-  --path-vars '{"order_id": "12345"}' \\
-  --query-params '{"limit": "10"}'
-\`\`\`
-
-Output format:
-\`\`\`json
-{"request": {"method": "POST", "url": "https://..."}, "response": {...}}
-\`\`\`
-
-## Error Handling
-
-All errors return JSON in agent mode:
-\`\`\`json
-{"error": "Error message here"}
-\`\`\`
-
-Parse the output as JSON. If the \`error\` key is present, the command failed \u2014 report the error message to the user.
-
-## Important Notes
-
-- **Always use \`--agent\` flag** \u2014 it produces structured JSON output without spinners, colors, or interactive prompts
-- Platform names are always **kebab-case** (e.g., \`hub-spot\` not \`HubSpot\`, \`ship-station\` not \`ShipStation\`)
-- Always use the **exact action ID** from search results \u2014 don't guess or construct them
-- Always read the knowledge output carefully \u2014 it tells you which parameters are required vs optional, what format they need to be in, and any caveats specific to that API
-- JSON values passed to \`-d\`, \`--path-vars\`, \`--query-params\`, and \`--headers\` must be valid JSON strings (use single quotes around the JSON to avoid shell escaping issues)
-- If search returns no results, try broader queries (e.g., \`"list"\` instead of \`"list active premium customers"\`)
-- The execute command respects access control settings configured via \`one config\` \u2014 if execution is blocked, the user may need to adjust their permissions
-`;
-var GUIDE_FLOWS = `# One Workflows \u2014 Multi-Step API Workflows
-
-You have access to the One CLI's workflow engine, which lets you create and execute multi-step API workflows as JSON files. Workflows chain actions across platforms \u2014 e.g., look up a Stripe customer, then send them a welcome email via Gmail.
-
-## 1. Overview
-
-- Workflows are JSON files stored at \`.one/flows/<key>.flow.json\`
-- All dynamic values (including connection keys) are declared as **inputs**
-- Each workflow has a unique **key** used to reference and execute it
-- Executed via \`one --agent flow execute <key> -i name=value\`
-
-## 2. Building a Workflow \u2014 Step-by-Step Process
-
-**You MUST follow this process to build a correct workflow:**
-
-### Step 1: Discover connections
-
-\`\`\`bash
-one --agent connection list
-\`\`\`
-
-Find out which platforms are connected and get their connection keys.
-
-### Step 2: For EACH API action needed, get the knowledge
-
-\`\`\`bash
-# Find the action ID
-one --agent actions search <platform> "<query>" -t execute
-
-# Read the full docs \u2014 REQUIRED before adding to a workflow
-one --agent actions knowledge <platform> <actionId>
-\`\`\`
-
-**CRITICAL:** You MUST call \`one actions knowledge\` for every action you include in the workflow. The knowledge output tells you the exact request body structure, required fields, path variables, and query parameters. Without this, your workflow JSON will have incorrect data shapes.
-
-### Step 3: Construct the workflow JSON
-
-Using the knowledge gathered, build the workflow JSON with:
-- All inputs declared (connection keys + user parameters)
-- Each step with the correct actionId, platform, and data structure (from knowledge)
-- Data wired between steps using \`$.input.*\` and \`$.steps.*\` selectors
-
-### Step 4: Write the workflow file
-
-\`\`\`bash
-one --agent flow create <key> --definition '<json>'
-\`\`\`
-
-Or write directly to \`.one/flows/<key>.flow.json\`.
-
-### Step 5: Validate
-
-\`\`\`bash
-one --agent flow validate <key>
-\`\`\`
-
-### Step 6: Execute
-
-\`\`\`bash
-one --agent flow execute <key> -i connectionKey=xxx -i param=value
-\`\`\`
-
-## 3. Workflow JSON Schema Reference
-
-\`\`\`json
-{
-  "key": "welcome-customer",
-  "name": "Welcome New Customer",
-  "description": "Look up a Stripe customer and send them a welcome email via Gmail",
-  "version": "1",
-  "inputs": {
-    "stripeConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Stripe connection key from one connection list",
-      "connection": { "platform": "stripe" }
+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" }
+      }
     },
-    "gmailConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Gmail connection key from one connection list",
-      "connection": { "platform": "gmail" }
+    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" }
+      }
     },
-    "customerEmail": {
-      "type": "string",
-      "required": true,
-      "description": "Customer email to look up"
+    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";
+function getConfig3() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    error("Not configured. Run `one init` first.");
+  }
+  const ac = getAccessControlFromAllSources();
+  const connectionKeys = ac.connectionKeys || ["*"];
+  return { apiKey, connectionKeys };
+}
+function parseJsonArg2(value, argName) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    error(`Invalid JSON for ${argName}: ${value}`);
+  }
+}
+async function relayCreateCommand(options) {
+  const { apiKey, connectionKeys } = getConfig3();
+  if (!connectionKeys.includes("*") && !connectionKeys.includes(options.connectionKey)) {
+    error(`Connection key "${options.connectionKey}" is not allowed.`);
+  }
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Creating relay endpoint...");
+  try {
+    const body = {
+      connectionKey: options.connectionKey
+    };
+    if (options.description) body.description = options.description;
+    if (options.eventFilters) body.eventFilters = parseJsonArg2(options.eventFilters, "--event-filters");
+    if (options.tags) body.tags = parseJsonArg2(options.tags, "--tags");
+    if (options.createWebhook) body.createWebhook = true;
+    const result = await api.createRelayEndpoint(body);
+    if (isAgentMode()) {
+      json(result);
+      return;
+    }
+    spinner5.stop("Relay endpoint created");
+    console.log();
+    console.log(`  ${pc8.dim("ID:")}          ${result.id}`);
+    console.log(`  ${pc8.dim("URL:")}         ${result.url}`);
+    console.log(`  ${pc8.dim("Active:")}      ${result.active}`);
+    if (result.description) console.log(`  ${pc8.dim("Description:")} ${result.description}`);
+    if (result.eventFilters?.length) console.log(`  ${pc8.dim("Events:")}      ${result.eventFilters.join(", ")}`);
+    if (result.webhookPayload?.id) console.log(`  ${pc8.dim("Webhook ID:")}  ${result.webhookPayload.id}`);
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to create relay endpoint");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayListCommand(options) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Loading relay endpoints...");
+  try {
+    const query = {};
+    if (options.limit) query.limit = options.limit;
+    if (options.page) query.page = options.page;
+    const result = await api.listRelayEndpoints(query);
+    const endpoints = result.rows || [];
+    if (isAgentMode()) {
+      json({
+        total: result.total,
+        showing: endpoints.length,
+        endpoints: endpoints.map((e) => ({
+          id: e.id,
+          active: e.active,
+          description: e.description,
+          eventFilters: e.eventFilters,
+          actionsCount: e.actions?.length || 0,
+          url: e.url,
+          createdAt: e.createdAt
+        }))
+      });
+      return;
+    }
+    spinner5.stop(`${endpoints.length} relay endpoint${endpoints.length === 1 ? "" : "s"} found`);
+    if (endpoints.length === 0) {
+      console.log("\n  No relay endpoints yet.\n");
+      return;
+    }
+    printTable(
+      ["Status", "Description", "Events", "Actions", "ID"],
+      endpoints.map((e) => [
+        e.active ? pc8.green("\u25CF") : pc8.dim("\u25CB"),
+        e.description || pc8.dim("(none)"),
+        e.eventFilters?.join(", ") || pc8.dim("all"),
+        String(e.actions?.length || 0),
+        pc8.dim(e.id.slice(0, 8))
+      ])
+    );
+  } catch (error2) {
+    spinner5.stop("Failed to list relay endpoints");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayGetCommand(id) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Loading relay endpoint...");
+  try {
+    const result = await api.getRelayEndpoint(id);
+    if (isAgentMode()) {
+      json(result);
+      return;
+    }
+    spinner5.stop("Relay endpoint loaded");
+    console.log();
+    console.log(`  ${pc8.dim("ID:")}          ${result.id}`);
+    console.log(`  ${pc8.dim("URL:")}         ${result.url}`);
+    console.log(`  ${pc8.dim("Active:")}      ${result.active}`);
+    if (result.description) console.log(`  ${pc8.dim("Description:")} ${result.description}`);
+    if (result.eventFilters?.length) console.log(`  ${pc8.dim("Events:")}      ${result.eventFilters.join(", ")}`);
+    console.log(`  ${pc8.dim("Actions:")}     ${result.actions?.length || 0}`);
+    if (result.actions?.length) {
+      for (const [i, action] of result.actions.entries()) {
+        console.log(`    ${pc8.dim(`[${i}]`)} type=${action.type}${action.actionId ? ` actionId=${action.actionId}` : ""}${action.url ? ` url=${action.url}` : ""}`);
+      }
+    }
+    console.log(`  ${pc8.dim("Created:")}     ${result.createdAt}`);
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to load relay endpoint");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayUpdateCommand(id, options) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Updating relay endpoint...");
+  try {
+    const body = {};
+    if (options.description !== void 0) body.description = options.description;
+    if (options.active !== void 0) body.active = options.active;
+    if (options.eventFilters) body.eventFilters = parseJsonArg2(options.eventFilters, "--event-filters");
+    if (options.tags) body.tags = parseJsonArg2(options.tags, "--tags");
+    if (options.actions) body.actions = parseJsonArg2(options.actions, "--actions");
+    const result = await api.updateRelayEndpoint(id, body);
+    if (isAgentMode()) {
+      json(result);
+      return;
+    }
+    spinner5.stop("Relay endpoint updated");
+    console.log(`  ${pc8.dim("ID:")} ${result.id}`);
+    console.log(`  ${pc8.dim("Active:")} ${result.active}`);
+    console.log(`  ${pc8.dim("Actions:")} ${result.actions?.length || 0}`);
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to update relay endpoint");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayDeleteCommand(id) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Deleting relay endpoint...");
+  try {
+    const result = await api.deleteRelayEndpoint(id);
+    if (isAgentMode()) {
+      json({ deleted: true, id: result.id });
+      return;
+    }
+    spinner5.stop("Relay endpoint deleted");
+    console.log(`  Deleted: ${result.id}`);
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to delete relay endpoint");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayActivateCommand(id, options) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Activating relay endpoint...");
+  try {
+    const actions2 = parseJsonArg2(options.actions, "--actions");
+    const body = { actions: actions2 };
+    if (options.webhookSecret) body.webhookSecret = options.webhookSecret;
+    const result = await api.activateRelayEndpoint(id, body);
+    if (isAgentMode()) {
+      json(result);
+      return;
+    }
+    spinner5.stop("Relay endpoint activated");
+    console.log(`  ${pc8.dim("ID:")} ${result.id}`);
+    console.log(`  ${pc8.dim("Active:")} ${result.active}`);
+    console.log(`  ${pc8.dim("Actions:")} ${result.actions?.length || 0}`);
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to activate relay endpoint");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayEventsCommand(options) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Loading relay events...");
+  try {
+    const query = {};
+    if (options.limit) query.limit = options.limit;
+    if (options.page) query.page = options.page;
+    if (options.platform) query.platform = options.platform;
+    if (options.eventType) query.eventType = options.eventType;
+    if (options.after) query.after = options.after;
+    if (options.before) query.before = options.before;
+    const result = await api.listRelayEvents(query);
+    const events = result.rows || [];
+    if (isAgentMode()) {
+      json({
+        total: result.total,
+        showing: events.length,
+        events: events.map((e) => ({
+          id: e.id,
+          platform: e.platform,
+          eventType: e.eventType,
+          timestamp: e.timestamp || e.createdAt
+        }))
+      });
+      return;
+    }
+    spinner5.stop(`${events.length} event${events.length === 1 ? "" : "s"} found`);
+    if (events.length === 0) {
+      console.log("\n  No events found.\n");
+      return;
+    }
+    printTable(
+      ["Platform", "Event Type", "Timestamp", "ID"],
+      events.map((e) => [
+        e.platform,
+        e.eventType || pc8.dim("unknown"),
+        e.timestamp || e.createdAt,
+        pc8.dim(e.id.slice(0, 8))
+      ])
+    );
+  } catch (error2) {
+    spinner5.stop("Failed to list relay events");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayEventGetCommand(id) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Loading relay event...");
+  try {
+    const result = await api.getRelayEvent(id);
+    if (isAgentMode()) {
+      json(result);
+      return;
+    }
+    spinner5.stop("Relay event loaded");
+    console.log();
+    console.log(`  ${pc8.dim("ID:")}        ${result.id}`);
+    console.log(`  ${pc8.dim("Platform:")}  ${result.platform}`);
+    console.log(`  ${pc8.dim("Event:")}     ${result.eventType}`);
+    console.log(`  ${pc8.dim("Timestamp:")} ${result.timestamp || result.createdAt}`);
+    console.log(`  ${pc8.dim("Payload:")}`);
+    console.log(JSON.stringify(result.payload, null, 2));
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to load relay event");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayDeliveriesCommand(options) {
+  if (!options.endpointId && !options.eventId) {
+    error("Provide either --endpoint-id or --event-id");
+  }
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start("Loading deliveries...");
+  try {
+    const deliveries = options.endpointId ? await api.listRelayEndpointDeliveries(options.endpointId) : await api.listRelayEventDeliveries(options.eventId);
+    const items = Array.isArray(deliveries) ? deliveries : deliveries.rows || [];
+    if (isAgentMode()) {
+      json({ deliveries: items });
+      return;
+    }
+    spinner5.stop(`${items.length} deliver${items.length === 1 ? "y" : "ies"} found`);
+    if (items.length === 0) {
+      console.log("\n  No deliveries found.\n");
+      return;
+    }
+    printTable(
+      ["Status", "Code", "Attempt", "Delivered At", "Error"],
+      items.map((d) => [
+        d.status === "success" ? pc8.green(d.status) : pc8.red(d.status),
+        d.statusCode != null ? String(d.statusCode) : pc8.dim("-"),
+        String(d.attempt),
+        d.deliveredAt || pc8.dim("-"),
+        d.error ? pc8.red(d.error.slice(0, 50)) : pc8.dim("-")
+      ])
+    );
+  } catch (error2) {
+    spinner5.stop("Failed to load deliveries");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
+}
+async function relayEventTypesCommand(platform) {
+  const { apiKey } = getConfig3();
+  const api = new OneApi(apiKey);
+  const spinner5 = createSpinner();
+  spinner5.start(`Loading event types for ${pc8.cyan(platform)}...`);
+  try {
+    const eventTypes = await api.listRelayEventTypes(platform);
+    if (isAgentMode()) {
+      json({ platform, eventTypes });
+      return;
     }
-  },
-  "steps": [
-    {
-      "id": "stepId",
-      "name": "Human-readable label",
-      "type": "action",
-      "action": {
-        "platform": "stripe",
-        "actionId": "the-action-id-from-search",
-        "connectionKey": "$.input.stripeConnectionKey",
-        "data": {},
-        "pathVars": {},
-        "queryParams": {},
-        "headers": {}
-      }
+    spinner5.stop(`${eventTypes.length} event type${eventTypes.length === 1 ? "" : "s"} found`);
+    if (eventTypes.length === 0) {
+      console.log(`
+  No event types found for ${platform}.
+`);
+      return;
     }
-  ]
+    console.log();
+    for (const type of eventTypes) {
+      console.log(`  ${type}`);
+    }
+    console.log();
+  } catch (error2) {
+    spinner5.stop("Failed to load event types");
+    error(`Error: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+  }
 }
-\`\`\`
-
-### Input declarations
 
-| Field | Type | Description |
-|---|---|---|
-| \`type\` | string | \`string\`, \`number\`, \`boolean\`, \`object\`, \`array\` |
-| \`required\` | boolean | Whether this input must be provided (default: true) |
-| \`default\` | any | Default value if not provided |
-| \`description\` | string | Human-readable description |
-| \`connection\` | object | Connection metadata: \`{ "platform": "gmail" }\` \u2014 enables auto-resolution |
-
-**Connection inputs** have a \`connection\` field. If the user has exactly one connection for that platform, the workflow engine auto-resolves it.
+// src/commands/guide.ts
+import pc9 from "picocolors";
 
-## 4. Selector Syntax Reference
+// src/lib/guide-content.ts
+var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
 
-| Pattern | Resolves To |
-|---|---|
-| \`$.input.gmailConnectionKey\` | Input value (including connection keys) |
-| \`$.input.customerEmail\` | Any input parameter |
-| \`$.steps.stepId.response\` | Full API response from a step |
-| \`$.steps.stepId.response.data[0].email\` | Nested field with array index |
-| \`$.steps.stepId.response.data[*].id\` | Wildcard \u2014 maps array to field |
-| \`$.env.MY_VAR\` | Environment variable |
-| \`$.loop.item\` | Current loop item |
-| \`$.loop.i\` | Current loop index |
-| \`"Hello {{$.steps.getUser.response.data.name}}"\` | String interpolation |
+## Setup
 
-**Rules:**
-- A value that is purely \`$.xxx\` resolves to the raw type (object, array, number)
-- A string containing \`{{$.xxx}}\` does string interpolation (stringifies objects)
-- Selectors inside objects/arrays are resolved recursively
+1. Run \`one init\` to configure your API key
+2. Run \`one add <platform>\` to connect platforms via OAuth
+3. Run \`one --agent connection list\` to verify connections
 
-## 5. Step Types Reference
+## The --agent Flag
 
-### \`action\` \u2014 Execute a One API action
+Always use \`--agent\` for machine-readable JSON output. It disables colors, spinners, and interactive prompts.
 
-\`\`\`json
-{
-  "id": "findCustomer",
-  "name": "Search Stripe customers",
-  "type": "action",
-  "action": {
-    "platform": "stripe",
-    "actionId": "conn_mod_def::xxx::yyy",
-    "connectionKey": "$.input.stripeConnectionKey",
-    "data": {
-      "query": "email:'{{$.input.customerEmail}}'"
-    }
-  }
-}
+\`\`\`bash
+one --agent <command>
 \`\`\`
 
-### \`transform\` \u2014 Transform data with a JS expression
+All commands return JSON. If an \`error\` key is present, the command failed.
 
-\`\`\`json
-{
-  "id": "extractNames",
-  "name": "Extract customer names",
-  "type": "transform",
-  "transform": {
-    "expression": "$.steps.findCustomer.response.data.map(c => c.name)"
-  }
-}
-\`\`\`
+## IMPORTANT: Read the guide before you act
 
-The expression is evaluated with the full flow context as \`$\`.
+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.
 
-### \`code\` \u2014 Run multi-line JavaScript
+## Features
 
-Unlike \`transform\` (single expression, implicit return), \`code\` runs a full function body with explicit \`return\`. Use it when you need variables, loops, try/catch, or \`await\`.
+### 1. Actions \u2014 Execute API calls on 200+ platforms
+Search for actions, read their docs, and execute them. This is the core workflow.
 
-\`\`\`json
-{
-  "id": "processData",
-  "name": "Process and enrich data",
-  "type": "code",
-  "code": {
-    "source": "const customers = $.steps.listCustomers.response.data;\\nconst enriched = customers.map(c => ({\\n  ...c,\\n  tier: c.spend > 1000 ? 'gold' : 'silver'\\n}));\\nreturn enriched;"
-  }
-}
+**Quick start:**
+\`\`\`bash
+one --agent connection list                                    # See connected platforms
+one --agent actions search <platform> "<query>" -t execute     # Find an action
+one --agent actions knowledge <platform> <actionId>            # Read docs (REQUIRED)
+one --agent actions execute <platform> <actionId> <key> -d '{}'  # Execute it
 \`\`\`
 
-The \`source\` field contains a JS function body. The flow context is available as \`$\`. The function is async, so you can use \`await\`. The return value is stored as the step result.
+**Parameter flags:**
+- \`-d <json>\` \u2014 Request body (POST/PUT/PATCH)
+- \`--path-vars <json>\` \u2014 URL path variables (e.g., \`{"userId": "me"}\`)
+- \`--query-params <json>\` \u2014 Query parameters (arrays expand to repeated params)
+- \`--form-url-encoded\` \u2014 Send as form data instead of JSON
+- \`--dry-run\` \u2014 Preview request without executing
 
-### \`condition\` \u2014 If/then/else branching
-
-\`\`\`json
-{
-  "id": "checkFound",
-  "name": "Check if customer was found",
-  "type": "condition",
-  "condition": {
-    "expression": "$.steps.findCustomer.response.data.length > 0",
-    "then": [
-      { "id": "sendEmail", "name": "Send welcome email", "type": "action", "action": { "..." : "..." } }
-    ],
-    "else": [
-      { "id": "logNotFound", "name": "Log not found", "type": "transform", "transform": { "expression": "'Customer not found'" } }
-    ]
-  }
-}
-\`\`\`
+Do NOT pass path or query parameters in \`-d\` \u2014 use the correct flags.
 
-### \`loop\` \u2014 Iterate over an array
+### 2. Flows \u2014 Multi-step API workflows
+Chain actions across platforms as JSON workflow files with conditions, loops, parallel execution, transforms, and AI analysis via bash steps.
 
-\`\`\`json
-{
-  "id": "processOrders",
-  "name": "Process each order",
-  "type": "loop",
-  "loop": {
-    "over": "$.steps.listOrders.response.data",
-    "as": "order",
-    "indexAs": "i",
-    "maxIterations": 1000,
-    "maxConcurrency": 5,
-    "steps": [
-      {
-        "id": "createInvoice",
-        "name": "Create invoice for order",
-        "type": "action",
-        "action": {
-          "platform": "quickbooks",
-          "actionId": "...",
-          "connectionKey": "$.input.qbConnectionKey",
-          "data": { "amount": "$.loop.order.total" }
-        }
-      }
-    ]
-  }
-}
+**Quick start:**
+\`\`\`bash
+one --agent flow create <key> --definition '<json>'   # Create a workflow
+one --agent flow validate <key>                       # Validate it
+one --agent flow execute <key> -i param=value         # Execute it
+one --agent flow list                                 # List all workflows
 \`\`\`
 
-- \`maxConcurrency\` (optional): When set > 1, loop iterations run in parallel batches of that size. Default is sequential (1).
+**Key concepts:**
+- Workflows are JSON files at \`.one/flows/<key>.flow.json\`
+- 12 step types: action, transform, code, condition, loop, parallel, file-read, file-write, while, flow, paginate, bash
+- Data wiring via selectors: \`$.input.param\`, \`$.steps.stepId.response\`, \`$.loop.item\`
+- AI analysis via bash steps: \`claude --print\` with \`parseJson: true\`
+- Use \`--allow-bash\` to enable bash steps, \`--mock\` for dry-run with mock responses
 
-### \`parallel\` \u2014 Run steps concurrently
+### 3. Relay \u2014 Webhook event forwarding between platforms
+Receive webhooks from platforms (Stripe, GitHub, Airtable, Attio, Google Calendar) and forward event data to any connected platform using passthrough actions with Handlebars templates. No middleware, no code.
 
-\`\`\`json
-{
-  "id": "parallelLookups",
-  "name": "Look up in parallel",
-  "type": "parallel",
-  "parallel": {
-    "maxConcurrency": 5,
-    "steps": [
-      { "id": "getStripe", "name": "Get Stripe data", "type": "action", "action": { "...": "..." } },
-      { "id": "getHubspot", "name": "Get HubSpot data", "type": "action", "action": { "...": "..." } }
-    ]
-  }
-}
+**Quick start:**
+\`\`\`bash
+one --agent relay event-types <platform>                        # See available events
+one --agent relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
+one --agent relay activate <id> --actions '[{"type":"passthrough","actionId":"...","connectionKey":"...","body":{...}}]'
+one --agent relay list                                          # List endpoints
+one --agent relay events --platform <p>                         # List received events
+one --agent relay deliveries --endpoint-id <id>                 # Check delivery status
 \`\`\`
 
-### \`file-read\` \u2014 Read from filesystem
+**Key concepts:**
+- \`passthrough\` actions map webhook fields to another platform's API using Handlebars: \`{{payload.data.object.email}}\`
+- Template context: \`{{relayEventId}}\`, \`{{platform}}\`, \`{{eventType}}\`, \`{{payload}}\`, \`{{timestamp}}\`, \`{{connectionId}}\`
+- \`--create-webhook\` auto-registers the webhook URL with the source platform
+- Use \`actions knowledge\` to learn both the incoming payload shape AND the destination API shape before building templates
 
-\`\`\`json
-{
-  "id": "readConfig",
-  "name": "Read config file",
-  "type": "file-read",
-  "fileRead": { "path": "./data/config.json", "parseJson": true }
-}
-\`\`\`
+## Topics
 
-### \`file-write\` \u2014 Write to filesystem
+Request specific sections:
+- \`one guide overview\` \u2014 This section
+- \`one guide actions\` \u2014 Actions reference (search, knowledge, execute)
+- \`one guide flows\` \u2014 Workflow engine reference (step types, selectors, examples)
+- \`one guide relay\` \u2014 Webhook relay reference (templates, passthrough actions)
+- \`one guide all\` \u2014 Everything
 
-\`\`\`json
-{
-  "id": "writeResults",
-  "name": "Save results",
-  "type": "file-write",
-  "fileWrite": {
-    "path": "./output/results.json",
-    "content": "$.steps.transform.output",
-    "append": false
-  }
-}
-\`\`\`
+## Important Notes
 
-### \`while\` \u2014 Condition-driven loop (do-while)
+- **Always use \`--agent\` flag** for structured JSON output
+- Platform names are always **kebab-case** (e.g., \`hub-spot\`, \`google-calendar\`)
+- Always use the **exact action ID** from search results \u2014 don't guess
+- Always read **knowledge** before executing any action
+- Connection keys come from \`one connection list\` \u2014 don't hardcode them
+`;
+var GUIDE_ACTIONS = `# One Actions \u2014 Reference
 
-Iterates until a condition becomes falsy. The first iteration always runs (do-while semantics), then the condition is checked before each subsequent iteration. Useful for pagination.
+## Workflow: search \u2192 knowledge \u2192 execute
 
-\`\`\`json
-{
-  "id": "paginate",
-  "name": "Paginate through all 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": "GMAIL_LIST_MESSAGES_ACTION_ID",
-          "connectionKey": "$.input.gmailKey",
-          "queryParams": {
-            "pageToken": "$.steps.paginate.output.lastResult.nextPageToken"
-          }
-        }
-      }
-    ]
-  }
-}
-\`\`\`
+Always follow this sequence. Never skip the knowledge step.
 
-| Field | Type | Description |
-|---|---|---|
-| \`condition\` | string | JS expression evaluated before each iteration (after iteration 0) |
-| \`maxIterations\` | number | Safety cap, default: 100 |
-| \`steps\` | FlowStep[] | Steps to execute each iteration |
+### 1. List Connections
 
-The step output contains \`lastResult\` (last step's output from most recent iteration), \`iteration\` (count), and \`results\` (array of all iteration outputs). Reference via \`$.steps.<id>.output.lastResult\`.
+\`\`\`bash
+one --agent connection list
+\`\`\`
 
-### \`flow\` \u2014 Execute a sub-flow
+Returns platforms, status, connection keys, and tags.
 
-Loads and executes another saved flow, enabling flow composition. Circular flows are detected and blocked.
+### 2. Search Actions
 
-\`\`\`json
-{
-  "id": "processCustomer",
-  "name": "Run customer enrichment flow",
-  "type": "flow",
-  "flow": {
-    "key": "enrich-customer",
-    "inputs": {
-      "email": "$.steps.getCustomer.response.email",
-      "connectionKey": "$.input.hubspotConnectionKey"
-    }
-  }
-}
+\`\`\`bash
+one --agent actions search <platform> "<query>" -t execute
 \`\`\`
 
-| Field | Type | Description |
-|---|---|---|
-| \`key\` | string | Flow key or path (supports selectors) |
-| \`inputs\` | object | Input values mapped to the sub-flow's declared inputs (supports selectors) |
+- Use \`-t execute\` when the user wants to perform an action
+- Use \`-t knowledge\` (default) for documentation/code generation
+- Returns up to 5 matching actions with IDs, methods, and paths
 
-### \`paginate\` \u2014 Auto-collect paginated API results
+### 3. Get Knowledge
 
-Automatically pages through a paginated API, collecting all results into a single array.
-
-\`\`\`json
-{
-  "id": "allMessages",
-  "name": "Fetch all Gmail messages",
-  "type": "paginate",
-  "paginate": {
-    "action": {
-      "platform": "gmail",
-      "actionId": "GMAIL_LIST_MESSAGES_ACTION_ID",
-      "connectionKey": "$.input.gmailKey",
-      "queryParams": { "maxResults": 100 }
-    },
-    "pageTokenField": "nextPageToken",
-    "resultsField": "messages",
-    "inputTokenParam": "queryParams.pageToken",
-    "maxPages": 10
-  }
-}
+\`\`\`bash
+one --agent actions knowledge <platform> <actionId>
 \`\`\`
 
-| Field | Type | Description |
-|---|---|---|
-| \`action\` | FlowActionConfig | The API action to call (same format as action steps) |
-| \`pageTokenField\` | string | Dot-path in the API response to the next page token |
-| \`resultsField\` | string | Dot-path in the API response to the results array |
-| \`inputTokenParam\` | string | Dot-path in the action config where the page token is injected |
-| \`maxPages\` | number | Maximum pages to fetch, default: 10 |
+Returns full API docs: required fields, validation rules, request structure. **REQUIRED before execute.** The output includes a CLI PARAMETER MAPPING section showing which flags to use.
 
-### \`bash\` \u2014 Execute shell commands
+### 4. Execute
 
-Runs a shell command. **Requires \`--allow-bash\` flag** for security.
-
-\`\`\`json
-{
-  "id": "analyzeData",
-  "name": "Analyze data with Claude",
-  "type": "bash",
-  "bash": {
-    "command": "claude --print 'Analyze: {{$.steps.fetchData.response}}' --output-format json",
-    "timeout": 120000,
-    "parseJson": true
-  }
-}
+\`\`\`bash
+one --agent actions execute <platform> <actionId> <connectionKey> [options]
 \`\`\`
 
-| Field | Type | Description |
-|---|---|---|
-| \`command\` | string | Shell command to execute (supports selectors and interpolation) |
-| \`timeout\` | number | Timeout in ms, default: 30000 |
-| \`parseJson\` | boolean | Parse stdout as JSON, default: false |
-| \`cwd\` | string | Working directory (supports selectors) |
-| \`env\` | object | Additional environment variables |
+**Flags:**
+- \`-d, --data <json>\` \u2014 Request body (POST/PUT/PATCH)
+- \`--path-vars <json>\` \u2014 Path variables: \`{"userId": "me"}\`
+- \`--query-params <json>\` \u2014 Query params: \`{"limit": "10"}\`
+  - Arrays expand to repeated params: \`{"metadataHeaders": ["From", "Subject"]}\`
+- \`--headers <json>\` \u2014 Additional headers
+- \`--form-data\` / \`--form-url-encoded\` \u2014 Alternative content types
+- \`--dry-run\` \u2014 Preview without executing
 
-**Security:** Bash steps are blocked by default. Pass \`--allow-bash\` to \`one flow execute\` to enable them.
+**Do NOT** pass path or query parameters in \`-d\`. Use the correct flags.
 
-## 6. Error Handling
+## Error Handling
 
-### \`onError\` strategies
+All errors return JSON: \`{"error": "message"}\`. Check the \`error\` key.
 
-\`\`\`json
-{
-  "id": "riskyStep",
-  "name": "Might fail",
-  "type": "action",
-  "onError": {
-    "strategy": "retry",
-    "retries": 3,
-    "retryDelayMs": 1000
-  },
-  "action": { "...": "..." }
-}
-\`\`\`
+## Notes
 
-| Strategy | Behavior |
-|---|---|
-| \`fail\` | Stop the flow immediately (default) |
-| \`continue\` | Mark step as failed, continue to next step |
-| \`retry\` | Retry up to N times with delay |
-| \`fallback\` | On failure, execute a different step |
+- Platform names are **kebab-case** (e.g., \`hub-spot\`)
+- JSON flags use single quotes around the JSON to avoid shell escaping
+- If search returns no results, try broader queries
+- Access control settings from \`one config\` may restrict execution
+`;
+var GUIDE_FLOWS = generateFlowGuide();
+var GUIDE_RELAY = `# One Relay \u2014 Reference
 
-### Conditional execution
+## Overview
 
-Skip a step based on previous results:
+Webhook relay receives events from platforms (Stripe, GitHub, Airtable, Attio, Google Calendar) and forwards them to any connected platform using passthrough actions with Handlebars templates.
 
-\`\`\`json
-{
-  "id": "sendEmail",
-  "name": "Send email only if customer found",
-  "type": "action",
-  "if": "$.steps.findCustomer.response.data.length > 0",
-  "action": { "...": "..." }
-}
+## Commands
+
+\`\`\`bash
+one --agent relay event-types <platform>          # List available events
+one --agent relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
+one --agent relay activate <id> --actions '<json>' # Add forwarding actions
+one --agent relay list                             # List endpoints
+one --agent relay get <id>                         # Get endpoint details
+one --agent relay update <id> --actions '<json>'   # Update endpoint
+one --agent relay delete <id>                      # Delete endpoint
+one --agent relay events --platform <p>            # List received events
+one --agent relay event <id>                       # Get event with payload
+one --agent relay deliveries --endpoint-id <id>    # Check delivery status
 \`\`\`
 
-## 7. Updating Existing Workflows
+## Building a Relay
 
-To modify an existing workflow:
+1. **Discover connections** \u2014 identify source and destination platforms
+2. **Get event types** \u2014 \`one --agent relay event-types <platform>\`
+3. **Get source knowledge** \u2014 understand the incoming webhook payload shape (\`{{payload.*}}\` paths)
+4. **Get destination knowledge** \u2014 understand the outgoing API body shape
+5. **Create endpoint** \u2014 with \`--create-webhook\` and \`--event-filters\`
+6. **Activate** \u2014 with passthrough action mapping source fields to destination fields
 
-1. Read the workflow JSON file at \`.one/flows/<key>.flow.json\`
-2. Understand its current structure
-3. Use \`one --agent actions knowledge <platform> <actionId>\` for any new actions
-4. Modify the JSON (add/remove/update steps, change data mappings, add inputs)
-5. Write back the updated workflow file
-6. Validate: \`one --agent flow validate <key>\`
+## Template Context
 
-## 8. Complete Examples
+| Variable | Description |
+|----------|-------------|
+| \`{{relayEventId}}\` | Unique event UUID |
+| \`{{platform}}\` | Source platform (e.g., \`stripe\`) |
+| \`{{eventType}}\` | Event type (e.g., \`customer.created\`) |
+| \`{{payload}}\` | Full incoming webhook body |
+| \`{{timestamp}}\` | When the event was received |
+| \`{{connectionId}}\` | Source connection UUID |
+| \`{{json payload}}\` | Embed full payload as JSON string |
 
-### Example 1: Simple 2-step workflow \u2014 Search Stripe customer, send Gmail email
+Access nested fields: \`{{payload.data.object.email}}\`
 
+## Action Types
+
+**passthrough** (primary) \u2014 forward to another platform's API:
 \`\`\`json
 {
-  "key": "welcome-customer",
-  "name": "Welcome New Customer",
-  "description": "Look up a Stripe customer and send them a welcome email",
-  "version": "1",
-  "inputs": {
-    "stripeConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Stripe connection key",
-      "connection": { "platform": "stripe" }
-    },
-    "gmailConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Gmail connection key",
-      "connection": { "platform": "gmail" }
-    },
-    "customerEmail": {
-      "type": "string",
-      "required": true,
-      "description": "Customer email to look up"
-    }
-  },
-  "steps": [
-    {
-      "id": "findCustomer",
-      "name": "Search for customer in Stripe",
-      "type": "action",
-      "action": {
-        "platform": "stripe",
-        "actionId": "STRIPE_SEARCH_CUSTOMERS_ACTION_ID",
-        "connectionKey": "$.input.stripeConnectionKey",
-        "data": {
-          "query": "email:'{{$.input.customerEmail}}'"
-        }
-      }
-    },
-    {
-      "id": "sendWelcome",
-      "name": "Send welcome email via Gmail",
-      "type": "action",
-      "if": "$.steps.findCustomer.response.data && $.steps.findCustomer.response.data.length > 0",
-      "action": {
-        "platform": "gmail",
-        "actionId": "GMAIL_SEND_EMAIL_ACTION_ID",
-        "connectionKey": "$.input.gmailConnectionKey",
-        "data": {
-          "to": "{{$.input.customerEmail}}",
-          "subject": "Welcome, {{$.steps.findCustomer.response.data[0].name}}!",
-          "body": "Thank you for being a customer. We're glad to have you!"
-        }
-      }
-    }
-  ]
+  "type": "passthrough",
+  "actionId": "<action-id>",
+  "connectionKey": "<dest-connection-key>",
+  "body": { "channel": "#alerts", "text": "New customer: {{payload.data.object.name}}" },
+  "eventFilters": ["customer.created"]
 }
 \`\`\`
 
-### Example 2: Conditional \u2014 Check if HubSpot contact exists, create or update
-
+**url** \u2014 forward raw event to a URL:
 \`\`\`json
-{
-  "key": "sync-hubspot-contact",
-  "name": "Sync Contact to HubSpot",
-  "description": "Check if a contact exists in HubSpot, create if new or update if existing",
-  "version": "1",
-  "inputs": {
-    "hubspotConnectionKey": {
-      "type": "string",
-      "required": true,
-      "connection": { "platform": "hub-spot" }
-    },
-    "email": { "type": "string", "required": true },
-    "firstName": { "type": "string", "required": true },
-    "lastName": { "type": "string", "required": true }
-  },
-  "steps": [
-    {
-      "id": "searchContact",
-      "name": "Search for existing contact",
-      "type": "action",
-      "action": {
-        "platform": "hub-spot",
-        "actionId": "HUBSPOT_SEARCH_CONTACTS_ACTION_ID",
-        "connectionKey": "$.input.hubspotConnectionKey",
-        "data": {
-          "filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "EQ", "value": "$.input.email" }] }]
-        }
-      }
-    },
-    {
-      "id": "createOrUpdate",
-      "name": "Create or update contact",
-      "type": "condition",
-      "condition": {
-        "expression": "$.steps.searchContact.response.total > 0",
-        "then": [
-          {
-            "id": "updateContact",
-            "name": "Update existing contact",
-            "type": "action",
-            "action": {
-              "platform": "hub-spot",
-              "actionId": "HUBSPOT_UPDATE_CONTACT_ACTION_ID",
-              "connectionKey": "$.input.hubspotConnectionKey",
-              "pathVars": { "contactId": "$.steps.searchContact.response.results[0].id" },
-              "data": {
-                "properties": { "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
-              }
-            }
-          }
-        ],
-        "else": [
-          {
-            "id": "createContact",
-            "name": "Create new contact",
-            "type": "action",
-            "action": {
-              "platform": "hub-spot",
-              "actionId": "HUBSPOT_CREATE_CONTACT_ACTION_ID",
-              "connectionKey": "$.input.hubspotConnectionKey",
-              "data": {
-                "properties": { "email": "$.input.email", "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
-              }
-            }
-          }
-        ]
-      }
-    }
-  ]
-}
+{"type": "url", "url": "https://your-app.com/webhook", "eventFilters": ["customer.created"]}
 \`\`\`
 
-### Example 3: Loop workflow \u2014 Iterate over Shopify orders, create invoices
-
+**agent** \u2014 send to an agent:
 \`\`\`json
-{
-  "key": "shopify-to-invoices",
-  "name": "Shopify Orders to Invoices",
-  "description": "Fetch recent Shopify orders and create an invoice for each",
-  "version": "1",
-  "inputs": {
-    "shopifyConnectionKey": {
-      "type": "string",
-      "required": true,
-      "connection": { "platform": "shopify" }
-    },
-    "qbConnectionKey": {
-      "type": "string",
-      "required": true,
-      "connection": { "platform": "quick-books" }
-    }
-  },
-  "steps": [
-    {
-      "id": "listOrders",
-      "name": "List recent Shopify orders",
-      "type": "action",
-      "action": {
-        "platform": "shopify",
-        "actionId": "SHOPIFY_LIST_ORDERS_ACTION_ID",
-        "connectionKey": "$.input.shopifyConnectionKey",
-        "queryParams": { "status": "any", "limit": "50" }
-      }
-    },
-    {
-      "id": "createInvoices",
-      "name": "Create invoice for each order",
-      "type": "loop",
-      "loop": {
-        "over": "$.steps.listOrders.response.orders",
-        "as": "order",
-        "indexAs": "i",
-        "steps": [
-          {
-            "id": "createInvoice",
-            "name": "Create QuickBooks invoice",
-            "type": "action",
-            "onError": { "strategy": "continue" },
-            "action": {
-              "platform": "quick-books",
-              "actionId": "QB_CREATE_INVOICE_ACTION_ID",
-              "connectionKey": "$.input.qbConnectionKey",
-              "data": {
-                "Line": [
-                  {
-                    "Amount": "$.loop.order.total_price",
-                    "Description": "Shopify Order #{{$.loop.order.order_number}}"
-                  }
-                ]
-              }
-            }
-          }
-        ]
-      }
-    },
-    {
-      "id": "summary",
-      "name": "Generate summary",
-      "type": "transform",
-      "transform": {
-        "expression": "({ totalOrders: $.steps.listOrders.response.orders.length, processed: $.steps.createInvoices.output.length })"
-      }
-    }
-  ]
-}
+{"type": "agent", "agentId": "<uuid>", "eventFilters": ["customer.created"]}
 \`\`\`
 
-## CLI Commands Reference
-
-\`\`\`bash
-# Create a workflow
-one --agent flow create <key> --definition '<json>'
-
-# List all workflows
-one --agent flow list
-
-# Validate a workflow
-one --agent flow validate <key>
+## Supported Source Platforms
 
-# Execute a workflow
-one --agent flow execute <key> -i connectionKey=value -i param=value
+Airtable, Attio, GitHub, Google Calendar, Stripe
 
-# Execute with dry run (validate only)
-one --agent flow execute <key> --dry-run -i connectionKey=value
+Any connected platform can be a destination via passthrough actions.
 
-# Execute with mock mode (dry-run + mock API responses, runs transforms/code normally)
-one --agent flow execute <key> --dry-run --mock -i connectionKey=value
+## Debugging
 
-# Execute with bash steps enabled
-one --agent flow execute <key> --allow-bash -i connectionKey=value
-
-# Execute with verbose output
-one --agent flow execute <key> -v -i connectionKey=value
-
-# List workflow runs
-one --agent flow runs [flowKey]
-
-# Resume a paused/failed run
-one --agent flow resume <runId>
-\`\`\`
-
-## Important Notes
-
-- **Always use \`--agent\` flag** for structured JSON output
-- **Always call \`one actions knowledge\`** before adding an action step to a workflow
-- Platform names are **kebab-case** (e.g., \`hub-spot\`, not \`HubSpot\`)
-- Connection keys are **inputs**, not hardcoded \u2014 makes workflows portable and shareable
-- Use \`$.input.*\` for input values, \`$.steps.*\` for step results
-- Action IDs in examples (like \`STRIPE_SEARCH_CUSTOMERS_ACTION_ID\`) are placeholders \u2014 always use \`one actions search\` to find the real IDs
-- **Parallel step outputs** are accessible both by index (\`$.steps.parallelStep.output[0]\`) and by substep ID (\`$.steps.substepId.response\`)
-- **Loop step outputs** include iteration details via \`$.steps.myLoop.response.iterations[0].innerStepId.response\`
-- **Code steps** support \`await require('crypto')\`, \`await require('buffer')\`, \`await require('url')\`, \`await require('path')\` \u2014 \`fs\`, \`http\`, \`child_process\`, etc. are blocked
-- **Bash steps** require \`--allow-bash\` flag for security
-- **State is persisted** after every step completion \u2014 resume picks up where it left off
+1. \`relay get <id>\` \u2014 verify endpoint is active with actions configured
+2. \`relay events --platform <p>\` \u2014 check events are arriving
+3. \`relay deliveries --event-id <id>\` \u2014 check delivery status and errors
+4. \`relay event <id>\` \u2014 inspect full payload to verify template paths
 `;
 var TOPICS = [
-  { topic: "overview", description: "Setup, --agent flag, discovery workflow" },
+  { topic: "overview", description: "Setup, features, and quick start for each" },
   { topic: "actions", description: "Search, read docs, and execute platform actions" },
   { topic: "flows", description: "Build and execute multi-step workflows" },
+  { topic: "relay", description: "Receive webhooks and forward to other platforms" },
   { topic: "all", description: "Complete guide (all topics combined)" }
 ];
 function getGuideContent(topic) {
@@ -3407,10 +3681,12 @@ function getGuideContent(topic) {
       return { title: "One CLI \u2014 Agent Guide: Actions", content: GUIDE_ACTIONS };
     case "flows":
       return { title: "One CLI \u2014 Agent Guide: Workflows", content: GUIDE_FLOWS };
+    case "relay":
+      return { title: "One CLI \u2014 Agent Guide: Relay", content: GUIDE_RELAY };
     case "all":
       return {
         title: "One CLI \u2014 Agent Guide: Complete",
-        content: [GUIDE_OVERVIEW, GUIDE_ACTIONS, GUIDE_FLOWS].join("\n---\n\n")
+        content: [GUIDE_OVERVIEW, GUIDE_ACTIONS, GUIDE_FLOWS, GUIDE_RELAY].join("\n---\n\n")
       };
   }
 }
@@ -3419,7 +3695,7 @@ function getAvailableTopics() {
 }
 
 // src/commands/guide.ts
-var VALID_TOPICS = ["overview", "actions", "flows", "all"];
+var VALID_TOPICS = ["overview", "actions", "flows", "relay", "all"];
 async function guideCommand(topic = "all") {
   if (!VALID_TOPICS.includes(topic)) {
     error(
@@ -3432,14 +3708,14 @@ async function guideCommand(topic = "all") {
     json({ topic, title, content, availableTopics });
     return;
   }
-  intro2(pc8.bgCyan(pc8.black(" One Guide ")));
+  intro2(pc9.bgCyan(pc9.black(" One Guide ")));
   console.log();
   console.log(content);
-  console.log(pc8.dim("\u2500".repeat(60)));
+  console.log(pc9.dim("\u2500".repeat(60)));
   console.log(
-    pc8.dim("Available topics: ") + availableTopics.map((t) => pc8.cyan(t.topic)).join(", ")
+    pc9.dim("Available topics: ") + availableTopics.map((t) => pc9.cyan(t.topic)).join(", ")
   );
-  console.log(pc8.dim(`Run ${pc8.cyan("one guide <topic>")} for a specific section.`));
+  console.log(pc9.dim(`Run ${pc9.cyan("one guide <topic>")} for a specific section.`));
 }
 
 // src/lib/platform-meta.ts
@@ -3587,18 +3863,30 @@ The \`--agent\` flag gives structured JSON output. Always include it right
 after \`one\`:
   one --agent <command>
 
+### IMPORTANT: Learn before you use
+Before using any feature (actions, flows, relay), you MUST read the
+corresponding skill documentation first. The skills are bundled with
+the CLI and teach you the correct workflow, required steps, and
+common mistakes to avoid. Never guess \u2014 read the skill, then act.
+
 ### Quick reference:
 - \`one --agent list\` \u2014 See connected platforms and connection keys
 - \`one --agent actions search <platform> "<query>"\` \u2014 Find actions
 - \`one --agent actions knowledge <platform> <actionId>\` \u2014 Read docs (REQUIRED before execute)
 - \`one --agent actions execute <platform> <actionId> <connectionKey>\` \u2014 Execute action
 - \`one --agent flow create\` \u2014 Build multi-step workflows
+- \`one --agent relay create\` \u2014 Set up webhook relay (receive events, forward to other platforms)
 - \`one --agent guide\` \u2014 Full documentation
 - \`one add <platform>\` \u2014 Connect a new platform (interactive, no --agent)
 
 ### Workflow: search -> knowledge -> execute
 Always read the knowledge before executing. It tells you required parameters,
 validation rules, and platform-specific details.
+
+### Webhook Relay
+Use \`one relay\` to receive webhooks from platforms (Stripe, GitHub, etc.)
+and forward event data to other platforms using passthrough actions with
+Handlebars templates. No middleware needed.
 \`\`\``);
   sections.push(buildCurrentState(connections));
   sections.push(`## How To Use the CLI
@@ -3624,6 +3912,17 @@ The \`--agent\` flag goes right after \`one\`, before the subcommand.
 Use \`one flow create\` to build JSON workflows that chain actions across
 platforms with conditions, loops, parallel execution, and transforms.
 
+### Webhook Relay:
+Use \`one relay create\` to receive webhooks from platforms (Stripe, GitHub,
+Airtable, Attio, Google Calendar) and forward event data to any connected
+platform using passthrough actions with Handlebars templates.
+
+### IMPORTANT: Learn before you use
+Before using flows or relay, you MUST read the corresponding skill
+documentation first. The skills teach you the correct workflow, template
+syntax, required steps, and common mistakes. Never guess \u2014 read the
+skill, then act.
+
 Run \`one --agent guide\` for the complete reference documentation with examples.`);
   sections.push(`## What to tell the user
 
@@ -3849,6 +4148,14 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
     one flow execute <key>                Execute a workflow
     one flow validate <key>               Validate a flow
 
+  Webhook Relay:
+    one relay create                      Create a relay endpoint for a connection
+    one relay list                        List relay endpoints
+    one relay activate <id>               Activate with passthrough actions
+    one relay event-types <platform>      List supported event types
+    one relay events                      List received webhook events
+    one relay deliveries                  List delivery attempts
+
   Example \u2014 send an email through Gmail:
     $ one list
     # Find: gmail  operational  live::gmail::default::abc123
@@ -3943,7 +4250,41 @@ 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);
 });
-program.command("guide [topic]").description("Full CLI usage guide for agents (topics: overview, actions, flows, all)").action(async (topic) => {
+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);
+});
+relay.command("list").alias("ls").description("List all relay endpoints").option("--limit <n>", "Max results per page").option("--page <n>", "Page number").action(async (options) => {
+  await relayListCommand(options);
+});
+relay.command("get <id>").description("Get details of a relay endpoint").action(async (id) => {
+  await relayGetCommand(id);
+});
+relay.command("update <id>").description("Update a relay endpoint").option("--description <desc>", "Update description").option("--active", "Set active").option("--no-active", "Set inactive").option("--event-filters <json>", "JSON array of event types").option("--tags <json>", "JSON array of tags").option("--actions <json>", "JSON array of actions (url, passthrough, or agent)").action(async (id, options) => {
+  await relayUpdateCommand(id, options);
+});
+relay.command("delete <id>").description("Delete a relay endpoint").action(async (id) => {
+  await relayDeleteCommand(id);
+});
+relay.command("activate <id>").description("Activate a relay endpoint with forwarding actions").requiredOption("--actions <json>", "JSON array of actions (url, passthrough, or agent)").option("--webhook-secret <secret>", "Webhook signing secret for signature verification").action(async (id, options) => {
+  await relayActivateCommand(id, options);
+});
+relay.command("events").description("List received webhook events").option("--limit <n>", "Max results per page").option("--page <n>", "Page number").option("--platform <platform>", "Filter by platform").option("--event-type <type>", "Filter by event type").option("--after <iso>", "Events after this timestamp").option("--before <iso>", "Events before this timestamp").action(async (options) => {
+  await relayEventsCommand(options);
+});
+relay.command("event <id>").description("Get details of a specific webhook event").action(async (id) => {
+  await relayEventGetCommand(id);
+});
+relay.command("deliveries").description("List delivery attempts for an endpoint or event").option("--endpoint-id <id>", "Relay endpoint ID").option("--event-id <id>", "Relay event ID").action(async (options) => {
+  await relayDeliveriesCommand(options);
+});
+relay.command("event-types <platform>").description("List supported webhook event types for a platform").action(async (platform) => {
+  await relayEventTypesCommand(platform);
+});
+program.command("guide [topic]").description("Full CLI usage guide for agents (topics: overview, actions, flows, relay, all)").action(async (topic) => {
   await guideCommand(topic);
 });
 program.command("onboard").description("Agent onboarding \u2014 teaches your agent what the One CLI can do").option("--step <number>", "Run a specific onboarding step (1, 2, or 3)").action(async (options) => {