@withone/cli 1.15.0 → 1.16.0

package/dist/index.js

@@ -1714,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") {
@@ -1740,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") {
@@ -1763,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") {
@@ -1786,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}]`;
@@ -1800,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);
-        }
+    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 === "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);
-        }
+      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 === "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"' });
-        }
+      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 === "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 (fd.type === "boolean" && value !== void 0 && typeof value !== "boolean") {
+        errors.push({ path: fieldPath, message: `${fieldName} must be a boolean` });
       }
-    } 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' });
+      if (fd.stepsArray) {
+        if (!Array.isArray(value)) {
+          errors.push({ path: fieldPath, message: `"${fieldName}" must be 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" });
+          validateStepsArray(value, fieldPath, errors);
         }
       }
-    } 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" });
-        }
-      }
-    } 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' });
-        } 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" });
-        }
-      }
-    } else if (type === "bash") {
-      if (!s.bash || typeof s.bash !== "object") {
-        errors.push({ path: `${path4}.bash`, message: 'Bash step must have a "bash" config object' });
-      } else {
-        const b = s.bash;
-        if (!b.command || typeof b.command !== "string") {
-          errors.push({ path: `${path4}.bash.command`, message: 'Bash must have a string "command"' });
-        }
-        if (b.timeout !== void 0 && (typeof b.timeout !== "number" || b.timeout <= 0)) {
-          errors.push({ path: `${path4}.bash.timeout`, message: "timeout must be a positive number" });
-        }
-        if (b.parseJson !== void 0 && typeof b.parseJson !== "boolean") {
-          errors.push({ path: `${path4}.bash.parseJson`, message: "parseJson must be a boolean" });
+      if (descriptor.type === "paginate" && fieldName === "action") {
+        if (typeof value === "object" && value !== null) {
+          const a = value;
+          if (!a.platform) errors.push({ path: `${fieldPath}.platform`, message: 'Action must have "platform"' });
+          if (!a.actionId) errors.push({ path: `${fieldPath}.actionId`, message: 'Action must have "actionId"' });
+          if (!a.connectionKey) errors.push({ path: `${fieldPath}.connectionKey`, message: 'Action must have "connectionKey"' });
         }
       }
     }
   }
 }
