opencode-skills-collection 4.0.7 → 4.0.8

package/bundled-skills/n8n-agents/references/EXAMPLES.md

@@ -0,0 +1,432 @@
+# Examples
+
+Three practical node-object snippets for the shell + core + sub-agent topology. These are **community n8n JSON fragments** to adapt, not full importable exports — credential IDs, workflow IDs, and channel/bot IDs are placeholders. Build with `n8n_update_partial_workflow` (`addNode` + `addConnection` on the `ai_*` outputs), then verify with `n8n_get_workflow` and `validate_workflow`.
+
+For the architecture these fit into, see **CHAT_AGENT_PATTERNS.md**.
+
+---
+
+## 1. Stateless agent core
+
+A reusable agent sub-workflow: `chatInput` + `threadId` in, agent output out. Memory keyed on `threadId`, native tools, a sub-agent tool, and Block Kit structured output with an autoFix fixer model. This is the "brain" called by the shell.
+
+```json
+{
+  "name": "Chat agent core",
+  "nodes": [
+    {
+      "parameters": {
+        "workflowInputs": {
+          "values": [{ "name": "chatInput" }, { "name": "threadId" }]
+        }
+      },
+      "type": "n8n-nodes-base.executeWorkflowTrigger",
+      "typeVersion": 1.1,
+      "position": [-480, -96],
+      "id": "core-trigger",
+      "name": "When Executed by Another Workflow"
+    },
+    {
+      "parameters": {
+        "promptType": "define",
+        "text": "={{ $json.chatInput }}",
+        "hasOutputParser": true,
+        "options": {
+          "systemMessage": "=You are a concise, direct assistant. Be a thinking partner, not an answer machine.\n\nCurrent date: {{ $now.format('DDDD') }}\n\n## Output\nYou are replying in Slack using Block Kit. Your entire response must be valid JSON with a 'blocks' array at the root. Bold is *single asterisks*. Links are <https://url|text>. Max 10 blocks.\n\n## Tool usage\nFact-check verifiable claims with the web search tool before answering. Use the idea database manager for anything about content ideas.",
+          "maxIterations": 50
+        }
+      },
+      "type": "@n8n/n8n-nodes-langchain.agent",
+      "typeVersion": 3.1,
+      "position": [-48, -96],
+      "id": "core-agent",
+      "name": "AI Agent"
+    },
+    {
+      "parameters": { "model": "anthropic/claude-opus-4.6", "options": { "temperature": 0.1 } },
+      "type": "@n8n/n8n-nodes-langchain.lmChatOpenRouter",
+      "typeVersion": 1,
+      "position": [-288, 192],
+      "id": "core-main-llm",
+      "name": "Main LLM",
+      "credentials": { "openRouterApi": { "id": "REPLACE_OPENROUTER_CRED", "name": "OpenRouter" } }
+    },
+    {
+      "parameters": {
+        "sessionIdType": "customKey",
+        "sessionKey": "={{ $json.threadId }}",
+        "contextWindowLength": 50
+      },
+      "type": "@n8n/n8n-nodes-langchain.memoryBufferWindow",
+      "typeVersion": 1.3,
+      "position": [-128, 192],
+      "id": "core-memory",
+      "name": "Simple Memory"
+    },
+    {
+      "parameters": {
+        "descriptionType": "manual",
+        "toolDescription": "Search the web fast to fact-check a claim or find a source. Use for verifying anything from training data.",
+        "query": "={{ $fromAI('query', 'The search query, phrased to match relevant sources', 'string') }}",
+        "options": { "search_depth": "fast" }
+      },
+      "type": "@tavily/n8n-nodes-tavily.tavilyTool",
+      "typeVersion": 1,
+      "position": [32, 192],
+      "id": "core-web-search",
+      "name": "Search the web",
+      "credentials": { "tavilyApi": { "id": "REPLACE_TAVILY_CRED", "name": "Tavily" } }
+    },
+    {
+      "parameters": {},
+      "type": "@n8n/n8n-nodes-langchain.toolCalculator",
+      "typeVersion": 1,
+      "position": [192, 192],
+      "id": "core-calc",
+      "name": "Calculator"
+    },
+    {
+      "parameters": {
+        "description": "Manages the content-ideas database. Use for ANY task about content ideas: querying, creating, dedupe-checks.\n\nIMPORTANT: This tool is stateless. Send all relevant context in a single message. If creating, include ALL required fields upfront. Returns the page URL for anything referenced or created.",
+        "workflowId": { "__rl": true, "value": "REPLACE_SUBAGENT_WF_ID", "mode": "list", "cachedResultName": "Notion ideas sub-agent" },
+        "workflowInputs": {
+          "mappingMode": "defineBelow",
+          "value": { "chatInput": "={{ $fromAI('chatInput', 'The full request to the ideas database, with all context', 'string') }}" },
+          "schema": [
+            { "id": "chatInput", "displayName": "chatInput", "type": "string", "display": true, "canBeUsedToMatch": true }
+          ]
+        }
+      },
+      "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
+      "typeVersion": 2.2,
+      "position": [352, 192],
+      "id": "core-idea-tool",
+      "name": "Idea database manager"
+    },
+    {
+      "parameters": {
+        "schemaType": "manual",
+        "inputSchema": "{ \"type\": \"object\", \"properties\": { \"text\": { \"type\": \"string\" }, \"blocks\": { \"type\": \"array\", \"items\": { \"oneOf\": [ { \"type\": \"object\", \"properties\": { \"type\": { \"const\": \"header\" }, \"text\": { \"type\": \"object\" } }, \"required\": [\"type\", \"text\"] }, { \"type\": \"object\", \"properties\": { \"type\": { \"const\": \"section\" }, \"text\": { \"type\": \"object\" } }, \"required\": [\"type\", \"text\"] }, { \"type\": \"object\", \"properties\": { \"type\": { \"const\": \"divider\" } }, \"required\": [\"type\"] } ] } } }, \"required\": [\"text\", \"blocks\"] }",
+        "autoFix": true
+      },
+      "type": "@n8n/n8n-nodes-langchain.outputParserStructured",
+      "typeVersion": 1.3,
+      "position": [560, 176],
+      "id": "core-parser",
+      "name": "Structured Output Parser (Block Kit)"
+    },
+    {
+      "parameters": { "model": "anthropic/claude-sonnet-4.6", "options": { "temperature": 0 } },
+      "type": "@n8n/n8n-nodes-langchain.lmChatOpenRouter",
+      "typeVersion": 1,
+      "position": [620, 336],
+      "id": "core-fixer-llm",
+      "name": "Fixer LLM (coding-capable)",
+      "credentials": { "openRouterApi": { "id": "REPLACE_OPENROUTER_CRED", "name": "OpenRouter" } }
+    }
+  ],
+  "connections": {
+    "When Executed by Another Workflow": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
+    "Main LLM": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
+    "Simple Memory": { "ai_memory": [[{ "node": "AI Agent", "type": "ai_memory", "index": 0 }]] },
+    "Search the web": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] },
+    "Calculator": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] },
+    "Idea database manager": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] },
+    "Structured Output Parser (Block Kit)": { "ai_outputParser": [[{ "node": "AI Agent", "type": "ai_outputParser", "index": 0 }]] },
+    "Fixer LLM (coding-capable)": { "ai_languageModel": [[{ "node": "Structured Output Parser (Block Kit)", "type": "ai_languageModel", "index": 0 }]] }
+  }
+}
+```
+
+What to notice:
+
+- **Memory keyed on `threadId`**, not on a user/channel ID (those cross conversations). The shell supplies `threadId`.
+- **`maxIterations: 50`** — raised from the low default because this agent chains several tools per turn.
+- **`$now.format('DDDD')`** in the system prompt — no hardcoded date.
+- **Two models**: the main model on the agent, a separate coding-capable fixer wired into the parser. Both connect via `ai_languageModel` but to different nodes.
+- **`hasOutputParser: true`** on the agent activates the `ai_outputParser` slot.
+- The sub-agent tool's description repeats **"This tool is stateless"** — the router can't rely on shared context.
+
+---
+
+## 2. Slack router shell
+
+The "shell": trigger, trigger-level anti-loop filter, event-type Switch, loading reaction, the agent-core call with an error branch, and the Block Kit reply envelope. No LLM here.
+
+```json
+{
+  "name": "Slack chat router",
+  "nodes": [
+    {
+      "parameters": {
+        "trigger": ["message"],
+        "watchWorkspace": true,
+        "options": { "userIds": "={{ [\"U00000000BOT\"] }}" }
+      },
+      "type": "n8n-nodes-base.slackTrigger",
+      "typeVersion": 1,
+      "position": [-288, 48],
+      "id": "shell-trigger",
+      "name": "Slack Trigger",
+      "credentials": { "slackApi": { "id": "REPLACE_SLACK_CRED", "name": "Slack" } }
+    },
+    {
+      "parameters": {
+        "rules": {
+          "values": [
+            {
+              "conditions": {
+                "options": { "version": 3 },
+                "conditions": [{ "leftValue": "={{ $json.user === \"U00000000OWNER\" && $json.type === \"message\" }}", "rightValue": "", "operator": { "type": "boolean", "operation": "true", "singleValue": true } }],
+                "combinator": "and"
+              },
+              "renameOutput": true, "outputKey": "Owner message"
+            },
+            {
+              "conditions": {
+                "options": { "version": 3 },
+                "conditions": [{ "leftValue": "={{ $json.user !== \"U00000000OWNER\" && $json.type === \"message\" }}", "rightValue": "", "operator": { "type": "boolean", "operation": "true", "singleValue": true } }],
+                "combinator": "and"
+              },
+              "renameOutput": true, "outputKey": "Unknown user"
+            }
+          ]
+        }
+      },
+      "type": "n8n-nodes-base.switch",
+      "typeVersion": 3.4,
+      "position": [-32, 48],
+      "id": "shell-switch",
+      "name": "Switch"
+    },
+    {
+      "parameters": {
+        "resource": "reaction",
+        "channelId": { "__rl": true, "value": "={{ $json.channel }}", "mode": "id" },
+        "timestamp": "={{ $json.ts }}",
+        "name": "spinner"
+      },
+      "type": "n8n-nodes-base.slack",
+      "typeVersion": 2.4,
+      "position": [240, -64],
+      "id": "shell-add-reaction",
+      "name": "Add Loading Reaction",
+      "credentials": { "slackApi": { "id": "REPLACE_SLACK_CRED", "name": "Slack" } }
+    },
+    {
+      "parameters": {
+        "workflowId": { "__rl": true, "value": "REPLACE_AGENT_CORE_WF_ID", "mode": "list", "cachedResultName": "Chat agent core" },
+        "workflowInputs": {
+          "mappingMode": "defineBelow",
+          "value": {
+            "chatInput": "={{ $('Slack Trigger').item.json.text }}",
+            "threadId": "={{ $('Slack Trigger').item.json.thread_ts || $('Slack Trigger').item.json.ts }}"
+          },
+          "schema": [
+            { "id": "chatInput", "displayName": "chatInput", "type": "string", "display": true },
+            { "id": "threadId", "displayName": "threadId", "type": "string", "display": true }
+          ]
+        }
+      },
+      "type": "n8n-nodes-base.executeWorkflow",
+      "typeVersion": 1.3,
+      "position": [480, -64],
+      "id": "shell-call-core",
+      "name": "Call Agent core",
+      "retryOnFail": true,
+      "maxTries": 2,
+      "waitBetweenTries": 5000,
+      "onError": "continueErrorOutput"
+    },
+    {
+      "parameters": {
+        "resource": "reaction",
+        "operation": "remove",
+        "channelId": { "__rl": true, "value": "={{ $('Switch').item.json.channel }}", "mode": "id" },
+        "timestamp": "={{ $('Switch').item.json.ts }}",
+        "name": "spinner"
+      },
+      "type": "n8n-nodes-base.slack",
+      "typeVersion": 2.4,
+      "position": [720, -160],
+      "id": "shell-remove-reaction-ok",
+      "name": "Remove Loading Reaction (success)",
+      "credentials": { "slackApi": { "id": "REPLACE_SLACK_CRED", "name": "Slack" } }
+    },
+    {
+      "parameters": {
+        "select": "user",
+        "user": { "__rl": true, "value": "={{ $('Slack Trigger').item.json.user }}", "mode": "id" },
+        "messageType": "block",
+        "blocksUi": "={{ { \"blocks\": $('Call Agent core').item.json.output.blocks } }}",
+        "otherOptions": {
+          "thread_ts": { "replyValues": { "thread_ts": "={{ $('Slack Trigger').item.json.thread_ts || $('Slack Trigger').item.json.ts }}" } }
+        }
+      },
+      "type": "n8n-nodes-base.slack",
+      "typeVersion": 2.4,
+      "position": [960, -160],
+      "id": "shell-send-reply",
+      "name": "Send Block Kit reply",
+      "credentials": { "slackApi": { "id": "REPLACE_SLACK_CRED", "name": "Slack" } }
+    },
+    {
+      "parameters": {
+        "select": "user",
+        "user": { "__rl": true, "value": "={{ $('Slack Trigger').item.json.user }}", "mode": "id" },
+        "text": "=There was a workflow error. https://<your-n8n-host>/workflow/<this-workflow-id>/executions/{{ $execution.id }}",
+        "otherOptions": {
+          "thread_ts": { "replyValues": { "thread_ts": "={{ $('Slack Trigger').item.json.thread_ts || $('Slack Trigger').item.json.ts }}" } }
+        }
+      },
+      "type": "n8n-nodes-base.slack",
+      "typeVersion": 2.4,
+      "position": [720, 64],
+      "id": "shell-send-error",
+      "name": "Send error message with execution link",
+      "credentials": { "slackApi": { "id": "REPLACE_SLACK_CRED", "name": "Slack" } }
+    }
+  ],
+  "connections": {
+    "Slack Trigger": { "main": [[{ "node": "Switch", "type": "main", "index": 0 }]] },
+    "Switch": { "main": [[{ "node": "Add Loading Reaction", "type": "main", "index": 0 }], []] },
+    "Add Loading Reaction": { "main": [[{ "node": "Call Agent core", "type": "main", "index": 0 }]] },
+    "Call Agent core": {
+      "main": [
+        [{ "node": "Remove Loading Reaction (success)", "type": "main", "index": 0 }],
+        [{ "node": "Send error message with execution link", "type": "main", "index": 0 }]
+      ]
+    },
+    "Remove Loading Reaction (success)": { "main": [[{ "node": "Send Block Kit reply", "type": "main", "index": 0 }]] }
+  }
+}
+```
+
+What to notice:
+
+- **Anti-loop at the trigger**: `options.userIds: ["U00000000BOT"]` is an exclusion list — the bot's own posts never enter the workflow. No separate filter node needed.
+- **`Call Agent core`** has `onError: 'continueErrorOutput'`, so `main[1]` carries the error branch (→ **n8n-error-handling**). The loading reaction is removed on the success path; the error branch surfaces a link instead of hanging forever.
+- **`threadId`** = `thread_ts || ts`, plumbed straight to the core (which keys memory on it).
+- **`blocksUi`** is the `{ "blocks": [...] }` envelope, not the bare array — the bare array fails silently.
+
+---
+
+## 3. Domain sub-agent (Notion ideas)
+
+A specialist sub-agent called via `.toolWorkflow` from the core. It fetches its DB schema fresh on every call and runs on a cheaper model than the router.
+
+```json
+{
+  "name": "Notion ideas sub-agent",
+  "nodes": [
+    {
+      "parameters": { "workflowInputs": { "values": [{ "name": "chatInput" }] } },
+      "type": "n8n-nodes-base.executeWorkflowTrigger",
+      "typeVersion": 1.1,
+      "position": [-240, 0],
+      "id": "sub-trigger",
+      "name": "When Executed by Another Workflow"
+    },
+    {
+      "parameters": {
+        "resource": "database",
+        "databaseId": { "__rl": true, "value": "REPLACE_NOTION_DB_ID", "mode": "id" },
+        "simple": false
+      },
+      "type": "n8n-nodes-base.notion",
+      "typeVersion": 2.2,
+      "position": [-32, 0],
+      "id": "sub-get-db",
+      "name": "Get a database",
+      "credentials": { "notionApi": { "id": "REPLACE_NOTION_CRED", "name": "Notion" } }
+    },
+    {
+      "parameters": {
+        "promptType": "define",
+        "text": "={{ $('When Executed by Another Workflow').item.json.chatInput }}",
+        "options": {
+          "systemMessage": "=You manage a Notion ideas database. Query and create idea entries.\n\n## Database schema (fetched fresh this call)\n{{ $('Get a database').first().json.properties.toJsonString() }}\n\n## Rules\n1. Always respond in chat with the result.\n2. Always return the Notion URL for any page created or referenced.\n3. Select/multi-select values must EXACTLY match an existing schema option.\n4. IMPORTANT: you are stateless. If information is missing, list exactly what's needed and remind the caller to resend the complete request with all details.",
+          "maxIterations": 15
+        }
+      },
+      "type": "@n8n/n8n-nodes-langchain.agent",
+      "typeVersion": 3.1,
+      "position": [208, 0],
+      "id": "sub-agent",
+      "name": "AI Agent"
+    },
+    {
+      "parameters": { "model": "anthropic/claude-haiku-4.6", "options": { "temperature": 0.1 } },
+      "type": "@n8n/n8n-nodes-langchain.lmChatOpenRouter",
+      "typeVersion": 1,
+      "position": [112, 256],
+      "id": "sub-llm",
+      "name": "Sub-agent LLM (cheaper than router)",
+      "credentials": { "openRouterApi": { "id": "REPLACE_OPENROUTER_CRED", "name": "OpenRouter" } }
+    },
+    {
+      "parameters": {
+        "descriptionType": "manual",
+        "toolDescription": "Returns all ideas that are still active (not rejected, cancelled, or started).",
+        "resource": "databasePage",
+        "operation": "getAll",
+        "databaseId": { "__rl": true, "value": "REPLACE_NOTION_DB_ID", "mode": "id" },
+        "returnAll": true,
+        "filterType": "manual",
+        "filters": { "conditions": [{ "key": "Status|status", "condition": "does_not_equal", "statusValue": "Rejected" }] }
+      },
+      "type": "n8n-nodes-base.notionTool",
+      "typeVersion": 2.2,
+      "position": [304, 256],
+      "id": "sub-get-active",
+      "name": "Get active ideas",
+      "credentials": { "notionApi": { "id": "REPLACE_NOTION_CRED", "name": "Notion" } }
+    },
+    {
+      "parameters": {
+        "descriptionType": "manual",
+        "toolDescription": "Creates an idea entry. Always enters as status 'Idea'. Select fields must match schema options exactly.",
+        "resource": "databasePage",
+        "databaseId": { "__rl": true, "value": "REPLACE_NOTION_DB_ID", "mode": "id" },
+        "title": "={{ $fromAI('Title', 'Short title of the idea', 'string') }}",
+        "propertiesUi": {
+          "propertyValues": [
+            { "key": "Status|status", "statusValue": "Idea" },
+            { "key": "Type|select", "selectValue": "={{ $fromAI('type', 'Type column; must EXACTLY match a schema option', 'string') }}" }
+          ]
+        }
+      },
+      "type": "n8n-nodes-base.notionTool",
+      "typeVersion": 2.2,
+      "position": [480, 256],
+      "id": "sub-create",
+      "name": "Create idea",
+      "credentials": { "notionApi": { "id": "REPLACE_NOTION_CRED", "name": "Notion" } }
+    }
+  ],
+  "connections": {
+    "When Executed by Another Workflow": { "main": [[{ "node": "Get a database", "type": "main", "index": 0 }]] },
+    "Get a database": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
+    "Sub-agent LLM (cheaper than router)": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
+    "Get active ideas": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] },
+    "Create idea": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] }
+  }
+}
+```
+
+What to notice:
+
+- **Fresh schema injection**: `Get a database` runs **before** the agent (on `main`), and its `properties` are templated into the system prompt with `.toJsonString()`. The sub-agent never operates on a stale schema, so it can't pick a select option that was renamed last week.
+- **Cheaper model** (`claude-haiku-4.6`) than the router — a focused single-domain agent doesn't need the orchestrator's model.
+- **Stateless contract** restated in the system prompt — matching the tool description on the core side.
+- **`maxIterations: 15`** — fine for a focused sub-agent (vs 50 on the broad router).
+- The `Status|status` / `Type|select` key shape is Notion's `Name|type` convention; match the live schema.
+
+---
+
+## Cross-references
+
+- The topology these fit into → **CHAT_AGENT_PATTERNS.md**
+- The `.toolWorkflow` mapping → **SUBWORKFLOW_AS_TOOL.md**
+- Block Kit schema and autoFix → **STRUCTURED_OUTPUT.md**
+- Error branch on the core call → **n8n-error-handling**

