@withone/cli 1.13.9 → 1.15.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.`
@@ -2495,8 +2497,345 @@ function colorStatus(status) {
   }
 }
 
-// src/commands/guide.ts
+// 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;
+    }
+    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"}`);
+  }
+}
+
+// src/commands/guide.ts
+import pc9 from "picocolors";
 
 // src/lib/guide-content.ts
 var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
@@ -2517,886 +2856,316 @@ 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
+## IMPORTANT: Learn before you use
 
-\`\`\`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.
+Before using any feature, you MUST read the corresponding skill documentation first. The skills are bundled with the CLI and teach you the correct workflow, required steps, template syntax, and common mistakes. Never guess \u2014 read the skill, then act.
 
-- \`<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"\`)
+## Features
 
-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\`.
+### 1. Actions \u2014 Execute API calls on 200+ platforms
+Search for actions, read their docs, and execute them. This is the core workflow.
 
-Example:
+**Quick start:**
 \`\`\`bash
-one --agent actions search gmail "send email" -t execute
+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
 \`\`\`
 
-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>
-\`\`\`
+**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
 
-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.
+Do NOT pass path or query parameters in \`-d\` \u2014 use the correct flags.
 
-Always call this before executing \u2014 it tells you exactly what parameters are required and how to structure the request.
+### 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.
 
-Example:
+**Quick start:**
 \`\`\`bash
-one --agent actions knowledge gmail 67890abcdef
+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
 \`\`\`
 
-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\`
+**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
 
-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
+### 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.
 
-Examples:
+**Quick start:**
 \`\`\`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": {...}}
+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
 \`\`\`
 
-## Error Handling
+**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
 
-All errors return JSON in agent mode:
-\`\`\`json
-{"error": "Error message here"}
-\`\`\`
+## Topics
 
-Parse the output as JSON. If the \`error\` key is present, the command failed \u2014 report the error message to the user.
+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
 
 ## 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
+- **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_FLOWS = `# One Workflows \u2014 Multi-Step API Workflows
+var GUIDE_ACTIONS = `# One Actions \u2014 Reference
 
-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.
+## Workflow: search \u2192 knowledge \u2192 execute
 
-## 1. Overview
+Always follow this sequence. Never skip the knowledge step.
 
-- 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
+### 1. List Connections
 
 \`\`\`bash
 one --agent connection list
 \`\`\`
 
-Find out which platforms are connected and get their connection keys.
+Returns platforms, status, connection keys, and tags.
 
-### Step 2: For EACH API action needed, get the knowledge
+### 2. Search Actions
 
 \`\`\`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
+- 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
 
-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
+### 3. Get Knowledge
 
 \`\`\`bash
-one --agent flow create <key> --definition '<json>'
+one --agent actions knowledge <platform> <actionId>
 \`\`\`
 
-Or write directly to \`.one/flows/<key>.flow.json\`.
+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.
 
-### Step 5: Validate
+### 4. Execute
 
 \`\`\`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" }
-    },
-    "gmailConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Gmail connection key from one connection list",
-      "connection": { "platform": "gmail" }
-    },
-    "customerEmail": {
-      "type": "string",
-      "required": true,
-      "description": "Customer email to look up"
-    }
-  },
-  "steps": [
-    {
-      "id": "stepId",
-      "name": "Human-readable label",
-      "type": "action",
-      "action": {
-        "platform": "stripe",
-        "actionId": "the-action-id-from-search",
-        "connectionKey": "$.input.stripeConnectionKey",
-        "data": {},
-        "pathVars": {},
-        "queryParams": {},
-        "headers": {}
-      }
-    }
-  ]
-}
-\`\`\`
-
-### Input declarations
-
-| Field | Type | Description |
-|---|---|---|
-| \`type\` | string | \`string\`, \`number\`, \`boolean\`, \`object\`, \`array\` |
-| \`required\` | boolean | Whether this input must be provided (default: true) |
-| \`default\` | any | Default value if not provided |
-| \`description\` | string | Human-readable description |
-| \`connection\` | object | Connection metadata: \`{ "platform": "gmail" }\` \u2014 enables auto-resolution |
-
-**Connection inputs** have a \`connection\` field. If the user has exactly one connection for that platform, the workflow engine auto-resolves it.
-
-## 4. Selector Syntax Reference
-
-| Pattern | Resolves To |
-|---|---|
-| \`$.input.gmailConnectionKey\` | Input value (including connection keys) |
-| \`$.input.customerEmail\` | Any input parameter |
-| \`$.steps.stepId.response\` | Full API response from a step |
-| \`$.steps.stepId.response.data[0].email\` | Nested field with array index |
-| \`$.steps.stepId.response.data[*].id\` | Wildcard \u2014 maps array to field |
-| \`$.env.MY_VAR\` | Environment variable |
-| \`$.loop.item\` | Current loop item |
-| \`$.loop.i\` | Current loop index |
-| \`"Hello {{$.steps.getUser.response.data.name}}"\` | String interpolation |
-
-**Rules:**
-- A value that is purely \`$.xxx\` resolves to the raw type (object, array, number)
-- A string containing \`{{$.xxx}}\` does string interpolation (stringifies objects)
-- Selectors inside objects/arrays are resolved recursively
-
-## 5. Step Types Reference
-
-### \`action\` \u2014 Execute a One API action
-
-\`\`\`json
-{
-  "id": "findCustomer",
-  "name": "Search Stripe customers",
-  "type": "action",
-  "action": {
-    "platform": "stripe",
-    "actionId": "conn_mod_def::xxx::yyy",
-    "connectionKey": "$.input.stripeConnectionKey",
-    "data": {
-      "query": "email:'{{$.input.customerEmail}}'"
-    }
-  }
-}
-\`\`\`
-
-### \`transform\` \u2014 Transform data with a JS expression
-
-\`\`\`json
-{
-  "id": "extractNames",
-  "name": "Extract customer names",
-  "type": "transform",
-  "transform": {
-    "expression": "$.steps.findCustomer.response.data.map(c => c.name)"
-  }
-}
-\`\`\`
-
-The expression is evaluated with the full flow context as \`$\`.
-
-### \`code\` \u2014 Run multi-line JavaScript
-
-Unlike \`transform\` (single expression, implicit return), \`code\` runs a full function body with explicit \`return\`. Use it when you need variables, loops, try/catch, or \`await\`.
-
-\`\`\`json
-{
-  "id": "processData",
-  "name": "Process and enrich data",
-  "type": "code",
-  "code": {
-    "source": "const customers = $.steps.listCustomers.response.data;\\nconst enriched = customers.map(c => ({\\n  ...c,\\n  tier: c.spend > 1000 ? 'gold' : 'silver'\\n}));\\nreturn enriched;"
-  }
-}
-\`\`\`
-
-The \`source\` field contains a JS function body. The flow context is available as \`$\`. The function is async, so you can use \`await\`. The return value is stored as the step result.
-
-### \`condition\` \u2014 If/then/else branching
-
-\`\`\`json
-{
-  "id": "checkFound",
-  "name": "Check if customer was found",
-  "type": "condition",
-  "condition": {
-    "expression": "$.steps.findCustomer.response.data.length > 0",
-    "then": [
-      { "id": "sendEmail", "name": "Send welcome email", "type": "action", "action": { "..." : "..." } }
-    ],
-    "else": [
-      { "id": "logNotFound", "name": "Log not found", "type": "transform", "transform": { "expression": "'Customer not found'" } }
-    ]
-  }
-}
-\`\`\`
-
-### \`loop\` \u2014 Iterate over an array
-
-\`\`\`json
-{
-  "id": "processOrders",
-  "name": "Process each order",
-  "type": "loop",
-  "loop": {
-    "over": "$.steps.listOrders.response.data",
-    "as": "order",
-    "indexAs": "i",
-    "maxIterations": 1000,
-    "maxConcurrency": 5,
-    "steps": [
-      {
-        "id": "createInvoice",
-        "name": "Create invoice for order",
-        "type": "action",
-        "action": {
-          "platform": "quickbooks",
-          "actionId": "...",
-          "connectionKey": "$.input.qbConnectionKey",
-          "data": { "amount": "$.loop.order.total" }
-        }
-      }
-    ]
-  }
-}
+one --agent actions execute <platform> <actionId> <connectionKey> [options]
 \`\`\`
 
-- \`maxConcurrency\` (optional): When set > 1, loop iterations run in parallel batches of that size. Default is sequential (1).
+**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
 
-### \`parallel\` \u2014 Run steps concurrently
+**Do NOT** pass path or query parameters in \`-d\`. Use the correct flags.
 
-\`\`\`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": { "...": "..." } }
-    ]
-  }
-}
-\`\`\`
+## Error Handling
 
-### \`file-read\` \u2014 Read from filesystem
+All errors return JSON: \`{"error": "message"}\`. Check the \`error\` key.
 
-\`\`\`json
-{
-  "id": "readConfig",
-  "name": "Read config file",
-  "type": "file-read",
-  "fileRead": { "path": "./data/config.json", "parseJson": true }
-}
-\`\`\`
+## Notes
 
-### \`file-write\` \u2014 Write to filesystem
+- 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 = `# One Flows \u2014 Reference
 
