nodestorm-mcp 0.1.0

package/dist/workflow-guide.md

@@ -0,0 +1,1655 @@
+# Workflow Builder Agent Guide
+
+**Purpose**: Enable an LLM agent to build executable NodeStorm workflow graphs from natural language prompts.
+
+**Last Updated**: 2026-01-19
+
+---
+
+## 1. Quick Reference
+
+### Handle Naming Convention
+Use these simple handle IDs (they are automatically normalized during import):
+
+```
+sourceHandle: "output"   # Standard output (sends data)
+targetHandle: "input"    # Standard input (receives data)
+sourceHandle: "true"     # Boolean true branch
+sourceHandle: "false"    # Boolean false branch
+sourceHandle: "each"     # Iteration (list/table)
+```
+
+**Note**: Both simple (`"output"`) and prefixed (`"{nodeId}-output-handle"`) formats are accepted.
+
+### Edge Branch Types
+| Branch Value | Used By | Purpose |
+|-------------|---------|---------|
+| `null` or omit | All nodes | Regular data flow |
+| `"true"` | boolean | True condition path |
+| `"false"` | boolean | False condition path |
+| `"each"` | list, table | Iteration (run child for each item) |
+| `"{case_name}"` | switch | Route to specific case |
+
+### Valid Node Types (EXACT VALUES)
+**CRITICAL**: The `type` field must be one of these exact lowercase values:
+
+```
+text, list, table, search, scraper, file, prompt, boolean, json, switch, wait, aggregate, http_request, email, google_drive, transcription, image_generation
+```
+
+**DO NOT use category names** like "Data Sources" or "AI/LLM" - use the exact type values above.
+
+| Category | Valid `type` Values |
+|----------|---------------------|
+| Data | `text`, `list`, `table`, `file` |
+| Web | `search`, `scraper` |
+| AI | `prompt`, `boolean`, `json` |
+| Control | `switch`, `wait`, `aggregate` |
+| Actions | `http_request`, `email` |
+| Integrations | `google_drive` |
+| Media | `transcription`, `image_generation` |
+
+### Minimal Valid Graph Template
+```json
+{
+  "nodes": [
+    {
+      "id": "text-1",
+      "type": "text",
+      "position": { "x": 100, "y": 100 },
+      "data": { "label": "text", "input": "Hello world" }
+    }
+  ],
+  "edges": []
+}
+```
+
+---
+
+## 2. Graph JSON Schema
+
+### 2.1 Top-Level Structure
+```json
+{
+  "nodes": [ /* Array of Node objects */ ],
+  "edges": [ /* Array of Edge objects */ ]
+}
+```
+
+### 2.2 Node Schema
+```typescript
+interface Node {
+  id: string;           // Unique identifier, format: "{type}-{uuid}" or custom
+  type: string;         // One of the 19 supported node types
+  position: {
+    x: number;          // Canvas X coordinate
+    y: number;          // Canvas Y coordinate
+  };
+  data: {
+    label: string;      // Display label (usually same as type)
+    // ... type-specific configuration fields
+  };
+}
+```
+
+### 2.3 Edge Schema
+```typescript
+interface Edge {
+  id: string;           // Unique identifier, format: "edge-{uuid}"
+  source: string;       // Source node ID
+  target: string;       // Target node ID
+  sourceHandle: string; // Format: "{sourceNodeId}-{handleType}-handle"
+  targetHandle: string; // Format: "{targetNodeId}-input-handle"
+  branch?: string;      // null | "true" | "false" | "each" | "{case_name}"
+  type: "custom";       // Required for ReactFlow rendering
+  markerEnd: { type: "arrowClosed" };  // Arrow at target end
+  style: { strokeWidth: 2 } | { strokeWidth: 2, strokeDasharray: "5,5" };  // Dashed for "each" edges
+}
+```
+
+### 2.4 Position Guidelines
+- **Horizontal spacing**: 300px between nodes
+- **Vertical spacing**: 150px between parallel branches
+- **Root nodes**: Start at x: 100, y: 100
+- **Flow direction**: Left to right (increasing X)
+
+### 2.5 ID Generation
+- Use format: `{type}-{random}` (e.g., `prompt-abc123`)
+- IDs must be unique within the graph
+- Edge IDs: `edge-{random}` or `e{index}`
+
+---
+
+## 3. Complete Node Type Catalog
+
+### 3.1 DATA NODES
+
+#### `text` - Static Text Input
+**Purpose**: Provide static text content to the workflow.
+
+**Config Schema**:
+```json
+{
+  "label": "text",
+  "input": "The static text content goes here"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ text: "The static text content" }`
+
+**Tip**: Most nodes (search, prompt, etc.) can work as root nodes with their own `input` field. Use `text` when you need a dedicated, editable text input at the start of a flow.
+
+---
+
+#### `list` - List Extractor/Creator
+**Purpose**: Extract list items using LLM OR enter items manually.
+
+**Config Schema (Extract Mode)**:
+```json
+{
+  "label": "list",
+  "mode": "extract",
+  "input": "Extract all company names mentioned"
+}
+```
+
+**Config Schema (Manual Mode)**:
+```json
+{
+  "label": "list",
+  "mode": "manual",
+  "input": "item1\nitem2\nitem3"
+}
+```
+
+**Note**: Manual mode uses `mode: "manual"` and the `input` field (not `"manual_input"` or `"manual_list_input"`).
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+- Each (iteration): `{id}-each-handle` (SOURCE)
+
+**Output**: `{ items: [...], list: [...], count: N, text: "item1\nitem2..." }`
+
+---
+
+#### `table` - Tabular Data
+**Purpose**: Store and iterate over tabular data. Import CSV files, paste from clipboard, or build tables manually.
+
+**Config Schema**:
+```json
+{
+  "label": "table",
+  "columns": [
+    { "id": "col_1", "name": "Name", "type": "text" },
+    { "id": "col_2", "name": "Email", "type": "text" }
+  ],
+  "rows": [
+    { "col_1": "John Doe", "col_2": "john@example.com" },
+    { "col_1": "Jane Smith", "col_2": "jane@example.com" }
+  ],
+  "row_count": 2,
+  "storage_mode": "inline"
+}
+```
+
+**Config Options**:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `columns` | array | `[]` | Column definitions with id, name, and type |
+| `rows` | array | `[]` | Row data (inline storage) |
+| `row_count` | number | `0` | Total row count (used for file storage display) |
+| `storage_mode` | enum | `"inline"` | `"inline"` (in config) or `"file"` (UserFile) |
+| `file_id` | string | `null` | UserFile ID when using file storage |
+
+**Column Types**: `text`, `number`, `date`, `boolean`
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+- Each (iteration): `{id}-each-handle` (SOURCE)
+
+**Output**: `{ rows: [...], list: [...], columns: [...], count: N, text: "N rows" }`
+
+**Iteration**: Connect `{id}-each-handle` to child with `branch: "each"` to iterate over rows. Each row is passed as an object with column values accessible by column ID.
+
+**Storage**: Tables under 500KB are stored inline in node config. Larger tables automatically use UserFile storage.
+
+**Limits**: Max 5000 rows, 50 columns, 500KB inline (then file storage)
+
+---
+
+#### `search` - Web Search
+**Purpose**: Search the web using Tavily AI Search (primary) or Brave Search (fallback).
+
+**Config Schema**:
+```json
+{
+  "label": "search",
+  "input": "Find information about...",
+  "useLlmCleaning": true,
+  "topic": "general",
+  "searchDepth": "basic",
+  "timeRange": "",
+  "includeDomains": [],
+  "excludeDomains": [],
+  "maxResults": 8,
+  "includeAnswer": false,
+  "modelConfig": {
+    "chat_model": "gpt-5.4-mini",
+    "temperature": 0.7,
+    "maxTokens": 100
+  }
+}
+```
+
+**Config Options**:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `input` | string | "" | Search query or instructions |
+| `useLlmCleaning` | boolean | `true` | AI optimizes query before search |
+| `topic` | enum | `"general"` | `"general"`, `"news"`, `"finance"` |
+| `searchDepth` | enum | `"basic"` | `"basic"` (1 credit), `"advanced"` (2 credits) |
+| `timeRange` | enum | `""` | `""` (any), `"day"`, `"week"`, `"month"`, `"year"` |
+| `includeDomains` | array | `[]` | Only include results from these domains |
+| `excludeDomains` | array | `[]` | Exclude results from these domains |
+| `maxResults` | number | `8` | Number of results (1-20) |
+| `includeAnswer` | boolean | `false` | Include AI-generated answer summary |
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ text: "formatted results", results: [...], query: "optimized query", provider: "tavily"|"brave" }`
+
+**Notes**:
+- Tavily is used as primary provider when `TAVILY_API_KEY` is configured
+- Falls back to Brave Search if Tavily is unavailable or fails
+- `useLlmCleaning: true` uses AI to optimize search query from natural language input
+- `includeAnswer: true` adds an AI-generated summary at the top of results (Tavily only)
+
+---
+
+#### `scraper` - Web Page Scraper
+**Purpose**: Extract content from web pages.
+
+**Config Schema**:
+```json
+{
+  "label": "scraper",
+  "input": "https://example.com/page"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ text: "cleaned HTML", html: "...", url: "..." }`
+
+**Note**: URL must start with `http://` or `https://`. May take up to 1 minute.
+
+---
+
+#### `file` - Persistent File Storage
+**Purpose**: Read, update, or create persistent files (CSV, JSON, TXT, MD) that persist across workflows.
+
+**Mode Inference** (automatic based on configuration):
+| Has Parent | Has File | Mode |
+|------------|----------|------|
+| No | Yes | **Read** - Load file content, pass to children |
+| Yes | Yes | **Update** - Update file with parent data |
+| Yes | No | **Create** - Create new file from parent data |
+
+**Config Schema (Read Mode)**:
+```json
+{
+  "label": "file",
+  "file_id": "123",
+  "file_name": "contacts.csv",
+  "file_path": "/projects/contacts.csv"
+}
+```
+
+**Config Schema (Update Mode)**:
+```json
+{
+  "label": "file",
+  "file_id": "123",
+  "file_name": "contacts.csv",
+  "file_path": "/projects/contacts.csv",
+  "update_instructions": "Append the new rows to the CSV"
+}
+```
+
+**Config Schema (Create Mode)**:
+```json
+{
+  "label": "file",
+  "create_instructions": "Create a CSV with columns: name, email, status",
+  "folder_path": "/projects/"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**:
+```json
+{
+  "text": "File content or operation summary",
+  "file_path": "/projects/contacts.csv",
+  "file_id": "123",
+  "metadata": {
+    "name": "contacts.csv",
+    "content_type": "text/csv",
+    "size_bytes": 1024
+  }
+}
+```
+
+**Supported File Types**:
+- `text/csv` - CSV files
+- `application/json` - JSON files
+- `text/plain` - Plain text files
+- `text/markdown` - Markdown files
+
+**Limits**: 10MB max file size, 1000 files per user
+
+**Note**: File node differs from CSV node - file node persists data to storage, CSV node parses inline CSV text. Use file node when you need data to persist across workflow runs.
+
+---
+
+### 3.3 AI/LLM NODES
+
+#### `prompt` - LLM Prompt
+**Purpose**: Send prompts to language models and get responses.
+
+**Config Schema**:
+```json
+{
+  "label": "prompt",
+  "input": "Your prompt or instruction here",
+  "modelConfig": {
+    "provider": "openai",
+    "chat_model": "gpt-5.4-mini",
+    "systemMessage": "You are a helpful assistant.",
+    "temperature": 0.7,
+    "maxTokens": 400
+  }
+}
+```
+
+**Supported Models**:
+| Provider | Models |
+|----------|--------|
+| `openai` | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano` |
+| `anthropic` | `claude-3-5-sonnet-20241022`, `claude-3-5-haiku`, `claude-3-opus` |
+| `google` | `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash` |
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ messages: [{role, content}...], text: "LLM response" }`
+
+**Auto-Chunking**: When input text exceeds 80,000 characters, the prompt node automatically:
+1. Splits input into chunks (500 char overlap for context continuity)
+2. Processes each chunk with the same prompt
+3. Concatenates results with double-newline separators
+
+This eliminates the need for a separate `chunk` node.
+
+---
+
+#### `boolean` - Conditional Branching
+**Purpose**: Evaluate a yes/no question and route to true or false branch.
+
+**Config Schema**:
+```json
+{
+  "label": "boolean",
+  "input": "Is this a positive sentiment?",
+  "modelConfig": {
+    "chat_model": "gpt-5.4-mini"
+  }
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- True output: `{id}-true-handle` (SOURCE)
+- False output: `{id}-false-handle` (SOURCE)
+
+**Output**: `{ text: "true"|"false", boolean: true|false, messages: [...] }`
+
+**Edge Usage**:
+- True path: `sourceHandle: "{id}-true-handle", branch: "true"`
+- False path: `sourceHandle: "{id}-false-handle", branch: "false"`
+
+---
+
+#### `json` - JSON Extractor
+**Purpose**: Extract structured JSON from text using LLM.
+
+**Config Schema**:
+```json
+{
+  "label": "json",
+  "input": "Extract name, email, and phone as JSON",
+  "modelConfig": {
+    "chat_model": "gpt-5.4-mini",
+    "temperature": 0.7,
+    "maxTokens": 1000
+  }
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ json: {...}, text: "pretty printed JSON" }`
+
+---
+
+### 3.4 LOGIC & CONTROL NODES
+
+#### `switch` - Multi-Path Router
+**Purpose**: Route execution to one of multiple paths based on conditions.
+
+**Config Schema**:
+```json
+{
+  "label": "switch",
+  "condition_type": "llm|regex|contains|equals",
+  "cases": [
+    {
+      "name": "positive",
+      "description": "Positive sentiment",
+      "value": "positive",
+      "pattern": "\\b(good|great|excellent)\\b"
+    },
+    {
+      "name": "negative",
+      "description": "Negative sentiment"
+    }
+  ],
+  "default_branch": "neutral",
+  "input_value": "",
+  "llm_prompt": "Classify the sentiment"
+}
+```
+
+**Condition Types**:
+| Type | Description | Case Fields |
+|------|-------------|-------------|
+| `equals` | Exact match | `value` or `values` array |
+| `contains` | Substring match | `value` or `values` array |
+| `regex` | Pattern match | `pattern` |
+| `llm` | AI classification | `name`, `description` |
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Case outputs: `{id}-output-handle` (one per case + default)
+
+**Output**: `{ branch: "case_name", text: "Routed to: case_name", result: {...} }`
+
+**Edge Usage**: `branch: "{case_name}"` routes to that case's path.
+
+---
+
+#### `wait` - Execution Delay
+**Purpose**: Pause workflow execution for a specified duration.
+
+**Config Schema**:
+```json
+{
+  "label": "wait",
+  "delay_type": "seconds|minutes|hours|until",
+  "delay_amount": 30,
+  "until_time": "2025-01-01T12:00:00Z"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ success: true, text: "Waited 30 seconds", result: {...} }`
+
+**Limits**: Maximum 7 days (168 hours)
+
+---
+
+#### `aggregate` - Iteration Collector
+**Purpose**: Collect all results from an iteration into a single array. **REQUIRED** to terminate iteration scope.
+
+**Config Schema**:
+```json
+{
+  "label": "aggregate"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ result: [...], count: N }`
+
+**CRITICAL**: Every iteration (list/table with `each` edge) MUST end with an aggregate node.
+
+---
+
+### 3.5 ACTION NODES
+
+#### `http_request` - HTTP API Calls
+**Purpose**: Make HTTP requests to external APIs.
+
+**Config Schema**:
+```json
+{
+  "label": "http_request",
+  "url": "https://api.example.com/endpoint",
+  "method": "GET|POST|PUT|PATCH|DELETE",
+  "headers": {
+    "Authorization": "Bearer token",
+    "Content-Type": "application/json"
+  },
+  "body": "{\"key\": \"value\"}",
+  "query_params": {
+    "param1": "value1"
+  },
+  "credential_id": null,
+  "timeout": 30
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ body: {...}, status: 200, headers: {...}, success: true, text: "..." }`
+
+**Limits**: Max 30 second timeout, 1MB response size
+
+---
+
+#### `email` - Send Email
+**Purpose**: Send email notifications to the workflow user.
+
+**Config Schema**:
+```json
+{
+  "label": "email",
+  "subject": "Flow Results: {{parent.text}}",
+  "body": "Here are your results:\n\n{{parent.result}}",
+  "format": "plain|html"
+}
+```
+
+**Variable Interpolation**: Use `{{parent.key}}` to insert parent output values.
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ sent: true, message_id: "...", recipient: "user@email.com", timestamp: "..." }`
+
+**Security**: Email is ALWAYS sent to the authenticated user only.
+**Limits**: 50 emails per day per user.
+
+---
+
+### 3.6 INTEGRATION NODES
+
+#### `google_drive` - Google Drive
+**Purpose**: Manage files and folders in Google Drive.
+
+**Config Schema**:
+```json
+{
+  "label": "google_drive",
+  "operation": "list_files|get_metadata|download_file|upload_file|update_file|create_folder|copy_file|move_file|delete_file|search_files",
+  "folder_id": "...",
+  "file_id": "...",
+  "file_name": "...",
+  "file_content": "...",
+  "query": "..."
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+---
+
+### 3.7 MEDIA NODES
+
+#### `transcription` - Audio to Text
+**Purpose**: Convert audio to text using Whisper or Google STT.
+
+**Config Schema**:
+```json
+{
+  "label": "transcription",
+  "provider": "openai|google",
+  "audio_source": "url|content",
+  "audio_url": "https://example.com/audio.mp3",
+  "language": "auto|en|es|fr|de|...",
+  "output_format": "text|json|verbose_json|srt|vtt",
+  "prompt": "Optional context prompt"
+}
+```
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ text: "transcribed text", success: true, ... }`
+
+**Supported Formats**: mp3, mp4, wav, m4a, webm, flac, ogg
+**Limits**: 25MB max file size (OpenAI)
+
+---
+
+#### `image_generation` - AI Image Creation
+**Purpose**: Generate images using DALL-E 3 or Imagen 3.
+
+**Config Schema**:
+```json
+{
+  "label": "image_generation",
+  "provider": "openai|google",
+  "operation": "generate|edit|variation",
+  "prompt": "A serene mountain landscape at sunset",
+  "size": "1024x1024|1792x1024|1024x1792",
+  "aspect_ratio": "1:1|16:9|9:16|4:3|3:4",
+  "quality": "standard|hd",
+  "style": "vivid|natural",
+  "count": 1,
+  "negative_prompt": "blurry, low quality"
+}
+```
+
+**Provider-Specific Options**:
+| Option | OpenAI (DALL-E 3) | Google (Imagen 3) |
+|--------|-------------------|-------------------|
+| Size | `size` field | `aspect_ratio` field |
+| Quality | `quality`, `style` | N/A |
+| Negative | N/A | `negative_prompt` |
+
+**Handles**:
+- Input: `{id}-input-handle`
+- Output: `{id}-output-handle`
+
+**Output**: `{ images: [{url, revised_prompt}], image_count: N, success: true }`
+
+---
+
+---
+
+## 4. Edge Connection Rules
+
+### 4.1 Handle Types
+- **Source handles** (output): Can only connect TO target handles
+- **Target handles** (input): Can only receive FROM source handles
+
+### 4.2 Handle Naming Convention
+```
+Standard output:  {nodeId}-output-handle
+Standard input:   {nodeId}-input-handle
+Boolean true:     {nodeId}-true-handle
+Boolean false:    {nodeId}-false-handle
+Each (iteration): {nodeId}-each-handle
+```
+
+### 4.3 Branch Property Rules
+| Source Node Type | Branch Value | Meaning |
+|------------------|--------------|---------|
+| Any (regular) | `null` or omit | Standard data flow |
+| `boolean` | `"true"` | True condition path |
+| `boolean` | `"false"` | False condition path |
+| `list`, `table` | `"each"` | Iterate over items |
+| `switch` | `"{case_name}"` | Route to named case |
+
+### 4.4 Multi-Input Nodes
+- Multiple parent nodes CAN connect to the same target handle
+- Messages from all parents are merged automatically
+- Use for combining data from multiple sources
+
+### 4.5 Edge Example
+```json
+{
+  "id": "edge-1",
+  "source": "prompt-1",
+  "target": "boolean-1",
+  "sourceHandle": "prompt-1-output-handle",
+  "targetHandle": "boolean-1-input-handle",
+  "type": "custom",
+  "markerEnd": { "type": "arrowClosed" },
+  "style": { "strokeWidth": 2 }
+}
+```
+
+For iteration edges (with `branch: "each"`), use dashed style:
+```json
+{
+  "id": "edge-iter",
+  "source": "list-1",
+  "target": "prompt-1",
+  "sourceHandle": "list-1-each-handle",
+  "targetHandle": "prompt-1-input-handle",
+  "branch": "each",
+  "type": "custom",
+  "markerEnd": { "type": "arrowClosed" },
+  "style": { "strokeWidth": 2, "strokeDasharray": "5,5" }
+}
+```
+
+---
+
+## 5. Iteration Scope Rules
+
+### 5.1 Iteration Sources
+Only these node types can start an iteration:
+- `list` (via `{id}-each-handle`)
+- `table` (via `{id}-each-handle`)
+
+### 5.2 Starting Iteration
+```json
+{
+  "id": "edge-iter",
+  "source": "list-1",
+  "target": "prompt-1",
+  "sourceHandle": "list-1-each-handle",
+  "targetHandle": "prompt-1-input-handle",
+  "branch": "each",
+  "type": "custom",
+  "markerEnd": { "type": "arrowClosed" },
+  "style": { "strokeWidth": 2, "strokeDasharray": "5,5" }
+}
+```
+
+### 5.3 Iteration Scope
+- **Starts**: When an edge with `branch: "each"` connects to a node
+- **Continues**: All downstream nodes until an aggregate node
+- **Ends**: At the `aggregate` node
+
+### 5.4 Aggregate Node Requirement
+**CRITICAL**: Every iteration MUST terminate with an `aggregate` node.
+
+```
+list --[each]--> prompt --> aggregate
+```
+
+Without aggregate:
+- Results are lost
+- Downstream nodes never execute
+- Workflow hangs
+
+### 5.5 What Happens During Iteration
+1. List/table has 10 items
+2. Child node runs 10 times (once per item)
+3. Each run gets the current item's data as context
+4. Aggregate collects all 10 results into an array
+5. Downstream nodes receive the aggregated array
+
+---
+
+## 6. Common Workflow Patterns
+
+### 6.1 Linear Chain
+```
+text --> prompt
+```
+Simple sequential processing. The last node's output is visible in execution results.
+
+### 6.2 Conditional Branching
+```
+prompt --> boolean --[true]--> promptA
+                  \--[false]--> promptB
+```
+Route based on yes/no decision.
+
+### 6.3 Iteration Pattern
+```
+list --[each]--> prompt --> aggregate
+```
+Process each item and combine results.
+
+### 6.4 Multi-Path Switch
+```
+prompt --> switch --[case1]--> action1
+                 \--[case2]--> action2
+                 \--[default]--> action3
+```
+Route to one of many paths.
+
+### 6.5 Data Enrichment
+```
+table --[each]--> scraper --> prompt --> aggregate
+```
+Fetch data for each row, process, combine.
+
+### 6.6 Multi-Input Merge
+```
+promptA ----\
+             --> prompt
+promptB ----/
+```
+Combine outputs from multiple nodes.
+
+---
+
+## 7. Example Workflows
+
+### 7.1 Simple Prompt Chain
+**User Request**: "Create a workflow that takes a question and answers it"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "text-1",
+      "type": "text",
+      "position": { "x": 100, "y": 100 },
+      "data": { "label": "text", "input": "What is machine learning?" }
+    },
+    {
+      "id": "prompt-1",
+      "type": "prompt",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "prompt",
+        "input": "Answer this question in simple terms",
+        "modelConfig": {
+          "provider": "openai",
+          "chat_model": "gpt-5.4-mini",
+          "systemMessage": "You are a helpful teacher.",
+          "temperature": 0.7,
+          "maxTokens": 400
+        }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "text-1",
+      "target": "prompt-1",
+      "sourceHandle": "text-1-output-handle",
+      "targetHandle": "prompt-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.2 URL Scraping with Iteration
+**User Request**: "Scrape 3 URLs and summarize each page"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "list-1",
+      "type": "list",
+      "position": { "x": 100, "y": 100 },
+      "data": {
+        "label": "list",
+        "mode": "manual",
+        "input": "https://example.com/page1\nhttps://example.com/page2\nhttps://example.com/page3"
+      }
+    },
+    {
+      "id": "scraper-1",
+      "type": "scraper",
+      "position": { "x": 400, "y": 100 },
+      "data": { "label": "scraper", "input": "" }
+    },
+    {
+      "id": "prompt-1",
+      "type": "prompt",
+      "position": { "x": 700, "y": 100 },
+      "data": {
+        "label": "prompt",
+        "input": "Summarize this web page content in 2-3 sentences",
+        "modelConfig": {
+          "provider": "openai",
+          "chat_model": "gpt-5.4-mini",
+          "temperature": 0.5,
+          "maxTokens": 200
+        }
+      }
+    },
+    {
+      "id": "aggregate-1",
+      "type": "aggregate",
+      "position": { "x": 1000, "y": 100 },
+      "data": { "label": "aggregate" }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "list-1",
+      "target": "scraper-1",
+      "sourceHandle": "list-1-each-handle",
+      "targetHandle": "scraper-1-input-handle",
+      "branch": "each",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2, "strokeDasharray": "5,5" }
+    },
+    {
+      "id": "e2",
+      "source": "scraper-1",
+      "target": "prompt-1",
+      "sourceHandle": "scraper-1-output-handle",
+      "targetHandle": "prompt-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e3",
+      "source": "prompt-1",
+      "target": "aggregate-1",
+      "sourceHandle": "prompt-1-output-handle",
+      "targetHandle": "aggregate-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.3 Conditional Email Notification
+**User Request**: "Analyze sentiment and send email only if positive"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "text-1",
+      "type": "text",
+      "position": { "x": 100, "y": 100 },
+      "data": { "label": "text", "input": "I absolutely love this product! It exceeded my expectations." }
+    },
+    {
+      "id": "boolean-1",
+      "type": "boolean",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "boolean",
+        "input": "Is this feedback positive?",
+        "modelConfig": { "chat_model": "gpt-5.4-mini" }
+      }
+    },
+    {
+      "id": "email-1",
+      "type": "email",
+      "position": { "x": 700, "y": 50 },
+      "data": {
+        "label": "email",
+        "subject": "Positive Feedback Received!",
+        "body": "Great news! We received positive feedback:\n\n{{parent.text}}",
+        "format": "plain"
+      }
+    },
+    {
+      "id": "prompt-1",
+      "type": "prompt",
+      "position": { "x": 700, "y": 200 },
+      "data": {
+        "label": "prompt",
+        "input": "Generate a response acknowledging this negative feedback",
+        "modelConfig": { "chat_model": "gpt-5.4-mini", "maxTokens": 200 }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "text-1",
+      "target": "boolean-1",
+      "sourceHandle": "text-1-output-handle",
+      "targetHandle": "boolean-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e2",
+      "source": "boolean-1",
+      "target": "email-1",
+      "sourceHandle": "boolean-1-true-handle",
+      "targetHandle": "email-1-input-handle",
+      "branch": "true",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e3",
+      "source": "boolean-1",
+      "target": "prompt-1",
+      "sourceHandle": "boolean-1-false-handle",
+      "targetHandle": "prompt-1-input-handle",
+      "branch": "false",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.4 API Integration with HTTP Request
+**User Request**: "Fetch data from an API and process it"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "http-1",
+      "type": "http_request",
+      "position": { "x": 100, "y": 100 },
+      "data": {
+        "label": "http_request",
+        "url": "https://api.example.com/data",
+        "method": "GET",
+        "headers": { "Accept": "application/json" },
+        "timeout": 30
+      }
+    },
+    {
+      "id": "json-1",
+      "type": "json",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "json",
+        "input": "Extract the name and status fields",
+        "modelConfig": { "chat_model": "gpt-5.4-mini" }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "http-1",
+      "target": "json-1",
+      "sourceHandle": "http-1-output-handle",
+      "targetHandle": "json-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.5 Multi-Path Switch Routing
+**User Request**: "Classify customer inquiries into categories and handle each differently"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "text-1",
+      "type": "text",
+      "position": { "x": 100, "y": 150 },
+      "data": { "label": "text", "input": "I want to return my order #12345" }
+    },
+    {
+      "id": "switch-1",
+      "type": "switch",
+      "position": { "x": 400, "y": 150 },
+      "data": {
+        "label": "switch",
+        "condition_type": "llm",
+        "cases": [
+          { "name": "refund", "description": "Request for refund or return" },
+          { "name": "shipping", "description": "Shipping or delivery question" },
+          { "name": "product", "description": "Product information inquiry" }
+        ],
+        "default_branch": "general",
+        "llm_prompt": "Classify this customer inquiry"
+      }
+    },
+    {
+      "id": "prompt-refund",
+      "type": "prompt",
+      "position": { "x": 700, "y": 50 },
+      "data": {
+        "label": "prompt",
+        "input": "Generate a helpful refund/return process response",
+        "modelConfig": { "chat_model": "gpt-5.4-mini", "maxTokens": 200 }
+      }
+    },
+    {
+      "id": "prompt-shipping",
+      "type": "prompt",
+      "position": { "x": 700, "y": 150 },
+      "data": {
+        "label": "prompt",
+        "input": "Generate a shipping status response",
+        "modelConfig": { "chat_model": "gpt-5.4-mini", "maxTokens": 200 }
+      }
+    },
+    {
+      "id": "prompt-general",
+      "type": "prompt",
+      "position": { "x": 700, "y": 250 },
+      "data": {
+        "label": "prompt",
+        "input": "Generate a general customer support response",
+        "modelConfig": { "chat_model": "gpt-5.4-mini", "maxTokens": 200 }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "text-1",
+      "target": "switch-1",
+      "sourceHandle": "text-1-output-handle",
+      "targetHandle": "switch-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e2",
+      "source": "switch-1",
+      "target": "prompt-refund",
+      "sourceHandle": "switch-1-output-handle",
+      "targetHandle": "prompt-refund-input-handle",
+      "branch": "refund",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e3",
+      "source": "switch-1",
+      "target": "prompt-shipping",
+      "sourceHandle": "switch-1-output-handle",
+      "targetHandle": "prompt-shipping-input-handle",
+      "branch": "shipping",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e4",
+      "source": "switch-1",
+      "target": "prompt-general",
+      "sourceHandle": "switch-1-output-handle",
+      "targetHandle": "prompt-general-input-handle",
+      "branch": "general",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.6 Web Search and Summary
+**User Request**: "Search for information and summarize the results"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "search-1",
+      "type": "search",
+      "position": { "x": 100, "y": 100 },
+      "data": {
+        "label": "search",
+        "input": "Latest developments in artificial intelligence 2024",
+        "useLlmCleaning": true,
+        "maxResults": 5
+      }
+    },
+    {
+      "id": "prompt-1",
+      "type": "prompt",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "prompt",
+        "input": "Summarize the key points from these search results in a concise paragraph",
+        "modelConfig": {
+          "chat_model": "gpt-5.4-mini",
+          "temperature": 0.5,
+          "maxTokens": 300
+        }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "search-1",
+      "target": "prompt-1",
+      "sourceHandle": "search-1-output-handle",
+      "targetHandle": "prompt-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.7 Image Generation
+**User Request**: "Generate an image based on a prompt"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "text-1",
+      "type": "text",
+      "position": { "x": 100, "y": 100 },
+      "data": { "label": "text", "input": "A serene mountain landscape at sunset with snow-capped peaks" }
+    },
+    {
+      "id": "image-1",
+      "type": "image_generation",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "image_generation",
+        "provider": "openai",
+        "operation": "generate",
+        "prompt": "",
+        "size": "1024x1024",
+        "quality": "standard",
+        "style": "vivid",
+        "count": 1
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "text-1",
+      "target": "image-1",
+      "sourceHandle": "text-1-output-handle",
+      "targetHandle": "image-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+### 7.8 Table-Based Data Pipeline
+**User Request**: "Process a table of data with AI and send results via email"
+
+```json
+{
+  "nodes": [
+    {
+      "id": "table-1",
+      "type": "table",
+      "position": { "x": 100, "y": 100 },
+      "data": {
+        "label": "table",
+        "columns": [
+          { "id": "col_1", "name": "Company", "type": "text" },
+          { "id": "col_2", "name": "Description", "type": "text" }
+        ],
+        "rows": [
+          { "col_1": "Acme Corp", "col_2": "Software development company" },
+          { "col_1": "TechStart", "col_2": "AI startup focused on automation" },
+          { "col_1": "DataFlow", "col_2": "Data analytics platform" }
+        ],
+        "storage_mode": "inline"
+      }
+    },
+    {
+      "id": "prompt-1",
+      "type": "prompt",
+      "position": { "x": 400, "y": 100 },
+      "data": {
+        "label": "prompt",
+        "input": "Analyze this company and provide a brief competitive analysis",
+        "modelConfig": { "chat_model": "gpt-5.4-mini", "maxTokens": 300 }
+      }
+    },
+    {
+      "id": "aggregate-1",
+      "type": "aggregate",
+      "position": { "x": 700, "y": 100 },
+      "data": { "label": "aggregate" }
+    },
+    {
+      "id": "email-1",
+      "type": "email",
+      "position": { "x": 1000, "y": 100 },
+      "data": {
+        "label": "email",
+        "subject": "Company Analysis Report",
+        "body": "Here are the analysis results:\n\n{{parent.text}}",
+        "format": "plain"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "source": "table-1",
+      "target": "prompt-1",
+      "sourceHandle": "table-1-each-handle",
+      "targetHandle": "prompt-1-input-handle",
+      "branch": "each",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2, "strokeDasharray": "5,5" }
+    },
+    {
+      "id": "e2",
+      "source": "prompt-1",
+      "target": "aggregate-1",
+      "sourceHandle": "prompt-1-output-handle",
+      "targetHandle": "aggregate-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    },
+    {
+      "id": "e3",
+      "source": "aggregate-1",
+      "target": "email-1",
+      "sourceHandle": "aggregate-1-output-handle",
+      "targetHandle": "email-1-input-handle",
+      "type": "custom",
+      "markerEnd": { "type": "arrowClosed" },
+      "style": { "strokeWidth": 2 }
+    }
+  ]
+}
+```
+
+---
+
+## 8. Validation Checklist
+
+### Server-Side Validation (FlowValidator)
+
+**Important**: Validation is now enforced server-side before execution via `FlowValidator`. The validator runs automatically when a flow is executed and returns detailed error messages if validation fails.
+
+**Location**: `backend/app/services/flow_validator.rb`
+
+**Error Format**: Errors include node IDs for easy debugging:
+- `[node-abc123] Missing required config: url`
+- `[node-xyz789] Unknown node type: invalid_type`
+- `Flow has no nodes`
+- `Flow contains a cycle`
+
+**Validation Categories**:
+1. **Structure**: Non-empty nodes array, unique IDs, required fields (id, type, data)
+2. **Node Types**: Must be in TASK_MAP (all 17 valid node types)
+3. **Connections**: Valid edges, no self-loops, no isolated nodes, DAG (no cycles), entry point exists
+4. **Iteration Scope**: Each edges must reach aggregate terminator
+5. **Config**: Truly required fields only; backend workers provide defaults for optional fields:
+   - `prompt/boolean/json`: No required fields (backend defaults to gpt-5.4-mini)
+   - `switch`: `cases` required (non-empty); `condition_type` validated only if present
+   - `http_request`: `url` required; `method` validated only if present (defaults to GET)
+   - `wait`: All fields optional (validated only if present, backend has defaults)
+   - `list` (manual mode): `input` field required when `mode == "manual"`
+   - `transcription/image_generation`: All fields optional (workers have defaults)
+6. **Credentials**: OAuth connections for google_drive, API credentials for http_request
+
+### Pre-Output Checklist
+
+Before outputting a graph, verify:
+
+### Node Validation
+- [ ] All nodes have unique IDs
+- [ ] All node types are valid (from the 19 supported types)
+- [ ] All required config fields are present
+- [ ] Position coordinates are numbers
+- [ ] `data.label` matches node `type`
+
+### Edge Validation
+- [ ] All edges have unique IDs
+- [ ] Source node exists in nodes array
+- [ ] Target node exists in nodes array
+- [ ] `sourceHandle` format: `{sourceNodeId}-{output|true|false|each}-handle`
+- [ ] `targetHandle` format: `{targetNodeId}-input-handle`
+- [ ] `type` is set to `"custom"` (required for rendering)
+- [ ] `markerEnd` is set to `{ "type": "arrowClosed" }`
+- [ ] `style` is set to `{ "strokeWidth": 2 }` (or with `"strokeDasharray": "5,5"` for iteration edges)
+- [ ] Branch value matches source node type:
+  - `boolean`: `"true"` or `"false"`
+  - `list`/`table` each: `"each"`
+  - `switch`: case name or default branch
+  - Other: `null` or omit
+
+### Graph Structure
+- [ ] No orphan nodes (all nodes connected except starting nodes)
+- [ ] No cycles (DAG requirement - data flows one direction)
+- [ ] Every iteration scope has an aggregate terminator
+- [ ] At least one root node (no incoming edges)
+- [ ] Boolean nodes have both true and false paths handled
+
+### Handle Compatibility
+- [ ] Each edge connects source handle to target handle
+- [ ] Boolean handles (`true-handle`, `false-handle`) only on boolean nodes
+- [ ] Each handles (`each-handle`) only on list/table nodes
+- [ ] Case handles (`case-{name}-handle`, `case-default-handle`) only on switch nodes
+
+---
+
+## 9. Common Pitfalls & Anti-Patterns
+
+### 9.1 Handle Naming Errors
+```
+WRONG: sourceHandle: "output"
+RIGHT: sourceHandle: "prompt-1-output-handle"
+
+WRONG: targetHandle: "prompt-1-output-handle"
+RIGHT: targetHandle: "prompt-1-input-handle"
+```
+
+### 9.2 Missing Aggregate Node
+```
+WRONG: list --[each]--> prompt
+RIGHT: list --[each]--> prompt --> aggregate
+```
+**Always terminate iteration scopes with aggregate.**
+
+### 9.3 Incorrect Branch Values
+```
+WRONG: branch: "True"  (capital T)
+RIGHT: branch: "true"  (lowercase)
+
+WRONG: branch: "yes"
+RIGHT: branch: "true"
+```
+
+### 9.4 Orphan Branches
+```
+WRONG: Boolean with only true path, no false path handling
+RIGHT: Both paths should connect somewhere (even to same result)
+```
+
+### 9.5 Using `text` Nodes Unnecessarily
+```
+WRONG: text --> search --> prompt
+RIGHT: search --> prompt  (search can be root, prompt output is visible)
+```
+Most workflows work better without `text` as a prefix:
+- Start with the first meaningful node (search, prompt, list, etc.) as root
+- The last node's output is automatically visible in execution results
+- Use `text` only when you need to provide static input that users can edit
+
+### 9.6 Circular Dependencies
+```
+WRONG: A --> B --> C --> A
+RIGHT: Ensure unidirectional flow (DAG)
+```
+
+### 9.7 Each Edge Without Aggregate
+```
+WRONG: list --[each]--> prompt --[each]--> scraper  (nested each)
+RIGHT: list --[each]--> prompt --> aggregate --> list --[each]--> ...
+```
+**Never nest iteration scopes. Always aggregate before starting new iteration.**
+
+### 9.8 Wrong Handle for Iteration
+```
+WRONG: sourceHandle: "list-1-output-handle", branch: "each"
+RIGHT: sourceHandle: "list-1-each-handle", branch: "each"
+```
+
+### 9.9 Model Config (Optional)
+```
+OPTIONAL: { "input": "..." }  (backend uses default model: gpt-5.4-mini)
+EXPLICIT: { "input": "...", "modelConfig": { "chat_model": "gpt-4" } }
+```
+**Note**: Model config is optional for prompt/boolean/json nodes. The backend uses `gpt-5.4-mini` by default when not specified. Only specify `modelConfig` when you need a different model.
+
+---
+
+## 10. Natural Language Translation Guide
+
+### 10.1 Intent Keywords to Node Types
+
+#### Data
+| Keywords | Node Type |
+|----------|-----------|
+| "static text", "constant", "fixed value" | `text` |
+| "list of", "multiple items", "array", "extract items" | `list` |
+| "table", "tabular data", "rows and columns" | `table` |
+| "file", "persistent", "save to file", "load file", "update file" | `file` |
+
+#### Web
+| Keywords | Node Type |
+|----------|-----------|
+| "scrape", "extract from website", "web page" | `scraper` |
+| "search", "look up", "find online" | `search` |
+
+#### AI Processing
+| Keywords | Node Type |
+|----------|-----------|
+| "summarize", "explain", "write", "generate text" | `prompt` |
+| "true/false", "yes/no", "decide if", "check if" | `boolean` |
+| "JSON", "structured data", "extract fields" | `json` |
+| "classify", "route", "which category" | `switch` |
+
+#### Logic & Control
+| Keywords | Node Type |
+|----------|-----------|
+| "wait", "delay", "pause", "schedule" | `wait` |
+| "combine", "collect all", "merge results" | `aggregate` |
+
+#### Actions
+| Keywords | Node Type |
+|----------|-----------|
+| "send email", "notify", "email" | `email` |
+| "API call", "HTTP request", "webhook", "fetch" | `http_request` |
+
+#### Integrations
+| Keywords | Node Type |
+|----------|-----------|
+| "Google Drive", "files", "folders" | `google_drive` |
+
+#### Media
+| Keywords | Node Type |
+|----------|-----------|
+| "transcribe", "audio to text", "speech" | `transcription` |
+| "generate image", "create picture", "DALL-E" | `image_generation` |
+
+### 10.2 Pattern Recognition
+
+#### "For each X, do Y"
+```
+list/table --[each]--> Y --> aggregate
+```
+
+#### "If X then A, else B"
+```
+boolean --[true]--> A
+        \--[false]--> B
+```
+
+#### "Scrape and summarize"
+```
+scraper --> prompt
+```
+
+#### "Search and process"
+```
+search --> prompt
+```
+
+### 10.3 Example Translations
+
+| User Request | Workflow Pattern |
+|--------------|------------------|
+| "Scrape 10 URLs and summarize each" | list (URLs) --[each]--> scraper --> prompt --> aggregate |
+| "Send email if sentiment is positive" | text --> boolean --[true]--> email |
+| "Process each item in my list" | list --[each]--> prompt --> aggregate |
+| "Generate an image from a description" | text --> image_generation |
+| "Search web and extract key facts" | search --> json |
+| "Wait 5 minutes then send email" | text --> wait --> email |
+| "Analyze each row in my table" | table --[each]--> prompt --> aggregate |
+
+---
+
+## Appendix: Supported Models Reference
+
+### OpenAI Models
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `gpt-5.4` | Most capable | Complex reasoning, multi-step tool orchestration |
+| `gpt-5.4-mini` | Fast & efficient | General tasks (default) |
+| `gpt-5.4-nano` | Cheapest, fastest | Simple/no-tool prompts |
+
+### Anthropic Models
+| Model ID | Description |
+|----------|-------------|
+| `claude-3-5-sonnet-20241022` | Balanced performance (default) |
+| `claude-3-5-haiku-20241022` | Fast responses |
+| `claude-3-opus-20240229` | Most capable |
+
+### Google Models
+| Model ID | Description |
+|----------|-------------|
+| `gemini-1.5-pro` | Most capable |
+| `gemini-1.5-flash` | Fast (default) |
+| `gemini-2.0-flash-exp` | Latest fast (experimental) |
+
+---
+
+**End of Guide**