package/bundled-skills/n8n-agents/references/HUMAN_REVIEW.md

@@ -0,0 +1,180 @@
+# Human review for agent tools
+
+Human review gates a tool behind explicit human approval. Until a human approves, the wrapped tool does not run — no matter how confident the agent is. This is the default safety pattern for any agent tool with user-visible side effects.
+
+n8n names this **HITL** / human-in-the-loop in the node IDs (`slackHitlTool`, `discordHitlTool`, …) and "Human Review" in the UI. Same concept.
+
+**Before adding or skipping review, ask the user.** Whether sign-off is needed is a product/policy call (blast radius, audit requirements, how much they trust the model). Surface the question, recommend based on the criteria below, and let them decide.
+
+---
+
+## Topology
+
+The review node sits **between** the wrapped tool and the agent on the `ai_tool` connection:
+
+```
+[wrapped tool]  --ai_tool-->  [review node]  --ai_tool-->  [Agent]
+```
+
+- **The agent doesn't know the review node is there.** It sees the wrapped tool by the wrapped tool's name, description, and parameter schema. The review node is a transparent intercept on the execution path.
+- When the agent calls the wrapped tool, the review node intercepts: collects the parameters the agent built, pauses, sends an approval prompt to a human, and only on approval does the wrapped tool run with those parameters.
+
+In workflow JSON, the wrapped tool's `ai_tool` output points at the **review node**, and the review node's `ai_tool` output points at the **agent**:
+
+```json
+"Refund customer": {
+  "ai_tool": [[{ "node": "Slack approval", "type": "ai_tool", "index": 0 }]]
+},
+"Slack approval": {
+  "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
+}
+```
+
+Do NOT wire the wrapped tool into the agent's `main` input — that flags the wrapped tool as a disconnected node in `validate_workflow`. The wrapped-tool-into-review wiring happens through `ai_tool` only.
+
+---
+
+## Tell the agent the review is there
+
+Because the agent doesn't see the review node, it doesn't know its tool is gated. Models with safety priors hedge on destructive-looking tools (send, delete, refund, charge): they refuse, ask the user for confirmation first, or pick a less-direct option. With review wrapping the tool, that caution doubles up — the model self-censors AND a human reviews, and sometimes the model never even reaches the review step.
+
+If you see the agent over-hedging on a wrapped tool, add a note to the **wrapped tool's description** (per the modular-prompt principle in **SYSTEM_PROMPT.md**):
+
+> This tool is gated by a human review step. Use it freely when relevant. A human will see the exact parameters and approve before anything is sent. Don't ask the user for confirmation first.
+
+Don't pre-emptively add this to every wrapped tool — many agents use the tool freely without it. Deploy when the symptom (hedging, refusing, talking itself out of trying) actually shows up.
+
+---
+
+## When to default to / recommend human review
+
+- **Sends, pays, refunds, account changes** — anything user-visible and hard to roll back.
+- **The approver differs from the chatter** — a customer triggers a workflow; support staff approves the refund. The customer never sees the approval.
+- **Non-chat triggers** — order received, form submitted, schedule fired. The action is taken on someone's behalf, and a person approves before it runs.
+- **Production agent tools** where the cost of a wrong call (money, trust, reputation) outweighs a one-step delay.
+
+Skip review when the tool is read-only, idempotent and cheap to undo, or the deployment is internal/exploratory with mocked services.
+
+---
+
+## Available review tool nodes
+
+| Node | When to use |
+|---|---|
+| `n8n-nodes-base.slackHitlTool` | Approver is on Slack (the common multi-channel case) |
+| `n8n-nodes-base.discordHitlTool` | Approver is on Discord |
+| `n8n-nodes-base.telegramHitlTool` | Approver is on Telegram |
+| `n8n-nodes-base.gmailHitlTool` | Approval via Gmail |
+| `n8n-nodes-base.emailSendHitlTool` | Approval via generic SMTP email |
+| `n8n-nodes-base.googleChatHitlTool` | Approval in Google Chat |
+| `n8n-nodes-base.microsoftOutlookHitlTool` | Approval via Outlook |
+
+More platforms are added over time — verify with `search_nodes({ query: 'hitl' })`.
+
+---
+
+## Response types
+
+`responseType` chooses the response shape the human sees:
+
+- **`approval`** — button-based, sub-configured via `approvalOptions.values.approvalType`:
+  - `'single'` (default): one Approve button. The approver acts or ignores.
+  - `'double'`: Approve / Disapprove. For actions where disapproval should be a loud, recordable choice.
+- **`freeText`** — the human types a free-form response. For when the agent is genuinely asking a question and any answer is valid.
+- **`customForm`** — a multi-field form (text, dropdown, radio, checkbox, file). **This is the practical answer to "editable parameters"**: define a form whose fields match the wrapped tool's parameters and the human can override what the agent picked.
+
+A two-button "semantic choice" ("Schedule today" / "Schedule tomorrow") is NOT a separate type — use `approval` with `approvalType: 'double'` and custom `approveLabel` / `disapproveLabel`.
+
+---
+
+## Wait timeout
+
+`options.limitWaitTime` (seconds) bounds how long the workflow pauses before erroring out. Default is 45 minutes. **Set it explicitly on production workflows** — without it, paused executions sit indefinitely if approvers don't act, and the queue piles up.
+
+---
+
+## Approval message content — show the ACTUAL parameters
+
+The model picked the parameters; the human approves the literal call. Reference the real values via `{{ $tool.parameters.<name> }}`:
+
+```
+The agent wants to refund {{ $tool.parameters.amount }} to {{ $tool.parameters.customerId }}.
+Reason: {{ $tool.parameters.reason }}.
+```
+
+`$tool.name` is the wrapped tool's display name; `$tool.parameters` is the full object the agent built. To avoid silently leaving a new parameter out of the message, iterate over all of them:
+
+```
+The agent wants to call {{ $tool.name }}:
+{{
+  $tool.parameters.keys()
+    .map(param => `${param}: ${$tool.parameters[param]}\n`)
+    .join('')
+}}
+```
+
+### Never fill the approval message via `$fromAI()`
+
+`$fromAI()` asks the *model* to produce a value — including, if you let it, the approval text itself. The human would then approve a model-paraphrased description instead of the literal parameters about to be sent. That defeats the entire point of review.
+
+```
+// ❌ WRONG — the model paraphrases what it's about to do
+message: ={{ $fromAI('approvalText', 'describe the action for approval') }}
+
+// ✅ RIGHT — the literal call is visible
+message: =Refund {{ $tool.parameters.amount }} to {{ $tool.parameters.customerId }}?
+```
+
+### Put values in the button labels
+
+```json
+"approvalOptions": {
+  "values": {
+    "approvalType": "double",
+    "approveLabel": "=Approve {{ $tool.parameters.amount }} refund",
+    "disapproveLabel": "Cancel"
+  }
+}
+```
+
+A button that says "Approve $50 refund" is unambiguous; "Approve" alone is not. `slackHitlTool` also exposes `buttonApprovalStyle` / `buttonDisapprovalStyle` (`'primary' | 'secondary'`) for visual emphasis.
+
+---
+
+## Multi-channel pattern: the approver isn't the chatter
+
+A common production shape: a customer chats with an agent on a website (or via email/order/form), and support staff approves sensitive actions in Slack.
+
+```
+[customer chat / order trigger]
+   → [Agent]
+       → [Slack review tool]  →  [refund / cancel / escalate tool]
+```
+
+The customer never sees the Slack channel. The Slack review message routes via `slackHitlTool.parameters.user` (a resource locator). On approval, the wrapped tool fires and the agent's response goes back to the customer via the original path. This works without any chat at all — the trigger can be a webhook, schedule, form, or queue; the review tool is the only human-facing surface.
+
+---
+
+## Editable parameters: use customForm
+
+For "approve, but at $40 instead of $50" workflows, use `responseType: 'customForm'`. The human fills a multi-field form whose values feed the wrapped tool. Don't try to build editable approvals on top of the `approval` type — the form mode is the supported path.
+
+> Note: the form mode UX is reported to feel like a workaround. Sometimes it's better UX to have the user decline and respond with the change in chat.
+
+---
+
+## UI quirk: test-data autofill
+
+When building a review tool, click "Approve" once on the canvas test execution. n8n autofills the test data so subsequent runs work without manual input. New builders often think the tool is broken because `$tool.parameters.<name>` shows red — that's just missing test data.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | What goes wrong | Fix |
+|---|---|---|
+| Tool that mutates user-visible state without review | Agent fires irreversible action on a wrong inference | Wrap with the right review tool node |
+| Approval message via `$fromAI()` | You approve a paraphrase, not the literal call | Use `$tool.parameters.<name>` |
+| "Approve" button with no context | Approver clicks without seeing what they approve | Embed actual values in the label |
+| Review on a channel the approver doesn't watch | Tool sits indefinitely, executions pile up | Pick a watched channel; set `limitWaitTime` + a fallback |
+| Wrapped tool wired into the agent's `main` input | Flags as a disconnected node in validation | Wire wrapped-tool → review → agent via `ai_tool` only |