-\`\`\`json
-{
-  "id": "writeResults",
-  "name": "Save results",
-  "type": "file-write",
-  "fileWrite": {
-    "path": "./output/results.json",
-    "content": "$.steps.transform.output",
-    "append": false
-  }
-}
-\`\`\`
+## Overview
 
-### \`while\` \u2014 Condition-driven loop (do-while)
+Workflows are JSON files at \`.one/flows/<key>.flow.json\` that chain actions across platforms.
 
-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.
+## Commands
 
-\`\`\`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"
-          }
-        }
-      }
-    ]
-  }
-}
+\`\`\`bash
+one --agent flow create <key> --definition '<json>'   # Create
+one --agent flow list                                  # List
+one --agent flow validate <key>                        # Validate
+one --agent flow execute <key> -i name=value           # Execute
+one --agent flow execute <key> --dry-run --mock        # Test with mock data
+one --agent flow execute <key> --allow-bash            # Enable bash steps
+one --agent flow runs [flowKey]                        # List past runs
+one --agent flow resume <runId>                        # Resume failed run
 \`\`\`
 
-| 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 |
+## Building a Workflow
+
+1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
+2. **Discover connections** \u2014 \`one --agent connection list\`
+3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
+4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
+5. **Validate** \u2014 \`one --agent flow validate <key>\`
+6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\`
+
+## Step Types
+
+| Type | Purpose |
+|------|---------|
+| \`action\` | Execute a platform API action |
+| \`transform\` | Single JS expression (implicit return) |
+| \`code\` | Multi-line async JS (explicit return) |
+| \`condition\` | If/then/else branching |
+| \`loop\` | Iterate over array with optional concurrency |
+| \`parallel\` | Run steps concurrently |
+| \`file-read\` | Read file (optional JSON parse) |
+| \`file-write\` | Write/append to file |
+| \`while\` | Do-while loop with condition |
+| \`flow\` | Execute a sub-flow |
+| \`paginate\` | Auto-paginate API results |
+| \`bash\` | Shell command (requires \`--allow-bash\`) |
+
+## Selectors
 
-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\`.
-
-### \`flow\` \u2014 Execute a sub-flow
+| 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 |
 
-Loads and executes another saved flow, enabling flow composition. Circular flows are detected and blocked.
+## Error Handling
 
 \`\`\`json
-{
-  "id": "processCustomer",
-  "name": "Run customer enrichment flow",
-  "type": "flow",
-  "flow": {
-    "key": "enrich-customer",
-    "inputs": {
-      "email": "$.steps.getCustomer.response.email",
-      "connectionKey": "$.input.hubspotConnectionKey"
-    }
-  }
-}
+{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
 \`\`\`
 
-| 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) |
+Strategies: \`fail\` (default), \`continue\`, \`retry\`, \`fallback\`
 
-### \`paginate\` \u2014 Auto-collect paginated API results
+Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
 
-Automatically pages through a paginated API, collecting all results into a single array.
+## AI-Augmented Pattern
 
-\`\`\`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
-  }
-}
-\`\`\`
+For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
 
-| 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 |
+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
 
-### \`bash\` \u2014 Execute shell commands
+Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
 
-Runs a shell command. **Requires \`--allow-bash\` flag** for security.
+## Notes
 
-\`\`\`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
-  }
-}
-\`\`\`
-
-| 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 |
+- Connection keys are **inputs**, not hardcoded
+- Action IDs in examples are placeholders \u2014 always use \`actions search\`
+- Code steps allow \`crypto\`, \`buffer\`, \`url\`, \`path\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
+- Bash steps require \`--allow-bash\` flag
+- State is persisted after every step \u2014 resume picks up where it left off
+`;
+var GUIDE_RELAY = `# One Relay \u2014 Reference
 
-**Security:** Bash steps are blocked by default. Pass \`--allow-bash\` to \`one flow execute\` to enable them.
+## Overview
 
-## 6. Error Handling
+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.
 
-### \`onError\` strategies
+## Commands
 
-\`\`\`json
-{
-  "id": "riskyStep",
-  "name": "Might fail",
-  "type": "action",
-  "onError": {
-    "strategy": "retry",
-    "retries": 3,
-    "retryDelayMs": 1000
-  },
-  "action": { "...": "..." }
-}
+\`\`\`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
 \`\`\`
 
-| 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 |
+## Building a Relay
 
-### Conditional execution
+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
 
-Skip a step based on previous results:
+## Template Context
 
-\`\`\`json
-{
-  "id": "sendEmail",
-  "name": "Send email only if customer found",
-  "type": "action",
-  "if": "$.steps.findCustomer.response.data.length > 0",
-  "action": { "...": "..." }
-}
-\`\`\`
-
-## 7. Updating Existing Workflows
-
-To modify an existing workflow:
+| 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 |
 
-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>\`
+Access nested fields: \`{{payload.data.object.email}}\`
 
-## 8. Complete Examples
-
-### Example 1: Simple 2-step workflow \u2014 Search Stripe customer, send Gmail 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>
-
-# Execute a workflow
-one --agent flow execute <key> -i connectionKey=value -i param=value
-
-# Execute with dry run (validate only)
-one --agent flow execute <key> --dry-run -i connectionKey=value
+## Supported Source Platforms
 
-# Execute with mock mode (dry-run + mock API responses, runs transforms/code normally)
-one --agent flow execute <key> --dry-run --mock -i connectionKey=value
+Airtable, Attio, GitHub, Google Calendar, Stripe
 
-# Execute with bash steps enabled
-one --agent flow execute <key> --allow-bash -i connectionKey=value
+Any connected platform can be a destination via passthrough actions.
 
-# 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>
-\`\`\`
+## Debugging
 
-## 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 +3176,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 +3190,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 +3203,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 +3358,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 +3407,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 +3643,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 +3745,38 @@ 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) => {
+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) => {