+function detectFlatConfigHint(step, descriptor) {
+  const requiredFields = Object.entries(descriptor.fields).filter(([, fd]) => fd.required).map(([name]) => name);
+  const flatFields = requiredFields.filter((f) => f in step);
+  if (flatFields.length > 0) {
+    return `. Hint: "${flatFields.join('", "')}" must be nested inside "${descriptor.configKey}": { ... }, not placed directly on the step`;
+  }
+  return "";
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 function validateStepIds(flow2) {
   const errors = [];
   const seen = /* @__PURE__ */ new Set();
+  const nestedKeys = getNestedStepsKeys();
   function collectIds(steps, pathPrefix) {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
@@ -1992,13 +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");
@@ -2007,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;
   }
@@ -2072,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}]`)
+            );
+          }
+        }
       }
     }
   }
@@ -2186,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 = [];
@@ -2496,6 +2886,205 @@ function colorStatus(status) {
       return status;
   }
 }
+var SCAFFOLD_TEMPLATES = {
+  basic: () => ({
+    key: "my-workflow",
+    name: "My Workflow",
+    description: "A basic workflow with a single action step",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key for the platform",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "step1",
+        name: "Execute action",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey",
+          data: {}
+        }
+      }
+    ]
+  }),
+  conditional: () => ({
+    key: "my-conditional-workflow",
+    name: "Conditional Workflow",
+    description: "Fetch data, then branch based on results",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetch",
+        name: "Fetch data",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "decide",
+        name: "Check results",
+        type: "condition",
+        condition: {
+          expression: "$.steps.fetch.response.data && $.steps.fetch.response.data.length > 0",
+          then: [
+            {
+              id: "handleFound",
+              name: "Handle found",
+              type: "transform",
+              transform: { expression: "$.steps.fetch.response.data[0]" }
+            }
+          ],
+          else: [
+            {
+              id: "handleNotFound",
+              name: "Handle not found",
+              type: "transform",
+              transform: { expression: "({ error: 'No results found' })" }
+            }
+          ]
+        }
+      }
+    ]
+  }),
+  loop: () => ({
+    key: "my-loop-workflow",
+    name: "Loop Workflow",
+    description: "Fetch a list, then process each item",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetchList",
+        name: "Fetch items",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "processItems",
+        name: "Process each item",
+        type: "loop",
+        loop: {
+          over: "$.steps.fetchList.response.data",
+          as: "item",
+          steps: [
+            {
+              id: "processItem",
+              name: "Process single item",
+              type: "transform",
+              transform: { expression: "({ id: $.loop.item.id, processed: true })" }
+            }
+          ]
+        }
+      },
+      {
+        id: "summary",
+        name: "Generate summary",
+        type: "transform",
+        transform: { expression: "({ total: $.steps.fetchList.response.data.length })" }
+      }
+    ]
+  }),
+  ai: () => ({
+    key: "my-ai-workflow",
+    name: "AI Analysis Workflow",
+    description: "Fetch data, analyze with Claude, and send results",
+    version: "1",
+    inputs: {
+      connectionKey: {
+        type: "string",
+        required: true,
+        description: "Connection key for data source",
+        connection: { platform: "PLATFORM_NAME" }
+      }
+    },
+    steps: [
+      {
+        id: "fetchData",
+        name: "Fetch raw data",
+        type: "action",
+        action: {
+          platform: "PLATFORM_NAME",
+          actionId: "ACTION_ID_FROM_SEARCH",
+          connectionKey: "$.input.connectionKey"
+        }
+      },
+      {
+        id: "writeData",
+        name: "Write data for analysis",
+        type: "file-write",
+        fileWrite: {
+          path: "/tmp/workflow-data.json",
+          content: "$.steps.fetchData.response"
+        }
+      },
+      {
+        id: "analyze",
+        name: "Analyze with Claude",
+        type: "bash",
+        bash: {
+          command: `cat /tmp/workflow-data.json | claude --print 'Analyze this data and return JSON with: {"summary": "...", "insights": [...], "recommendations": [...]}. Return ONLY valid JSON.' --output-format json`,
+          timeout: 18e4,
+          parseJson: true
+        }
+      },
+      {
+        id: "formatResult",
+        name: "Format analysis output",
+        type: "code",
+        code: {
+          source: "const a = $.steps.analyze.output;\nreturn {\n  summary: a.summary,\n  insights: a.insights,\n  recommendations: a.recommendations\n};"
+        }
+      }
+    ]
+  })
+};
+async function flowScaffoldCommand(template) {
+  const templateName = template || "basic";
+  const templateFn = SCAFFOLD_TEMPLATES[templateName];
+  if (!templateFn) {
+    const available = Object.keys(SCAFFOLD_TEMPLATES).join(", ");
+    if (isAgentMode()) {
+      json({ error: `Unknown template "${templateName}". Available: ${available}` });
+      process.exit(1);
+    }
+    error(`Unknown template "${templateName}". Available: ${available}`);
+  }
+  const scaffold = templateFn();
+  if (isAgentMode()) {
+    json(scaffold);
+    return;
+  }
+  console.log(JSON.stringify(scaffold, null, 2));
+}
 
 // src/commands/relay.ts
 import pc8 from "picocolors";
@@ -2856,9 +3445,9 @@ one --agent <command>
 
 All commands return JSON. If an \`error\` key is present, the command failed.
 
-## IMPORTANT: Learn before you use
+## IMPORTANT: Read the guide before you act
 
-Before using any feature, you MUST read the corresponding skill documentation first. The skills are bundled with the CLI and teach you the correct workflow, required steps, template syntax, and common mistakes. Never guess \u2014 read the skill, then act.
+Before using any feature, read its guide section first: \`one guide actions\`, \`one guide flows\`, or \`one guide relay\`. The guide teaches you the correct workflow, required fields, and common mistakes. Never guess \u2014 read the guide, then act.
 
 ## Features
 
@@ -2996,91 +3585,7 @@ All errors return JSON: \`{"error": "message"}\`. Check the \`error\` key.
 - If search returns no results, try broader queries
 - Access control settings from \`one config\` may restrict execution
 `;
-var GUIDE_FLOWS = `# One Flows \u2014 Reference
-
-## Overview
-
-Workflows are JSON files at \`.one/flows/<key>.flow.json\` that chain actions across platforms.
-
-## Commands
-
-\`\`\`bash
-one --agent flow create <key> --definition '<json>'   # Create
-one --agent flow list                                  # List
-one --agent flow validate <key>                        # Validate
-one --agent flow execute <key> -i name=value           # Execute
-one --agent flow execute <key> --dry-run --mock        # Test with mock data
-one --agent flow execute <key> --allow-bash            # Enable bash steps
-one --agent flow runs [flowKey]                        # List past runs
-one --agent flow resume <runId>                        # Resume failed run
-\`\`\`
-
-## Building a Workflow
-
-1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
-2. **Discover connections** \u2014 \`one --agent connection list\`
-3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
-4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
-5. **Validate** \u2014 \`one --agent flow validate <key>\`
-6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\`
-
-## Step Types
-
-| Type | Purpose |
-|------|---------|
-| \`action\` | Execute a platform API action |
-| \`transform\` | Single JS expression (implicit return) |
-| \`code\` | Multi-line async JS (explicit return) |
-| \`condition\` | If/then/else branching |
-| \`loop\` | Iterate over array with optional concurrency |
-| \`parallel\` | Run steps concurrently |
-| \`file-read\` | Read file (optional JSON parse) |
-| \`file-write\` | Write/append to file |
-| \`while\` | Do-while loop with condition |
-| \`flow\` | Execute a sub-flow |
-| \`paginate\` | Auto-paginate API results |
-| \`bash\` | Shell command (requires \`--allow-bash\`) |
-
-## Selectors
-
-| Pattern | Resolves To |
-|---------|-------------|
-| \`$.input.paramName\` | Input value |
-| \`$.steps.stepId.response\` | Full API response |
-| \`$.steps.stepId.response.data[0].email\` | Nested field |
-| \`$.steps.stepId.response.data[*].id\` | Wildcard array map |
-| \`$.env.MY_VAR\` | Environment variable |
-| \`$.loop.item\` / \`$.loop.i\` | Loop iteration |
-| \`"Hello {{$.steps.getUser.response.name}}"\` | String interpolation |
-
-## Error Handling
-
-\`\`\`json
-{"onError": {"strategy": "retry", "retries": 3, "retryDelayMs": 1000}}
-\`\`\`
-
-Strategies: \`fail\` (default), \`continue\`, \`retry\`, \`fallback\`
-
-Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
-
-## AI-Augmented Pattern
-
-For workflows that need analysis/summarization, use the file-write \u2192 bash \u2192 code pattern:
-
-1. \`file-write\` \u2014 save data to temp file
-2. \`bash\` \u2014 \`claude --print\` analyzes it (\`parseJson: true\`, \`timeout: 180000\`)
-3. \`code\` \u2014 parse and structure the output
-
-Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, not in parallel.
-
-## Notes
-
-- Connection keys are **inputs**, not hardcoded
-- Action IDs in examples are placeholders \u2014 always use \`actions search\`
-- Code steps allow \`crypto\`, \`buffer\`, \`url\`, \`path\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
-- Bash steps require \`--allow-bash\` flag
-- State is persisted after every step \u2014 resume picks up where it left off
-`;
+var GUIDE_FLOWS = generateFlowGuide();
 var GUIDE_RELAY = `# One Relay \u2014 Reference
 
 ## Overview
@@ -3745,6 +4250,9 @@ flow.command("resume <runId>").description("Resume a paused or failed workflow r
 flow.command("runs [flowKey]").description("List workflow runs (optionally filtered by flow key)").action(async (flowKey) => {
   await flowRunsCommand(flowKey);
 });
+flow.command("scaffold [template]").description("Generate a workflow scaffold (templates: basic, conditional, loop, ai)").action(async (template) => {
+  await flowScaffoldCommand(template);
+});
 var relay = program.command("relay").alias("r").description("Receive webhooks from platforms and relay them via passthrough actions");
 relay.command("create").description("Create a new relay endpoint for a connection").requiredOption("--connection-key <key>", "Connection key for the source platform").option("--description <desc>", "Description of the relay endpoint").option("--event-filters <json>", `JSON array of event types to filter (e.g. '["customer.created"]')`).option("--tags <json>", "JSON array of tags").option("--create-webhook", "Automatically register the webhook with the source platform").action(async (options) => {
   await relayCreateCommand(options);

package/package.json

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

package/skills/one-flow/SKILL.md

@@ -19,6 +19,8 @@ description: |
 
 # One Workflows — Multi-Step API Workflows
 
+<!-- Canonical flow schema: src/lib/flow-schema.ts (drives both validation and guide generation) -->
+
 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 — e.g., look up a Stripe customer, then send them a welcome email via Gmail.
 
 ## 1. Overview