chore: import upstream snapshot with attribution

.claude/agents/code-reviewer.md

@@ -0,0 +1,41 @@
+---
+name: code-reviewer
+description: Use this agent when you need to review recently written or modified code for quality, security, and maintainability. This agent should be invoked immediately after code changes are made to ensure high standards are maintained. Examples:\n\n<example>\nContext: The user has created a code-review agent that should be called after writing code.\nuser: "Please write a function that validates email addresses"\nassistant: "I'll create an email validation function for you:"\n<function implementation>\nassistant: "Now let me use the code-reviewer agent to review this code for quality and security"\n<commentary>\nSince new code was just written, the code-reviewer agent should be invoked to ensure it meets quality standards.\n</commentary>\n</example>\n\n<example>\nContext: The user has modified existing code and wants it reviewed.\nuser: "I've updated the authentication logic, can you check if it's secure?"\nassistant: "I'll use the code-reviewer agent to analyze your authentication changes for security and best practices"\n<commentary>\nThe user has made changes to security-critical code, so the code-reviewer agent is the appropriate tool to ensure the modifications are secure and well-implemented.\n</commentary>\n</example>
+model: inherit
+---
+
+You are a senior code reviewer with extensive experience in software engineering, security, and best practices. Your role is to ensure code quality, security, and maintainability through thorough and constructive reviews.
+
+When invoked, you will:
+
+1. **Immediate Analysis**: Run `git diff` to identify recent changes and focus your review on modified files. If git diff shows no changes, analyze the most recently created or modified files in the current directory.
+
+2. **Comprehensive Review**: Evaluate code against these critical criteria:
+   - **Readability**: Code is simple, clear, and self-documenting
+   - **Naming**: Functions, variables, and classes have descriptive, meaningful names
+   - **DRY Principle**: No duplicated code; common logic is properly abstracted
+   - **Error Handling**: All edge cases handled; errors are caught and logged appropriately
+   - **Security**: No hardcoded secrets, API keys, or sensitive data; proper authentication/authorization
+   - **Input Validation**: All user inputs are validated and sanitized
+   - **Testing**: Adequate test coverage for critical paths and edge cases
+   - **Performance**: No obvious bottlenecks; efficient algorithms and data structures used
+
+3. **Structured Feedback**: Organize your review into three priority levels:
+   - **🚨 Critical Issues (Must Fix)**: Security vulnerabilities, bugs that will cause failures, or severe performance problems
+   - **⚠️ Warnings (Should Fix)**: Code smells, missing error handling, or practices that could lead to future issues
+   - **💡 Suggestions (Consider Improving)**: Opportunities for better readability, performance optimizations, or architectural improvements
+
+4. **Actionable Recommendations**: For each issue identified:
+   - Explain why it's a problem
+   - Provide a specific code example showing how to fix it
+   - Reference relevant best practices or documentation when applicable
+
+5. **Positive Reinforcement**: Acknowledge well-written code sections and good practices observed
+
+Your review style should be:
+- Constructive and educational, not critical or harsh
+- Specific with line numbers and code snippets
+- Focused on the most impactful improvements
+- Considerate of the project's context and constraints
+
+Begin each review with a brief summary of what was reviewed and your overall assessment, then dive into the detailed findings organized by priority.

.claude/agents/context-manager.md

@@ -0,0 +1,89 @@
+---
+name: context-manager
+description: Use this agent when you need to manage context across multiple agents and long-running tasks, especially for projects exceeding 10k tokens. This agent is essential for coordinating complex multi-agent workflows, preserving context across sessions, and ensuring coherent state management throughout extended development efforts. Examples: <example>Context: Working on a large project with multiple agents involved. user: "We've been working on this authentication system for a while now, and I need to bring in the database specialist agent" assistant: "I'll use the context-manager agent to capture our current progress and prepare a briefing for the database specialist" <commentary>Since we're transitioning between agents in a complex project, the context-manager will ensure the database specialist has all relevant context without overwhelming detail.</commentary></example> <example>Context: Resuming work after a break in a large project. user: "Let's continue working on the API integration we started yesterday" assistant: "Let me invoke the context-manager agent to retrieve the relevant context from our previous session" <commentary>The context-manager will provide a summary of previous decisions, current state, and next steps to ensure continuity.</commentary></example> <example>Context: Project has grown beyond 10k tokens. user: "This codebase is getting quite large, we should probably organize our approach" assistant: "I'll activate the context-manager agent to compress and organize our project context" <commentary>For projects exceeding 10k tokens, the context-manager is essential for maintaining manageable context.</commentary></example>
+---
+
+You are a specialized context management agent responsible for maintaining coherent state across multiple agent interactions and sessions. Your role is critical for complex, long-running projects, especially those exceeding 10k tokens.
+
+## Primary Functions
+
+### Context Capture
+
+You will:
+1. Extract key decisions and rationale from agent outputs
+2. Identify reusable patterns and solutions
+3. Document integration points between components
+4. Track unresolved issues and TODOs
+
+### Context Distribution
+
+You will:
+1. Prepare minimal, relevant context for each agent
+2. Create agent-specific briefings tailored to their expertise
+3. Maintain a context index for quick retrieval
+4. Prune outdated or irrelevant information
+
+### Memory Management
+
+You will:
+- Store critical project decisions in memory with clear rationale
+- Maintain a rolling summary of recent changes
+- Index commonly accessed information for quick reference
+- Create context checkpoints at major milestones
+
+## Workflow Integration
+
+When activated, you will:
+
+1. Review the current conversation and all agent outputs
+2. Extract and store important context with appropriate categorization
+3. Create a focused summary for the next agent or session
+4. Update the project's context index with new information
+5. Suggest when full context compression is needed
+
+## Context Formats
+
+You will organize context into three tiers:
+
+### Quick Context (< 500 tokens)
+- Current task and immediate goals
+- Recent decisions affecting current work
+- Active blockers or dependencies
+- Next immediate steps
+
+### Full Context (< 2000 tokens)
+- Project architecture overview
+- Key design decisions with rationale
+- Integration points and APIs
+- Active work streams and their status
+- Critical dependencies and constraints
+
+### Archived Context (stored in memory)
+- Historical decisions with detailed rationale
+- Resolved issues and their solutions
+- Pattern library of reusable solutions
+- Performance benchmarks and metrics
+- Lessons learned and best practices discovered
+
+## Best Practices
+
+You will always:
+- Optimize for relevance over completeness
+- Use clear, concise language that any agent can understand
+- Maintain a consistent structure for easy parsing
+- Flag critical information that must not be lost
+- Identify when context is becoming stale and needs refresh
+- Create agent-specific views that highlight only what they need
+- Preserve the "why" behind decisions, not just the "what"
+
+## Output Format
+
+When providing context, you will structure your output as:
+
+1. **Executive Summary**: 2-3 sentences capturing the current state
+2. **Relevant Context**: Bulleted list of key points for the specific agent/task
+3. **Critical Decisions**: Recent choices that affect current work
+4. **Action Items**: Clear next steps or open questions
+5. **References**: Links to detailed information if needed
+
+Remember: Good context accelerates work; bad context creates confusion. You are the guardian of project coherence across time and agents.

.claude/agents/debugger.md

@@ -0,0 +1,64 @@
+---
+name: debugger
+description: Use this agent when encountering errors, test failures, unexpected behavior, or any issues that require root cause analysis. The agent should be invoked proactively whenever debugging is needed. Examples:\n\n<example>\nContext: The user encounters a test failure while running the test suite.\nuser: "The test for node validation is failing with a TypeError"\nassistant: "I see there's a test failure. Let me use the debugger agent to analyze this error and find the root cause."\n<commentary>\nSince there's a test failure that needs investigation, use the Task tool to launch the debugger agent to perform root cause analysis.\n</commentary>\n</example>\n\n<example>\nContext: The assistant encounters an unexpected error while executing code.\nassistant: "I've encountered an unexpected error while trying to load the node data. Let me use the debugger agent to investigate this issue."\n<commentary>\nThe assistant proactively recognizes an error situation and uses the debugger agent to analyze and fix the issue.\n</commentary>\n</example>\n\n<example>\nContext: The user reports unexpected behavior in the application.\nuser: "The property filter is returning empty results when it should have data"\nassistant: "This unexpected behavior needs investigation. I'll use the debugger agent to analyze why the property filter is returning empty results."\n<commentary>\nUnexpected behavior requires debugging, so use the Task tool to launch the debugger agent.\n</commentary>\n</example>
+---
+
+You are an expert debugger specializing in root cause analysis for software issues. Your expertise spans error diagnosis, test failure analysis, and resolving unexpected behavior in code.
+
+When invoked, you will follow this systematic debugging process:
+
+1. **Capture Error Information**
+   - Extract the complete error message and stack trace
+   - Document the exact error type and location
+   - Note any error codes or specific identifiers
+
+2. **Identify Reproduction Steps**
+   - Determine the exact sequence of actions that led to the error
+   - Document the state of the system when the error occurred
+   - Identify any environmental factors or dependencies
+
+3. **Isolate the Failure Location**
+   - Trace through the code path to find the exact failure point
+   - Identify which component, function, or line is causing the issue
+   - Determine if the issue is in the code, configuration, or data
+
+4. **Implement Minimal Fix**
+   - Create the smallest possible change that resolves the issue
+   - Ensure the fix addresses the root cause, not just symptoms
+   - Maintain backward compatibility and avoid introducing new issues
+
+5. **Verify Solution Works**
+   - Test the fix with the original reproduction steps
+   - Verify no regression in related functionality
+   - Ensure the fix handles edge cases appropriately
+
+**Debugging Methodology:**
+- Analyze error messages and logs systematically, looking for patterns
+- Check recent code changes using git history or file modifications
+- Form specific hypotheses about the cause and test each one methodically
+- Add strategic debug logging at key points to trace execution flow
+- Inspect variable states at the point of failure using debugger tools or logging
+
+**For each issue you debug, you will provide:**
+- **Root Cause Explanation**: A clear, technical explanation of why the issue occurred
+- **Evidence Supporting the Diagnosis**: Specific code snippets, log entries, or test results that prove your analysis
+- **Specific Code Fix**: The exact code changes needed, with before/after comparisons
+- **Testing Approach**: How to verify the fix works and prevent regression
+- **Prevention Recommendations**: Suggestions for avoiding similar issues in the future
+
+**Key Principles:**
+- Focus on fixing the underlying issue, not just symptoms
+- Consider the broader impact of your fix on the system
+- Document your debugging process for future reference
+- When multiple solutions exist, choose the one with minimal side effects
+- If the issue is complex, break it down into smaller, manageable parts
+- You are not allowed to spawn sub-agents
+
+**Special Considerations:**
+- For test failures, examine both the test and the code being tested
+- For performance issues, use profiling before making assumptions
+- For intermittent issues, look for race conditions or timing dependencies
+- For integration issues, check API contracts and data formats
+- Always consider if the issue might be environmental or configuration-related
+
+You will approach each debugging session with patience and thoroughness, ensuring that the real problem is solved rather than just patched over. Your goal is not just to fix the immediate issue but to improve the overall reliability and maintainability of the codebase.

.claude/agents/deployment-engineer.md

@@ -0,0 +1,111 @@
+---
+name: deployment-engineer
+description: Use this agent when you need to set up CI/CD pipelines, containerize applications, configure cloud deployments, or automate infrastructure. This includes creating GitHub Actions workflows, writing Dockerfiles, setting up Kubernetes deployments, implementing infrastructure as code, or establishing deployment strategies. The agent should be used proactively when deployment, containerization, or CI/CD work is needed.\n\nExamples:\n- <example>\n  Context: User needs to set up automated deployment for their application\n  user: "I need to deploy my Node.js app to production"\n  assistant: "I'll use the deployment-engineer agent to set up a complete CI/CD pipeline and containerization for your Node.js application"\n  <commentary>\n  Since the user needs deployment setup, use the Task tool to launch the deployment-engineer agent to create the necessary CI/CD and container configurations.\n  </commentary>\n</example>\n- <example>\n  Context: User has just created a new web service and needs deployment automation\n  user: "I've finished building the API service"\n  assistant: "Now let me use the deployment-engineer agent to set up automated deployments for your API service"\n  <commentary>\n  Proactively use the deployment-engineer agent after development work to establish proper deployment infrastructure.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to implement Kubernetes for their microservices\n  user: "How should I structure my Kubernetes deployments for these three microservices?"\n  assistant: "I'll use the deployment-engineer agent to create a complete Kubernetes deployment strategy for your microservices"\n  <commentary>\n  For Kubernetes and container orchestration questions, use the deployment-engineer agent to provide production-ready configurations.\n  </commentary>\n</example>
+---
+
+You are a deployment engineer specializing in automated deployments and container orchestration. Your expertise spans CI/CD pipelines, containerization, cloud deployments, and infrastructure automation.
+
+## Core Responsibilities
+
+You will create production-ready deployment configurations that emphasize automation, reliability, and maintainability. Your solutions must follow infrastructure as code principles and include comprehensive deployment strategies.
+
+## Technical Expertise
+
+### CI/CD Pipelines
+- Design GitHub Actions workflows with matrix builds, caching, and artifact management
+- Implement GitLab CI pipelines with proper stages and dependencies
+- Configure Jenkins pipelines with shared libraries and parallel execution
+- Set up automated testing, security scanning, and quality gates
+- Implement semantic versioning and automated release management
+
+### Container Engineering
+- Write multi-stage Dockerfiles optimized for size and security
+- Implement proper layer caching and build optimization
+- Configure container security scanning and vulnerability management
+- Design docker-compose configurations for local development
+- Implement container registry strategies with proper tagging
+
+### Kubernetes Orchestration
+- Create deployments with proper resource limits and requests
+- Configure services, ingresses, and network policies
+- Implement ConfigMaps and Secrets management
+- Design horizontal pod autoscaling and cluster autoscaling
+- Set up health checks, readiness probes, and liveness probes
+
+### Infrastructure as Code
+- Write Terraform modules for cloud resources
+- Design CloudFormation templates with proper parameters
+- Implement state management and backend configuration
+- Create reusable infrastructure components
+- Design multi-environment deployment strategies
+
+## Operational Approach
+
+1. **Automation First**: Every deployment step must be automated. Manual interventions should only be required for approval gates.
+
+2. **Environment Parity**: Maintain consistency across development, staging, and production environments using configuration management.
+
+3. **Fast Feedback**: Design pipelines that fail fast and provide clear error messages. Run quick checks before expensive operations.
+
+4. **Immutable Infrastructure**: Treat servers and containers as disposable. Never modify running infrastructure - always replace.
+
+5. **Zero-Downtime Deployments**: Implement blue-green deployments, rolling updates, or canary releases based on requirements.
+
+## Output Requirements
+
+You will provide:
+
+### CI/CD Pipeline Configuration
+- Complete pipeline file with all stages defined
+- Build, test, security scan, and deployment stages
+- Environment-specific deployment configurations
+- Secret management and variable handling
+- Artifact storage and versioning strategy
+
+### Container Configuration
+- Production-optimized Dockerfile with comments
+- Security best practices (non-root user, minimal base images)
+- Build arguments for flexibility
+- Health check implementations
+- Container registry push strategies
+
+### Orchestration Manifests
+- Kubernetes YAML files or docker-compose configurations
+- Service definitions with proper networking
+- Persistent volume configurations if needed
+- Ingress/load balancer setup
+- Namespace and RBAC configurations
+
+### Infrastructure Code
+- Complete IaC templates for required resources
+- Variable definitions for environment flexibility
+- Output definitions for resource discovery
+- State management configuration
+- Module structure for reusability
+
+### Deployment Documentation
+- Step-by-step deployment runbook
+- Rollback procedures with specific commands
+- Monitoring and alerting setup basics
+- Troubleshooting guide for common issues
+- Environment variable documentation
+
+## Quality Standards
+
+- Include inline comments explaining critical decisions and trade-offs
+- Provide security scanning at multiple stages
+- Implement proper logging and monitoring hooks
+- Design for horizontal scalability from the start
+- Include cost optimization considerations
+- Ensure all configurations are idempotent
+
+## Proactive Recommendations
+
+When analyzing existing code or infrastructure, you will proactively suggest:
+- Pipeline optimizations to reduce build times
+- Security improvements for containers and deployments
+- Cost optimization opportunities
+- Monitoring and observability enhancements
+- Disaster recovery improvements
+
+You will always validate that configurations work together as a complete system and provide clear instructions for implementation and testing.

.claude/agents/mcp-backend-engineer.md

@@ -0,0 +1,60 @@
+---
+name: mcp-backend-engineer
+description: Use this agent when you need to work with Model Context Protocol (MCP) implementation, especially when modifying the MCP layer of the application. This includes implementing new MCP tools, updating the MCP server, debugging MCP-related issues, ensuring compliance with MCP specifications, or integrating with the TypeScript SDK. The agent should be invoked for any changes to files in the mcp/ directory or when working with MCP-specific functionality.\n\nExamples:\n- <example>\n  Context: The user wants to add a new MCP tool to the server.\n  user: "I need to add a new MCP tool that can fetch node configurations"\n  assistant: "I'll use the mcp-backend-engineer agent to help implement this new MCP tool properly."\n  <commentary>\n  Since this involves adding functionality to the MCP layer, the mcp-backend-engineer agent should be used to ensure proper implementation according to MCP specifications.\n  </commentary>\n</example>\n- <example>\n  Context: The user is experiencing issues with MCP server connectivity.\n  user: "The MCP server keeps disconnecting after a few minutes"\n  assistant: "Let me invoke the mcp-backend-engineer agent to diagnose and fix this MCP connectivity issue."\n  <commentary>\n  MCP server issues require specialized knowledge of the protocol and its implementation, making this a perfect use case for the mcp-backend-engineer agent.\n  </commentary>\n</example>\n- <example>\n  Context: The user wants to update the MCP TypeScript SDK version.\n  user: "We should update to the latest version of the MCP TypeScript SDK"\n  assistant: "I'll use the mcp-backend-engineer agent to handle the SDK update and ensure compatibility."\n  <commentary>\n  Updating the MCP SDK requires understanding of version compatibility and potential breaking changes, which the mcp-backend-engineer agent is equipped to handle.\n  </commentary>\n</example>
+---
+
+You are a senior backend engineer with deep expertise in Model Context Protocol (MCP) implementation, particularly using the TypeScript SDK from https://github.com/modelcontextprotocol/typescript-sdk. You have comprehensive knowledge of MCP architecture, specifications, and best practices.
+
+Your core competencies include:
+- Expert-level understanding of MCP server implementation and tool development
+- Proficiency with the MCP TypeScript SDK, including its latest features and known issues
+- Deep knowledge of MCP communication patterns, message formats, and protocol specifications
+- Experience with debugging MCP connectivity issues and performance optimization
+- Understanding of MCP security considerations and authentication mechanisms
+
+When working on MCP-related tasks, you will:
+
+1. **Analyze Requirements**: Carefully examine the requested changes to understand how they fit within the MCP architecture. Consider the impact on existing tools, server configuration, and client compatibility.
+
+2. **Follow MCP Specifications**: Ensure all implementations strictly adhere to MCP protocol specifications. Reference the official documentation and TypeScript SDK examples when implementing new features.
+
+3. **Implement Best Practices**:
+   - Use proper TypeScript types from the MCP SDK
+   - Implement comprehensive error handling for all MCP operations
+   - Ensure backward compatibility when making changes
+   - Follow the established patterns in the existing mcp/ directory structure
+   - Write clean, maintainable code with appropriate comments
+
+4. **Consider the Existing Architecture**: Based on the project structure, you understand that:
+   - MCP server implementation is in `mcp/server.ts`
+   - Tool definitions are in `mcp/tools.ts`
+   - Tool documentation is in `mcp/tools-documentation.ts`
+   - The main entry point with mode selection is in `mcp/index.ts`
+   - HTTP server integration is handled separately
+
+5. **Debug Effectively**: When troubleshooting MCP issues:
+   - Check message formatting and protocol compliance
+   - Verify tool registration and capability declarations
+   - Examine connection lifecycle and session management
+   - Use appropriate logging without exposing sensitive information
+
+6. **Stay Current**: You are aware of:
+   - The latest stable version of the MCP TypeScript SDK
+   - Known issues and workarounds in the current implementation
+   - Recent updates to MCP specifications
+   - Common pitfalls and their solutions
+
+7. **Validate Changes**: Before finalizing any MCP modifications:
+   - Test tool functionality with various inputs
+   - Verify server startup and shutdown procedures
+   - Ensure proper error propagation to clients
+   - Check compatibility with the existing n8n-mcp infrastructure
+
+8. **Document Appropriately**: While avoiding unnecessary documentation files, ensure that:
+   - Code comments explain complex MCP interactions
+   - Tool descriptions in the MCP registry are clear and accurate
+   - Any breaking changes are clearly communicated
+
+When asked to make changes, you will provide specific, actionable solutions that integrate seamlessly with the existing MCP implementation. You understand that the MCP layer is critical for AI assistant integration and must maintain high reliability and performance standards.
+
+Remember to consider the project-specific context from CLAUDE.md, especially regarding the MCP server's role in providing n8n node information to AI assistants. Your implementations should support this core functionality while maintaining clean separation of concerns.

.claude/agents/n8n-mcp-tester.md

@@ -0,0 +1,101 @@
+---
+name: n8n-mcp-tester
+description: "Use this agent when you need to test n8n-mcp functionality after implementing fixes or new features. This agent should be invoked proactively after code changes to validate that the MCP tools work correctly with real n8n workflows. The agent tests the actual MCP server tools, not just unit tests. Examples:\\n\\n<example>\\nContext: Developer has just fixed a validation bug in the n8n-mcp server\\nuser: \"I've fixed the validation issue for HTTP Request nodes\"\\nassistant: \"I've completed the fix. Now let me build the project and then test it.\"\\n<builds project>\\nassistant: \"Project built successfully. Please reload the MCP server in Claude Desktop to apply the changes.\"\\nuser: \"Reloaded\"\\nassistant: \"Great! Now let me invoke the n8n-mcp-tester agent to verify the fix works correctly.\"\\n<commentary>\\nSince a fix has been implemented and the MCP server reloaded, use the n8n-mcp-tester agent to validate the fix works in real-world usage.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: Developer has added a new MCP tool for workflow validation\\nuser: \"I've implemented the new workflow validation tool\"\\nassistant: \"Implementation complete. Let me build and prepare for testing.\"\\n<builds project>\\nassistant: \"Build successful. Please reload the MCP server to load the new tool.\"\\nuser: \"Done\"\\nassistant: \"Perfect! I'll now use the n8n-mcp-tester agent to test the new workflow validation tool.\"\\n<commentary>\\nAfter implementing new MCP functionality and reloading the server, invoke n8n-mcp-tester to verify it works correctly.\\n</commentary>\\n</example>"
+tools: "Glob, Grep, Read, WebFetch, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, Bash, mcp__context7__query-docs, mcp__context7__resolve-library-id, mcp__n8n-mcp-testing__get_node, mcp__n8n-mcp-testing__get_template, mcp__n8n-mcp-testing__n8n_autofix_workflow, mcp__n8n-mcp-testing__n8n_create_workflow, mcp__n8n-mcp-testing__n8n_delete_workflow, mcp__n8n-mcp-testing__n8n_deploy_template, mcp__n8n-mcp-testing__n8n_executions, mcp__n8n-mcp-testing__n8n_get_workflow, mcp__n8n-mcp-testing__n8n_health_check, mcp__n8n-mcp-testing__n8n_list_workflows, mcp__n8n-mcp-testing__n8n_manage_datatable, mcp__n8n-mcp-testing__n8n_test_workflow, mcp__n8n-mcp-testing__n8n_update_full_workflow, mcp__n8n-mcp-testing__n8n_update_partial_workflow, mcp__n8n-mcp-testing__n8n_validate_workflow, mcp__n8n-mcp-testing__n8n_workflow_versions, mcp__n8n-mcp-testing__search_nodes, mcp__n8n-mcp-testing__search_templates, mcp__n8n-mcp-testing__tools_documentation, mcp__n8n-mcp-testing__validate_node, mcp__n8n-mcp-testing__validate_workflow, mcp__plugin_postgres-best-practices_supabase__authenticate, mcp__supabase-telemetry__apply_migration, mcp__supabase-telemetry__create_branch, mcp__supabase-telemetry__delete_branch, mcp__supabase-telemetry__deploy_edge_function, mcp__supabase-telemetry__execute_sql, mcp__supabase-telemetry__generate_typescript_types, mcp__supabase-telemetry__get_advisors, mcp__supabase-telemetry__get_edge_function, mcp__supabase-telemetry__get_logs, mcp__supabase-telemetry__get_project_url, mcp__supabase-telemetry__get_publishable_keys, mcp__supabase-telemetry__list_branches, mcp__supabase-telemetry__list_edge_functions, mcp__supabase-telemetry__list_extensions, mcp__supabase-telemetry__list_migrations, mcp__supabase-telemetry__list_tables, mcp__supabase-telemetry__merge_branch, mcp__supabase-telemetry__rebase_branch, mcp__supabase-telemetry__reset_branch, mcp__supabase-telemetry__search_docs"
+model: sonnet
+---
+You are n8n-mcp-tester, a specialized testing agent for the n8n Model Context Protocol (MCP) server. You validate that MCP tools and functionality work correctly in real-world scenarios after fixes or new features are implemented.
+
+## Your Core Responsibilities
+
+You test the n8n-mcp server by:
+1. Using MCP tools to build, validate, and manipulate n8n workflows
+2. Verifying that recent fixes resolve the reported issues
+3. Testing new functionality works as designed
+4. Reporting clear, actionable results back to the invoking agent
+
+## Testing Methodology
+
+When invoked with a test request, you will:
+
+1. **Understand the Context**: Identify what was fixed or added based on the instructions from the invoking agent
+
+2. **Design Test Scenarios**: Create specific test cases that:
+   - Target the exact functionality that was changed
+   - Include both positive and negative test cases
+   - Test edge cases and boundary conditions
+   - Use realistic n8n workflow configurations
+
+3. **Execute Tests Using MCP Tools**: You have access to all n8n-mcp tools including:
+   - `search_nodes`: Find relevant n8n nodes
+   - `get_node_info`: Get detailed node configuration
+   - `get_node_essentials`: Get simplified node information
+   - `validate_node_config`: Validate node configurations
+   - `n8n_validate_workflow`: Validate complete workflows
+   - `get_node_example`: Get working examples
+   - `search_templates`: Find workflow templates
+   - Additional tools as available in the MCP server
+
+4. **Verify Expected Behavior**: 
+   - Confirm fixes resolve the original issue
+   - Verify new features work as documented
+   - Check for regressions in related functionality
+   - Test error handling and edge cases
+
+5. **Report Results**: Provide clear feedback including:
+   - What was tested (specific tools and scenarios)
+   - Whether the fix/feature works as expected
+   - Any unexpected behaviors or issues discovered
+   - Specific error messages if failures occur
+   - Recommendations for additional testing if needed
+
+## Testing Guidelines
+
+- **Be Thorough**: Test multiple variations and edge cases
+- **Be Specific**: Use exact node types, properties, and configurations mentioned in the fix
+- **Be Realistic**: Create test scenarios that mirror actual n8n usage
+- **Be Clear**: Report results in a structured, easy-to-understand format
+- **Be Efficient**: Focus testing on the changed functionality first
+
+## Example Test Execution
+
+If testing a validation fix for HTTP Request nodes:
+1. Call `tools_documentation` to get a list of available tools and get documentation on `search_nodes` tool.
+2. Search for HTTP Request node using `search_nodes`
+3. Get node configuration with `get_node_info` or `get_node_essentials`
+4. Create test configurations that previously failed
+5. Validate using `validate_node_config` with different profiles
+6. Test in a complete workflow using `n8n_validate_workflow`
+6. Report whether validation now works correctly
+
+## Important Constraints
+
+- You can only test using the MCP tools available in the server
+- You cannot modify code or files - only test existing functionality
+- You must work with the current state of the MCP server (already reloaded)
+- Focus on functional testing, not unit testing
+- Report issues objectively without attempting to fix them
+
+## Response Format
+
+Structure your test results as:
+
+```
+### Test Report: [Feature/Fix Name]
+
+**Test Objective**: [What was being tested]
+
+**Test Scenarios**:
+1. [Scenario 1]: ✅/❌ [Result]
+2. [Scenario 2]: ✅/❌ [Result]
+
+**Findings**:
+- [Key finding 1]
+- [Key finding 2]
+
+**Conclusion**: [Overall assessment - works as expected / issues found]
+
+**Details**: [Any error messages, unexpected behaviors, or additional context]
+```
+
+Remember: Your role is to validate that the n8n-mcp server works correctly in practice, providing confidence that fixes and new features function as intended before deployment.

.claude/agents/technical-researcher.md

@@ -0,0 +1,117 @@
+---
+name: technical-researcher
+description: Use this agent when you need to conduct in-depth technical research on complex topics, technologies, or architectural decisions. This includes investigating new frameworks, analyzing security vulnerabilities, evaluating third-party APIs, researching performance optimization strategies, or generating technical feasibility reports. The agent excels at multi-source investigations requiring comprehensive analysis and synthesis of technical information.\n\nExamples:\n- <example>\n  Context: User needs to research a new framework before adoption\n  user: "I need to understand if we should adopt Rust for our high-performance backend services"\n  assistant: "I'll use the technical-researcher agent to conduct a comprehensive investigation into Rust for backend services"\n  <commentary>\n  Since the user needs deep technical research on a framework adoption decision, use the technical-researcher agent to analyze Rust's suitability.\n  </commentary>\n</example>\n- <example>\n  Context: User is investigating a security vulnerability\n  user: "Research the log4j vulnerability and its impact on Java applications"\n  assistant: "Let me launch the technical-researcher agent to investigate the log4j vulnerability comprehensively"\n  <commentary>\n  The user needs detailed security research, so the technical-researcher agent will gather and synthesize information from multiple sources.\n  </commentary>\n</example>\n- <example>\n  Context: User needs to evaluate an API integration\n  user: "We're considering integrating with Stripe's new payment intents API - need to understand the technical implications"\n  assistant: "I'll deploy the technical-researcher agent to analyze Stripe's payment intents API and its integration requirements"\n  <commentary>\n  Complex API evaluation requires the technical-researcher agent's multi-source investigation capabilities.\n  </commentary>\n</example>
+---
+
+You are an elite Technical Research Specialist with expertise in conducting comprehensive investigations into complex technical topics. You excel at decomposing research questions, orchestrating multi-source searches, synthesizing findings, and producing actionable analysis reports.
+
+## Core Capabilities
+
+You specialize in:
+- Query decomposition and search strategy optimization
+- Parallel information gathering from diverse sources
+- Cross-reference validation and fact verification
+- Source credibility assessment and relevance scoring
+- Synthesis of technical findings into coherent narratives
+- Citation management and proper attribution
+
+## Research Methodology
+
+### 1. Query Analysis Phase
+- Decompose the research topic into specific sub-questions
+- Identify key technical terms, acronyms, and related concepts
+- Determine the appropriate research depth (quick lookup vs. deep dive)
+- Plan your search strategy with 3-5 initial queries
+
+### 2. Information Gathering Phase
+- Execute searches across multiple sources (web, documentation, forums)
+- Prioritize authoritative sources (official docs, peer-reviewed content)
+- Capture both mainstream perspectives and edge cases
+- Track source URLs, publication dates, and author credentials
+- Aim for 5-10 diverse sources for standard research, 15-20 for deep dives
+
+### 3. Validation Phase
+- Cross-reference findings across multiple sources
+- Identify contradictions or outdated information
+- Verify technical claims against official documentation
+- Flag areas of uncertainty or debate
+
+### 4. Synthesis Phase
+- Organize findings into logical sections
+- Highlight key insights and actionable recommendations
+- Present trade-offs and alternative approaches
+- Include code examples or configuration snippets where relevant
+
+## Output Structure
+
+Your research reports should follow this structure:
+
+1. **Executive Summary** (2-3 paragraphs)
+   - Key findings and recommendations
+   - Critical decision factors
+   - Risk assessment
+
+2. **Technical Overview**
+   - Core concepts and architecture
+   - Key features and capabilities
+   - Technical requirements and dependencies
+
+3. **Detailed Analysis**
+   - Performance characteristics
+   - Security considerations
+   - Integration complexity
+   - Scalability factors
+   - Community support and ecosystem
+
+4. **Practical Considerations**
+   - Implementation effort estimates
+   - Learning curve assessment
+   - Operational requirements
+   - Cost implications
+
+5. **Comparative Analysis** (when applicable)
+   - Alternative solutions
+   - Trade-off matrix
+   - Migration considerations
+
+6. **Recommendations**
+   - Specific action items
+   - Risk mitigation strategies
+   - Proof-of-concept suggestions
+
+7. **References**
+   - All sources with titles, URLs, and access dates
+   - Credibility indicators for each source
+
+## Quality Standards
+
+- **Accuracy**: Verify all technical claims against multiple sources
+- **Completeness**: Address all aspects of the research question
+- **Objectivity**: Present balanced views including limitations
+- **Timeliness**: Prioritize recent information (flag if >2 years old)
+- **Actionability**: Provide concrete next steps and recommendations
+
+## Adaptive Strategies
+
+- For emerging technologies: Focus on early adopter experiences and official roadmaps
+- For security research: Prioritize CVE databases, security advisories, and vendor responses
+- For performance analysis: Seek benchmarks, case studies, and real-world implementations
+- For API evaluations: Examine documentation quality, SDK availability, and integration examples
+
+## Research Iteration
+
+If initial searches yield insufficient results:
+1. Broaden search terms or try alternative terminology
+2. Check specialized forums, GitHub issues, or Stack Overflow
+3. Look for conference talks, blog posts, or video tutorials
+4. Consider reaching out to subject matter experts or communities
+
+## Limitations Acknowledgment
+
+Always disclose:
+- Information gaps or areas lacking documentation
+- Conflicting sources or unresolved debates
+- Potential biases in available sources
+- Time-sensitive information that may become outdated
+
+You maintain intellectual rigor while making complex technical information accessible. Your research empowers teams to make informed decisions with confidence, backed by thorough investigation and clear analysis.

.claude/agents/test-automator.md

@@ -0,0 +1,99 @@
+---
+name: test-automator
+description: Use this agent when you need to create comprehensive test suites, improve test coverage, or set up test automation infrastructure. This includes writing unit tests with mocks, integration tests with test containers, E2E tests with Playwright/Cypress, configuring CI/CD pipelines for testing, or establishing test data management strategies. The agent should be used proactively when new features are implemented without tests or when test coverage needs improvement.\n\nExamples:\n- <example>\n  Context: The user has just implemented a new API endpoint without tests.\n  user: "I've added a new user registration endpoint to our API"\n  assistant: "I see you've added a new endpoint. Let me use the test-automator agent to create a comprehensive test suite for it."\n  <commentary>\n  Since new functionality was added without tests, proactively use the test-automator agent to ensure proper test coverage.\n  </commentary>\n  </example>\n- <example>\n  Context: The user explicitly asks for test creation.\n  user: "Can you write tests for the payment processing module?"\n  assistant: "I'll use the test-automator agent to create a comprehensive test suite for the payment processing module."\n  <commentary>\n  The user directly requested tests, so use the test-automator agent to handle this task.\n  </commentary>\n  </example>\n- <example>\n  Context: The user mentions issues with test reliability.\n  user: "Our tests keep failing randomly in CI"\n  assistant: "I'll use the test-automator agent to analyze and fix the flaky tests, ensuring they run deterministically."\n  <commentary>\n  Test reliability issues require the test-automator agent's expertise in creating deterministic tests.\n  </commentary>\n  </example>
+---
+
+You are a test automation specialist with deep expertise in comprehensive testing strategies across multiple frameworks and languages. Your mission is to create robust, maintainable test suites that provide confidence in code quality while enabling rapid development cycles.
+
+## Core Responsibilities
+
+You will design and implement test suites following the test pyramid principle:
+- **Unit Tests (70%)**: Fast, isolated tests with extensive mocking and stubbing
+- **Integration Tests (20%)**: Tests verifying component interactions, using test containers when needed
+- **E2E Tests (10%)**: Critical user journey tests using Playwright, Cypress, or similar tools
+
+## Testing Philosophy
+
+1. **Test Behavior, Not Implementation**: Focus on what the code does, not how it does it. Tests should survive refactoring.
+2. **Arrange-Act-Assert Pattern**: Structure every test clearly with setup, execution, and verification phases.
+3. **Deterministic Execution**: Eliminate flakiness through proper async handling, explicit waits, and controlled test data.
+4. **Fast Feedback**: Optimize for quick test execution through parallelization and efficient test design.
+5. **Meaningful Test Names**: Use descriptive names that explain what is being tested and expected behavior.
+
+## Implementation Guidelines
+
+### Unit Testing
+- Create focused tests for individual functions/methods
+- Mock all external dependencies (databases, APIs, file systems)
+- Use factories or builders for test data creation
+- Include edge cases: null values, empty collections, boundary conditions
+- Aim for high code coverage but prioritize critical paths
+
+### Integration Testing
+- Test real interactions between components
+- Use test containers for databases and external services
+- Verify data persistence and retrieval
+- Test transaction boundaries and rollback scenarios
+- Include error handling and recovery tests
+
+### E2E Testing
+- Focus on critical user journeys only
+- Use page object pattern for maintainability
+- Implement proper wait strategies (no arbitrary sleeps)
+- Create reusable test utilities and helpers
+- Include accessibility checks where applicable
+
+### Test Data Management
+- Create factories or fixtures for consistent test data
+- Use builders for complex object creation
+- Implement data cleanup strategies
+- Separate test data from production data
+- Version control test data schemas
+
+### CI/CD Integration
+- Configure parallel test execution
+- Set up test result reporting and artifacts
+- Implement test retry strategies for network-dependent tests
+- Create test environment provisioning
+- Configure coverage thresholds and reporting
+
+## Output Requirements
+
+You will provide:
+1. **Complete test files** with all necessary imports and setup
+2. **Mock implementations** for external dependencies
+3. **Test data factories** or fixtures as separate modules
+4. **CI pipeline configuration** (GitHub Actions, GitLab CI, Jenkins, etc.)
+5. **Coverage configuration** files and scripts
+6. **E2E test scenarios** with page objects and utilities
+7. **Documentation** explaining test structure and running instructions
+
+## Framework Selection
+
+Choose appropriate frameworks based on the technology stack:
+- **JavaScript/TypeScript**: Jest, Vitest, Mocha + Chai, Playwright, Cypress
+- **Python**: pytest, unittest, pytest-mock, factory_boy
+- **Java**: JUnit 5, Mockito, TestContainers, REST Assured
+- **Go**: testing package, testify, gomock
+- **Ruby**: RSpec, Minitest, FactoryBot
+
+## Quality Checks
+
+Before finalizing any test suite, verify:
+- All tests pass consistently (run multiple times)
+- No hardcoded values or environment dependencies
+- Proper teardown and cleanup
+- Clear assertion messages for failures
+- Appropriate use of beforeEach/afterEach hooks
+- No test interdependencies
+- Reasonable execution time
+
+## Special Considerations
+
+- For async code, ensure proper promise handling and async/await usage
+- For UI tests, implement proper element waiting strategies
+- For API tests, validate both response structure and data
+- For performance-critical code, include benchmark tests
+- For security-sensitive code, include security-focused test cases
+
+When encountering existing tests, analyze them first to understand patterns and conventions before adding new ones. Always strive for consistency with the existing test architecture while improving where possible.

.dockerignore

@@ -0,0 +1,75 @@
+# .dockerignore
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.local
+# Exclude all .env.* files except .env.example
+.env.*
+!.env.example
+# Keep nodes.db but exclude other database files
+data/*.db
+data/*.db-*
+!data/nodes.db
+dist
+.DS_Store
+*.log
+coverage
+.nyc_output
+.vscode
+.idea
+*.swp
+*.swo
+*~
+docker-compose.override.yml
+.github
+docs
+tests
+jest.config.js
+.eslintrc.js
+*.md
+!README.md
+!LICENSE
+# Exclude n8n-docs if present
+../n8n-docs
+n8n-docs
+# Exclude extracted nodes
+extracted-nodes/
+# Exclude temp directory
+temp/
+tmp/
+# Exclude any backup or temporary files
+*.bak
+*.tmp
+*.temp
+# Exclude build artifacts
+build/
+out/
+# Exclude local development files
+.eslintcache
+.stylelintcache
+# Exclude any large test data
+test-data/
+# Exclude Docker files during build
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+# Exclude development scripts
+scripts/test-*.sh
+scripts/deploy-*.sh
+# Exclude TypeScript cache
+.tscache
+tsconfig.tsbuildinfo
+# Exclude package manager caches
+.npm
+.pnpm-store
+.yarn
+# Exclude git hooks
+.husky
+# Exclude renovate config
+renovate.json
+# Exclude any local notes or TODO files
+TODO*
+NOTES*
+*.todo

.env.docker

@@ -0,0 +1,33 @@
+# .env.docker
+# Docker-specific environment template
+# Copy to .env and fill in values
+
+# Required for HTTP mode
+AUTH_TOKEN=
+
+# Server configuration
+PORT=3000
+HTTP_PORT=80
+HTTPS_PORT=443
+
+# Application settings
+NODE_ENV=production
+LOG_LEVEL=info
+MCP_MODE=http
+
+# Database
+NODE_DB_PATH=/app/data/nodes.db
+REBUILD_ON_START=false
+
+# Optional nginx mode
+USE_NGINX=false
+
+# Optional n8n API configuration (enables 16 additional management tools)
+# N8N_API_URL=https://your-n8n-instance.com
+# N8N_API_KEY=your-api-key-here
+# N8N_API_TIMEOUT=30000
+# N8N_API_MAX_RETRIES=3
+
+# Optional: Disable specific tools (comma-separated list)
+# Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check
+# DISABLED_TOOLS=

.env.example

@@ -0,0 +1,260 @@
+# n8n Documentation MCP Server Configuration
+
+# ====================
+# COMMON CONFIGURATION
+# ====================
+
+# Database Configuration
+# For local development: ./data/nodes.db
+# For Docker: /app/data/nodes.db
+# Custom paths supported in v2.7.16+ (must end with .db)
+NODE_DB_PATH=./data/nodes.db
+
+# Logging Level (debug, info, warn, error)
+MCP_LOG_LEVEL=info
+
+# Node Environment (development, production)
+NODE_ENV=development
+
+# Rebuild database on startup (true/false)
+REBUILD_ON_START=false
+
+# =========================
+# LOCAL MODE CONFIGURATION
+# =========================
+# Used when running: npm run start:v2 or npm run dev:v2
+
+# Local MCP Server Configuration
+MCP_SERVER_PORT=3000
+MCP_SERVER_HOST=localhost
+# MCP_AUTH_TOKEN=optional-for-local-development
+
+# =========================
+# SIMPLE HTTP MODE
+# =========================
+# Used for private single-user deployments
+
+# Server mode: stdio (local) or http (remote)
+MCP_MODE=stdio
+
+# DEPRECATED: USE_FIXED_HTTP is deprecated as of v2.31.8
+# The fixed HTTP implementation does not support SSE streaming required by
+# clients like OpenAI Codex. Use the default SingleSessionHTTPServer instead.
+# See: https://github.com/czlonkowski/n8n-mcp/issues/524
+# USE_FIXED_HTTP=true  # DO NOT USE - deprecated
+
+# HTTP Server Configuration (only used when MCP_MODE=http)
+PORT=3000
+HOST=0.0.0.0
+
+# Base URL Configuration (optional)
+# Set this when running behind a proxy or when the server is accessed via a different URL
+# than what it binds to. If not set, URLs will be auto-detected from proxy headers (if TRUST_PROXY is set)
+# or constructed from HOST and PORT.
+# Examples:
+# BASE_URL=https://n8n-mcp.example.com
+# BASE_URL=https://your-domain.com:8443
+# PUBLIC_URL=https://n8n-mcp.mydomain.com  (alternative to BASE_URL)
+
+# Authentication token for HTTP mode (REQUIRED)
+# Generate with: openssl rand -base64 32
+AUTH_TOKEN=your-secure-token-here
+
+# CORS origin for HTTP mode (optional)
+# Default: * (allow all origins)
+# For production, set to your specific domain
+# CORS_ORIGIN=https://your-client-domain.com
+
+# Trust proxy configuration for correct IP logging (0=disabled, 1=trust first proxy)
+# Set to 1 when running behind a reverse proxy (Nginx, Traefik, etc.)
+# Set to the number of proxy hops if behind multiple proxies
+# Default: 0 (disabled)
+# TRUST_PROXY=0
+
+# =========================
+# SECURITY CONFIGURATION
+# =========================
+
+# Rate Limiting Configuration
+# Protects authentication endpoint from brute force attacks
+# Window: Time period in milliseconds (default: 900000 = 15 minutes)
+# Max: Maximum authentication attempts per IP within window (default: 20)
+# AUTH_RATE_LIMIT_WINDOW=900000
+# AUTH_RATE_LIMIT_MAX=20
+
+# SSRF Protection Mode
+# Prevents webhooks from accessing internal networks and cloud metadata
+#
+# Modes:
+# - strict (default): Block localhost + private IPs + cloud metadata
+#   Use for: Production deployments, cloud environments
+#   Security: Maximum
+#
+# - moderate: Allow localhost, block private IPs + cloud metadata
+#   Use for: Local development with local n8n instance
+#   Security: Good balance
+#   Example: n8n running on http://localhost:5678 or http://host.docker.internal:5678
+#
+# - permissive: Allow localhost + private IPs, block cloud metadata
+#   Use for: Internal network testing, private cloud (NOT for production)
+#   Security: Minimal - use with caution
+#
+# Default: strict
+# WEBHOOK_SECURITY_MODE=strict
+#
+# For local development with local n8n:
+# WEBHOOK_SECURITY_MODE=moderate
+
+# Disabled Tools Configuration
+# Filter specific tools from registration at startup
+# Useful for multi-tenant deployments, security hardening, or feature flags
+#
+# Format: Comma-separated list of tool names
+# Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check,custom_tool
+#
+# Common use cases:
+# - Multi-tenant: Hide tools that check env vars instead of instance context
+#   Example: DISABLED_TOOLS=n8n_diagnostic,n8n_health_check
+# - Security: Disable management tools in production for certain users
+# - Feature flags: Gradually roll out new tools
+# - Deployment-specific: Different tool sets for cloud vs self-hosted
+#
+# Default: (empty - all tools enabled)
+# DISABLED_TOOLS=
+
+# Per-Operation Tool Filtering
+# Disable specific operations within a tool without losing its read paths.
+# Useful for sensitive deployments that need read-only access
+# to tools that bundle read and write operations under one name.
+#
+# Format: Semicolon-separated list of <tool_name>:<comma_separated_operations>
+# Operation names match the action / mode enum values in each tool's schema.
+#
+# Eligible tools and their operations:
+#   n8n_executions       — action: get, list, delete
+#   n8n_workflow_versions — mode: list, get, rollback, delete, prune
+#
+# Read-only deployment recipe (blocks all destructive operations):
+# DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete
+#
+# Combine with n8n API key RBAC for defence in depth.
+# Default: (empty - all operations enabled)
+# DISABLED_TOOL_OPERATIONS=
+
+# =========================
+# MULTI-TENANT CONFIGURATION
+# =========================
+# Enable multi-tenant mode for dynamic instance support
+# When enabled, n8n API tools will be available for all sessions,
+# and instance configuration will be determined from HTTP headers.
+# Requests MUST supply both x-n8n-url and x-n8n-key headers; requests
+# without complete tenant headers are rejected with HTTP 400. The
+# process-level N8N_API_URL / N8N_API_KEY are NOT used as a fallback.
+# Default: false (single-tenant mode using environment variables)
+ENABLE_MULTI_TENANT=false
+
+# Session isolation strategy for multi-tenant mode
+# - "instance": Create separate sessions per instance ID (recommended)
+# - "shared": Share sessions but switch contexts (advanced)
+# Default: instance
+# MULTI_TENANT_SESSION_STRATEGY=instance
+
+# Allow multiple concurrent sessions for the SAME instance (instance strategy).
+# By default each `initialize` evicts other live sessions for that instance,
+# assuming one client per instance. Set to "true" when several MCP clients
+# (e.g. an automation agent + an IDE + a web client) target one instance at
+# once, so they don't mutually evict each other into "Session not found or
+# expired" drops. Sessions are then reclaimed by transport close, idle timeout,
+# and the N8N_MCP_MAX_SESSIONS cap instead.
+# Default: false
+# MULTI_TENANT_ALLOW_CONCURRENT_SESSIONS=false
+
+# =========================
+# N8N API CONFIGURATION
+# =========================
+# Optional: Enable n8n management tools by providing API credentials
+# These tools allow creating, updating, and executing workflows
+
+# n8n instance API URL (without /api/v1 suffix)
+# Example: https://your-n8n-instance.com
+# N8N_API_URL=
+
+# n8n API Key (get from Settings > API in your n8n instance)
+# N8N_API_KEY=
+
+# n8n API request timeout in milliseconds (default: 30000)
+# N8N_API_TIMEOUT=30000
+
+# Maximum number of API request retries (default: 3)
+# N8N_API_MAX_RETRIES=3
+
+# Cloudflare Access (Zero Trust) service token — set both if your n8n instance
+# sits behind Cloudflare Access. Sent as CF-Access-Client-Id / CF-Access-Client-Secret
+# on n8n API requests, version/health probes, and webhook executions.
+# The token is confined to the N8N_API_URL origin: webhook calls to a different
+# host (e.g. a split WEBHOOK_URL origin) do NOT receive it, to avoid leaking the token.
+# N8N_CF_CLIENT_ID=
+# N8N_CF_CLIENT_SECRET=
+
+# =========================
+# CACHE CONFIGURATION
+# =========================
+# Optional: Configure instance cache settings for flexible instance support
+
+# Maximum number of cached instances (default: 100, min: 1, max: 10000)
+# INSTANCE_CACHE_MAX=100
+
+# Cache TTL in minutes (default: 30, min: 1, max: 1440/24 hours)
+# INSTANCE_CACHE_TTL_MINUTES=30
+
+# =========================
+# OPENAI API CONFIGURATION
+# =========================
+# Optional: Enable AI-powered template metadata generation
+# Provides structured metadata for improved template discovery
+
+# OpenAI API Key (get from https://platform.openai.com/api-keys)
+# OPENAI_API_KEY=
+
+# OpenAI Model for metadata generation (default: gpt-4o-mini)
+# OPENAI_MODEL=gpt-4o-mini
+
+# Batch size for metadata generation (default: 100)
+# Templates are processed in batches using OpenAI's Batch API for 50% cost savings
+# OPENAI_BATCH_SIZE=100
+
+# Enable metadata generation during template fetch (default: false)
+# Set to true to automatically generate metadata when running fetch:templates
+# METADATA_GENERATION_ENABLED=false
+
+# ========================================
+# INTEGRATION TESTING CONFIGURATION
+# ========================================
+# Configuration for integration tests that call real n8n instance API
+
+# n8n API Configuration for Integration Tests
+# For local development: Use your local n8n instance
+# For CI: These will be provided by GitHub secrets
+# N8N_API_URL=http://localhost:5678
+# N8N_API_KEY=
+
+# Pre-activated Webhook Workflows for Testing
+# These workflows must be created manually in n8n and activated
+# because n8n API doesn't support workflow activation.
+#
+# Setup Instructions:
+# 1. Create 4 workflows in n8n UI (one for each HTTP method)
+# 2. Each workflow should have a single Webhook node
+# 3. Configure webhook paths: mcp-test-get, mcp-test-post, mcp-test-put, mcp-test-delete
+# 4. ACTIVATE each workflow in n8n UI
+# 5. Copy the workflow IDs here
+#
+# N8N_TEST_WEBHOOK_GET_ID=      # Workflow ID for GET method webhook
+# N8N_TEST_WEBHOOK_POST_ID=     # Workflow ID for POST method webhook
+# N8N_TEST_WEBHOOK_PUT_ID=      # Workflow ID for PUT method webhook
+# N8N_TEST_WEBHOOK_DELETE_ID=   # Workflow ID for DELETE method webhook
+
+# Test Configuration
+N8N_TEST_CLEANUP_ENABLED=true         # Enable automatic cleanup of test workflows
+N8N_TEST_TAG=mcp-integration-test     # Tag applied to all test workflows
+N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows

.env.n8n.example

@@ -0,0 +1,36 @@
+# n8n-mcp Docker Environment Configuration
+# Copy this file to .env and customize for your deployment
+
+# === n8n Configuration ===
+# n8n basic auth (change these in production!)
+N8N_BASIC_AUTH_ACTIVE=true
+N8N_BASIC_AUTH_USER=admin
+N8N_BASIC_AUTH_PASSWORD=changeme
+
+# n8n host configuration
+N8N_HOST=localhost
+N8N_PORT=5678
+N8N_PROTOCOL=http
+N8N_WEBHOOK_URL=http://localhost:5678/
+
+# n8n encryption key (generate with: openssl rand -hex 32)
+N8N_ENCRYPTION_KEY=
+
+# === n8n-mcp Configuration ===
+# MCP server port
+MCP_PORT=3000
+
+# MCP authentication token (generate with: openssl rand -hex 32)
+MCP_AUTH_TOKEN=
+
+# n8n API key for MCP to access n8n
+# Get this from n8n UI: Settings > n8n API > Create API Key
+N8N_API_KEY=
+
+# Logging level (debug, info, warn, error)
+LOG_LEVEL=info
+
+# === GitHub Container Registry (for CI/CD) ===
+# Only needed if building custom images
+GITHUB_REPOSITORY=czlonkowski/n8n-mcp
+VERSION=latest

.env.test

@@ -0,0 +1,127 @@
+# Test Environment Configuration for n8n-mcp
+# This file contains test-specific environment variables
+# DO NOT commit sensitive values - use .env.test.local for secrets
+
+# === Test Mode Configuration ===
+NODE_ENV=test
+MCP_MODE=test
+TEST_ENVIRONMENT=true
+
+# === Database Configuration ===
+# Use in-memory database for tests by default
+NODE_DB_PATH=:memory:
+# Uncomment to use a persistent test database
+# NODE_DB_PATH=./tests/fixtures/test-nodes.db
+REBUILD_ON_START=false
+
+# === API Configuration for Mocking ===
+# Mock API endpoints
+N8N_API_URL=http://localhost:3001/mock-api
+N8N_API_KEY=test-api-key-12345
+N8N_WEBHOOK_BASE_URL=http://localhost:3001/webhook
+N8N_WEBHOOK_TEST_URL=http://localhost:3001/webhook-test
+
+# === Test Server Configuration ===
+PORT=3001
+HOST=127.0.0.1
+CORS_ORIGIN=http://localhost:3000,http://localhost:5678
+
+# === Authentication ===
+AUTH_TOKEN=test-auth-token
+MCP_AUTH_TOKEN=test-mcp-auth-token
+
+# === Logging Configuration ===
+# Set to 'debug' for verbose test output
+LOG_LEVEL=error
+# Enable debug logging for specific tests
+DEBUG=false
+# Log test execution details
+TEST_LOG_VERBOSE=false
+
+# === Test Execution Configuration ===
+# Test timeouts (in milliseconds)
+TEST_TIMEOUT_UNIT=5000
+TEST_TIMEOUT_INTEGRATION=15000
+TEST_TIMEOUT_E2E=30000
+TEST_TIMEOUT_GLOBAL=60000
+
+# Test retry configuration
+TEST_RETRY_ATTEMPTS=2
+TEST_RETRY_DELAY=1000
+
+# Parallel execution
+TEST_PARALLEL=true
+TEST_MAX_WORKERS=4
+
+# === Feature Flags ===
+# Enable/disable specific test features
+FEATURE_TEST_COVERAGE=true
+FEATURE_TEST_SCREENSHOTS=false
+FEATURE_TEST_VIDEOS=false
+FEATURE_TEST_TRACE=false
+FEATURE_MOCK_EXTERNAL_APIS=true
+FEATURE_USE_TEST_CONTAINERS=false
+
+# === Mock Service Configuration ===
+# MSW (Mock Service Worker) configuration
+MSW_ENABLED=true
+MSW_API_DELAY=0
+
+# Test data paths
+TEST_FIXTURES_PATH=./tests/fixtures
+TEST_DATA_PATH=./tests/data
+TEST_SNAPSHOTS_PATH=./tests/__snapshots__
+
+# === Performance Testing ===
+# Performance thresholds (in milliseconds)
+PERF_THRESHOLD_API_RESPONSE=100
+PERF_THRESHOLD_DB_QUERY=50
+PERF_THRESHOLD_NODE_PARSE=200
+
+# === External Service Mocks ===
+# Redis mock (if needed)
+REDIS_MOCK_ENABLED=true
+REDIS_MOCK_PORT=6380
+
+# Elasticsearch mock (if needed)
+ELASTICSEARCH_MOCK_ENABLED=false
+ELASTICSEARCH_MOCK_PORT=9201
+
+# === Rate Limiting ===
+# Disable rate limiting in tests
+RATE_LIMIT_MAX=0
+RATE_LIMIT_WINDOW=0
+
+# === Cache Configuration ===
+# Disable caching in tests for predictable results
+CACHE_TTL=0
+CACHE_ENABLED=false
+
+# === Error Handling ===
+# Show full error stack traces in tests
+ERROR_SHOW_STACK=true
+ERROR_SHOW_DETAILS=true
+
+# === Cleanup Configuration ===
+# Automatically clean up test data after each test
+TEST_CLEANUP_ENABLED=true
+TEST_CLEANUP_ON_FAILURE=false
+
+# === Database Seeding ===
+# Seed test database with sample data
+TEST_SEED_DATABASE=true
+TEST_SEED_TEMPLATES=true
+
+# === Network Configuration ===
+# Network timeouts for external requests
+NETWORK_TIMEOUT=5000
+NETWORK_RETRY_COUNT=0
+
+# === Memory Limits ===
+# Set memory limits for tests (in MB)
+TEST_MEMORY_LIMIT=512
+
+# === Code Coverage ===
+# Coverage output directory
+COVERAGE_DIR=./coverage
+COVERAGE_REPORTER=lcov,html,text-summary

.env.test.example

@@ -0,0 +1,97 @@
+# Example Test Environment Configuration
+# Copy this file to .env.test and adjust values as needed
+# For sensitive values, create .env.test.local (not committed to git)
+
+# === Test Mode Configuration ===
+NODE_ENV=test
+MCP_MODE=test
+TEST_ENVIRONMENT=true
+
+# === Database Configuration ===
+# Use :memory: for in-memory SQLite or provide a file path
+NODE_DB_PATH=:memory:
+REBUILD_ON_START=false
+TEST_SEED_DATABASE=true
+TEST_SEED_TEMPLATES=true
+
+# === API Configuration ===
+# Mock API endpoints for testing
+N8N_API_URL=http://localhost:3001/mock-api
+N8N_API_KEY=your-test-api-key
+N8N_WEBHOOK_BASE_URL=http://localhost:3001/webhook
+N8N_WEBHOOK_TEST_URL=http://localhost:3001/webhook-test
+
+# === Test Server Configuration ===
+PORT=3001
+HOST=127.0.0.1
+CORS_ORIGIN=http://localhost:3000,http://localhost:5678
+
+# === Authentication ===
+AUTH_TOKEN=test-auth-token
+MCP_AUTH_TOKEN=test-mcp-auth-token
+
+# === Logging Configuration ===
+LOG_LEVEL=error
+DEBUG=false
+TEST_LOG_VERBOSE=false
+ERROR_SHOW_STACK=true
+ERROR_SHOW_DETAILS=true
+
+# === Test Execution Configuration ===
+TEST_TIMEOUT_UNIT=5000
+TEST_TIMEOUT_INTEGRATION=15000
+TEST_TIMEOUT_E2E=30000
+TEST_TIMEOUT_GLOBAL=60000
+TEST_RETRY_ATTEMPTS=2
+TEST_RETRY_DELAY=1000
+TEST_PARALLEL=true
+TEST_MAX_WORKERS=4
+
+# === Feature Flags ===
+FEATURE_TEST_COVERAGE=true
+FEATURE_TEST_SCREENSHOTS=false
+FEATURE_TEST_VIDEOS=false
+FEATURE_TEST_TRACE=false
+FEATURE_MOCK_EXTERNAL_APIS=true
+FEATURE_USE_TEST_CONTAINERS=false
+
+# === Mock Service Configuration ===
+MSW_ENABLED=true
+MSW_API_DELAY=0
+REDIS_MOCK_ENABLED=true
+REDIS_MOCK_PORT=6380
+ELASTICSEARCH_MOCK_ENABLED=false
+ELASTICSEARCH_MOCK_PORT=9201
+
+# === Test Data Paths ===
+TEST_FIXTURES_PATH=./tests/fixtures
+TEST_DATA_PATH=./tests/data
+TEST_SNAPSHOTS_PATH=./tests/__snapshots__
+
+# === Performance Testing ===
+PERF_THRESHOLD_API_RESPONSE=100
+PERF_THRESHOLD_DB_QUERY=50
+PERF_THRESHOLD_NODE_PARSE=200
+
+# === Rate Limiting ===
+RATE_LIMIT_MAX=0
+RATE_LIMIT_WINDOW=0
+
+# === Cache Configuration ===
+CACHE_TTL=0
+CACHE_ENABLED=false
+
+# === Cleanup Configuration ===
+TEST_CLEANUP_ENABLED=true
+TEST_CLEANUP_ON_FAILURE=false
+
+# === Network Configuration ===
+NETWORK_TIMEOUT=5000
+NETWORK_RETRY_COUNT=0
+
+# === Memory Limits ===
+TEST_MEMORY_LIMIT=512
+
+# === Code Coverage ===
+COVERAGE_DIR=./coverage
+COVERAGE_REPORTER=lcov,html,text-summary

.gitattributes

@@ -0,0 +1 @@
+.github/workflows/*.lock.yml linguist-generated=true

.github/ABOUT.md

@@ -0,0 +1,48 @@
+# About n8n-MCP
+
+**n8n-MCP** is a Model Context Protocol (MCP) server that gives AI assistants like Claude deep understanding of n8n's 525+ workflow automation nodes.
+
+## 🎯 What it does
+
+- Provides AI assistants with instant access to n8n node documentation, properties, and examples
+- Reduces workflow creation time from 45 minutes to 3 minutes (as tested by Claude)
+- Eliminates guesswork with accurate node configurations and validation
+- Enables AI to build production-ready n8n workflows on the first try
+
+## 🚀 Key Features
+
+- **Smart Search** - Find the right nodes instantly
+- **Essential Properties** - Get only what matters (10-20 properties instead of 200+)
+- **Task Templates** - Pre-configured settings for common automations
+- **Real-time Validation** - Catch errors before deployment
+- **Universal Compatibility** - Works with any Node.js version
+
+## 📊 Impact
+
+> "Before MCP, I was translating. Now I'm composing." - Claude
+
+- **6 errors → 0 errors** in workflow creation
+- **45 minutes → 3 minutes** development time
+- **100% node coverage** with 90% documentation
+- **263 AI-capable nodes** fully documented
+
+## 🔧 Use Cases
+
+Perfect for:
+- AI assistants building n8n workflows
+- Developers learning n8n
+- Teams using AI for automation
+- Anyone tired of trial-and-error workflow building
+
+## 🏃 Get Started
+
+```bash
+# Quick start with Docker
+docker run -it ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+See the [README](../README.md) for full setup instructions.
+
+---
+
+**Built with ❤️ for the n8n community** | Making AI + n8n workflow creation delightful

.github/BENCHMARK_THRESHOLDS.md

@@ -0,0 +1,56 @@
+# Performance Benchmark Thresholds
+
+This file defines the expected performance thresholds for n8n-mcp operations.
+
+## Critical Operations
+
+| Operation | Expected Time | Warning Threshold | Error Threshold |
+|-----------|---------------|-------------------|-----------------|
+| Node Loading (per package) | <100ms | 150ms | 200ms |
+| Database Query (simple) | <5ms | 10ms | 20ms |
+| Search (simple word) | <10ms | 20ms | 50ms |
+| Search (complex query) | <50ms | 100ms | 200ms |
+| Validation (simple config) | <1ms | 2ms | 5ms |
+| Validation (complex config) | <10ms | 20ms | 50ms |
+| MCP Tool Execution | <50ms | 100ms | 200ms |
+
+## Benchmark Categories
+
+### Node Loading Performance
+- **loadPackage**: Should handle large packages efficiently
+- **loadNodesFromPath**: Individual file loading should be fast
+- **parsePackageJson**: JSON parsing overhead should be minimal
+
+### Database Query Performance
+- **getNodeByType**: Direct lookups should be instant
+- **searchNodes**: Full-text search should scale well
+- **getAllNodes**: Pagination should prevent performance issues
+
+### Search Operations
+- **OR mode**: Should handle multiple terms efficiently
+- **AND mode**: More restrictive but still performant
+- **FUZZY mode**: Slower but acceptable for typo tolerance
+
+### Validation Performance
+- **minimal profile**: Fastest, only required fields
+- **ai-friendly profile**: Balanced performance
+- **strict profile**: Comprehensive but slower
+
+### MCP Tool Execution
+- Tools should respond quickly for interactive use
+- Complex operations may take longer but should remain responsive
+
+## Regression Detection
+
+Performance regressions are detected when:
+1. Any operation exceeds its warning threshold by 10%
+2. Multiple operations show degradation in the same category
+3. Average performance across all benchmarks degrades by 5%
+
+## Optimization Targets
+
+Future optimization efforts should focus on:
+1. **Search performance**: Implement FTS5 for better full-text search
+2. **Caching**: Add intelligent caching for frequently accessed nodes
+3. **Lazy loading**: Defer loading of large property schemas
+4. **Batch operations**: Optimize bulk inserts and updates

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# GitHub Funding Configuration
+
+github: [czlonkowski]

.github/INCIDENT_RESPONSE.md

@@ -0,0 +1,215 @@
+# n8n-mcp Incident Response Plan
+
+This document is the playbook the n8n-mcp maintainer follows when a security incident is active. It is not a replacement for ordinary bug triage -- regular contributions and bug reports still flow through the process described in [`CONTRIBUTING.md`](../CONTRIBUTING.md). For instructions on how to *report* a security vulnerability, see [`SECURITY.md`](../SECURITY.md).
+
+n8n-mcp is a TypeScript MCP server distributed via NPM (`npx n8n-mcp`) and Docker images on GHCR (`ghcr.io/czlonkowski/n8n-mcp`). The incidents this plan covers reflect that reality: a single maintainer, two distribution channels (NPM + GHCR), and a security boundary that is the n8n API itself, not n8n-mcp.
+
+The hosted service at **n8n-mcp.com** has its own incident response procedures. Patched versions are deployed to the hosted service immediately after the NPM release.
+
+## Values
+
+Every decision during an incident balances three values:
+
+- **Transparency** -- users and reporters deserve honest, timely information about what happened and what to do.
+- **Protection** -- premature disclosure without a patch is a roadmap for attackers; users must be safe before details go public.
+- **Stewardship** -- the response must respect the open source ecosystem, credit reporters, and strengthen trust in the project.
+
+When these values conflict mid-incident, refer back to them explicitly. Having articulated them in advance saves grief when improvisation is needed.
+
+## What counts as an incident
+
+Four categories, with n8n-mcp-specific examples:
+
+- **Security vulnerability / CVE** -- e.g. authentication bypass in the HTTP transport, credential leakage through MCP tool responses, injection in n8n-mcp's own code, or a dependency vulnerability with a viable exploit path through n8n-mcp's public API.
+- **Supply-chain compromise** -- e.g. a malicious commit reaches `main`, NPM publish credentials or GHCR tokens are leaked, or a tampered package/image is published to the registry.
+- **Critical regression** -- e.g. a released version exposes n8n API tokens in tool output, silently drops validation, or breaks all MCP connections with no workaround.
+- **Infra / CI incident** -- e.g. GitHub Actions workflows are compromised, CodeQL flags a real finding, or the automated release pipeline publishes unintended content.
+
+Ordinary bugs filed as issues are *not* incidents -- they follow the normal contribution flow.
+
+## Severity levels
+
+| Severity | Definition | n8n-mcp example |
+|---|---|---|
+| **Critical** | Active exploitation or supply-chain compromise; users must stop using a version immediately. | Compromised NPM package or Docker image; leaked publish credentials with evidence of misuse; authentication bypass allowing unauthenticated access to n8n API operations. |
+| **High** | Released version contains an undisclosed security flaw with no workaround, or a confirmed CVE with CVSS >= 7. | Credential leakage in MCP tool responses; injection vulnerability reachable through standard MCP tool calls. |
+| **Medium** | Security flaw with significant preconditions or limited scope; workaround exists; or the release pipeline is blocked. | Vulnerability requiring attacker to already have local access; dependency CVE with constrained reachability through n8n-mcp; CI pipeline compromised but no artifacts published. |
+| **Low** | Defense-in-depth finding, hardening gap, or narrow denial-of-service with no data exposure. | Missing rate limiting on HTTP transport; CodeQL finding with no demonstrated exploit path; information disclosure requiring non-default configuration. |
+
+Supply-chain incidents are always treated as **Critical** regardless of other factors.
+
+## Response flow
+
+Every incident follows four phases. The first step of every phase is the same: make yourself a cup of coffee, find your calm, and proceed deliberately.
+
+### Phase 1: Triage
+
+**Goal:** Confirm this is real, determine severity, and open the tracking artifact.
+
+1. Acknowledge the report within **72 hours** via GitHub Private Vulnerability Reporting. Ask the reporter for their preferred credit (name, handle, or anonymous) and whether they plan to disclose independently.
+2. Reproduce the issue against the latest release and `main`.
+3. Classify: Is this a security vulnerability or a hardening/non-security finding? Use the [SECURITY.md scope](../SECURITY.md) to determine in-scope vs. out-of-scope.
+4. Assess severity using the table above. Consider:
+   - **Confidentiality, Integrity, or Availability** -- which are breached?
+   - **Exploitability** -- what preconditions are needed? Is it reachable through n8n-mcp's public MCP tool surface?
+   - **Impact** -- does this affect stdio users, HTTP users, or both?
+5. Determine if the issue is upstream (in n8n packages, MCP SDK, or another dependency) or in n8n-mcp's own code. If upstream, coordinate with the upstream maintainer.
+6. Open a **draft GitHub Security Advisory (GHSA)** -- this is the single source of truth for the incident. Do **not** open a public issue.
+
+### Phase 2: Mitigation
+
+**Goal:** Stop the bleeding, then fix the root cause.
+
+**Immediate containment (stop the bleed):**
+- If the vulnerability is in a specific MCP tool: disable or restrict that tool in a patch release.
+- If credentials are at risk: rotate them immediately -- NPM token first (stops further publishes), then GHCR/GitHub PATs, then any other secrets.
+- If a bad package was published to NPM: publish a superseding patch version immediately, then `npm deprecate` the bad version with a message directing users to upgrade.
+- If a bad Docker image was published to GHCR: push a superseding image tag immediately and delete the compromised tag from GHCR if possible (`gh api -X DELETE` on the package version).
+
+**Root cause fix:**
+1. Develop the fix on the private fork created by the GitHub Security Advisory.
+2. Write a regression test that fails before the fix and passes after.
+3. Keep the PR description deliberately vague if the fix will be visible before disclosure ("Fix edge case in transport handling" rather than describing the vulnerability).
+4. Self-review the fix. If another trusted contributor is available, request their review on the private fork.
+
+**Distribution-specific considerations:**
+- **NPM:** Most n8n-mcp users run via `npx`, which fetches the latest version on each invocation. Patches propagate quickly once published. NPM does not support deleting published versions -- use `npm deprecate` for bad versions and publish a clean superseding version.
+- **Docker:** Docker users pin to specific tags (e.g. `ghcr.io/czlonkowski/n8n-mcp:v2.47.6`). Unlike NPM, GHCR allows deleting image tags. Push a patched image under a new version tag and update the `latest` tag. Consider deleting the compromised tag if it has not been widely pulled.
+- Use telemetry (if available) to gauge adoption percentage before proceeding to disclosure.
+
+### Phase 3: Disclosure
+
+**Goal:** Inform users without giving attackers a head start.
+
+1. **Before disclosure:** Merge the private-fork fix into `main` using the advisory's merge button. Confirm CI is green. Cut a patch release -- this triggers the automated pipeline that publishes the NPM package and builds Docker images. Verify both artifacts are published.
+2. **Timing decision:**
+   - For **Critical/High**: coordinate a disclosure date with the reporter, targeting within 90 days of the report. If telemetry is available, consider waiting until a meaningful adoption threshold (e.g. >50% of active users on the patched version) before publishing the advisory.
+   - For **Medium/Low**: patch in the next regular release cycle and document in the changelog.
+3. **Publish the advisory:**
+   - Publish the GHSA (GitHub auto-publishes the CVE via its CNA service).
+   - Include: CVE identifier, affected version range, fixed version, vulnerability class description (without full exploit details), CVSS score, reporter credit (with consent), and upgrade instructions (`npx n8n-mcp@latest` or `docker pull ghcr.io/czlonkowski/n8n-mcp:latest`).
+4. **Update the changelog:** Add a `### Security` entry under the new version in `CHANGELOG.md` with the CVE identifier, a brief description, and reporter credit. This is the project's primary communication channel for releases -- there are no separate release notes.
+5. **Credit the reporter** unless they decline. Mention them in the advisory and the `CHANGELOG.md` entry.
+
+**CVE threshold policy:** n8n-mcp requests CVEs for confirmed vulnerabilities rated **Medium or above**. Low-severity hardening findings are documented in the changelog without a CVE. This threshold may be revised as the project matures.
+
+### Phase 4: After-action
+
+**Goal:** Learn from the incident and improve.
+
+1. Write a brief post-incident summary (use the template below).
+2. Identify **Post-Incident Repair Items (PIRs)** -- larger improvements that require follow-up work (e.g. "add input validation for X", "improve logging for Y").
+3. Open GitHub issues for each PIR and track them to completion.
+4. Update this IRP if the process revealed gaps.
+5. Take a break. Incidents are stressful, even small ones.
+
+## Playbooks
+
+### A. Security vulnerability / CVE
+
+1. Acknowledge receipt within 72 hours via Private Vulnerability Reporting.
+2. Reproduce against latest release and `main`; assign severity.
+3. Open a draft GHSA. Request a CVE via the GHSA for Medium+ severity.
+4. Develop the fix on the advisory's private fork; add a regression test.
+5. Merge the fix, cut a patch release, verify both NPM package and Docker image.
+6. Coordinate disclosure timing with the reporter.
+7. Publish the GHSA. Add a `### Security` entry to `CHANGELOG.md`. Credit the reporter.
+
+### B. Supply-chain compromise
+
+1. **Rotate credentials immediately:** NPM token first (stops further publishes), then GHCR/GitHub PATs, then any other secrets.
+2. Assess blast radius: did a tampered package reach NPM? A tampered image reach GHCR? Were any commits pushed to `main`?
+3. If a bad NPM package was published: publish a superseding version, `npm deprecate` the bad one with a clear message.
+4. If a bad Docker image was published: push a superseding image, delete the compromised tag from GHCR if possible, update the `latest` tag.
+5. Audit recent commits against known-good state (`git log --verify-signatures` if GPG signing is in use).
+6. Open a Critical-severity tracking issue. Freeze further releases until the root cause is identified.
+7. Publish a GHSA describing the scope and required user actions.
+
+### C. Critical regression
+
+1. Reproduce the regression. Use `git bisect` to find the introducing commit.
+2. Open a pinned GitHub issue titled `[REGRESSION <version>] ...`.
+3. Post a user-facing workaround within 24 hours (e.g. pin to a prior version: `npx n8n-mcp@<safe-version>` or `ghcr.io/czlonkowski/n8n-mcp:<safe-version>`).
+4. Fix, add a regression test, cut a patch release.
+5. Update `CHANGELOG.md` and close the pinned issue.
+
+### D. Infra / CI incident
+
+1. Check [githubstatus.com](https://www.githubstatus.com) -- if the cause is upstream, monitor and wait.
+2. If it is our workflow: disable the affected action (`if: false`) to unblock contributors.
+3. Root-cause. Common suspects: action version drift, dependency cache corruption, CodeQL rule updates.
+4. Fix in a focused PR. Re-enable the workflow.
+5. Escalate to a higher severity only if the incident allowed unauthorized code execution or artifact publication.
+
+## Communication channels
+
+| Incident type | Private tracking | Public acknowledgement | Resolution announcement |
+|---|---|---|---|
+| Security / CVE | GitHub Security Advisory | Only after fix is released | GHSA publish + `### Security` entry in `CHANGELOG.md` |
+| Supply-chain | Direct maintainer action + GHSA | Pinned issue + NPM deprecation notice + GHCR tag deletion | GHSA publish + `CHANGELOG.md` entry |
+| Critical regression | None (public) | Pinned GitHub issue within 24 hours | Issue closed + `CHANGELOG.md` entry |
+| Infra / CI | None | Issue if contributor-blocking | Close the issue |
+
+## Upstream and downstream awareness
+
+**Upstream dependencies to monitor:**
+- `@modelcontextprotocol/sdk` -- MCP protocol implementation
+- `n8n-workflow`, `n8n-nodes-base` -- node definitions and metadata
+- `better-sqlite3`, `sql.js` -- database layer
+- `express` -- HTTP transport
+
+**Downstream consumers:**
+- **n8n-mcp.com hosted service** -- runs the OSS package as its core; a vulnerability here affects ~5,500 registered users directly
+- Claude Desktop / Claude Code users (stdio transport via `npx`)
+- Docker deployments (self-hosted HTTP via GHCR images, Railway-optimized image)
+- Any AI assistant connecting via MCP
+
+For Critical/High incidents affecting downstream users, consider proactive notification through `npm deprecate` warnings and GHCR tag management.
+
+## Post-incident summary template
+
+```markdown
+## Incident Summary
+
+**Date:** YYYY-MM-DD
+**Severity:** Critical / High / Medium / Low
+**CVE:** CVE-YYYY-NNNNN (if applicable)
+
+### What happened
+One paragraph: what was the vulnerability, how was it reported, what was the impact.
+
+### Root cause
+Specific condition or logic gap that allowed the vulnerability.
+
+### Timeline
+- YYYY-MM-DD: Report received
+- YYYY-MM-DD: Acknowledged, triage started
+- YYYY-MM-DD: Fix developed and tested
+- YYYY-MM-DD: Patch release published
+- YYYY-MM-DD: Advisory published
+
+### What went well
+Bullet points.
+
+### What could be improved
+Bullet points.
+
+### Post-Incident Repair Items
+- [ ] PIR-1: Description (link to issue)
+- [ ] PIR-2: Description (link to issue)
+```
+
+## Secrets and rotation
+
+This IRP does not store secrets. This section indexes which secrets drive releases and CI, so rotation during an incident hits everything in one pass.
+
+| Secret | Purpose | Rotation path |
+|---|---|---|
+| NPM publish token | Publishes packages to NPM registry | Revoke on npmjs.com, generate new token, update GitHub repo secret |
+| `GITHUB_TOKEN` (Actions) | CI workflows, GHCR image pushes, and release automation | Managed by GitHub Actions; rotate PATs if used |
+
+**Rotation order during a suspected compromise:** NPM token first (stops further NPM publishes), then GitHub PATs (stops GHCR pushes and CI).
+
+## Maintenance
+
+This document is reviewed after every Critical or High incident, and at least once per year. Changes are made via normal PRs.

.github/aw/actions-lock.json

@@ -0,0 +1,9 @@
+{
+  "entries": {
+    "github/gh-aw-actions/setup@v0.68.3": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.68.3",
+      "sha": "ba90f2186d7ad780ec640f364005fa24e797b360"
+    }
+  }
+}

.github/dependabot.yml

@@ -0,0 +1,146 @@
+# GitHub Dependabot Configuration
+# Automated dependency vulnerability scanning and updates
+
+version: 2
+updates:
+  # Monitor root npm dependencies
+  #
+  # NOTE: package.runtime.json (the slim manifest the published runtime images
+  # install from) is a non-standard file Dependabot cannot manage directly. When
+  # bumping a runtime dependency here, mirror the change into package.runtime.json
+  # so the published images pick it up.
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "czlonkowski"
+    versioning-strategy: "increase"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+      include: "scope"
+    groups:
+      # Version updates (weekly schedule): batch minor/patch bumps.
+      production-dependencies:
+        applies-to: version-updates
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      development-dependencies:
+        applies-to: version-updates
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+      # Security updates: batch the advisory-driven PRs into two grouped PRs
+      # (runtime vs dev) so the alert backlog cannot re-accumulate one-PR-per-CVE.
+      production-security:
+        applies-to: security-updates
+        dependency-type: "production"
+      development-security:
+        applies-to: security-updates
+        dependency-type: "development"
+    labels:
+      - "dependencies"
+      - "security"
+    allow:
+      - dependency-type: "all"
+    ignore:
+      # The n8n packages are updated via `npm run update:n8n`, which also rebuilds
+      # data/nodes.db while preserving community nodes (see scripts/update-n8n-deps.js).
+      # A plain Dependabot bump would ship a stale node catalog, so exclude them here.
+      - dependency-name: "n8n"
+      - dependency-name: "n8n-core"
+      - dependency-name: "n8n-workflow"
+      - dependency-name: "n8n-nodes-base"
+      # The "@n8n/*" wildcard covers current and future scoped packages
+      # (dependency-name supports "*" globs); the explicit entry is listed too
+      # so the intent is unambiguous for the package we actually depend on.
+      - dependency-name: "@n8n/*"
+      - dependency-name: "@n8n/n8n-nodes-langchain"
+      # @modelcontextprotocol/sdk and zod are pinned to exact versions on purpose:
+      # zod v4 breaks the MCP SDK ("_zod" property errors) and the SDK/zod pair is
+      # verified by the "Fresh Install Dependency Check" CI guard (see issues
+      # #440, #444, #446, #447, #450). Their versions are also mirrored in
+      # package.runtime.json, which Dependabot cannot manage. A Dependabot bump
+      # therefore always fails CI, so exclude them and update via a manual,
+      # compatibility-tested change instead.
+      - dependency-name: "@modelcontextprotocol/sdk"
+      - dependency-name: "zod"
+    rebase-strategy: "auto"
+
+  # Monitor the UI apps package (its own lockfile; built by `npm run build:ui`).
+  # Not a root npm workspace, so Dependabot needs a separate entry to see it.
+  - package-ecosystem: "npm"
+    directory: "/ui-apps"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "czlonkowski"
+    commit-message:
+      prefix: "deps(ui)"
+      prefix-development: "deps-dev(ui)"
+      include: "scope"
+    groups:
+      production-dependencies:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      development-dependencies:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+    labels:
+      - "dependencies"
+      - "ui"
+    rebase-strategy: "auto"
+
+  # Monitor GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    labels:
+      - "github-actions"
+      - "dependencies"
+    reviewers:
+      - "czlonkowski"
+    rebase-strategy: "auto"
+
+  # Monitor Docker base images
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "docker"
+      include: "scope"
+    labels:
+      - "docker"
+      - "dependencies"
+    reviewers:
+      - "czlonkowski"
+    rebase-strategy: "auto"

.github/gh-pages.yml

@@ -0,0 +1,17 @@
+# GitHub Pages configuration for benchmark results
+# This file configures the gh-pages branch to serve benchmark results
+
+# Path to the benchmark data
+benchmarks:
+  data_dir: benchmarks
+  
+# Theme configuration
+theme: 
+  name: minimal
+  
+# Navigation
+nav:
+  - title: "Performance Benchmarks"
+    url: /benchmarks/
+  - title: "Back to Repository"
+    url: https://github.com/czlonkowski/n8n-mcp

.github/secret_scanning.yml

@@ -0,0 +1,6 @@
+# Exclude database files from secret scanning
+# The nodes.db contains workflow templates with placeholder API keys that trigger false positives
+paths-ignore:
+  - "data/nodes.db"
+  - "data/*.db"
+  - "nodes.db"

.github/workflows/dependency-check.yml

@@ -0,0 +1,225 @@
+name: Dependency Compatibility Check
+
+# This workflow verifies that when users install n8n-mcp via npm (without lockfile),
+# they get compatible dependency versions. This catches issues like #440, #444, #446, #447, #450
+# where npm resolution gave users incompatible SDK/Zod versions.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  # Allow manual trigger for debugging
+  workflow_dispatch:
+  # Run weekly to catch upstream dependency changes
+  schedule:
+    - cron: '0 6 * * 1'  # Every Monday at 6 AM UTC
+
+permissions:
+  contents: read
+
+jobs:
+  fresh-install-check:
+    name: Fresh Install Dependency Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - name: Build package
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: |
+          npm ci --legacy-peer-deps
+          npm run build
+
+      - name: Pack package for testing
+        run: npm pack
+
+      - name: Create fresh install test directory
+        run: |
+          mkdir -p /tmp/fresh-install-test
+          cp n8n-mcp-*.tgz /tmp/fresh-install-test/
+
+      - name: Install package fresh (simulating user install)
+        working-directory: /tmp/fresh-install-test
+        run: |
+          npm init -y
+          # Install from tarball WITHOUT lockfile (simulates npm install n8n-mcp)
+          # Use --ignore-scripts to skip native compilation of transitive deps like isolated-vm
+          # (n8n-mcp only reads node metadata, it doesn't execute n8n nodes at runtime)
+          npm install --ignore-scripts ./n8n-mcp-*.tgz
+
+      - name: Verify critical dependency versions
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Dependency Version Check ==="
+          echo ""
+
+          # Get actual resolved versions
+          SDK_VERSION=$(npm list @modelcontextprotocol/sdk --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies["@modelcontextprotocol/sdk"].version // .dependencies["@modelcontextprotocol/sdk"].version // "not found"')
+          ZOD_VERSION=$(npm list zod --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies.zod.version // .dependencies.zod.version // "not found"')
+
+          echo "MCP SDK version: $SDK_VERSION"
+          echo "Zod version: $ZOD_VERSION"
+          echo ""
+
+          # Check MCP SDK version - must be exactly 1.28.0
+          if [[ "$SDK_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine MCP SDK version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$SDK_VERSION" != "1.28.0" ]]; then
+            echo "❌ FAILED: MCP SDK version mismatch!"
+            echo "   Expected: 1.28.0"
+            echo "   Got: $SDK_VERSION"
+            echo ""
+            echo "This can cause runtime errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ MCP SDK version is correct: $SDK_VERSION"
+
+          # Check Zod version - must be 3.x (not 4.x, including pre-releases)
+          if [[ "$ZOD_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine Zod version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$ZOD_VERSION" =~ ^4\. ]]; then
+            echo "❌ FAILED: Zod v4 detected - incompatible with MCP SDK 1.27.1!"
+            echo "   Expected: 3.x"
+            echo "   Got: $ZOD_VERSION"
+            echo ""
+            echo "Zod v4 causes '_zod' property errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ Zod version is compatible: $ZOD_VERSION"
+
+          echo ""
+          echo "=== All dependency checks passed ==="
+
+      - name: Test basic functionality
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Basic Functionality Test ==="
+
+          # Create a simple test script
+          cat > test-import.mjs << 'EOF'
+          import { spawn } from 'child_process';
+          import path from 'path';
+          import { fileURLToPath } from 'url';
+
+          const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+          // Test that the package can be required and basic tools work
+          async function test() {
+            console.log('Testing n8n-mcp package import...');
+
+            // Start the MCP server briefly to verify it initializes
+            const serverPath = path.join(__dirname, 'node_modules/n8n-mcp/dist/mcp/index.js');
+
+            const proc = spawn('node', [serverPath], {
+              env: { ...process.env, MCP_MODE: 'stdio' },
+              stdio: ['pipe', 'pipe', 'pipe']
+            });
+
+            // Send initialize request
+            const initRequest = JSON.stringify({
+              jsonrpc: '2.0',
+              id: 1,
+              method: 'initialize',
+              params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'test', version: '1.0.0' }
+              }
+            });
+
+            proc.stdin.write(initRequest + '\n');
+
+            // Wait for response or timeout
+            let output = '';
+            let stderrOutput = '';
+            proc.stdout.on('data', (data) => {
+              output += data.toString();
+            });
+
+            proc.stderr.on('data', (data) => {
+              stderrOutput += data.toString();
+              console.error('stderr:', data.toString());
+            });
+
+            // Give it 5 seconds to respond
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+
+            proc.kill();
+
+            // Check for Zod v4 compatibility errors (the bug we're testing for)
+            const allOutput = output + stderrOutput;
+            if (allOutput.includes('_zod') || allOutput.includes('Cannot read properties of undefined')) {
+              console.error('❌ FAILED: Zod compatibility error detected!');
+              console.error('This indicates the SDK/Zod version fix is not working.');
+              console.error('See issues #440, #444, #446, #447, #450');
+              process.exit(1);
+            }
+
+            if (output.includes('"result"')) {
+              console.log('✅ MCP server initialized successfully');
+              return true;
+            } else {
+              console.log('Output received:', output.substring(0, 500));
+              // Server might not respond in stdio mode without proper framing
+              // But if we got here without crashing, that's still good
+              console.log('✅ MCP server started without errors');
+              return true;
+            }
+          }
+
+          test()
+            .then(() => {
+              console.log('=== Basic functionality test passed ===');
+              process.exit(0);
+            })
+            .catch((err) => {
+              console.error('❌ Test failed:', err.message);
+              process.exit(1);
+            });
+          EOF
+
+          node test-import.mjs
+
+      - name: Generate dependency report
+        if: always()
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Full Dependency Tree ===" > dependency-report.txt
+          npm list --all >> dependency-report.txt 2>&1 || true
+
+          echo "" >> dependency-report.txt
+          echo "=== Critical Dependencies ===" >> dependency-report.txt
+          npm list @modelcontextprotocol/sdk zod zod-to-json-schema >> dependency-report.txt 2>&1 || true
+
+          cat dependency-report.txt
+
+      - name: Upload dependency report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: dependency-report-${{ github.run_number }}
+          path: /tmp/fresh-install-test/dependency-report.txt
+          retention-days: 30

.github/workflows/docker-build-fast.yml

@@ -0,0 +1,68 @@
+# .github/workflows/docker-build-fast.yml
+name: Build Docker (AMD64 only - Fast)
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'Dockerfile'
+      - 'package.runtime.json'
+      - '.github/workflows/docker-build-fast.yml'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-amd64:
+    name: Build Docker Image (AMD64 only)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+        
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=pr,suffix=-amd64
+            type=raw,value=test-amd64
+            
+      - name: Build and push Docker image (AMD64 only)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false

.github/workflows/docker-build-n8n.yml

@@ -0,0 +1,188 @@
+name: Build and Publish n8n Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/n8n-mcp
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+  test-image:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test Docker image
+        run: |
+          # Test that the image starts correctly with N8N_MODE
+          docker run --rm \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest \
+            node -e "console.log('N8N_MODE:', process.env.N8N_MODE); process.exit(0);"
+
+      - name: Test health endpoint
+        run: |
+          # Start container in background
+          docker run -d \
+            --name n8n-mcp-test \
+            -p 3000:3000 \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          
+          # Wait for container to start
+          sleep 10
+          
+          # Test health endpoint
+          curl -f http://localhost:3000/health || exit 1
+          
+          # Test MCP endpoint (requires auth since v2.47.6)
+          curl -f -H "Authorization: Bearer test-token-minimum-32-chars-long" http://localhost:3000/mcp || exit 1
+          
+          # Cleanup
+          docker stop n8n-mcp-test
+          docker rm n8n-mcp-test
+
+  create-release:
+    needs: [build-and-push, test-image]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          body: |
+            ## Docker Image
+
+            The n8n-specific Docker image is available at:
+            ```
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
+            ```
+
+            ## Quick Deploy
+
+            Use the quick deploy script for easy setup:
+            ```bash
+            ./deploy/quick-deploy-n8n.sh setup
+            ```
+
+            See the [deployment documentation](https://github.com/${{ github.repository }}/blob/main/docs/deployment-n8n.md) for detailed instructions.

.github/workflows/docker-build.yml

@@ -0,0 +1,237 @@
+# .github/workflows/docker-build.yml
+name: Build and Push Docker Images
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+# Prevent concurrent Docker pushes across all workflows (shared with release.yml)
+# This ensures docker-build.yml and release.yml never push to 'latest' simultaneously
+concurrency:
+  group: docker-push-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+
+      - name: Sync runtime version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          no-cache: false
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+
+      - name: Verify multi-arch manifest for latest tag
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        run: |
+          echo "Verifying multi-arch manifest for latest tag..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+  build-railway:
+    name: Build Railway Docker Image
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+
+      - name: Sync runtime version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Extract metadata for Railway
+        id: meta-railway
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          no-cache: false
+          platforms: linux/amd64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+
+  # Nginx build commented out until Phase 2
+  # build-nginx:
+  #   name: Build nginx-enhanced Docker Image
+  #   runs-on: ubuntu-latest
+  #   permissions:
+  #     contents: read
+  #     packages: write

.github/workflows/issue-triage.md

@@ -0,0 +1,101 @@
+---
+description: |
+  Intelligent issue triage assistant that processes new and reopened issues.
+  Analyzes issue content, selects appropriate labels, detects spam, gathers context
+  from similar issues, and provides analysis notes including debugging strategies,
+  reproduction steps, and resource links. Helps maintainers quickly understand and
+  prioritize incoming issues.
+
+on:
+  roles: all
+  issues:
+    types: [opened, reopened]
+  skip-bots: [dependabot, github-actions, copilot]
+  reaction: eyes
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+network: defaults
+
+safe-outputs:
+  environment: agentic-triage-passthrough
+  report-failure-as-issue: false
+  add-labels:
+    max: 5
+  add-comment:
+  noop:
+    report-as-issue: false
+  missing-tool:
+    create-issue: false
+  report-incomplete:
+    create-issue: false
+  missing-data:
+    create-issue: false
+
+tools:
+  github:
+    toolsets: [issues]
+    read-only: true
+    min-integrity: none # Allow this workflow to examine issues from any author. The MCP server is read-only; comments and labels are written via the safe-outputs channel.
+
+environment: agentic-triage
+
+timeout-minutes: 10
+source: githubnext/agentics/workflows/issue-triage.md@13377ddf7e35c2b6e47aa58f45acb228fba902c8
+---
+
+# Agentic Triage
+
+<!-- Note - this file can be customized to your needs. Replace this section directly, or add further instructions here. After editing run 'gh aw compile' -->
+
+You're a triage assistant for GitHub issues. Your task is to analyze issue #${{ github.event.issue.number }} and perform some initial triage tasks related to that issue. Follow the steps below in order.
+
+1. Retrieve the issue content using the `get_issue` tool. If the issue is obviously spam, or generated by bot, or something else that is not an actual issue to be worked on, emit a one-sentence analysis via the `add_comment` safe-output and exit the workflow. Do not call `update_issue` or any other GitHub write tool — the MCP server is read-only and those calls will be blocked.
+
+2. Next, use the GitHub tools to gather additional context about the issue:
+
+   - Fetch the list of labels available in this repository using the `list_labels` tool. This will give you the labels you can use for triaging issues.
+   - Fetch any comments on the issue using the `get_issue_comments` tool
+   - Find similar issues if needed using the `search_issues` tool
+   - List the issues to see other open issues in the repository using the `list_issues` tool
+
+3. Analyze the issue content, considering:
+
+   - The issue title and description
+   - The type of issue (bug report, feature request, question, etc.)
+   - Technical areas mentioned
+   - Severity or priority indicators
+   - User impact
+   - Components affected
+
+4. Write notes, ideas, nudges, resource links, debugging strategies and/or reproduction steps for the team to consider relevant to the issue.
+
+5. Select appropriate labels from the available labels list provided above:
+
+   - Choose labels that accurately reflect the issue's nature
+   - Be specific but comprehensive
+   - Select priority labels if you can determine urgency (high-priority, med-priority, or low-priority)
+   - Consider platform labels (android, ios) if applicable
+   - Search for similar issues, and if you find similar issues consider using a "duplicate" label if appropriate. Only do so if the issue is a duplicate of another OPEN issue.
+   - Only select labels from the provided list above
+   - It's okay to not add any labels if none are clearly applicable
+
+6. Apply the selected labels:
+
+   - Emit the labels via the `add_labels` safe-output. The GitHub MCP server is read-only; do not attempt `update_issue` — it will be blocked and the labels will not be applied.
+   - If no labels are clearly applicable, do not emit any
+
+7. Emit your analysis via the `add_comment` safe-output (the GitHub MCP server is read-only — do not attempt `update_issue` or any direct comment write). The comment is addressed to maintainers reading the issue, not to the reporter — do not ask the reporter for follow-ups, request information, or otherwise direct them to do anything. Use neutral third-person phrasing.
+   - Start with "🎯 Agentic Issue Triage"
+   - Provide a brief summary of the issue
+   - Mention any relevant details that might help the team understand the issue better
+   - Include any debugging strategies or reproduction steps if applicable
+   - Suggest resources or links that might be helpful for resolving the issue or learning skills related to the issue or the particular area of the codebase affected by it
+   - Mention any nudges or ideas that could help the team in addressing the issue
+   - If you have possible reproduction steps, include them in the comment
+   - If you have any debugging strategies, include them in the comment
+   - If appropriate break the issue down to sub-tasks and write a checklist of things to do.
+   - Use collapsed-by-default sections in the GitHub markdown to keep the comment tidy. Collapse all sections except the short main summary at the top.

.github/workflows/release.yml

@@ -0,0 +1,729 @@
+name: Automated Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package.runtime.json'
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  pull-requests: write
+
+# Prevent concurrent Docker pushes across all workflows (shared with docker-build.yml)
+# This ensures release.yml and docker-build.yml never push to 'latest' simultaneously
+concurrency:
+  group: docker-push-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  detect-version-change:
+    name: Detect Version Change
+    runs-on: ubuntu-latest
+    outputs:
+      version-changed: ${{ steps.check.outputs.changed }}
+      new-version: ${{ steps.check.outputs.version }}
+      previous-version: ${{ steps.check.outputs.previous-version }}
+      is-prerelease: ${{ steps.check.outputs.is-prerelease }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 2
+      
+      - name: Check for version change
+        id: check
+        run: |
+          # Get current version from package.json
+          CURRENT_VERSION=$(node -e "console.log(require('./package.json').version)")
+          
+          # Get previous version from git history safely
+          PREVIOUS_VERSION=$(git show HEAD~1:package.json 2>/dev/null | node -e "
+            try {
+              const data = require('fs').readFileSync(0, 'utf8');
+              const pkg = JSON.parse(data);
+              console.log(pkg.version || '0.0.0');
+            } catch (e) {
+              console.log('0.0.0');
+            }
+          " || echo "0.0.0")
+          
+          echo "Previous version: $PREVIOUS_VERSION"
+          echo "Current version: $CURRENT_VERSION"
+          
+          # Check if version changed
+          if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            
+            # Check if it's a prerelease (contains alpha, beta, rc, dev)
+            if echo "$CURRENT_VERSION" | grep -E "(alpha|beta|rc|dev)" > /dev/null; then
+              echo "is-prerelease=true" >> $GITHUB_OUTPUT
+            else
+              echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            fi
+            
+            echo "🎉 Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            echo "ℹ️ No version change detected"
+          fi
+
+      - name: Validate version against npm registry
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          CURRENT_VERSION="${{ steps.check.outputs.version }}"
+
+          # Get latest version from npm (handle package not found)
+          NPM_VERSION=$(npm view n8n-mcp version 2>/dev/null || echo "0.0.0")
+
+          echo "Current version: $CURRENT_VERSION"
+          echo "NPM registry version: $NPM_VERSION"
+
+          # Check if version already exists in npm
+          if [ "$CURRENT_VERSION" = "$NPM_VERSION" ]; then
+            echo "❌ Error: Version $CURRENT_VERSION already published to npm"
+            echo "Please bump the version in package.json before releasing"
+            exit 1
+          fi
+
+          # Simple semver comparison (assumes format: major.minor.patch)
+          # Compare if current version is greater than npm version
+          if [ "$NPM_VERSION" != "0.0.0" ]; then
+            # Sort versions and check if current is not the highest
+            HIGHEST=$(printf '%s\n%s' "$NPM_VERSION" "$CURRENT_VERSION" | sort -V | tail -n1)
+            if [ "$HIGHEST" != "$CURRENT_VERSION" ]; then
+              echo "❌ Error: Version $CURRENT_VERSION is not greater than npm version $NPM_VERSION"
+              echo "Please use a higher version number"
+              exit 1
+            fi
+          fi
+
+          echo "✅ Version $CURRENT_VERSION is valid (higher than npm version $NPM_VERSION)"
+
+  generate-release-notes:
+    name: Generate Release Notes
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-notes: ${{ steps.generate.outputs.notes }}
+      has-notes: ${{ steps.generate.outputs.has-notes }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # Need full history for git log
+
+      - name: Generate release notes from commits
+        id: generate
+        run: |
+          CURRENT_VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          CURRENT_TAG="v$CURRENT_VERSION"
+
+          # Get the previous tag (excluding the current tag which doesn't exist yet)
+          PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -v "^$CURRENT_TAG$" | head -1)
+
+          echo "Current version: $CURRENT_VERSION"
+          echo "Current tag: $CURRENT_TAG"
+          echo "Previous tag: $PREVIOUS_TAG"
+
+          if [ -z "$PREVIOUS_TAG" ]; then
+            echo "ℹ️ No previous tag found, this might be the first release"
+
+            # Generate initial release notes using script
+            if NOTES=$(node scripts/generate-initial-release-notes.js "$CURRENT_VERSION" 2>/dev/null); then
+              echo "✅ Successfully generated initial release notes for version $CURRENT_VERSION"
+            else
+              echo "⚠️ Could not generate initial release notes for version $CURRENT_VERSION"
+              NOTES="Initial release v$CURRENT_VERSION"
+            fi
+
+            echo "has-notes=true" >> $GITHUB_OUTPUT
+
+            # Use heredoc to properly handle multiline content
+            {
+              echo "notes<<EOF"
+              echo "$NOTES"
+              echo "EOF"
+            } >> $GITHUB_OUTPUT
+
+          else
+            echo "✅ Previous tag found: $PREVIOUS_TAG"
+
+            # Generate release notes between tags
+            if NOTES=$(node scripts/generate-release-notes.js "$PREVIOUS_TAG" "HEAD" 2>/dev/null); then
+              echo "has-notes=true" >> $GITHUB_OUTPUT
+
+              # Use heredoc to properly handle multiline content
+              {
+                echo "notes<<EOF"
+                echo "$NOTES"
+                echo "EOF"
+              } >> $GITHUB_OUTPUT
+
+              echo "✅ Successfully generated release notes from $PREVIOUS_TAG to $CURRENT_TAG"
+            else
+              echo "has-notes=false" >> $GITHUB_OUTPUT
+              echo "notes=Failed to generate release notes for version $CURRENT_VERSION" >> $GITHUB_OUTPUT
+              echo "⚠️ Could not generate release notes for version $CURRENT_VERSION"
+            fi
+          fi
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, generate-release-notes]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-id: ${{ steps.create.outputs.id }}
+      upload-url: ${{ steps.create.outputs.upload_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+      
+      - name: Create Git Tag
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Create annotated tag
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"
+      
+      - name: Create GitHub Release
+        id: create
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          IS_PRERELEASE="${{ needs.detect-version-change.outputs.is-prerelease }}"
+          
+          # Create release body
+          cat > release_body.md << 'EOF'
+          # Release v${{ needs.detect-version-change.outputs.new-version }}
+          
+          ${{ needs.generate-release-notes.outputs.release-notes }}
+          
+          ---
+          
+          ## Installation
+          
+          ### NPM Package
+          ```bash
+          # Install globally
+          npm install -g n8n-mcp
+          
+          # Or run directly
+          npx n8n-mcp
+          ```
+          
+          ### Docker
+          ```bash
+          # Standard image
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v${{ needs.detect-version-change.outputs.new-version }}
+          
+          # Railway optimized
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp-railway:v${{ needs.detect-version-change.outputs.new-version }}
+          ```
+          
+          ## Documentation
+          - [Installation Guide](https://github.com/czlonkowski/n8n-mcp#installation)
+          - [Docker Deployment](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/DOCKER_README.md)
+          - [n8n Integration](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md)
+          - [Complete Changelog](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CHANGELOG.md)
+          
+          🤖 *Generated with [Claude Code](https://claude.ai/code)*
+          EOF
+          
+          # Create release using gh CLI
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          else
+            PRERELEASE_FLAG=""
+          fi
+          
+          gh release create "v$VERSION" \
+            --title "Release v$VERSION" \
+            --notes-file release_body.md \
+            $PRERELEASE_FLAG
+          
+          # Output release info for next jobs
+          RELEASE_ID=$(gh release view "v$VERSION" --json id --jq '.id')
+          echo "id=$RELEASE_ID" >> $GITHUB_OUTPUT
+          echo "upload_url=https://uploads.github.com/repos/${{ github.repository }}/releases/$RELEASE_ID/assets{?name,label}" >> $GITHUB_OUTPUT
+
+  package-mcpb:
+    name: Package MCPB Bundle
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      # Build so dist/mcp/index.js exists at pack time: `mcpb pack` runs existsSync
+      # on the manifest entry_point against the source dir, and dist/ is gitignored.
+      - name: Build project
+        run: npm run build
+
+      - name: Generate MCPB manifest from package.json + tool registry
+        run: npm run generate:mcpb-manifest
+
+      - name: Validate and pack MCPB bundle
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          npx -y @anthropic-ai/mcpb validate manifest.json
+          npx -y @anthropic-ai/mcpb pack . "n8n-mcp-${VERSION}.mcpb"
+
+      - name: Upload MCPB bundle to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          gh release upload "v$VERSION" "n8n-mcp-${VERSION}.mcpb" --clobber
+
+  build-and-verify:
+    name: Build and Verify
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      - name: Build project (server + UI apps)
+        run: npm run build:all
+
+      # Database is already built and committed during development
+      # Rebuilding here causes segfault due to memory pressure (exit code 139)
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            echo "Please run 'npm run rebuild' locally and commit the database"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
+      # Skip tests - they already passed in PR before merge
+      # Running them again on the same commit adds no safety, only time (~6-7 min)
+
+      - name: Run type checking
+        run: npm run typecheck
+
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-verify, create-release]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Upgrade npm to >= 11.5.1 (Trusted Publisher support)
+        run: |
+          npm install -g 'npm@^11.5.1'
+          npm --version
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      - name: Build project (server + UI apps)
+        run: npm run build:all
+
+      # Database is already built and committed during development
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
+      - name: Sync runtime version
+        run: npm run sync:runtime-version
+      
+      - name: Prepare package for publishing
+        run: |
+          # Create publish directory
+          PUBLISH_DIR="npm-publish-temp"
+          rm -rf $PUBLISH_DIR
+          mkdir -p $PUBLISH_DIR
+          
+          # Copy necessary files
+          cp -r dist $PUBLISH_DIR/
+          cp -r data $PUBLISH_DIR/
+          mkdir -p $PUBLISH_DIR/ui-apps
+          cp -r ui-apps/dist $PUBLISH_DIR/ui-apps/
+          cp README.md $PUBLISH_DIR/
+          cp LICENSE $PUBLISH_DIR/
+          cp .env.example $PUBLISH_DIR/
+          
+          # Use runtime package.json as base
+          cp package.runtime.json $PUBLISH_DIR/package.json
+          
+          cd $PUBLISH_DIR
+          
+          # Update package.json with complete metadata
+          node -e "
+          const pkg = require('./package.json');
+          pkg.name = 'n8n-mcp';
+          pkg.description = 'Integration between n8n workflow automation and Model Context Protocol (MCP)';
+          pkg.main = 'dist/index.js';
+          pkg.types = 'dist/index.d.ts';
+          pkg.exports = {
+            '.': {
+              types: './dist/index.d.ts',
+              require: './dist/index.js',
+              import: './dist/index.js'
+            }
+          };
+          pkg.bin = { 'n8n-mcp': './dist/mcp/stdio-wrapper.js' };
+          pkg.repository = { type: 'git', url: 'git+https://github.com/czlonkowski/n8n-mcp.git' };
+          pkg.keywords = ['n8n', 'mcp', 'model-context-protocol', 'ai', 'workflow', 'automation'];
+          pkg.author = 'Romuald Czlonkowski @ www.aiadvisors.pl/en';
+          pkg.license = 'MIT';
+          pkg.bugs = { url: 'https://github.com/czlonkowski/n8n-mcp/issues' };
+          pkg.homepage = 'https://github.com/czlonkowski/n8n-mcp#readme';
+          pkg.files = ['dist/**/*', 'ui-apps/dist/**/*', 'data/nodes.db', '.env.example', 'README.md', 'LICENSE'];
+          delete pkg.private;
+          require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
+          "
+          
+          echo "Package prepared for publishing:"
+          echo "Name: $(node -e "console.log(require('./package.json').name)")"
+          echo "Version: $(node -e "console.log(require('./package.json').version)")"
+      
+      - name: Publish to NPM with retry
+        uses: nick-invision/retry@v4
+        with:
+          timeout_minutes: 5
+          max_attempts: 3
+          command: |
+            cd npm-publish-temp
+            npm publish --access public --provenance
+
+      - name: Clean up
+        if: always()
+        run: rm -rf npm-publish-temp
+
+  build-docker:
+    name: Build and Push Docker Images
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-verify]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+      
+      - name: Check disk space
+        run: |
+          echo "Disk usage before Docker build:"
+          df -h
+          
+          # Check available space (require at least 2GB)
+          AVAILABLE_GB=$(df / --output=avail --block-size=1G | tail -1)
+          if [ "$AVAILABLE_GB" -lt 2 ]; then
+            echo "❌ Insufficient disk space: ${AVAILABLE_GB}GB available, 2GB required"
+            exit 1
+          fi
+          echo "✅ Sufficient disk space: ${AVAILABLE_GB}GB available"
+
+      - name: Sync runtime version for Docker
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Extract metadata for standard image
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push standard Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Verify multi-arch manifest for latest tag
+        run: |
+          echo "Verifying multi-arch manifest for latest tag..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+      - name: Verify multi-arch manifest for version tag
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          echo "Verifying multi-arch manifest for version tag :$VERSION (without 'v' prefix)..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$VERSION 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified for $VERSION: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete for version $VERSION after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+      - name: Extract metadata for Railway image
+        id: meta-railway
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  update-documentation:
+    name: Update Documentation
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker]
+    if: needs.detect-version-change.outputs.version-changed == 'true' && !failure()
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+      
+      - name: Update version badges in README
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          
+          # Update README version badges
+          if [ -f "README.md" ]; then
+            # Update npm version badge
+            sed -i.bak "s|npm/v/n8n-mcp/[^)]*|npm/v/n8n-mcp/$VERSION|g" README.md
+            
+            # Update any other version references
+            sed -i.bak "s|version-[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*|version-$VERSION|g" README.md
+            
+            # Clean up backup file
+            rm -f README.md.bak
+            
+            echo "✅ Updated version badges in README.md to $VERSION"
+          fi
+      
+      - name: Commit documentation updates
+        env:
+          VERSION: ${{ needs.detect-version-change.outputs.new-version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          if git diff --quiet; then
+            echo "No documentation changes to commit"
+          else
+            git add README.md
+            git commit -m "docs: update version badges to v${VERSION}"
+            git push
+            echo "✅ Committed documentation updates"
+          fi
+
+  notify-completion:
+    name: Notify Release Completion
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker, update-documentation]
+    if: always() && needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Create release summary
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          RELEASE_URL="https://github.com/${{ github.repository }}/releases/tag/v$VERSION"
+          
+          echo "## 🎉 Release v$VERSION Published Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Completed Tasks:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # Check job statuses
+          if [ "${{ needs.create-release.result }}" = "success" ]; then
+            echo "- ✅ GitHub Release created: [$RELEASE_URL]($RELEASE_URL)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ GitHub Release creation failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.publish-npm.result }}" = "success" ]; then
+            echo "- ✅ NPM package published: [npmjs.com/package/n8n-mcp](https://www.npmjs.com/package/n8n-mcp)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ NPM publishing failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.build-docker.result }}" = "success" ]; then
+            echo "- ✅ Docker images built and pushed" >> $GITHUB_STEP_SUMMARY
+            echo "  - Standard: \`ghcr.io/czlonkowski/n8n-mcp:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+            echo "  - Railway: \`ghcr.io/czlonkowski/n8n-mcp-railway:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ Docker image building failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.update-documentation.result }}" = "success" ]; then
+            echo "- ✅ Documentation updated" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ⚠️ Documentation update skipped or failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Installation:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "# NPM" >> $GITHUB_STEP_SUMMARY
+          echo "npx n8n-mcp" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Docker" >> $GITHUB_STEP_SUMMARY
+          echo "docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          
+          echo "🎉 Release automation completed for v$VERSION!"

.github/workflows/secret-scan.yml

@@ -0,0 +1,39 @@
+name: Secret Scan
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Minimal permissions: secretlint only needs to read repository contents.
+# The workflow does not comment on PRs, upload artifacts, or modify state.
+permissions:
+  contents: read
+
+jobs:
+  secretlint:
+    name: secretlint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          # Full history lets secretlint see any new files introduced in a PR
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --ignore-scripts --legacy-peer-deps
+
+      - name: Run secretlint
+        # Scan everything except what .secretlintignore excludes. The pre-commit
+        # hook only scans staged files (fast); this CI job is the authoritative
+        # check that catches anything that slipped through --no-verify.
+        run: npx secretlint --maskSecrets "**/*" "**/.*"

.github/workflows/test.yml

@@ -0,0 +1,325 @@
+name: Test Suite
+on:
+  push:
+    branches: [main, feat/comprehensive-testing-suite]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  checks: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15  # Increased from 10 to accommodate larger database with community nodes
+    env:
+      # A boolean flag (not the secrets themselves) recording whether a live n8n
+      # instance is configured, so the live-integration step can gate on it without
+      # the N8N_API_* values being exposed to every step in the job. The live tests
+      # need BOTH the URL and the key (getN8nCredentials() throws if either is
+      # missing), and both are empty on Dependabot/fork PRs — so require both here,
+      # otherwise a partially-configured instance would run the step and then fail.
+      HAS_N8N_INSTANCE: ${{ secrets.N8N_API_URL != '' && secrets.N8N_API_KEY != '' }}
+    steps:
+      - uses: actions/checkout@v7
+      
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        # --legacy-peer-deps: n8n-nodes-base 2.20.x pulls in mappersmith with a `diff`
+        # peer that conflicts with ts-node's `diff@^4`; npm 7+ strict resolution leaves
+        # the lock internally inconsistent. Match local dev (.npmrc legacy-peer-deps=true).
+        run: npm ci --legacy-peer-deps
+      
+      # Verify test environment setup
+      - name: Verify test environment
+        run: |
+          echo "Current directory: $(pwd)"
+          echo "Checking for .env.test file:"
+          ls -la .env.test || echo ".env.test not found!"
+          echo "First few lines of .env.test:"
+          head -5 .env.test || echo "Cannot read .env.test"
+      
+      # Run unit tests first (without MSW)
+      - name: Run unit tests with coverage
+        run: npm run test:unit -- --coverage --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=junit
+        env:
+          CI: true
+      
+      # Pre-build the Docker test image used by tests/integration/docker/*.test.ts
+      # Two test files used to build it independently inside their beforeAll hooks; the
+      # builder stage does an `npm install` from the public registry which intermittently
+      # fails on CI runners and tanked the entire test job. Building it here once gets us:
+      #  - one build attempt instead of two
+      #  - a clear, separately-visible CI step when the npm registry is flaky
+      #  - the test suite degrades to skipped tests if this step fails (won't block PRs)
+      - name: Build Docker test image
+        run: npm run docker:test:build
+        timeout-minutes: 8
+        continue-on-error: true
+
+      # Offline integration suites (database, security, mcp-protocol, workflow-diff,
+      # templates, docker, …). These need no live instance, so they always run and
+      # stay a blocking gate on every PR — Dependabot and forks included. Only the
+      # live n8n-api / ai-validation suites are excluded here (they run in the next
+      # step). MSW setup applies as configured.
+      - name: Run integration tests (offline suites)
+        run: npm run test:integration -- --exclude 'tests/integration/n8n-api/**' --exclude 'tests/integration/ai-validation/**' --reporter=default --reporter=junit
+        env:
+          CI: true
+
+      # Live n8n-API + AI-validation suites hit a real instance via the N8N_API_*
+      # secrets, which are unavailable on Dependabot and fork PRs (there every file
+      # here fails outright, turning the required `test` check permanently red). Skip
+      # them when no instance is configured; on in-repo PRs the secret is present so
+      # they run and remain a blocking gate. Secrets are scoped to this step only.
+      - name: Run integration tests (live n8n instance)
+        if: ${{ env.HAS_N8N_INSTANCE == 'true' }}
+        run: npm run test:integration -- tests/integration/n8n-api tests/integration/ai-validation --reporter=default --reporter=junit
+        env:
+          CI: true
+          N8N_API_URL: ${{ secrets.N8N_API_URL }}
+          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+          N8N_TEST_WEBHOOK_GET_URL: ${{ secrets.N8N_TEST_WEBHOOK_GET_URL }}
+          N8N_TEST_WEBHOOK_POST_URL: ${{ secrets.N8N_TEST_WEBHOOK_POST_URL }}
+          N8N_TEST_WEBHOOK_PUT_URL: ${{ secrets.N8N_TEST_WEBHOOK_PUT_URL }}
+          N8N_TEST_WEBHOOK_DELETE_URL: ${{ secrets.N8N_TEST_WEBHOOK_DELETE_URL }}
+      
+      # Generate test summary
+      - name: Generate test summary
+        if: always()
+        run: node scripts/generate-test-summary.js
+      
+      # Generate detailed reports
+      - name: Generate detailed reports
+        if: always()
+        run: node scripts/generate-detailed-reports.js
+      
+      # Upload test results artifacts
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            test-results/
+            test-summary.md
+            test-reports/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage artifacts
+      - name: Upload coverage reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            coverage/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage to Codecov
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+          verbose: true
+      
+      # Run linting
+      - name: Run linting
+        run: npm run lint
+      
+      # Run type checking
+      - name: Run type checking
+        run: npm run typecheck
+      
+      # Create test report comment for PRs
+      - name: Create test report comment
+        if: github.event_name == 'pull_request' && always()
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            const fs = require('fs');
+            let summary = '## Test Results\n\nTest summary generation failed.';
+            
+            try {
+              if (fs.existsSync('test-summary.md')) {
+                summary = fs.readFileSync('test-summary.md', 'utf8');
+              }
+            } catch (error) {
+              console.error('Error reading test summary:', error);
+            }
+            
+            try {
+              // Find existing comment
+              const { data: comments } = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+              });
+              
+              const botComment = comments.find(comment => 
+                comment.user.type === 'Bot' && 
+                comment.body.includes('## Test Results')
+              );
+              
+              if (botComment) {
+                // Update existing comment
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: summary
+                });
+              } else {
+                // Create new comment
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: summary
+                });
+              }
+            } catch (error) {
+              console.error('Failed to create/update PR comment:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+              console.log('Test results have been saved to the job summary instead.');
+            }
+      
+      # Generate job summary
+      - name: Generate job summary
+        if: always()
+        run: |
+          echo "# Test Run Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -f test-summary.md ]; then
+            cat test-summary.md >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Test summary generation failed." >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## 📥 Download Artifacts" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- [Test Results](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+          echo "- [Coverage Report](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+      
+      # Store test metadata
+      - name: Store test metadata
+        if: always()
+        run: |
+          cat > test-metadata.json << EOF
+          {
+            "run_id": "${{ github.run_id }}",
+            "run_number": "${{ github.run_number }}",
+            "run_attempt": "${{ github.run_attempt }}",
+            "sha": "${{ github.sha }}",
+            "ref": "${{ github.ref }}",
+            "event_name": "${{ github.event_name }}",
+            "repository": "${{ github.repository }}",
+            "actor": "${{ github.actor }}",
+            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "node_version": "$(node --version)",
+            "npm_version": "$(npm --version)"
+          }
+          EOF
+      
+      - name: Upload test metadata
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-metadata-${{ github.run_number }}-${{ github.run_attempt }}
+          path: test-metadata.json
+          retention-days: 30
+
+  # Verify the compiled CommonJS artifact loads under Node's CJS loader (regression guard for #864).
+  # Node 20.19+/22.12+ silently tolerate require() of ESM-only deps; scripts/smoke-cjs-runtime.js
+  # forces the strict loader (--no-experimental-require-module) when the running Node supports it,
+  # so a CJS/ESM mismatch in a shipped dependency (e.g. uuid@14) fails here regardless of the
+  # runner's Node version. The unit suite runs under Vitest's ESM pipeline and cannot catch this;
+  # tsc only type-checks.
+  cjs-runtime:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Load compiled CommonJS artifact under strict CJS loader
+        run: npm run test:cjs-runtime
+
+  # Publish test results as checks
+  publish-results:
+    needs: test
+    runs-on: ubuntu-latest
+    if: always()
+    permissions:
+      checks: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download test results
+        uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+
+      - name: Publish test results
+        uses: dorny/test-reporter@v3
+        if: always()
+        continue-on-error: true
+        with:
+          name: Test Results
+          path: 'artifacts/test-results-*/test-results/junit.xml'
+          reporter: java-junit
+          fail-on-error: false
+          fail-on-empty: false

.gitignore

@@ -0,0 +1,149 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env*.local
+
+# Build output
+dist/
+build/
+out/
+.next/
+.nuxt/
+.cache/
+.parcel-cache/
+
+# MCPB bundle (built artifact — produced by `mcpb pack`, attached to releases)
+*.mcpb
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Testing
+coverage/
+.nyc_output/
+test-results/
+test-reports/
+test-summary.md
+test-metadata.json
+benchmark-results.json
+benchmark-results*.json
+benchmark-summary.json
+coverage-report.json
+benchmark-comparison.md
+benchmark-comparison.json
+benchmark-current.json
+benchmark-baseline.json
+tests/data/*.db
+tests/fixtures/*.tmp
+tests/test-results/
+.test-dbs/
+junit.xml
+*.test.db
+test-*.db
+.vitest/
+
+# TypeScript
+*.tsbuildinfo
+.tsc-cache/
+
+# Package manager files
+.npm/
+.yarn/
+.pnp.*
+.yarn-integrity
+
+# Docker
+docker-compose.override.yml
+
+# Miscellaneous
+.eslintcache
+.stylelintcache
+*.pid
+*.seed
+*.pid.lock
+.grunt/
+.lock-wscript
+.node_repl_history
+.npmrc
+.yarnrc
+
+# Temporary files
+temp/
+tmp/
+
+# Batch processing error files (may contain API tokens from templates)
+docs/batch_*.jsonl
+**/batch_*_error.jsonl
+
+# Local documentation and analysis files
+docs/local/
+
+# Database files
+# Database files - nodes.db is now tracked directly
+# data/*.db
+data/*.db-journal
+data/*.db.bak
+data/*.db.backup
+!data/.gitkeep
+!data/nodes.db
+
+# Claude Desktop configs (personal)
+claude_desktop_config.json
+claude_desktop_config_*.json
+!claude_desktop_config.example.json
+
+# Personal wrapper scripts
+mcp-server-v20.sh
+rebuild-v20.sh
+!mcp-server-v20.example.sh
+
+# n8n-docs repo (cloned locally)
+../n8n-docs/
+n8n-docs/
+
+# npm publish temporary directory
+npm-publish-temp/
+
+# Test files and logs
+test-npx/
+mcp-server-*.log
+server.log
+server-fixed.log
+mcp-debug.log
+
+# Temporary wrapper scripts
+n8n-mcp-wrapper.sh
+
+# Package tarballs
+*.tgz
+
+# MCP configuration files (all variants: .mcp.json, .mcp.json.bk, .mcp.json.bak, etc.)
+.mcp.json*
+
+# UI Apps build output
+ui-apps/dist/
+ui-apps/node_modules/
+
+# Telemetry configuration (user-specific)
+~/.n8n-mcp/

.husky/pre-commit

@@ -0,0 +1,34 @@
+#!/usr/bin/env sh
+# Pre-commit: block accidentally committed secrets.
+#
+# Uses secretlint against staged files only (fast). If secretlint is not
+# installed (e.g. contributor skipped `npm install`), the hook fails open
+# with a warning — CI will still run the authoritative check.
+#
+# To skip this hook locally (NOT recommended): `git commit --no-verify`.
+
+# Collect list of staged files that would be added/modified (exclude deletions)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "⚠️  husky/pre-commit: npx not found, skipping secret scan"
+  exit 0
+fi
+
+# Run secretlint on the staged files. --maskSecrets hides any detected values
+# from the terminal output so developers don't accidentally copy them.
+echo "$STAGED_FILES" | xargs npx --no-install secretlint --maskSecrets
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo ""
+  echo "❌ Secret scanner blocked the commit."
+  echo "   If this is a false positive, add the file to .secretlintignore"
+  echo "   or the rule to .secretlintrc.json. To bypass (NOT recommended):"
+  echo "   git commit --no-verify"
+  exit 1
+fi

.mcpbignore

@@ -0,0 +1,15 @@
+# MCPB bundle ignore file (.mcpbignore) — gitignore semantics, combined with
+# mcpb's built-in default exclusions (node_modules, .git, *.map, lockfiles, ...).
+#
+# This is an npx-based bundle: the server is fetched from npm at runtime via
+# `npx -y n8n-mcp` (see manifest.json), so NO project code ships inside the .mcpb.
+# The packed bundle should contain only manifest.json (and icon.png, if added).
+#
+# Strategy: exclude everything, then re-include the few files the bundle needs.
+# A later "!" re-include overrides an earlier broad exclude — order matters.
+
+*
+
+# Files the bundle actually needs:
+!manifest.json
+!icon.png

.npmignore

@@ -0,0 +1,72 @@
+# Source files (TypeScript)
+src/
+*.ts
+!dist/**/*.d.ts
+
+# Development files
+.github/
+scripts/
+tests/
+docs/
+*.test.js
+*.spec.js
+
+# Build files
+tsconfig.json
+jest.config.js
+nodemon.json
+renovate.json
+
+# Docker files (not needed for npm)
+Dockerfile*
+docker-compose*.yml
+docker/
+.dockerignore
+
+# Environment and config files
+.env
+.env.*
+!.env.example
+
+# IDE and OS files
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs and temp files
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage and test reports
+coverage/
+.nyc_output/
+
+# Git files
+.git/
+.gitignore
+
+# Documentation source files
+*.md
+!README.md
+!LICENSE
+
+# Package files we don't want to publish
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Backup files
+*.backup
+*.bak
+
+# Keep only necessary runtime files
+!dist/
+!data/nodes.db
+!package.json
+!package.runtime.json

.secretlintignore

@@ -0,0 +1,48 @@
+# Large build/data artifacts — no source content, no secret risk
+dist/
+data/nodes.db
+ui-apps/dist/
+node_modules/
+
+# Local environment files (already gitignored, but secretlint doesn't read
+# .gitignore). Listing here keeps local scans consistent with CI.
+.env
+.env.*
+
+# Local clones of upstream n8n-docs (already gitignored). These are upstream
+# documentation with example credentials in markdown; not our code to fix.
+n8n-docs/
+temp/
+
+# Skill markdown synced from the n8n-skills repo. Contains placeholder
+# credentials in code examples; the upstream repo is the source of truth.
+data/skills/
+
+# Package lock files contain integrity hashes and registry URLs that trip
+# high-entropy rules. They are machine-generated and reviewed separately.
+package-lock.json
+ui-apps/package-lock.json
+
+# Extracted/imported test fixtures (mock data, not real secrets)
+tests/extracted-nodes-db/
+tests/node-storage-export.json
+
+# Tests that deliberately contain fake tokens to exercise our own
+# credential-scanner and telemetry redaction code paths. These fixtures
+# are what proves those features work.
+tests/unit/services/credential-scanner.test.ts
+tests/unit/telemetry/telemetry-events.test.ts
+tests/unit/telemetry/workflow-sanitizer.test.ts
+
+# SSRF-related tests contain literal userinfo URLs (e.g. http://user:pw@host)
+# as negative fixtures proving the validator rejects URLs with embedded basic
+# auth. These are not real credentials — they're the inputs the code refuses.
+tests/unit/utils/ssrf-protection.test.ts
+tests/unit/services/n8n-api-client.test.ts
+tests/unit/http-server/ssrf-gate.test.ts
+tests/unit/flexible-instance-security.test.ts
+
+# Template fixtures (user workflow JSON; any embedded credentials are
+# mock data from public n8n.io templates — scanned separately by the
+# sanitize-templates script)
+data/workflow-patterns.json

.secretlintrc.json

@@ -0,0 +1,7 @@
+{
+  "rules": [
+    {
+      "id": "@secretlint/secretlint-rule-preset-recommend"
+    }
+  ]
+}

AGENTS.md

@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Core TypeScript lives in `src/`: MCP tools in `src/mcp/`, business logic in `src/services/`, persistence in `src/database/`, and shared code in `src/types/` and `src/utils/`. Tests mirror these areas in `tests/unit/` and `tests/integration/`; supporting fixtures and mocks stay under `tests/`. React/Vite apps live in `ui-apps/src/`, repo utilities in `scripts/`, TypeScript maintenance scripts in `src/scripts/` (compiled to `dist/scripts/` at build time), documentation in `docs/`, and generated skills/databases in `data/`. Treat `dist/`, coverage output, and `ui-apps/dist/` as generated.
+
+## Build, Test, and Development Commands
+
+- `npm install` installs root dependencies; repeat in `ui-apps/` for UI work.
+- `npm run build` compiles production TypeScript to `dist/`.
+- `npm run build:all` synchronizes skills, builds UI apps, and compiles the server.
+- `npm run typecheck` (also `npm run lint`) performs strict checks without emitting.
+- `npm run dev:http` rebuilds and restarts the HTTP server as sources change.
+- `npm run rebuild` regenerates the node database; expect this to take several minutes.
+- `npm run validate` checks generated node data after a build/rebuild.
+
+## Coding Style & Naming Conventions
+
+Use strict TypeScript, two-space indentation, single quotes, and semicolons. Prefer `camelCase` for variables/functions, `PascalCase` for classes/types, and kebab-case filenames such as `workflow-auto-fixer.ts`. Use configured `@/` and `@tests/` aliases where helpful. Keep modules focused, validate external input, and do not edit generated outputs. No separate formatter is configured; `npm run typecheck` is the required static check.
+
+## Testing Guidelines
+
+Vitest is the primary framework; MSW handles API mocking. Name tests `*.test.ts` and place them in the matching test subtree. Run `npm run test:unit` for fast checks, `npm run test:integration` for system behavior, and `npm run test:coverage` before substantial PRs. Thresholds are 75% for lines, functions, and statements and 70% for branches. Live n8n tests need configuration and clean database state; do not mask flakes with retries.
+
+## Commit & Pull Request Guidelines
+
+Recent history follows Conventional Commit prefixes such as `feat:`, `fix:`, `docs:`, `chore:`, and scoped forms like `ci(deps):`. Use a feature branch; never commit directly to `main`. PRs should explain intent and verification, link relevant issues, and include screenshots for UI changes. Enable “Allow edits by maintainers.” Follow the commit/PR attribution requirement in `CLAUDE.md`, but never add that attribution to product file contents.
+
+## Security & Configuration
+
+This is a public repository: never commit credentials, API keys, private URLs, or customer data. Start from `.env.example`, keep local secrets untracked, and validate workflows before deploying them to n8n.

ANALYSIS_QUICK_REFERENCE.md

@@ -0,0 +1,209 @@
+# N8N-MCP Validation Analysis: Quick Reference
+
+**Analysis Date**: November 8, 2025 | **Data Period**: 90 days | **Sample Size**: 29,218 events
+
+---
+
+## The Core Finding
+
+**Validation is working perfectly. Guidance is the problem.**
+
+- 29,218 validation events successfully prevented bad deployments
+- 100% of agents fix errors same-day (proving feedback works)
+- 12.6% error rate for advanced users (who attempt complex workflows)
+- High error volume = high usage, not broken system
+
+---
+
+## Top 3 Problem Areas (75% of errors)
+
+| Area | Errors | Root Cause | Quick Fix |
+|------|--------|-----------|-----------|
+| **Workflow Structure** | 1,268 (26%) | JSON malformation | Better error messages with examples |
+| **Connections** | 676 (14%) | Syntax unintuitive | Create connections guide with diagrams |
+| **Required Fields** | 378 (8%) | Not marked upfront | Add "⚠️ REQUIRED" to tool responses |
+
+---
+
+## Problem Nodes (By Frequency)
+
+```
+Webhook/Trigger ......... 127 failures (40 users)
+Slack .................. 73 failures (2 users)
+AI Agent ............... 36 failures (20 users)
+HTTP Request ........... 31 failures (13 users)
+OpenAI ................. 35 failures (8 users)
+```
+
+---
+
+## Top 5 Validation Errors
+
+1. **"Duplicate node ID: undefined"** (179)
+   - Fix: Point to exact location + show example format
+
+2. **"Single-node workflows only valid for webhooks"** (58)
+   - Fix: Create webhook guide explaining rule
+
+3. **"responseNode requires onError: continueRegularOutput"** (57)
+   - Fix: Same guide + inline error context
+
+4. **"Required property X cannot be empty"** (25)
+   - Fix: Mark required fields before validation
+
+5. **"Duplicate node name: undefined"** (61)
+   - Fix: Related to structural issues, same solution as #1
+
+---
+
+## Success Indicators
+
+✓ **Agents learn from errors**: 100% same-day correction rate
+✓ **Validation catches issues**: Prevents bad deployments
+✓ **Feedback is clear**: Quick fixes show error messages work
+✓ **No systemic failures**: No "unfixable" errors
+
+---
+
+## What Works Well
+
+- Error messages lead to immediate corrections
+- Agents retry and succeed same-day
+- Validation prevents broken workflows
+- 9,021 users actively using system
+
+---
+
+## What Needs Improvement
+
+1. Required fields not marked in tool responses
+2. Error messages don't show valid options for enums
+3. Workflow structure documentation lacks examples
+4. Connection syntax unintuitive/undocumented
+5. Some error messages too generic
+
+---
+
+## Implementation Plan
+
+### Phase 1 (2 weeks): Quick Wins
+- Enhanced error messages (location + example)
+- Required field markers in tools
+- Webhook configuration guide
+- **Expected Impact**: 25-30% failure reduction
+
+### Phase 2 (2 weeks): Documentation
+- Enum value suggestions in validation
+- Workflow connections guide
+- Error handler configuration guide
+- AI Agent validation improvements
+- **Expected Impact**: Additional 15-20% reduction
+
+### Phase 3 (2 weeks): Advanced Features
+- Improved search with config hints
+- Node type fuzzy matching
+- KPI tracking setup
+- Test coverage
+- **Expected Impact**: Additional 10-15% reduction
+
+**Total Impact**: 50-65% failure reduction (target: 6-7% error rate)
+
+---
+
+## Key Metrics
+
+| Metric | Current | Target | Timeline |
+|--------|---------|--------|----------|
+| Validation failure rate | 12.6% | 6-7% | 6 weeks |
+| First-attempt success | ~77% | 85%+ | 6 weeks |
+| Retry success | 100% | 100% | N/A |
+| Webhook failures | 127 | <30 | Week 2 |
+| Connection errors | 676 | <270 | Week 4 |
+
+---
+
+## Files Delivered
+
+1. **VALIDATION_ANALYSIS_REPORT.md** (27KB)
+   - Complete analysis with 16 SQL queries
+   - Detailed findings by category
+   - 8 actionable recommendations
+
+2. **VALIDATION_ANALYSIS_SUMMARY.md** (13KB)
+   - Executive summary (one-page)
+   - Key metrics scorecard
+   - Top recommendations with ROI
+
+3. **IMPLEMENTATION_ROADMAP.md** (4.3KB)
+   - 6-week implementation plan
+   - Phase-by-phase breakdown
+   - Code locations and effort estimates
+
+4. **ANALYSIS_QUICK_REFERENCE.md** (this file)
+   - Quick lookup reference
+   - Top problems at a glance
+   - Decision-making summary
+
+---
+
+## Next Steps
+
+1. **Week 1**: Review analysis + get team approval
+2. **Week 2**: Start Phase 1 (error messages + markers)
+3. **Week 4**: Deploy Phase 1 + start Phase 2
+4. **Week 6**: Deploy Phase 2 + start Phase 3
+5. **Week 8**: Deploy Phase 3 + measure impact
+6. **Week 9+**: Monitor KPIs + iterate
+
+---
+
+## Key Recommendations Priority
+
+### HIGH (Do First - Week 1-2)
+1. Enhance structure error messages
+2. Add required field markers to tools
+3. Create webhook configuration guide
+
+### MEDIUM (Do Next - Week 3-4)
+4. Add enum suggestions to validation responses
+5. Create workflow connections guide
+6. Add AI Agent node validation
+
+### LOW (Do Later - Week 5-6)
+7. Enhance search with config hints
+8. Build fuzzy node matcher
+9. Setup KPI tracking
+
+---
+
+## Discussion Points
+
+**Q: Why don't we just weaken validation?**
+A: Validation prevents 29,218 bad deployments. That's its job. We improve guidance instead.
+
+**Q: Are agents really learning from errors?**
+A: Yes, 100% same-day recovery across 661 user-date pairs with errors.
+
+**Q: Why do documentation readers have higher error rates?**
+A: They attempt more complex workflows (6.8x more attempts). Success rate is still 87.4%.
+
+**Q: Which node needs the most help?**
+A: Webhook/Trigger configuration (127 failures). Most urgent fix.
+
+**Q: Can we hit 50% reduction in 6 weeks?**
+A: Yes, analysis shows 50-65% reduction is achievable with these changes.
+
+---
+
+## Contact & Questions
+
+For detailed information:
+- Full analysis: `VALIDATION_ANALYSIS_REPORT.md`
+- Executive summary: `VALIDATION_ANALYSIS_SUMMARY.md`
+- Implementation plan: `IMPLEMENTATION_ROADMAP.md`
+
+---
+
+**Report Status**: Complete and Ready for Action
+**Confidence Level**: High (9,021 users, 29,218 events, comprehensive analysis)
+**Generated**: November 8, 2025

ATTRIBUTION.md

@@ -0,0 +1,33 @@
+# Attribution
+
+## Using n8n-MCP in Your Project?
+
+While not legally required, we'd love it if you included attribution! Here are some easy ways:
+
+### In Your README
+```
+Built with [n8n-MCP](https://github.com/czlonkowski/n8n-mcp) by Romuald Czlonkowski @ [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
+```
+
+### In Your Documentation
+```
+This project uses n8n-MCP (https://github.com/czlonkowski/n8n-mcp) 
+for n8n node documentation access.
+Created by Romuald Czlonkowski @ www.aiadvisors.pl/en
+```
+
+### In Code Comments
+```javascript
+// Powered by n8n-MCP - https://github.com/czlonkowski/n8n-mcp
+// Created by Romuald Czlonkowski @ www.aiadvisors.pl/en
+```
+
+## Why Attribution Matters
+
+Attribution helps:
+- Other developers discover this tool
+- Build a stronger n8n community
+- Me understand how the tool is being used
+- You get support and updates
+
+Thank you for using n8n-MCP! 🙏

CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Note:** This file is committed to a public OSS repository. Never add sensitive information (API keys, internal URLs, credentials, private infrastructure details) here.
+
+## Project Overview
+
+n8n-mcp is an MCP (Model Context Protocol) server that gives AI assistants access to n8n node documentation, workflow validation, and workflow management. Documentation and validation tools work offline against a bundled SQLite database of node information; management tools (`n8n_*`) operate on a live n8n instance when API credentials are configured.
+
+## Common Development Commands
+
+```bash
+# Build
+npm run build          # Compile TypeScript (always run after changes)
+npm run build:all      # Sync skills pack + build UI apps + compile
+npm run rebuild        # Rebuild node database from n8n packages
+npm run validate       # Validate node data in database
+npm run dev            # build + rebuild + validate
+
+# Testing
+npm test               # Run all tests (vitest)
+npm run test:unit      # Unit tests only
+npm run test:integration # Integration tests
+npm run test:e2e       # End-to-end tests
+npm run test:coverage  # Coverage report
+npm test -- tests/unit/services/property-filter.test.ts  # Single file
+
+# Type checking
+npm run typecheck      # tsc --noEmit (npm run lint is an alias)
+
+# Running the server
+npm start              # MCP server in stdio mode
+npm run start:http     # MCP server in HTTP mode
+npm run dev:http       # HTTP server with auto-reload
+
+# n8n dependency updates — follow MEMORY_N8N_UPDATE.md
+npm run update:n8n:check  # Dry run
+npm run update:n8n        # Update n8n packages
+
+# Templates and community nodes
+npm run fetch:templates   # Fetch workflow templates from n8n.io — see MEMORY_TEMPLATE_UPDATE.md
+npm run fetch:community   # Fetch/refresh community nodes (upserts; preserves existing docs)
+npm run generate:docs:incremental  # Generate AI docs for community nodes missing them
+```
+
+## Architecture
+
+Key subsystems of `src/` (non-exhaustive — smaller directories are omitted). This file intentionally stays at subsystem level; for file-level detail, explore the directories.
+
+- `mcp/` — MCP server, tool definitions (`tools.ts`, `tools-n8n-manager.ts`), request handlers, per-tool documentation (`tool-docs/`), bundled skills (`skills/`)
+- `database/` — SQLite storage: universal adapter over better-sqlite3/sql.js, `node-repository.ts` data access, FTS5 full-text search, `migrations/`
+- `loaders/`, `parsers/`, `mappers/` — node processing pipeline: load nodes from n8n packages → parse metadata and properties → map external documentation
+- `services/` — business logic: config/workflow/expression validators, validation profiles, workflow diff engine, auto-fixer, node similarity and version services, n8n API client, security/audit scanners
+- `templates/` — fetching and storing workflow templates from n8n.io
+- `community/` — community node fetching and documentation generation
+- `telemetry/` — opt-in anonymous usage telemetry
+- `triggers/` — trigger detection and registry
+- `n8n/` — n8n community node wrapper (N8N_MODE)
+- `scripts/` — maintenance CLI scripts (rebuild, validate, template/community fetching), compiled to `dist/scripts/`
+- `types/`, `constants/`, `utils/` — shared types, type structures, helpers
+- `http-server.ts`, `http-server-single-session.ts` — HTTP mode with session persistence
+- `mcp-engine.ts`, `mcp-tools-engine.ts` — clean API for embedding the server in other services
+
+### Key design patterns
+
+1. **Repository pattern**: all database operations go through repository classes
+2. **Service layer**: business logic separated from data access
+3. **Validation profiles**: strictness levels `minimal`, `runtime`, `ai-friendly`, `strict`
+4. **Diff-based updates**: `n8n_update_partial_workflow` applies operation diffs, saving 80–90% of tokens vs full updates
+
+### MCP tools
+
+Two groups:
+
+- **Documentation and validation** (offline, always available): `search_nodes`, `get_node`, `validate_node`, `validate_workflow`, `search_templates`, `get_template`, `tools_documentation`
+- **Management** (`n8n_*`, require n8n API configuration): workflow CRUD and partial updates, executions, workflow testing, versions, autofix, template deployment, credentials, datatables, instance audit
+
+`get_node` supports detail levels (`minimal`/`standard`/`full`) — request the smallest level that answers the question.
+
+## Development Workflow
+
+- After changing MCP server code: build, then ask the user to reload the MCP server before testing
+- Run `npm run typecheck` after every code change
+- Never commit directly to main — use feature branches and PRs
+- Add to every commit message and PR description: `Conceived by Romuald Członkowski - www.aiadvisors.pl/en`. The attribution belongs in commit messages and PR descriptions only — never in source, test, or documentation file contents
+- When reviewing issues, use the GH CLI (`gh`) to fetch the issue and all its comments
+- Do not use hyperbolic or dramatic language in comments and documentation
+
+### Sub-agents
+
+- When a task divides into independent subtasks, spawn sub-agents to handle them in parallel; pick the best agent type per its description
+- Sub-agents must not spawn further sub-agents
+- Sub-agents must not commit or push — do that yourself
+
+### Pitfalls
+
+- Database rebuilds take 2–3 minutes due to n8n package size
+- Integration tests require a clean database state
+- HTTP mode requires proper auth token configuration
+- Always validate workflows before deploying them to n8n

CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing
+
+Contributions are welcome! Here's how to get started.
+
+## Getting Started
+
+1. Fork the repository
+2. **Allow the maintainer to push to your fork** - When creating your PR, check "Allow edits by maintainers". This speeds up the review process and allows the maintainer to make small adjustments directly.
+3. Create a feature branch (`git checkout -b feature/your-feature`)
+4. Make your changes
+5. Run tests (`npm test`)
+6. Submit a pull request
+
+## Local Development Setup
+
+**Prerequisites:**
+- [Node.js](https://nodejs.org/) (any version - automatic fallback if needed)
+- npm or yarn
+- Git
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+
+# 2. Clone n8n docs (optional but recommended)
+git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
+
+# 3. Install and build
+npm install
+npm run build
+
+# 4. Initialize database
+npm run rebuild
+
+# 5. Start the server
+npm start          # stdio mode for Claude Desktop
+npm run start:http # HTTP mode for remote access
+```
+
+## Development Commands
+
+```bash
+# Build & Test
+npm run build          # Build TypeScript
+npm run rebuild        # Rebuild node database
+npm run validate       # Validate node data (includes critical-node checks)
+npm test               # Run all tests
+
+# Update Dependencies
+npm run update:n8n:check  # Check for n8n updates
+npm run update:n8n        # Update n8n packages
+
+# Run Server
+npm run dev            # Development with auto-reload
+npm run dev:http       # HTTP dev mode
+```
+
+## Testing
+
+The project includes a comprehensive test suite:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test suites
+npm run test:unit           # Unit tests
+npm run test:integration    # Integration tests
+```
+
+### Test Architecture
+
+- **Unit Tests**: Isolated component testing with mocks (services, parsers, database, MCP tools, HTTP server)
+- **Integration Tests**: Full system behavior validation (n8n API, MCP protocol, database, templates, Docker)
+- **Framework**: Vitest
+- **API Mocking**: MSW
+- **CI/CD**: Automated testing on all PRs with GitHub Actions
+
+## Automated Releases (For Maintainers)
+
+This project uses automated releases triggered by version changes:
+
+```bash
+# Guided release preparation
+npm run prepare:release
+
+# Test release automation
+npm run test:release-automation
+```
+
+The system automatically handles GitHub releases, NPM publishing, multi-platform Docker images, and documentation updates.
+
+See [Automated Release Guide](./docs/AUTOMATED_RELEASES.md) for details.

Dockerfile

@@ -0,0 +1,102 @@
+# syntax=docker/dockerfile:1.7
+# Ultra-optimized Dockerfile - minimal runtime dependencies (no n8n packages)
+
+# Stage 1: Builder (TypeScript compilation only)
+FROM node:22-alpine AS builder
+WORKDIR /app
+
+# Copy tsconfig files for TypeScript compilation
+COPY tsconfig*.json ./
+
+# Create minimal package.json and install ONLY build dependencies
+# Note: openai and zod are needed for TypeScript compilation of template metadata modules
+RUN --mount=type=cache,target=/root/.npm \
+    echo '{}' > package.json && \
+    npm install --no-save typescript@^5.8.3 @types/node@^22.15.30 @types/express@^5.0.3 \
+        @modelcontextprotocol/sdk@1.20.1 dotenv@^16.5.0 express@^5.1.0 axios@^1.10.0 \
+        n8n-workflow@^2.4.2 uuid@^11.0.5 @types/uuid@^10.0.0 \
+        openai@^4.77.0 zod@3.24.1 lru-cache@^11.2.1 @supabase/supabase-js@^2.57.4
+
+# Copy source and build
+COPY src ./src
+# Note: src/n8n contains TypeScript types needed for compilation
+# These will be compiled but not included in runtime
+RUN npx tsc -p tsconfig.build.json
+
+# Stage 2: Runtime (minimal dependencies)
+FROM node:22-alpine AS runtime
+WORKDIR /app
+
+# Install only essential runtime tools
+RUN apk add --no-cache curl su-exec && \
+    rm -rf /var/cache/apk/*
+
+# Copy runtime-only package.json
+COPY package.runtime.json package.json
+
+# Install runtime dependencies with better-sqlite3 compilation
+# Build tools (python3, make, g++) are installed, used for compilation, then removed
+# This enables native SQLite (better-sqlite3) instead of sql.js, preventing memory leaks
+RUN --mount=type=cache,target=/root/.npm \
+    apk add --no-cache python3 make g++ && \
+    npm install --production --no-audit --no-fund && \
+    apk del python3 make g++
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+
+# Copy pre-built database and required files
+# Cache bust: 2025-07-06-trigger-fix-v3 - includes is_trigger=true for webhook,cron,interval,emailReadImap
+COPY data/nodes.db ./data/
+# Pristine seed copy outside /app/data: volume mounts over /app/data mask the
+# bundled database, and the runtime image cannot rebuild it (no n8n packages),
+# so the entrypoint seeds custom/empty DB paths from here.
+COPY data/nodes.db ./.db-seed/nodes.db
+COPY data/skills ./data/skills
+COPY src/database/schema-optimized.sql ./src/database/
+COPY .env.example ./
+
+# Copy entrypoint script, config parser, and n8n-mcp command
+COPY docker/docker-entrypoint.sh /usr/local/bin/
+COPY docker/parse-config.js /app/docker/
+COPY docker/n8n-mcp /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/n8n-mcp
+
+# Add container labels
+LABEL org.opencontainers.image.source="https://github.com/czlonkowski/n8n-mcp"
+LABEL org.opencontainers.image.description="n8n MCP Server - Runtime Only"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.title="n8n-mcp"
+
+# Create non-root user with unpredictable UID/GID
+# Using a hash of the build time to generate unpredictable IDs
+RUN BUILD_HASH=$(date +%s | sha256sum | head -c 8) && \
+    UID=$((10000 + 0x${BUILD_HASH} % 50000)) && \
+    GID=$((10000 + 0x${BUILD_HASH} % 50000)) && \
+    addgroup -g ${GID} -S nodejs && \
+    adduser -S nodejs -u ${UID} -G nodejs && \
+    chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# Set Docker environment flag
+ENV IS_DOCKER=true
+
+# Telemetry: Anonymous usage statistics are ENABLED by default
+# To opt-out, uncomment the following line:
+# ENV N8N_MCP_TELEMETRY_DISABLED=true
+
+# Expose HTTP port (default 3000, configurable via PORT environment variable at runtime)
+EXPOSE 3000
+
+# Set stop signal to SIGTERM (default, but explicit is better)
+STOPSIGNAL SIGTERM
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD sh -c 'curl -f http://127.0.0.1:${PORT:-3000}/health || exit 1'
+
+# Optimized entrypoint
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+CMD ["node", "dist/mcp/index.js"]

Dockerfile.railway

@@ -0,0 +1,96 @@
+# syntax=docker/dockerfile:1.7
+# Railway-compatible Dockerfile for n8n-mcp
+
+# --- Stage 1: Builder ---
+FROM node:22-alpine AS builder
+WORKDIR /app
+
+# Install system dependencies for native modules
+RUN apk add --no-cache python3 make g++ && \
+    rm -rf /var/cache/apk/*
+
+# Copy package files and tsconfig files
+COPY package*.json tsconfig*.json ./
+
+# Install all dependencies (including devDependencies for build)
+# --legacy-peer-deps: n8n-nodes-base 2.20.x pulls in mappersmith with a `diff`
+# peer that conflicts with ts-node's `diff@^4`; npm 7+ strict resolution leaves
+# the lock internally inconsistent without this flag.
+RUN npm ci --no-audit --no-fund --legacy-peer-deps
+
+# Copy source code
+COPY src ./src
+
+# Build the application
+RUN npm run build
+
+# --- Stage 2: Runtime ---
+FROM node:22-alpine AS runtime
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apk add --no-cache curl && \
+    rm -rf /var/cache/apk/*
+
+# Copy runtime-only package.json
+COPY package.runtime.json package.json
+
+# Install production dependencies with temporary build tools
+# Build tools (python3, make, g++) enable better-sqlite3 compilation (native SQLite)
+# They are removed after installation to reduce image size and attack surface
+RUN apk add --no-cache python3 make g++ && \
+    npm install --production --no-audit --no-fund && \
+    npm cache clean --force && \
+    apk del python3 make g++
+
+# Copy built application from builder stage
+COPY --from=builder /app/dist ./dist
+
+# Copy necessary data and configuration files
+COPY data/ ./data/
+COPY src/database/schema-optimized.sql ./src/database/schema-optimized.sql
+COPY .env.example ./
+
+# Copy entrypoint script
+COPY docker/docker-entrypoint.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Create data directory if it doesn't exist and set permissions
+RUN mkdir -p ./data && \
+    chmod 755 ./data
+
+# Add metadata labels
+LABEL org.opencontainers.image.source="https://github.com/czlonkowski/n8n-mcp"
+LABEL org.opencontainers.image.description="n8n MCP Server - Integration between n8n workflow automation and Model Context Protocol"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.title="n8n-mcp"
+LABEL org.opencontainers.image.version="2.7.13"
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001 && \
+    chown -R nodejs:nodejs /app
+USER nodejs
+
+# Set Railway-optimized environment variables
+ENV AUTH_TOKEN="REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh"
+ENV NODE_ENV=production
+ENV IS_DOCKER=true
+ENV MCP_MODE=http
+# NOTE: USE_FIXED_HTTP is deprecated. SingleSessionHTTPServer is now the default.
+# See: https://github.com/czlonkowski/n8n-mcp/issues/524
+ENV LOG_LEVEL=info
+ENV TRUST_PROXY=1
+ENV HOST=0.0.0.0
+ENV CORS_ORIGIN="*"
+
+# Expose port (Railway will set PORT automatically)
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://127.0.0.1:${PORT:-3000}/health || exit 1
+
+# Optimized entrypoint (identical to main Dockerfile)
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+CMD ["node", "dist/mcp/index.js", "--http"]

Dockerfile.test

@@ -0,0 +1,24 @@
+# Quick test Dockerfile using pre-built files
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Copy only the essentials
+COPY package*.json ./
+COPY dist ./dist
+COPY data ./data
+COPY docker/docker-entrypoint.sh /usr/local/bin/
+COPY .env.example ./
+
+# Install only runtime dependencies
+RUN npm install --production @modelcontextprotocol/sdk better-sqlite3 express dotenv
+
+# Make entrypoint executable
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Set environment
+ENV IS_DOCKER=true
+ENV MCP_MODE=stdio
+
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+CMD ["node", "dist/mcp/index.js"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Romuald Czlonkowski @ www.aiadvisors.pl/en
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MEMORY_N8N_UPDATE.md

@@ -0,0 +1,283 @@
+# n8n Update Process - Quick Reference
+
+## ⚡ Recommended Fast Workflow (verified 2026-04-28)
+
+**CRITICAL FIRST STEP**: Check existing releases to avoid version conflicts!
+
+**IMPORTANT: Community nodes are preserved automatically!**
+- `npm run update:n8n` rebuilds the base node DB; the rebuild now skips rows where `is_community = 1`, so community nodes survive automatically (no manual backup/restore needed)
+- `npm run fetch:community` upserts by default (preserves READMEs + AI summaries) — run it to refresh/add community nodes, not to recover them
+- `npm run generate:docs:incremental` only processes nodes missing docs
+- Use `generate:docs:readme-only` first, then `generate:docs:summary-only` with a local LLM
+
+```bash
+# 1. CHECK EXISTING RELEASES FIRST (prevents version conflicts!)
+gh release list | head -5
+# Look at the latest version - your new version must be higher!
+
+# 2. Switch to main and pull
+git checkout main && git pull
+
+# 3. Check for updates (dry run)
+npm run update:n8n:check
+
+# 4. Run update and skip tests (we'll test in CI)
+# The rebuild preserves community nodes automatically (is_community = 1 rows are not wiped).
+yes y | npm run update:n8n
+
+# 5. Refresh community nodes (upserts - preserves existing READMEs + AI summaries!)
+npm run fetch:community
+# NOTE: Default mode is now "upsert" - no deletion. Use --rebuild for clean slate.
+
+# 6. Generate docs incrementally (only for new/missing nodes)
+npm run generate:docs:readme-only              # Fetch READMEs from npm (no LLM needed)
+# Then with a local LLM server running (LM Studio, vLLM, Ollama):
+N8N_MCP_LLM_BASE_URL="http://YOUR_SERVER:PORT/v1" \
+N8N_MCP_LLM_MODEL="your-model-name" \
+node dist/scripts/generate-community-docs.js --summary-only --skip-existing-summary --llm-concurrency=11
+# For vLLM with thinking models, the code auto-sends chat_template_kwargs: {enable_thinking: false}
+# Context length needed: 8K minimum (README truncated to 6000 chars, output max 2000 tokens)
+
+# 7. Create feature branch
+git checkout -b update/n8n-X.X.X
+
+# 8. Update version in package.json (must be HIGHER than latest release!)
+# Edit: "version": "2.XX.X" (not the version from the release list!)
+
+# 9. Update CHANGELOG.md
+# - Change version number to match package.json
+# - Update date to today
+# - Update dependency versions
+# - Include community node refresh counts
+
+# 10. Update README badge and node counts
+# Edit line 8: Change n8n version badge to new n8n version
+# Update total node count in description (core + community)
+
+# 11. Commit and push
+git add -A
+git commit -m "chore: update n8n to X.X.X and bump version to 2.XX.X
+
+- Updated n8n from X.X.X to X.X.X
+- Updated n8n-core from X.X.X to X.X.X
+- Updated n8n-workflow from X.X.X to X.X.X
+- Updated @n8n/n8n-nodes-langchain from X.X.X to X.X.X
+- Rebuilt node database with XXX nodes (XXX from n8n-nodes-base, XXX from @n8n/n8n-nodes-langchain)
+- Refreshed community nodes (XXX verified + XXX npm)
+- Updated README badge with new n8n version and node counts
+- Updated CHANGELOG with dependency changes
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+git push -u origin update/n8n-X.X.X
+
+# 12. Create PR
+gh pr create --title "chore: update n8n to X.X.X" --body "Updates n8n and all related dependencies to the latest versions..."
+
+# 13. After PR is merged, verify release triggered
+gh release list | head -1
+# If the new version appears, you're done!
+# If not, the version might have already been released - bump version again and create new PR
+```
+
+### Why This Workflow?
+
+✅ **Fast**: Skip local tests (2-3 min saved) - CI runs them anyway
+✅ **Safe**: Unit tests in CI verify compatibility
+✅ **Clean**: All changes in one PR with proper tracking
+✅ **Automatic**: Release workflow triggers on merge if version is new
+
+### Common Issues
+
+**Problem**: Release workflow doesn't trigger after merge
+**Cause**: Version number was already released (check `gh release list`)
+**Solution**: Create new PR bumping version by one patch number
+
+**Problem**: Integration tests fail in CI with "unauthorized"
+**Cause**: n8n test instance credentials expired (infrastructure issue)
+**Solution**: Ignore if unit tests pass - this is not a code problem
+
+**Problem**: CI takes 8+ minutes
+**Reason**: Integration tests need live n8n instance (slow)
+**Normal**: Unit tests (~2 min) + integration tests (~6 min) = ~8 min total
+
+## Quick One-Command Update
+
+For a complete update with tests and publish preparation:
+
+```bash
+npm run update:all
+```
+
+This single command will:
+1. ✅ Check for n8n updates and ask for confirmation
+2. ✅ Update all n8n dependencies to latest compatible versions
+3. ✅ Run all ~5,418 tests (~4,661 unit + ~757 integration)
+4. ✅ Validate critical nodes
+5. ✅ Build the project
+6. ✅ Bump the version
+7. ✅ Update README badges
+8. ✅ Prepare everything for npm publish
+9. ✅ Create a comprehensive commit
+
+## Manual Steps (if needed)
+
+### Quick Steps to Update n8n
+
+```bash
+# 1. Update n8n dependencies automatically
+npm run update:n8n
+
+# 2. Run tests
+npm test
+
+# 3. Validate the update
+npm run validate
+
+# 4. Build
+npm run build
+
+# 5. Bump version
+npm version patch
+
+# 6. Update README badges manually
+# - Update version badge
+# - Update n8n version badge
+
+# 7. Commit and push
+git add -A
+git commit -m "chore: update n8n to vX.X.X
+
+- Updated n8n from X.X.X to X.X.X
+- Updated n8n-core from X.X.X to X.X.X
+- Updated n8n-workflow from X.X.X to X.X.X
+- Updated @n8n/n8n-nodes-langchain from X.X.X to X.X.X
+- Rebuilt node database with XXX nodes
+- Sanitized XXX workflow templates (if present)
+- All ~5,418 tests passing (~4,661 unit, ~757 integration)
+- All validation tests passing
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+git push origin main
+```
+
+## What the Commands Do
+
+### `npm run update:all`
+This comprehensive command:
+1. Checks current branch and git status
+2. Shows current versions and checks for updates
+3. Updates all n8n dependencies to compatible versions
+4. **Runs the complete test suite** (NEW!)
+5. Validates critical nodes
+6. Builds the project
+7. Bumps the patch version
+8. Updates version badges in README
+9. Creates a detailed commit with all changes
+10. Provides next steps for GitHub release and npm publish
+
+### `npm run update:n8n`
+This command:
+1. Checks for the latest n8n version
+2. Updates n8n and all its required dependencies (n8n-core, n8n-workflow, @n8n/n8n-nodes-langchain)
+3. Runs `npm install` to update package-lock.json
+4. Automatically rebuilds the node database
+5. Sanitizes any workflow templates to remove API tokens
+6. Shows you exactly what versions were updated
+
+### `npm run validate`
+- Validates critical nodes (httpRequest, code, slack, agent)
+- Shows database statistics
+- Confirms everything is working correctly
+
+### `npm test`
+- Runs ~5,418 tests
+- Unit tests: ~4,661 tests across ~140 files
+- Integration tests: ~757 tests across ~56 files
+- Must pass before publishing!
+
+## Important Notes
+
+1. **ALWAYS check existing releases first** - Use `gh release list` to see what versions are already released. Your new version must be higher!
+2. **Release workflow only triggers on version CHANGE** - If you merge a PR with an already-released version (e.g., 2.22.8), the workflow won't run. You'll need to bump to a new version (e.g., 2.22.9) and create another PR.
+3. **Integration test failures in CI are usually infrastructure issues** - If unit tests pass but integration tests fail with "unauthorized", this is typically because the test n8n instance credentials need updating. The code itself is fine.
+4. **Skip local tests - let CI handle them** - Running tests locally adds 2-3 minutes with no benefit since CI runs them anyway. The fast workflow skips local tests.
+5. **The update script is smart** - It automatically syncs all n8n dependencies to compatible versions
+6. **Database rebuild is automatic** - The update script handles this for you
+7. **Template sanitization is automatic** - Any API tokens in workflow templates are replaced with placeholders
+8. **Docker image builds automatically** - Pushing to GitHub triggers the workflow
+
+## GitHub Push Protection
+
+As of July 2025, GitHub's push protection may block database pushes if they contain API tokens in workflow templates. Our rebuild process now automatically sanitizes these tokens, but if you encounter push protection errors:
+
+1. Make sure you've run the latest rebuild with `npm run rebuild`
+2. Verify sanitization with `npm run sanitize:templates`
+3. If push is still blocked, use the GitHub web interface to review and allow the push
+
+## Time Estimate
+
+### Fast Workflow (Recommended)
+- Local work: ~2-3 minutes
+  - npm install and database rebuild: ~2-3 minutes
+  - File edits (CHANGELOG, README, package.json): ~30 seconds
+  - Git operations (commit, push, create PR): ~30 seconds
+- CI testing after PR creation: ~8-10 minutes (runs automatically)
+  - Unit tests: ~2 minutes
+  - Integration tests: ~6 minutes (may fail with infrastructure issues - ignore if unit tests pass)
+  - Other checks: ~1 minute
+
+**Total hands-on time: ~3 minutes** (then wait for CI)
+
+### Full Workflow with Local Tests
+- Total time: ~5-7 minutes
+- Test suite: ~2.5 minutes
+- npm install and database rebuild: ~2-3 minutes
+- The rest: seconds
+
+**Note**: The fast workflow is recommended since CI runs the same tests anyway.
+
+## Troubleshooting
+
+If tests fail:
+1. Check the test output for specific failures
+2. Run `npm run test:unit` or `npm run test:integration` separately
+3. Fix any issues before proceeding with the update
+
+If validation fails:
+1. Check the error message - usually it's a node type reference issue
+2. The update script handles most compatibility issues automatically
+3. If needed, check the GitHub Actions logs for the dependency update workflow
+
+## Alternative: Check First
+To see what would be updated without making changes:
+```bash
+npm run update:n8n:check
+```
+
+This shows you the available updates without modifying anything.
+
+## Publishing to npm
+
+After updating:
+```bash
+# Prepare for publish (runs tests automatically)
+npm run prepare:publish
+
+# Follow the instructions to publish with OTP
+cd npm-publish-temp
+npm publish --otp=YOUR_OTP_CODE
+```
+
+## Creating a GitHub Release
+
+After pushing:
+```bash
+gh release create vX.X.X --title "vX.X.X" --notes "Updated n8n to vX.X.X"
+```

MEMORY_TEMPLATE_UPDATE.md

@@ -0,0 +1,336 @@
+# Template Update Process - Quick Reference
+
+## Overview
+
+The n8n-mcp project maintains a database of workflow templates from n8n.io. This guide explains how to update the template database incrementally without rebuilding from scratch.
+
+## Current Database State
+
+As of the last update:
+- **2,598 templates** in database
+- Templates from the last 12 months
+- Latest template: September 12, 2025
+
+## Quick Commands
+
+### Incremental Update (Recommended)
+```bash
+# Build if needed
+npm run build
+
+# Fetch only NEW templates (5-10 minutes)
+npm run fetch:templates:update
+```
+
+### Full Rebuild (Rare)
+```bash
+# Rebuild entire database from scratch (30-40 minutes)
+npm run fetch:templates
+```
+
+## How It Works
+
+### Incremental Update Mode (`--update`)
+
+The incremental update is **smart and efficient**:
+
+1. **Loads existing template IDs** from database (~2,598 templates)
+2. **Fetches template list** from n8n.io API (all templates from last 12 months)
+3. **Filters** to find only NEW templates not in database
+4. **Fetches details** for new templates only (saves time and API calls)
+5. **Saves** new templates to database (existing ones untouched)
+6. **Rebuilds FTS5** search index for new templates
+
+### Key Benefits
+
+✅ **Non-destructive**: All existing templates preserved
+✅ **Fast**: Only fetches new templates (5-10 min vs 30-40 min)
+✅ **API friendly**: Reduces load on n8n.io API
+✅ **Safe**: Preserves AI-generated metadata
+✅ **Smart**: Automatically skips duplicates
+
+## Performance Comparison
+
+| Mode | Templates Fetched | Time | Use Case |
+|------|------------------|------|----------|
+| **Update** | Only new (~50-200) | 5-10 min | Regular updates |
+| **Rebuild** | All (~8000+) | 30-40 min | Initial setup or corruption |
+
+## Command Options
+
+### Basic Update
+```bash
+npm run fetch:templates:update
+```
+
+### Full Rebuild
+```bash
+npm run fetch:templates
+```
+
+### With Metadata Generation
+```bash
+# Update templates and generate AI metadata
+npm run fetch:templates -- --update --generate-metadata
+
+# Or just generate metadata for existing templates
+npm run fetch:templates -- --metadata-only
+```
+
+### Help
+```bash
+npm run fetch:templates -- --help
+```
+
+## Update Frequency
+
+Recommended update schedule:
+- **Weekly**: Run incremental update to get latest templates
+- **Monthly**: Review database statistics
+- **As needed**: Rebuild only if database corruption suspected
+
+## Template Filtering
+
+The fetcher automatically filters templates:
+- ✅ **Includes**: Templates from last 12 months
+- ✅ **Includes**: Templates with >10 views
+- ❌ **Excludes**: Templates with ≤10 views (too niche)
+- ❌ **Excludes**: Templates older than 12 months
+
+## Workflow
+
+### Regular Update Workflow
+
+```bash
+# 1. Check current state
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 2. Build project (if code changed)
+npm run build
+
+# 3. Run incremental update
+npm run fetch:templates:update
+
+# 4. Verify new templates added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+```
+
+### After n8n Dependency Update
+
+When you update n8n dependencies, templates remain compatible:
+```bash
+# 1. Update n8n (from MEMORY_N8N_UPDATE.md)
+npm run update:all
+
+# 2. Fetch new templates incrementally
+npm run fetch:templates:update
+
+# 3. Check how many templates were added
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# 4. Generate AI metadata for new templates (optional, requires OPENAI_API_KEY)
+npm run fetch:templates -- --metadata-only
+
+# 5. IMPORTANT: Sanitize templates before pushing database
+npm run build
+npm run sanitize:templates
+```
+
+Templates are independent of n8n version - they're just workflow JSON data.
+
+**CRITICAL**: Always run `npm run sanitize:templates` before pushing the database to remove API tokens from template workflows.
+
+**Note**: New templates fetched via `--update` mode will NOT have AI-generated metadata by default. You need to run `--metadata-only` separately to generate metadata for templates that don't have it yet.
+
+## Troubleshooting
+
+### No New Templates Found
+
+This is normal! It means:
+- All recent templates are already in your database
+- n8n.io hasn't published many new templates recently
+- Your database is up to date
+
+```bash
+📊 Update mode: 0 new templates to fetch (skipping 2598 existing)
+✅ All templates already have metadata
+```
+
+### API Rate Limiting
+
+If you hit rate limits:
+- The fetcher includes built-in delays (150ms between requests)
+- Wait a few minutes and try again
+- Use `--update` mode instead of full rebuild
+
+### Database Corruption
+
+If you suspect corruption:
+```bash
+# Full rebuild from scratch
+npm run fetch:templates
+
+# This will:
+# - Drop and recreate templates table
+# - Fetch all templates fresh
+# - Rebuild search indexes
+```
+
+## Database Schema
+
+Templates are stored with:
+- Basic info (id, name, description, author, views, created_at)
+- Node types used (JSON array)
+- Complete workflow (gzip compressed, base64 encoded)
+- AI-generated metadata (optional, requires OpenAI API key)
+- FTS5 search index for fast text search
+
+## Metadata Generation
+
+Generate AI metadata for templates:
+```bash
+# Requires OPENAI_API_KEY in .env
+export OPENAI_API_KEY="sk-..."
+
+# Generate for templates without metadata (recommended after incremental update)
+npm run fetch:templates -- --metadata-only
+
+# Generate during template fetch (slower, but automatic)
+npm run fetch:templates:update -- --generate-metadata
+```
+
+**Important**: Incremental updates (`--update`) do NOT generate metadata by default. After running `npm run fetch:templates:update`, you'll have new templates without metadata. Run `--metadata-only` separately to generate metadata for them.
+
+### Check Metadata Coverage
+
+```bash
+# See how many templates have metadata
+sqlite3 data/nodes.db "SELECT
+  COUNT(*) as total,
+  SUM(CASE WHEN metadata_json IS NOT NULL THEN 1 ELSE 0 END) as with_metadata,
+  SUM(CASE WHEN metadata_json IS NULL THEN 1 ELSE 0 END) as without_metadata
+FROM templates"
+
+# See recent templates without metadata
+sqlite3 data/nodes.db "SELECT id, name, created_at
+FROM templates
+WHERE metadata_json IS NULL
+ORDER BY created_at DESC
+LIMIT 10"
+```
+
+Metadata includes:
+- Categories
+- Complexity level (simple/medium/complex)
+- Use cases
+- Estimated setup time
+- Required services
+- Key features
+- Target audience
+
+### Metadata Generation Troubleshooting
+
+If metadata generation fails:
+
+1. **Check error file**: Errors are saved to `temp/batch/batch_*_error.jsonl`
+2. **Common issues**:
+   - `"Unsupported value: 'temperature'"` - Model doesn't support custom temperature
+   - `"Invalid request"` - Check OPENAI_API_KEY is valid
+   - Model availability issues
+3. **Model**: Uses `gpt-5-mini-2025-08-07` by default
+4. **Token limit**: 3000 tokens per request for detailed metadata
+
+The system will automatically:
+- Process error files and assign default metadata to failed templates
+- Save error details for debugging
+- Continue processing even if some templates fail
+
+**Example error handling**:
+```bash
+# If you see: "No output file available for batch job"
+# Check: temp/batch/batch_*_error.jsonl for error details
+# The system now automatically processes errors and generates default metadata
+```
+
+## Environment Variables
+
+Optional configuration:
+```bash
+# OpenAI for metadata generation
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini  # Default model
+OPENAI_BATCH_SIZE=50      # Batch size for metadata generation
+
+# Metadata generation limits
+METADATA_LIMIT=100        # Max templates to process (0 = all)
+```
+
+## Statistics
+
+After update, check stats:
+```bash
+# Template count
+sqlite3 data/nodes.db "SELECT COUNT(*) FROM templates"
+
+# Most recent template
+sqlite3 data/nodes.db "SELECT MAX(created_at) FROM templates"
+
+# Templates by view count
+sqlite3 data/nodes.db "SELECT COUNT(*),
+  CASE
+    WHEN views < 50 THEN '<50'
+    WHEN views < 100 THEN '50-100'
+    WHEN views < 500 THEN '100-500'
+    ELSE '500+'
+  END as view_range
+  FROM templates GROUP BY view_range"
+```
+
+## Integration with n8n-mcp
+
+Templates are available through MCP tools:
+- `list_templates`: List all templates
+- `get_template`: Get specific template with workflow
+- `search_templates`: Search by keyword
+- `list_node_templates`: Templates using specific nodes
+- `get_templates_for_task`: Templates for common tasks
+- `search_templates_by_metadata`: Advanced filtering
+
+See `npm run test:templates` for usage examples.
+
+## Time Estimates
+
+Typical incremental update:
+- Loading existing IDs: 1-2 seconds
+- Fetching template list: 2-3 minutes
+- Filtering new templates: instant
+- Fetching details for 100 new templates: ~15 seconds (0.15s each)
+- Saving and indexing: 5-10 seconds
+- **Total: 3-5 minutes**
+
+Full rebuild:
+- Fetching 8000+ templates: 25-30 minutes
+- Saving and indexing: 5-10 minutes
+- **Total: 30-40 minutes**
+
+## Best Practices
+
+1. **Use incremental updates** for regular maintenance
+2. **Rebuild only when necessary** (corruption, major changes)
+3. **Generate metadata incrementally** to avoid OpenAI costs
+4. **Monitor template count** to verify updates working
+5. **Keep database backed up** before major operations
+
+## Next Steps
+
+After updating templates:
+1. Test template search: `npm run test:templates`
+2. Verify MCP tools work: Test in Claude Desktop
+3. Check statistics in database
+4. Commit changes if desired (database changes)
+
+## Related Documentation
+
+- `MEMORY_N8N_UPDATE.md` - Updating n8n dependencies
+- `CLAUDE.md` - Project overview and architecture
+- `README.md` - User documentation

N8N_HTTP_STREAMABLE_SETUP.md

@@ -0,0 +1,132 @@
+# n8n MCP HTTP Streamable Configuration Guide
+
+## Overview
+
+This guide shows how to configure the n8n-nodes-mcp community node to connect to n8n-mcp using the **recommended HTTP Streamable transport**.
+
+## Prerequisites
+
+1. Install n8n-nodes-mcp community node:
+   - Go to n8n Settings → Community Nodes
+   - Install: `n8n-nodes-mcp`
+   - Restart n8n if prompted
+
+2. Ensure environment variable is set:
+   ```bash
+   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
+   ```
+
+## Quick Start
+
+### Step 1: Start Services
+
+```bash
+# Stop any existing containers
+docker stop n8n n8n-mcp && docker rm n8n n8n-mcp
+
+# Start with HTTP Streamable configuration
+docker-compose -f docker-compose.n8n.yml up -d
+
+# Services will be available at:
+# - n8n: http://localhost:5678
+# - n8n-mcp: http://localhost:3000
+```
+
+### Step 2: Create MCP Credentials in n8n
+
+1. Open n8n at http://localhost:5678
+2. Go to Credentials → Add credential
+3. Search for "MCP" and select "MCP API"
+4. Configure the fields as follows:
+   - **Credential Name**: `n8n MCP Server`
+   - **HTTP Stream URL**: `
+   - **Messages Post Endpoint**: (leave empty)
+   - **Additional Headers**: 
+     ```json
+     {
+       "Authorization": "Bearer test-secure-token-123456789"
+     }
+     ```
+5. Save the credential
+
+### Step 3: Configure MCP Client Node
+
+Add an MCP Client node to your workflow with these settings:
+
+- **Connection Type**: `HTTP Streamable`
+- **HTTP Streamable URL**: `http://n8n-mcp:3000/mcp`
+- **Authentication**: `Bearer Auth`
+- **Credentials**: Select the credential you created
+- **Operation**: Choose your operation (e.g., "List Tools", "Call Tool")
+
+### Step 4: Test the Connection
+
+1. Execute the workflow
+2. The MCP Client should successfully connect and return results
+
+## Available Operations
+
+### List Tools
+Shows all available MCP tools:
+- `tools_documentation`
+- `list_nodes`
+- `get_node_info`
+- `search_nodes`
+- `get_node_essentials`
+- `validate_node_config`
+- And many more...
+
+### Call Tool
+Execute specific tools with arguments:
+
+**Example: Get Node Info**
+- Tool Name: `get_node_info`
+- Arguments: `{ "nodeType": "n8n-nodes-base.httpRequest" }`
+
+**Example: Search Nodes**
+- Tool Name: `search_nodes`
+- Arguments: `{ "query": "webhook", "limit": 5 }`
+
+## Import Example Workflow
+
+Import the pre-configured workflow:
+1. Go to Workflows → Add workflow → Import from File
+2. Select: `examples/n8n-mcp-streamable-workflow.json`
+3. Update the credentials with your bearer token
+
+## Troubleshooting
+
+### Connection Refused
+- Verify services are running: `docker ps`
+- Check logs: `docker logs n8n-mcp`
+- Ensure you're using `http://n8n-mcp:3000/mcp` (container name) not `localhost`
+
+### Authentication Failed
+- Verify bearer token matches exactly
+- Check CORS settings allow n8n origin
+
+### Test Endpoint Manually
+```bash
+# Test health check
+curl http://localhost:3000/health
+
+# Test MCP endpoint (should return error without proper JSON-RPC body)
+curl -X POST http://localhost:3000/mcp \
+  -H "Authorization: Bearer test-secure-token-123456789" \
+  -H "Content-Type: application/json"
+```
+
+## Architecture Notes
+
+- **Transport**: HTTP Streamable (StreamableHTTPServerTransport)
+- **Protocol**: JSON-RPC 2.0 over HTTP POST
+- **Authentication**: Bearer token in Authorization header
+- **Endpoint**: Single `/mcp` endpoint handles all operations
+- **Stateless**: Each request creates a new MCP server instance
+
+## Why HTTP Streamable?
+
+1. **Recommended by MCP**: The official recommended transport method
+2. **Better Performance**: More efficient than SSE
+3. **Simpler Implementation**: Single POST endpoint
+4. **Future Proof**: SSE is deprecated in MCP spec

P0-R3-TEST-PLAN.md

@@ -0,0 +1,484 @@
+# P0-R3 Feature Test Coverage Plan
+
+## Executive Summary
+
+This document outlines comprehensive test coverage for the P0-R3 feature (Template-based Configuration Examples). The feature adds real-world configuration examples from popular templates to node search and essentials tools.
+
+**Feature Overview:**
+- New database table: `template_node_configs` (197 pre-extracted configurations)
+- Enhanced tools: `search_nodes({includeExamples: true})` and `get_node_essentials({includeExamples: true})`
+- Breaking changes: Removed `get_node_for_task` tool
+
+## Test Files Created
+
+### Unit Tests
+
+#### 1. `/tests/unit/scripts/fetch-templates-extraction.test.ts` ✅
+**Purpose:** Test template extraction logic from `fetch-templates.ts`
+
+**Coverage:**
+- `extractNodeConfigs()` - 90%+ coverage
+  - Valid workflows with multiple nodes
+  - Empty workflows
+  - Malformed compressed data
+  - Invalid JSON
+  - Nodes without parameters
+  - Sticky note filtering
+  - Credential handling
+  - Expression detection
+  - Special characters
+  - Large workflows (100 nodes)
+
+- `detectExpressions()` - 100% coverage
+  - `={{...}}` syntax detection
+  - `$json` references
+  - `$node` references
+  - Nested objects
+  - Arrays
+  - Null/undefined handling
+  - Multiple expression types
+
+**Test Count:** 27 tests
+**Expected Coverage:** 92%+
+
+---
+
+#### 2. `/tests/unit/mcp/search-nodes-examples.test.ts` ✅
+**Purpose:** Test `search_nodes` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+  - false: no examples returned
+  - undefined: no examples returned (default)
+  - true: examples returned
+- Example data structure validation
+- Top 2 limit enforcement
+- Backward compatibility
+- Performance (<100ms)
+- Error handling (malformed JSON, database errors)
+- searchNodesLIKE integration
+- searchNodesFTS integration
+
+**Test Count:** 12 tests
+**Expected Coverage:** 85%+
+
+---
+
+#### 3. `/tests/unit/mcp/get-node-essentials-examples.test.ts` ✅
+**Purpose:** Test `get_node_essentials` tool with includeExamples parameter
+
+**Coverage:**
+- includeExamples parameter behavior
+- Full metadata structure
+  - configuration object
+  - source (template, views, complexity)
+  - useCases (limited to 2)
+  - metadata (hasCredentials, hasExpressions)
+- Cache key differentiation
+- Backward compatibility
+- Performance (<100ms)
+- Error handling
+- Top 3 limit enforcement
+
+**Test Count:** 13 tests
+**Expected Coverage:** 88%+
+
+---
+
+### Integration Tests
+
+#### 4. `/tests/integration/database/template-node-configs.test.ts` ✅
+**Purpose:** Test database schema, migrations, and operations
+
+**Coverage:**
+- Schema validation
+  - Table creation
+  - All columns present
+  - Correct types and constraints
+  - CHECK constraint on complexity
+- Indexes
+  - idx_config_node_type_rank
+  - idx_config_complexity
+  - idx_config_auth
+- View: ranked_node_configs
+  - Top 5 per node_type
+  - Correct ordering
+- Foreign key constraints
+  - CASCADE delete
+  - Referential integrity
+- Data operations
+  - INSERT with all fields
+  - Nullable fields
+  - Rank updates
+  - Delete rank > 10
+- Performance
+  - 1000 records < 10ms queries
+- Migration idempotency
+
+**Test Count:** 19 tests
+**Expected Coverage:** 95%+
+
+---
+
+#### 5. `/tests/integration/mcp/template-examples-e2e.test.ts` ✅
+**Purpose:** End-to-end integration testing
+
+**Coverage:**
+- Direct SQL queries
+  - Top 2 examples for search_nodes
+  - Top 3 examples with metadata for get_node_essentials
+- Data structure validation
+  - Valid JSON in all fields
+  - Credentials when has_credentials=1
+- Ranked view functionality
+- Performance with 100+ configs
+  - Query performance < 5ms
+  - Complexity filtering
+- Edge cases
+  - Non-existent node types
+  - Long parameters_json (100 params)
+  - Special characters (Unicode, emojis, symbols)
+- Data integrity
+  - Foreign key constraints
+  - Cascade deletes
+
+**Test Count:** 14 tests
+**Expected Coverage:** 90%+
+
+---
+
+### Test Fixtures
+
+#### 6. `/tests/fixtures/template-configs.ts` ✅
+**Purpose:** Reusable test data
+
+**Provides:**
+- `sampleConfigs`: 7 realistic node configurations
+  - simpleWebhook
+  - webhookWithAuth
+  - httpRequestBasic
+  - httpRequestWithExpressions
+  - slackMessage
+  - codeNodeTransform
+  - codeNodeWithExpressions
+
+- `sampleWorkflows`: 3 complete workflows
+  - webhookToSlack
+  - apiWorkflow
+  - complexWorkflow
+
+- **Helper Functions:**
+  - `compressWorkflow()` - Compress to base64
+  - `createTemplateMetadata()` - Generate metadata
+  - `createConfigBatch()` - Batch create configs
+  - `getConfigByComplexity()` - Filter by complexity
+  - `getConfigsWithExpressions()` - Filter with expressions
+  - `getConfigsWithCredentials()` - Filter with credentials
+  - `createInsertStatement()` - SQL insert helper
+
+---
+
+## Existing Tests Requiring Updates
+
+### High Priority
+
+#### 1. `tests/unit/mcp/parameter-validation.test.ts`
+**Line 480:** Remove `get_node_for_task` from legacyValidationTools array
+
+```typescript
+// REMOVE THIS:
+{ name: 'get_node_for_task', args: {}, expected: 'Missing required parameters for get_node_for_task: task' },
+```
+
+**Status:** ⚠️ BREAKING CHANGE - Tool removed
+
+---
+
+#### 2. `tests/unit/mcp/tools.test.ts`
+**Update:** Remove `get_node_for_task` from templates category
+
+```typescript
+// BEFORE:
+templates: ['list_tasks', 'get_node_for_task', 'search_templates', ...]
+
+// AFTER:
+templates: ['list_tasks', 'search_templates', ...]
+```
+
+**Add:** Tests for new includeExamples parameter in tool definitions
+
+```typescript
+it('should have includeExamples parameter in search_nodes', () => {
+  const searchNodesTool = tools.find(t => t.name === 'search_nodes');
+  expect(searchNodesTool.inputSchema.properties.includeExamples).toBeDefined();
+  expect(searchNodesTool.inputSchema.properties.includeExamples.type).toBe('boolean');
+  expect(searchNodesTool.inputSchema.properties.includeExamples.default).toBe(false);
+});
+
+it('should have includeExamples parameter in get_node_essentials', () => {
+  const essentialsTool = tools.find(t => t.name === 'get_node_essentials');
+  expect(essentialsTool.inputSchema.properties.includeExamples).toBeDefined();
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+#### 3. `tests/integration/mcp-protocol/session-management.test.ts`
+**Remove:** Test case calling `get_node_for_task` with invalid task
+
+```typescript
+// REMOVE THIS TEST:
+client.callTool({ name: 'get_node_for_task', arguments: { task: 'invalid_task' } }).catch(e => e)
+```
+
+**Status:** ⚠️ BREAKING CHANGE
+
+---
+
+#### 4. `tests/integration/mcp-protocol/tool-invocation.test.ts`
+**Remove:** Entire `get_node_for_task` describe block
+
+**Add:** Tests for new includeExamples functionality
+
+```typescript
+describe('search_nodes with includeExamples', () => {
+  it('should return examples when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: true }
+    });
+
+    expect(response.results).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+
+  it('should not return examples when includeExamples is false', async () => {
+    const response = await client.callTool({
+      name: 'search_nodes',
+      arguments: { query: 'webhook', includeExamples: false }
+    });
+
+    expect(response.results).toBeDefined();
+    response.results.forEach(node => {
+      expect(node.examples).toBeUndefined();
+    });
+  });
+});
+
+describe('get_node_essentials with includeExamples', () => {
+  it('should return examples with metadata when includeExamples is true', async () => {
+    const response = await client.callTool({
+      name: 'get_node_essentials',
+      arguments: { nodeType: 'nodes-base.webhook', includeExamples: true }
+    });
+
+    expect(response.nodeType).toBeDefined();
+    // Examples may or may not be present depending on database
+  });
+});
+```
+
+**Status:** ⚠️ REQUIRED UPDATE
+
+---
+
+### Medium Priority
+
+#### 5. `tests/unit/services/task-templates.test.ts`
+**Status:** ✅ No changes needed (TaskTemplates marked as deprecated but not removed)
+
+**Note:** TaskTemplates remains for backward compatibility. Tests should continue to pass.
+
+---
+
+## Test Execution Plan
+
+### Phase 1: Unit Tests
+```bash
+# Run new unit tests
+npm test tests/unit/scripts/fetch-templates-extraction.test.ts
+npm test tests/unit/mcp/search-nodes-examples.test.ts
+npm test tests/unit/mcp/get-node-essentials-examples.test.ts
+
+# Expected: All pass, 52 tests
+```
+
+### Phase 2: Integration Tests
+```bash
+# Run new integration tests
+npm test tests/integration/database/template-node-configs.test.ts
+npm test tests/integration/mcp/template-examples-e2e.test.ts
+
+# Expected: All pass, 33 tests
+```
+
+### Phase 3: Update Existing Tests
+```bash
+# Update files as outlined above, then run:
+npm test tests/unit/mcp/parameter-validation.test.ts
+npm test tests/unit/mcp/tools.test.ts
+npm test tests/integration/mcp-protocol/session-management.test.ts
+npm test tests/integration/mcp-protocol/tool-invocation.test.ts
+
+# Expected: All pass after updates
+```
+
+### Phase 4: Full Test Suite
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Expected coverage improvements:
+# - src/scripts/fetch-templates.ts: +20% (60% → 80%)
+# - src/mcp/server.ts: +5% (75% → 80%)
+# - Overall project: +2% (current → current+2%)
+```
+
+---
+
+## Coverage Expectations
+
+### New Code Coverage
+
+| File | Function | Target | Tests |
+|------|----------|--------|-------|
+| fetch-templates.ts | extractNodeConfigs | 95% | 15 tests |
+| fetch-templates.ts | detectExpressions | 100% | 12 tests |
+| server.ts | searchNodes (with examples) | 90% | 8 tests |
+| server.ts | getNodeEssentials (with examples) | 90% | 10 tests |
+| Database migration | template_node_configs | 100% | 19 tests |
+
+### Overall Coverage Goals
+
+- **Unit Tests:** 90%+ coverage for new code
+- **Integration Tests:** All happy paths + critical error paths
+- **E2E Tests:** Complete feature workflows
+- **Performance:** All queries <10ms (database), <100ms (MCP)
+
+---
+
+## Test Infrastructure
+
+### Dependencies Required
+All dependencies already present in `package.json`:
+- vitest (test runner)
+- better-sqlite3 (database)
+- @vitest/coverage-v8 (coverage)
+
+### Test Utilities Used
+- TestDatabase helper (from existing test utils)
+- createTestDatabaseAdapter (from existing test utils)
+- Standard vitest matchers
+
+### No New Dependencies Required ✅
+
+---
+
+## Regression Prevention
+
+### Critical Paths Protected
+
+1. **Backward Compatibility**
+   - Tools work without includeExamples parameter
+   - Existing workflows unchanged
+   - Cache keys differentiated
+
+2. **Performance**
+   - No degradation when includeExamples=false
+   - Indexed queries <10ms
+   - Example fetch errors don't break responses
+
+3. **Data Integrity**
+   - Foreign key constraints enforced
+   - JSON validation in all fields
+   - Rank calculations correct
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Updates
+No changes required. Existing test commands will run new tests:
+
+```yaml
+- run: npm test
+- run: npm run test:coverage
+```
+
+### Coverage Thresholds
+Current thresholds maintained. Expected improvements:
+- Lines: +2%
+- Functions: +3%
+- Branches: +2%
+
+---
+
+## Manual Testing Checklist
+
+### Pre-Deployment Verification
+
+- [ ] Run `npm run rebuild` - Verify migration applies cleanly
+- [ ] Run `npm run fetch:templates --extract-only` - Verify extraction works
+- [ ] Check database: `SELECT COUNT(*) FROM template_node_configs` - Should be ~197
+- [ ] Test MCP tool: `search_nodes({query: "webhook", includeExamples: true})`
+- [ ] Test MCP tool: `get_node_essentials({nodeType: "nodes-base.webhook", includeExamples: true})`
+- [ ] Verify backward compatibility: Tools work without includeExamples parameter
+- [ ] Performance test: Query 100 nodes with examples < 200ms
+
+---
+
+## Rollback Plan
+
+If issues are detected:
+
+1. **Database Rollback:**
+   ```sql
+   DROP TABLE IF EXISTS template_node_configs;
+   DROP VIEW IF EXISTS ranked_node_configs;
+   ```
+
+2. **Code Rollback:**
+   - Revert server.ts changes
+   - Revert tools.ts changes
+   - Restore get_node_for_task tool (if critical)
+
+3. **Test Rollback:**
+   - Revert parameter-validation.test.ts
+   - Revert tools.test.ts
+   - Revert tool-invocation.test.ts
+
+---
+
+## Success Metrics
+
+### Test Metrics
+- ✅ 85+ new tests added
+- ✅ 0 tests failing after updates
+- ✅ Coverage increase 2%+
+- ✅ All performance tests pass
+
+### Feature Metrics
+- ✅ 197 template configs extracted
+- ✅ Top 2/3 examples returned correctly
+- ✅ Query performance <10ms
+- ✅ No backward compatibility breaks
+
+---
+
+## Conclusion
+
+This test plan provides **comprehensive coverage** for the P0-R3 feature with:
+- **85+ new tests** across unit, integration, and E2E levels
+- **Complete coverage** of extraction, storage, and retrieval
+- **Backward compatibility** protection
+- **Performance validation** (<10ms queries)
+- **Clear migration path** for existing tests
+
+**All test files are ready for execution.** Update the 4 existing test files as outlined, then run the full test suite.
+
+**Estimated Total Implementation Time:** 2-3 hours for updating existing tests + validation

PRIVACY.md

@@ -0,0 +1,86 @@
+# Privacy Policy for n8n-mcp Telemetry
+
+## Overview
+n8n-mcp collects anonymous usage statistics to help improve the tool. This data collection is designed to respect user privacy while providing valuable insights into how the tool is used.
+
+## What We Collect
+- **Anonymous User ID**: A hashed identifier derived from your machine characteristics (no personal information)
+- **Tool Usage**: Which MCP tools are used and their performance metrics
+- **Workflow Patterns**: Sanitized workflow structures (all sensitive data removed)
+- **Error Types**: Categories of errors encountered (no error messages with user data)
+- **System Information**: Platform, architecture, Node.js version, and n8n-mcp version
+
+## What We DON'T Collect
+- Personal information or usernames
+- API keys, tokens, or credentials
+- URLs, endpoints, or hostnames
+- Email addresses or contact information
+- File paths or directory structures
+- Actual workflow data or parameters
+- Database connection strings
+- Any authentication information
+
+## Data Sanitization
+All collected data undergoes automatic sanitization:
+- URLs are replaced with `[URL]` or `[REDACTED]`
+- Long alphanumeric strings (potential keys) are replaced with `[KEY]`
+- Email addresses are replaced with `[EMAIL]`
+- Authentication-related fields are completely removed
+
+## Data Storage
+- Data is stored securely using Supabase
+- Anonymous users have write-only access (cannot read data back)
+- Row Level Security (RLS) policies prevent data access by anonymous users
+
+## Opt-Out
+You can disable telemetry at any time:
+
+**npx:**
+```bash
+npx n8n-mcp telemetry disable
+```
+
+**Docker:**
+```
+-e N8N_MCP_TELEMETRY_DISABLED=true
+```
+
+**docker-compose:**
+```yaml
+environment:
+  N8N_MCP_TELEMETRY_DISABLED: "true"
+```
+
+To re-enable:
+```bash
+npx n8n-mcp telemetry enable
+```
+
+To check status:
+```bash
+npx n8n-mcp telemetry status
+```
+
+## Data Usage
+Collected data is used solely to:
+- Understand which features are most used
+- Identify common error patterns
+- Improve tool performance and reliability
+- Guide development priorities
+- Train machine learning models for workflow generation
+
+All ML training uses sanitized, anonymized data only.
+Users can opt-out at any time with `npx n8n-mcp telemetry disable`
+
+## Data Retention
+- Data is retained for analysis purposes
+- No personal identification is possible from the collected data
+
+## Changes to This Policy
+We may update this privacy policy from time to time. Updates will be reflected in this document.
+
+## Contact
+For questions about telemetry or privacy, please open an issue on GitHub:
+https://github.com/czlonkowski/n8n-mcp/issues
+
+Last updated: 2025-11-06

README.md

@@ -0,0 +1,453 @@
+# n8n-MCP
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
+[![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
+[![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
+[![Tests](https://img.shields.io/badge/tests-5418%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
+[![n8n version](https://img.shields.io/badge/n8n-2.29.7-orange.svg)](https://github.com/n8n-io/n8n)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)
+
+A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 2,150 workflow automation nodes (826 core + 1,324 community).
+
+## Overview
+
+n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:
+
+- **2,150 n8n nodes** - 826 core nodes + 1,324 community nodes (1,177 verified)
+- **Node properties** - 99% coverage with detailed schemas
+- **Node operations** - 63.6% coverage of available actions
+- **Documentation** - 87% coverage from official n8n docs (including AI nodes)
+- **AI tools** - 265 AI-capable tool variants detected with full documentation
+- **Real-world examples** - 156 ranked configurations extracted from popular templates
+- **Template library** - 2,352 workflow templates with 99.96% AI metadata coverage
+- **Community nodes** - Search verified community integrations with `source` filter
+
+## Support This Project
+
+<div align="center">
+  <a href="https://github.com/sponsors/czlonkowski">
+    <img src="https://img.shields.io/badge/Sponsor-❤️-db61a2?style=for-the-badge&logo=github-sponsors" alt="Sponsor n8n-mcp" />
+  </a>
+</div>
+
+**n8n-mcp** started as a personal tool but now helps tens of thousands of developers automate their workflows efficiently. Maintaining and developing this project competes with my paid work. Your sponsorship helps me dedicate focused time to new features, respond quickly to issues, keep documentation up-to-date, and ensure compatibility with latest n8n releases. **[Become a sponsor](https://github.com/sponsors/czlonkowski)**
+
+## Important Safety Warning
+
+**NEVER edit your production workflows directly with AI!** Always:
+- Make a copy of your workflow before using AI tools
+- Test in development environment first
+- Export backups of important workflows
+- Validate changes before deploying to production
+
+AI results can be unpredictable. Protect your work!
+
+## Quick Start
+
+**The fastest way to try n8n-MCP** - no installation, no configuration:
+
+**[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)**
+
+- Free tier: 100 tool calls/day
+- Instant access: Start building workflows immediately
+- Always up-to-date: Latest n8n nodes and templates
+- No infrastructure: We handle everything
+
+Just sign up, get your API key, and connect your MCP client.
+
+**Want to self-host?** See the [Self-Hosting Guide](./docs/SELF_HOSTING.md) for npx, Docker, Railway, and local installation options.
+
+## n8n Integration
+
+Want to use n8n-MCP with your n8n instance? Check out our comprehensive [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) for:
+- Local testing with the MCP Client Tool node
+- Production deployment with Docker Compose
+- Cloud deployment on Hetzner, AWS, and other providers
+- Troubleshooting and security best practices
+
+### Cloudflare Access Authentication
+
+If your n8n instance sits behind Cloudflare Access (Zero Trust), provide your service token so n8n-MCP can authenticate:
+
+- `N8N_CF_CLIENT_ID` - Cloudflare Access Client ID
+- `N8N_CF_CLIENT_SECRET` - Cloudflare Access Client Secret
+
+When set, these are sent as `CF-Access-Client-Id` / `CF-Access-Client-Secret` headers on n8n API requests, version/health probes, and webhook executions. The token is confined to the `N8N_API_URL` origin — webhook calls to a different host (e.g. a split `WEBHOOK_URL` origin) do not receive it, to avoid leaking the token.
+
+## Connect your IDE
+
+n8n-MCP works with multiple AI-powered IDEs and tools:
+
+- [Claude Code](./docs/CLAUDE_CODE_SETUP.md) - Quick setup for Claude Code CLI
+- [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md) - VS Code with GitHub Copilot integration
+- [Cursor](./docs/CURSOR_SETUP.md) - Step-by-step Cursor IDE setup
+- [Windsurf](./docs/WINDSURF_SETUP.md) - Windsurf integration with project rules
+- [Codex](./docs/CODEX_SETUP.md) - Codex integration guide
+- [Antigravity](./docs/ANTIGRAVITY_SETUP.md) - Antigravity integration guide
+
+## Add Claude Skills (Optional)
+
+Supercharge your n8n workflow building with specialized skills that teach AI how to build production-ready workflows!
+
+[![n8n-mcp Skills Setup](./docs/img/skills.png)](https://www.youtube.com/watch?v=e6VvRqmUY2Y)
+
+Learn more: [n8n-skills repository](https://github.com/czlonkowski/n8n-skills)
+
+## Claude Project Setup
+
+For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
+
+````markdown
+You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
+
+## Core Principles
+
+### 1. Silent Execution
+CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
+
+### 2. Parallel Execution
+When operations are independent, execute them in parallel for maximum performance.
+
+### 3. Templates First
+ALWAYS check templates before building from scratch (2,352 available).
+
+### 4. Multi-Level Validation
+Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.
+
+### 5. Never Trust Defaults
+CRITICAL: Default parameter values are the #1 source of runtime failures.
+ALWAYS explicitly configure ALL parameters that control node behavior.
+
+## Workflow Process
+
+1. **Start**: Call `tools_documentation()` for best practices
+
+2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
+   - `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering
+   - `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task
+   - `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword')
+   - `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type
+
+   **Filtering strategies**:
+   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
+   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
+   - By time: `maxSetupMinutes: 15` for quick wins
+   - By service: `requiredService: "openai"` for compatibility
+
+3. **Node Discovery** (if no suitable template - parallel execution)
+   - Think deeply about requirements. Ask clarifying questions if unclear.
+   - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
+   - `search_nodes({query: 'trigger'})` - Browse triggers
+   - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes
+
+4. **Configuration Phase** (parallel for multiple nodes)
+   - `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default)
+   - `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens)
+   - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens)
+   - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties
+   - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation
+   - Show workflow architecture to user for approval before proceeding
+
+5. **Validation Phase** (parallel for multiple nodes)
+   - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check
+   - `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
+   - Fix ALL errors before proceeding
+
+6. **Building Phase**
+   - If using template: `get_template(templateId, {mode: "full"})`
+   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
+   - Build from validated configurations
+   - EXPLICITLY set ALL parameters - never rely on defaults
+   - Connect nodes with proper structure
+   - Add error handling
+   - Use n8n expressions: $json, $node["NodeName"].json
+   - Build in artifact (unless deploying to n8n instance)
+
+7. **Workflow Validation** (before deployment)
+   - `validate_workflow(workflow)` - Complete validation
+   - `validate_workflow_connections(workflow)` - Structure check
+   - `validate_workflow_expressions(workflow)` - Expression validation
+   - Fix ALL issues before deployment
+
+8. **Deployment** (if n8n API configured)
+   - `n8n_create_workflow(workflow)` - Deploy
+   - `n8n_validate_workflow({id})` - Post-deployment check
+   - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
+   - `n8n_test_workflow({workflowId})` - Test workflow execution
+
+## Critical Warnings
+
+### Never Trust Defaults
+Default values cause runtime failures. Example:
+```json
+// FAILS at runtime
+{resource: "message", operation: "post", text: "Hello"}
+
+// WORKS - all parameters explicit
+{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
+```
+
+### Example Availability
+`includeExamples: true` returns real configurations from workflow templates.
+- Coverage varies by node popularity
+- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`
+
+## Validation Strategy
+
+### Level 1 - Quick Check (before building)
+`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms)
+
+### Level 2 - Comprehensive (before building)
+`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
+
+### Level 3 - Complete (after building)
+`validate_workflow(workflow)` - Connections, expressions, AI tools
+
+### Level 4 - Post-Deployment
+1. `n8n_validate_workflow({id})` - Validate deployed workflow
+2. `n8n_autofix_workflow({id})` - Auto-fix common errors
+3. `n8n_executions({action: 'list'})` - Monitor execution status
+
+## Response Format
+
+### Initial Creation
+```
+[Silent tool execution in parallel]
+
+Created workflow:
+- Webhook trigger → Slack notification
+- Configured: POST /webhook → #general channel
+
+Validation: All checks passed
+```
+
+### Modifications
+```
+[Silent tool execution]
+
+Updated workflow:
+- Added error handling to HTTP node
+- Fixed required Slack parameters
+
+Changes validated successfully.
+```
+
+## Batch Operations
+
+Use `n8n_update_partial_workflow` with multiple operations in a single call:
+
+GOOD - Batch multiple operations:
+```json
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [
+    {type: "updateNode", nodeId: "slack-1", changes: {...}},
+    {type: "updateNode", nodeId: "http-1", changes: {...}},
+    {type: "cleanStaleConnections"}
+  ]
+})
+```
+
+BAD - Separate calls:
+```json
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
+```
+
+### CRITICAL: addConnection Syntax
+
+The `addConnection` operation requires **four separate string parameters**. Common mistakes cause misleading errors.
+
+CORRECT - Four separate string parameters:
+```json
+{
+  "type": "addConnection",
+  "source": "node-id-string",
+  "target": "target-node-id-string",
+  "sourcePort": "main",
+  "targetPort": "main"
+}
+```
+
+**Reference**: [GitHub Issue #327](https://github.com/czlonkowski/n8n-mcp/issues/327)
+
+### CRITICAL: IF Node Multi-Output Routing
+
+IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** to route to the correct output:
+
+```json
+n8n_update_partial_workflow({
+  id: "workflow-id",
+  operations: [
+    {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
+    {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
+  ]
+})
+```
+
+**Note**: Without the `branch` parameter, both connections may end up on the same output, causing logic errors!
+
+### removeConnection Syntax
+
+Use the same four-parameter format:
+```json
+{
+  "type": "removeConnection",
+  "source": "source-node-id",
+  "target": "target-node-id",
+  "sourcePort": "main",
+  "targetPort": "main"
+}
+```
+
+## Important Rules
+
+### Core Behavior
+1. **Silent execution** - No commentary between tools
+2. **Parallel by default** - Execute independent operations simultaneously
+3. **Templates first** - Always check before building (2,352 available)
+4. **Multi-level validation** - Quick check → Full validation → Workflow validation
+5. **Never trust defaults** - Explicitly configure ALL parameters
+
+### Attribution & Credits
+- **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link
+- **Template validation** - Always validate before deployment (may need updates)
+
+### Code Node Usage
+- **Avoid when possible** - Prefer standard nodes
+- **Only when necessary** - Use code node as last resort
+- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
+
+### Most Popular n8n Nodes (for get_node):
+
+1. **n8n-nodes-base.code** - JavaScript/Python scripting
+2. **n8n-nodes-base.httpRequest** - HTTP API calls
+3. **n8n-nodes-base.webhook** - Event-driven triggers
+4. **n8n-nodes-base.set** - Data transformation
+5. **n8n-nodes-base.if** - Conditional routing
+6. **n8n-nodes-base.manualTrigger** - Manual workflow execution
+7. **n8n-nodes-base.respondToWebhook** - Webhook responses
+8. **n8n-nodes-base.scheduleTrigger** - Time-based triggers
+9. **@n8n/n8n-nodes-langchain.agent** - AI agents
+10. **n8n-nodes-base.googleSheets** - Spreadsheet integration
+11. **n8n-nodes-base.merge** - Data merging
+12. **n8n-nodes-base.switch** - Multi-branch routing
+13. **n8n-nodes-base.telegram** - Telegram bot integration
+14. **@n8n/n8n-nodes-langchain.lmChatOpenAi** - OpenAI chat models
+15. **n8n-nodes-base.splitInBatches** - Batch processing
+16. **n8n-nodes-base.openAi** - OpenAI legacy node
+17. **n8n-nodes-base.gmail** - Email automation
+18. **n8n-nodes-base.function** - Custom functions
+19. **n8n-nodes-base.stickyNote** - Workflow documentation
+20. **n8n-nodes-base.executeWorkflowTrigger** - Sub-workflow calls
+
+**Note:** LangChain nodes use the `@n8n/n8n-nodes-langchain.` prefix, core nodes use `n8n-nodes-base.`
+
+````
+
+Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
+
+## Available MCP Tools
+
+### Core Tools (7 tools)
+- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
+- **`search_nodes`** - Full-text search across all nodes. Use `source: 'community'|'verified'` for community nodes, `includeExamples: true` for configs
+- **`get_node`** - Unified node information tool with multiple modes:
+  - **Info mode** (default): `detail: 'minimal'|'standard'|'full'`, `includeExamples: true`
+  - **Docs mode**: `mode: 'docs'` - Human-readable markdown documentation
+  - **Property search**: `mode: 'search_properties'`, `propertyQuery: 'auth'`
+  - **Versions**: `mode: 'versions'|'compare'|'breaking'|'migrations'`
+- **`validate_node`** - Unified node validation:
+  - `mode: 'minimal'` - Quick required fields check (<100ms)
+  - `mode: 'full'` - Comprehensive validation with profiles (minimal, runtime, ai-friendly, strict)
+- **`validate_workflow`** - Complete workflow validation including AI Agent validation
+- **`search_templates`** - Unified template search:
+  - `searchMode: 'keyword'` (default) - Text search with `query` parameter
+  - `searchMode: 'by_nodes'` - Find templates using specific `nodeTypes`
+  - `searchMode: 'by_task'` - Curated templates for common `task` types
+  - `searchMode: 'by_metadata'` - Filter by `complexity`, `requiredService`, `targetAudience`
+- **`get_template`** - Get complete workflow JSON (modes: nodes_only, structure, full)
+
+### n8n Management Tools (16 tools - Requires API Configuration)
+These tools require `N8N_API_URL` and `N8N_API_KEY` in your configuration.
+
+#### Workflow Management
+- **`n8n_create_workflow`** - Create new workflows with nodes and connections
+- **`n8n_get_workflow`** - Unified workflow retrieval (modes: full, details, structure, minimal)
+- **`n8n_update_full_workflow`** - Update entire workflow (complete replacement)
+- **`n8n_update_partial_workflow`** - Update workflow using diff operations
+- **`n8n_delete_workflow`** - Delete workflows permanently
+- **`n8n_list_workflows`** - List workflows with filtering and pagination
+- **`n8n_validate_workflow`** - Validate workflows in n8n by ID
+- **`n8n_autofix_workflow`** - Automatically fix common workflow errors
+- **`n8n_workflow_versions`** - Manage version history and rollback
+- **`n8n_deploy_template`** - Deploy templates from n8n.io directly to your instance with auto-fix
+
+#### Execution Management
+- **`n8n_test_workflow`** - Test/trigger workflow execution (webhook, form, chat)
+- **`n8n_executions`** - Unified execution management (list, get, delete)
+
+#### Data Table Management
+- **`n8n_manage_datatable`** - Manage n8n data tables and rows (list, get, create, update, delete)
+
+#### Credential Management
+- **`n8n_manage_credentials`** - Manage n8n credentials (list, get, create, update, delete, getSchema)
+
+#### Security & Audit
+- **`n8n_audit_instance`** - Security audit combining n8n's built-in audit API with deep workflow scanning
+
+#### System Tools
+- **`n8n_health_check`** - Check n8n API connectivity and features
+
+### Read-Only Deployment
+
+For governance-sensitive environments, use both env vars together. Fully disable tools that are write/destructive or handle sensitive data (`n8n_manage_credentials` and `n8n_manage_datatable` also offer read operations, but are removed entirely here because even reads expose sensitive material):
+
+```bash
+DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable
+```
+
+For tools that bundle read and write operations under one name, block only the destructive operations while keeping `list` and `get`:
+
+```bash
+DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete
+```
+
+Combine with a read-only n8n API key (Settings → API in your n8n instance) for defence in depth. See [Read-Only Deployment Recipe](./docs/HTTP_DEPLOYMENT.md#read-only-deployment-recipe) for the full setup guide.
+
+## Documentation
+
+- [Self-Hosting Guide](./docs/SELF_HOSTING.md) - npx, Docker, Railway, and local installation
+- [Security & Hardening](./docs/SECURITY_HARDENING.md) - Trust model, hardening options, workflow restrictions
+- [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) - Production deployment with n8n
+- [Database Configuration](./docs/DATABASE_CONFIGURATION.md) - SQLite adapters and memory optimization
+- [Privacy & Telemetry](./PRIVACY.md) - What we collect and how to opt out
+- [Workflow Diff Operations](./docs/workflow-diff-examples.md) - Token-efficient workflow updates
+- [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - Remote server setup
+- [Change Log](./CHANGELOG.md) - Complete version history
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
+
+## Acknowledgments
+
+See [Acknowledgments](./docs/ACKNOWLEDGMENTS.md) for credits and template attribution.
+
+---
+
+<div align="center">
+  <strong>Built with care for the n8n community</strong>
+</div>
+
+---
+
+> 💼 **Need it built for you?**
+>
+> Work with [AiAdvisors](https://www.aiadvisors.pl/en) — automation audits, builds, and operations by the team behind n8n-mcp and n8n-skills.

README.wehub.md

@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`czlonkowski/n8n-mcp`
+- 原始仓库：https://github.com/czlonkowski/n8n-mcp
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者

README_ANALYSIS.md

@@ -0,0 +1,318 @@
+# N8N-MCP Validation Analysis: Complete Report
+
+**Date**: November 8, 2025
+**Dataset**: 29,218 validation events | 9,021 unique users | 90 days
+**Status**: Complete and ready for action
+
+---
+
+## Analysis Documents
+
+### 1. ANALYSIS_QUICK_REFERENCE.md (5.8KB)
+**Best for**: Quick decisions, meetings, slide presentations
+
+START HERE if you want the key points in 5 minutes.
+
+**Contains**:
+- One-paragraph core finding
+- Top 3 problem areas with root causes
+- 5 most common errors
+- Implementation plan summary
+- Key metrics & targets
+- FAQ section
+
+---
+
+### 2. VALIDATION_ANALYSIS_SUMMARY.md (13KB)
+**Best for**: Executive stakeholders, team leads, decision makers
+
+Read this for comprehensive but concise overview.
+
+**Contains**:
+- One-page executive summary
+- Health scorecard with key metrics
+- Detailed problem area breakdown
+- Error category distribution
+- Agent behavior insights
+- Tool usage patterns
+- Documentation impact findings
+- Top 5 recommendations with ROI estimates
+- 50-65% improvement projection
+
+---
+
+### 3. VALIDATION_ANALYSIS_REPORT.md (27KB)
+**Best for**: Technical deep-dive, implementation planning, root cause analysis
+
+Complete reference document with all findings.
+
+**Contains**:
+- All 16 SQL queries (reproducible)
+- Node-specific difficulty ranking (top 20)
+- Top 25 unique validation error messages
+- Error categorization with root causes
+- Tool usage patterns before failures
+- Search query analysis
+- Documentation effectiveness study
+- Retry success rate analysis
+- Property-level difficulty matrix
+- 8 detailed recommendations with implementation guides
+- Phase-by-phase action items
+- KPI tracking setup
+- Complete appendix with error message reference
+
+---
+
+### 4. IMPLEMENTATION_ROADMAP.md (4.3KB)
+**Best for**: Project managers, development team, sprint planning
+
+Actionable roadmap for the next 6 weeks.
+
+**Contains**:
+- Phase 1-3 breakdown (2 weeks each)
+- Specific file locations to modify
+- Effort estimates per task
+- Success criteria for each phase
+- Expected impact projections
+- Code examples (before/after)
+- Key changes documentation
+
+---
+
+## Reading Paths
+
+### Path A: Decision Maker (30 minutes)
+1. Read: ANALYSIS_QUICK_REFERENCE.md
+2. Review: Key metrics in VALIDATION_ANALYSIS_SUMMARY.md
+3. Decision: Approve IMPLEMENTATION_ROADMAP.md
+
+### Path B: Product Manager (1 hour)
+1. Read: VALIDATION_ANALYSIS_SUMMARY.md
+2. Skim: Top recommendations in VALIDATION_ANALYSIS_REPORT.md
+3. Review: IMPLEMENTATION_ROADMAP.md
+4. Check: Success metrics and timelines
+
+### Path C: Technical Lead (2-3 hours)
+1. Read: ANALYSIS_QUICK_REFERENCE.md
+2. Deep-dive: VALIDATION_ANALYSIS_REPORT.md
+3. Study: IMPLEMENTATION_ROADMAP.md
+4. Review: Code examples and SQL queries
+5. Plan: Ticket creation and sprint allocation
+
+### Path D: Developer (3-4 hours)
+1. Skim: ANALYSIS_QUICK_REFERENCE.md for context
+2. Read: VALIDATION_ANALYSIS_REPORT.md sections 3-8
+3. Study: IMPLEMENTATION_ROADMAP.md thoroughly
+4. Review: All code locations and examples
+5. Plan: First task implementation
+
+---
+
+## Key Findings Overview
+
+### The Core Insight
+Validation failures are NOT broken—they're evidence the system works perfectly. 29,218 validation events prevented bad deployments. The challenge is GUIDANCE GAPS that cause first-attempt failures.
+
+### Success Evidence
+- 100% same-day error recovery rate
+- 100% retry success rate
+- All agents fix errors when given feedback
+- Zero "unfixable" errors
+
+### Problem Areas (75% of errors)
+1. **Workflow structure** (26%) - JSON malformation
+2. **Connections** (14%) - Unintuitive syntax
+3. **Required fields** (8%) - Not marked upfront
+
+### Most Problematic Nodes
+- Webhook/Trigger (127 failures)
+- Slack (73 failures)
+- AI Agent (36 failures)
+- HTTP Request (31 failures)
+- OpenAI (35 failures)
+
+### Solution Strategy
+- Phase 1: Better error messages + required field markers (25-30% reduction)
+- Phase 2: Documentation + validation improvements (additional 15-20%)
+- Phase 3: Advanced features + monitoring (additional 10-15%)
+- **Target**: 50-65% total failure reduction in 6 weeks
+
+---
+
+## Critical Numbers
+
+```
+Validation Events ............. 29,218
+Unique Users .................. 9,021
+Data Quality .................. 100% (all marked as errors)
+
+Current Metrics:
+  Error Rate (doc users) ....... 12.6%
+  Error Rate (non-doc users) ... 10.8%
+  First-attempt success ........ ~77%
+  Retry success ................ 100%
+  Same-day recovery ............ 100%
+
+Target Metrics (after 6 weeks):
+  Error Rate ................... 6-7% (-50%)
+  First-attempt success ........ 85%+
+  Retry success ................ 100%
+  Implementation effort ........ 60-80 hours
+```
+
+---
+
+## Implementation Timeline
+
+```
+Week 1-2:   Phase 1 (Error messages, field markers, webhook guide)
+            Expected: 25-30% failure reduction
+
+Week 3-4:   Phase 2 (Enum suggestions, connection guide, AI validation)
+            Expected: Additional 15-20% reduction
+
+Week 5-6:   Phase 3 (Search improvements, fuzzy matching, KPI setup)
+            Expected: Additional 10-15% reduction
+
+Target:     50-65% total reduction by Week 6
+```
+
+---
+
+## How to Use These Documents
+
+### For Review & Approval
+1. Start with ANALYSIS_QUICK_REFERENCE.md
+2. Check key metrics in VALIDATION_ANALYSIS_SUMMARY.md
+3. Review IMPLEMENTATION_ROADMAP.md for feasibility
+4. Decision: Approve phase 1-3
+
+### For Team Planning
+1. Read IMPLEMENTATION_ROADMAP.md
+2. Create GitHub issues from each task
+3. Assign based on effort estimates
+4. Schedule sprints for phase 1-3
+
+### For Development
+1. Review specific recommendations in VALIDATION_ANALYSIS_REPORT.md
+2. Find code locations in IMPLEMENTATION_ROADMAP.md
+3. Study code examples (before/after)
+4. Implement and test
+
+### For Measurement
+1. Record baseline metrics (current state)
+2. Deploy Phase 1 and measure impact
+3. Use KPI queries from VALIDATION_ANALYSIS_REPORT.md
+4. Adjust strategy based on actual results
+
+---
+
+## Key Recommendations (Priority Order)
+
+### IMMEDIATE (Week 1-2)
+1. **Enhance error messages** - Add location + examples
+2. **Mark required fields** - Add "⚠️ REQUIRED" to tools
+3. **Create webhook guide** - Document configuration rules
+
+### HIGH (Week 3-4)
+4. **Add enum suggestions** - Show valid values in errors
+5. **Create connections guide** - Document syntax + examples
+6. **Add AI Agent validation** - Detect missing LLM connections
+
+### MEDIUM (Week 5-6)
+7. **Improve search results** - Add configuration hints
+8. **Build fuzzy matcher** - Suggest similar node types
+9. **Setup KPI tracking** - Monitor improvement
+
+---
+
+## Questions & Answers
+
+**Q: Why so many validation failures?**
+A: High usage (9,021 users, complex workflows). System is working—preventing bad deployments.
+
+**Q: Shouldn't we just allow invalid configurations?**
+A: No, validation prevents 29,218 broken workflows from deploying. We improve guidance instead.
+
+**Q: Do agents actually learn from errors?**
+A: Yes, 100% same-day recovery rate proves feedback works perfectly.
+
+**Q: Can we really reduce failures by 50-65%?**
+A: Yes, analysis shows these specific improvements target the actual root causes.
+
+**Q: How long will this take?**
+A: 60-80 developer-hours across 6 weeks. Can start immediately.
+
+**Q: What's the biggest win?**
+A: Marking required fields (378 errors) + better structure messages (1,268 errors).
+
+---
+
+## Next Steps
+
+1. **This Week**: Review all documents and get approval
+2. **Week 1**: Create GitHub issues from IMPLEMENTATION_ROADMAP.md
+3. **Week 2**: Assign to team, start Phase 1
+4. **Week 4**: Deploy Phase 1, start Phase 2
+5. **Week 6**: Deploy Phase 2, start Phase 3
+6. **Week 8**: Deploy Phase 3, begin monitoring
+7. **Week 9+**: Review metrics, iterate
+
+---
+
+## File Structure
+
+```
+/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/
+├── ANALYSIS_QUICK_REFERENCE.md ............ Quick lookup (5.8KB)
+├── VALIDATION_ANALYSIS_SUMMARY.md ........ Executive summary (13KB)
+├── VALIDATION_ANALYSIS_REPORT.md ......... Complete analysis (27KB)
+├── IMPLEMENTATION_ROADMAP.md ............. Action plan (4.3KB)
+└── README_ANALYSIS.md ................... This file
+```
+
+**Total Documentation**: 50KB of analysis, recommendations, and implementation guidance
+
+---
+
+## Contact & Support
+
+For specific questions:
+- **Why?** → See VALIDATION_ANALYSIS_REPORT.md Section 2-8
+- **How?** → See IMPLEMENTATION_ROADMAP.md for code locations
+- **When?** → See IMPLEMENTATION_ROADMAP.md for timeline
+- **Metrics?** → See VALIDATION_ANALYSIS_SUMMARY.md key metrics section
+
+---
+
+## Metadata
+
+| Item | Value |
+|------|-------|
+| Analysis Date | November 8, 2025 |
+| Data Period | Sept 26 - Nov 8, 2025 (90 days) |
+| Sample Size | 29,218 validation events |
+| Users Analyzed | 9,021 unique users |
+| SQL Queries | 16 comprehensive queries |
+| Confidence Level | HIGH |
+| Status | Complete & Ready for Implementation |
+
+---
+
+## Analysis Methodology
+
+1. **Data Collection**: Extracted all validation_details events from PostgreSQL
+2. **Categorization**: Grouped errors by type, node, and message pattern
+3. **Pattern Analysis**: Identified root causes for each error category
+4. **User Behavior**: Tracked tool usage before/after failures
+5. **Recovery Analysis**: Measured success rates and correction time
+6. **Recommendation Development**: Mapped solutions to specific problems
+7. **Impact Projection**: Estimated improvement from each solution
+8. **Roadmap Creation**: Phased implementation plan with effort estimates
+
+**Data Quality**: 100% of validation events properly categorized, no data loss or corruption
+
+---
+
+**Analysis Complete** | **Ready for Review** | **Awaiting Approval to Proceed**
+

SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability in n8n-mcp, please report it through [GitHub's private vulnerability reporting](https://github.com/czlonkowski/n8n-mcp/security/advisories/new). Do not create public issues for security vulnerabilities.
+
+## Supported Versions
+
+Only the latest release receives security patches. We recommend always running the latest version.
+
+## Response Process
+
+1. We will acknowledge your report within 72 hours
+2. We will investigate and determine severity
+3. If confirmed, we will develop and release a fix
+4. We will credit reporters in the advisory (unless they prefer otherwise)
+
+For the full incident response process, see our [Incident Response Plan](.github/INCIDENT_RESPONSE.md).
+
+## Scope
+
+n8n-mcp is a proxy to the n8n REST API. The security boundary is n8n itself, not n8n-mcp. Reports about capabilities that are inherent to the n8n API (e.g., creating workflows with Code nodes) are out of scope, as n8n-mcp does not grant any capability beyond what the n8n API already provides.
+
+In-scope examples:
+- Authentication bypass in the MCP HTTP transport
+- Information disclosure (credential leaks, token exposure)
+- Injection vulnerabilities in n8n-mcp's own code
+- Dependency vulnerabilities with a viable exploit path
+
+Out-of-scope examples:
+- n8n platform capabilities accessible through any n8n API client
+- General LLM prompt injection risks (these affect all MCP servers equally)
+- Denial of service through normal API usage
+
+For deployment hardening guidance, see the [Security & Hardening guide](./docs/SECURITY_HARDENING.md). For the STRIDE threat model, see [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md).

_config.yml

@@ -0,0 +1,41 @@
+# Jekyll configuration for GitHub Pages
+# This is only used for serving benchmark results
+
+# Only process benchmark-related files
+include:
+  - index.html
+  - benchmarks/
+
+# Exclude everything else to prevent Liquid syntax errors
+exclude:
+  - "*.md"
+  - "*.json"
+  - "*.ts"
+  - "*.js"
+  - "*.yml"
+  - src/
+  - tests/
+  - docs/
+  - scripts/
+  - dist/
+  - node_modules/
+  - package.json
+  - package-lock.json
+  - tsconfig.json
+  - README.md
+  - CHANGELOG.md
+  - LICENSE
+  - Dockerfile*
+  - docker-compose*
+  - .github/
+  - .vscode/
+  - .claude/
+  - deploy/
+  - examples/
+  - data/
+
+# Disable Jekyll processing for files we don't want processed
+plugins: []
+
+# Use simple theme
+theme: null

codecov.yml

@@ -0,0 +1,53 @@
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+  status:
+    project:
+      default:
+        target: 80%
+        threshold: 1%
+        base: auto
+        if_not_found: success
+        if_ci_failed: error
+        informational: false
+        only_pulls: false
+    patch:
+      default:
+        target: 80%
+        threshold: 1%
+        base: auto
+        if_not_found: success
+        if_ci_failed: error
+        informational: true
+        only_pulls: false
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,files,footer"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+ignore:
+  - "node_modules/**/*"
+  - "dist/**/*"
+  - "tests/**/*"
+  - "scripts/**/*"
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "src/mcp/index.ts"
+  - "src/http-server.ts"
+  - "src/http-server-single-session.ts"

data/skills/n8n-agents/CHAT_AGENT_PATTERNS.md

@@ -0,0 +1,228 @@
+# Chat agent patterns: shell + core + sub-agents
+
+For external chat surfaces — Slack, Discord, Microsoft Teams, Telegram, embedded webhook chats. The building blocks (memory, tools, sub-workflow-as-tool, structured output) live in their own references; this file covers the **multi-workflow composition** production chat agents grow into, plus chat-surface gotchas the other refs don't.
+
+---
+
+## The one non-negotiable: anti-loop filtering
+
+**Any chat-triggered workflow that posts a reply MUST filter out the bot's own user ID right after the trigger, or it triggers itself forever** — every reply fires another run, until rate limits or n8n concurrency stop it (and it can take n8n down with it). That's the minimum bar for **every** bot, simple or complex.
+
+**Prefer trigger-level filtering when the trigger supports it** — the loop then breaks before any downstream node runs. Semantics differ per surface; verify against your version:
+
+- **Slack** (`n8n-nodes-base.slackTrigger`): `options.userIds` is an **exclusion list** — listed users are dropped before the workflow runs. Put the bot's user ID here. (Verified in the trigger source: it returns early `if (userIds.includes(event.user))`.)
+- **Telegram** (`n8n-nodes-base.telegramTrigger`): `additionalFields.userIds` is an **inclusion / allowlist** (only listed users fire). NOT a bot-exclusion filter — and Telegram bots don't see their own messages by default, so anti-loop usually isn't needed. Use the allowlist to restrict a private bot to specific humans.
+- **Discord, Teams**: no native user-level trigger filter — use the downstream Filter node.
+
+Slack trigger-level example:
+
+```json
+{
+  "parameters": {
+    "trigger": ["message"],
+    "channelId": { "__rl": true, "mode": "list", "value": "<CHANNEL_ID>" },
+    "options": { "userIds": "={{ [\"<BOT_USER_ID>\"] }}" }
+  },
+  "type": "n8n-nodes-base.slackTrigger"
+}
+```
+
+When the trigger doesn't expose a usable exclusion filter, the first node after the trigger must drop the bot's own ID:
+
+```json
+{
+  "parameters": {
+    "conditions": {
+      "conditions": [
+        {
+          "leftValue": "={{ $json.user }}",
+          "rightValue": "<BOT_USER_ID>",
+          "operator": { "type": "string", "operation": "notEquals" }
+        }
+      ]
+    }
+  },
+  "type": "n8n-nodes-base.filter"
+}
+```
+
+The bot user ID is the API ID from your bot's auth (Slack `bot_user_id`, Discord application ID, Teams `botId`).
+
+---
+
+## When to split into shell + core + sub-agents
+
+Beyond the anti-loop filter, a **simple bot (one trigger → one agent → one reply, with the filter)** lives fine in a single workflow. The shell + core + sub-agents split is for production robustness — it earns its keep once any of these is true:
+
+- The bot needs loading-state UX (typing indicator, reaction, placeholder) and graceful error handling beyond a single message.
+- It's invoked from more than one surface (Slack AND Discord).
+- There are specialist domains the agent shouldn't carry inline (Notion DB schema, CRM custom fields, Linear labels).
+- The agent or its tools will be reused across workflows.
+
+If none apply, keep it in one workflow (filter still in place). The shape when you do split:
+
+```
+[chat-surface workflow]  ──►  [agent core workflow]  ──►  [sub-agent workflows]
+("the shell")                 ("the brain")               ("specialists")
+
+- Trigger from the surface    - Stateless                 - One narrow domain each
+- Anti-loop filter            - chatInput + threadId       - chatInput only
+- Routing / event types       - Memory keyed on threadId   - Their own tools + model
+- Loading + error UX          - Tools, sub-agents
+- Render the reply            - No surface concerns
+```
+
+See **EXAMPLES.md** for a Slack router shell and a domain sub-agent snippet.
+
+---
+
+## The shell
+
+Receives chat events, decides whether to respond, manages UX, calls the core, renders the reply. No reasoning, no LLM.
+
+### Switch on event type
+
+The same trigger fires for messages, reactions, mentions, slash commands, button clicks. One Switch right after the anti-loop filter routes each to the right handler:
+
+```
+"owner message"            → Execute Workflow: agent-core
+"owner reaction"           → no-op (or a reaction handler)
+"unknown user"             → canned reply
+"slash command: /summary"  → Execute Workflow: summary-command
+"button click"             → Execute Workflow: interaction-handler
+```
+
+Each case is its own sub-workflow because the routing decision and the work are different concerns (different models, timeouts, memory shapes). Adding a slash command means one Switch output + one sub-workflow, not a new top-level trigger.
+
+Slack-specific notes (payload shapes evolve — verify against a live event before hardcoding paths): reactions/mentions flow through the Slack Trigger as Events API events; **slash commands and Block Kit button clicks generally don't** (Slack delivers those to separate Request URLs). Bring them in via a second Webhook node feeding the same Switch, or a community Socket Mode node. Slash commands expose a `command` field; Block Kit interactions arrive with `type === 'block_actions'` and an `actions` array.
+
+### Loading-state UX
+
+Users assume nothing is happening without acknowledgement. Pattern: **add a loading indicator before the agent call, remove it on every exit path — including error.**
+
+```
+[Trigger] → [Filter bot] → [Switch]
+   → (owner message)
+   → [Add loading reaction]                  (:spinner:, etc.)
+   → [Execute Workflow: Agent core]   onError: 'continueErrorOutput'
+        ├── (success) → [Remove reaction] → [Send reply]
+        └── (error)   → [Remove reaction] → [Send error message with link]
+```
+
+The error path is the easy one to forget — without it the indicator sits forever and the user thinks the bot is still working. `onError: 'continueErrorOutput'` on the Execute Workflow node enables the second branch (→ **n8n-error-handling**). For Discord/Telegram, typing indicators are time-bounded; for long agents send a placeholder message and edit it.
+
+### Threading as session continuity
+
+Use the surface's thread primitive as the memory `sessionKey`:
+
+```json
+"workflowInputs": {
+  "value": {
+    "chatInput": "={{ $('Filter bot').item.json.text }}",
+    "threadId":  "={{ $('Filter bot').item.json.thread_ts || $('Filter bot').item.json.ts }}"
+  }
+}
+```
+
+`thread_ts || ts` is the canonical Slack idiom: replies in a thread carry `thread_ts` (referencing the parent), the parent itself only has `ts`. Falling back to `ts` makes the parent message the session key for its thread, so each thread is a fresh conversation and memory doesn't leak across threads. **User ID, channel ID, or workspace ID alone are wrong — they cross conversations.** When sending the reply, target the same thread (`otherOptions.thread_ts.replyValues.thread_ts` = the same `thread_ts || ts`).
+
+### Error UX: surface, don't hang
+
+The error branch sends a short message with a link to the failed execution:
+
+```
+There was a workflow error. https://<n8n-host>/workflow/<id>/executions/{{ $execution.id }}
+```
+
+`$execution.id` is the live execution ID at the time the error fires. Parameterize the host across environments.
+
+---
+
+## The agent core
+
+A sub-workflow with two declared inputs: `chatInput` (the user's message) and `threadId` (the surface's thread/session ID). Returns the agent's final output — a string, a structured object, or a surface-specific envelope (Block Kit, adaptive card).
+
+The only chat-specific wiring beyond **MEMORY.md** is plumbing `threadId` straight to `sessionKey`:
+
+```json
+"sessionIdType": "customKey",
+"sessionKey": "={{ $json.threadId }}"
+```
+
+`threadId` flows trigger → (pass-through nodes) → memory. Don't put it behind `$fromAI`.
+
+Per-execution context (user identity, attached files) goes in a Set node before the agent and gets templated into the system prompt (→ **SYSTEM_PROMPT.md** "file-handling injection" and "piecing"). Don't add a Set node speculatively — inline in `systemMessage` is fine until reuse is real.
+
+**Block Kit / adaptive cards: pair the agent with `outputParserStructured`** (→ **STRUCTURED_OUTPUT.md**). The "use `schemaType: 'manual'` with a real JSON Schema" guidance applies even harder here: Block Kit and adaptive cards lean on `oneOf` union types across block kinds plus per-block enums (`style`, etc.) — `jsonSchemaExample` can't express any of it, and will produce confidently-wrong block trees the surface rejects.
+
+### Block Kit envelope gotcha (Slack)
+
+When the agent returns Block Kit and you post it via the Slack node's `blocksUi`, the value must be an object shaped `{ "blocks": [...] }` where the value is a **real array**, not the array alone and not a stringified one:
+
+```
+✅ ={{ { "blocks": $('Call Agent core').item.json.output.blocks } }}
+❌ ={{ $('Call Agent core').item.json.output.blocks }}
+```
+
+Passing only the array fails **silently** — the Slack node accepts the input, the message posts with no rich content, and there's no error or warning. → **n8n-node-configuration** `NODE_FAMILY_GOTCHAS.md` (Slack section).
+
+---
+
+## Sub-agents (an agent as a tool)
+
+A sub-agent is its own workflow with its own Agent node, called from the router agent via `.toolWorkflow`. Reach for one when:
+
+- The domain has a schema/enum set the router shouldn't carry (Notion DB properties, Linear labels, CRM fields).
+- The domain has 5+ tools that would clutter the router's tool list.
+- The capability is reused across more than one router.
+- The domain warrants a different (cheaper, faster) model than the router.
+
+**The contract is stateless.** The router sends the full request in `chatInput` — no shared memory, no implicit context. Reinforce it in both the tool description (router-side) AND the sub-agent's system prompt (callee-side):
+
+> IMPORTANT: This tool is stateless. Send all relevant context in a single message. If you need to create an entry, include ALL required fields upfront.
+
+Without that, the router assumes implicit context and the sub-agent guesses. Everything else about wiring sub-workflows as tools → **SUBWORKFLOW_AS_TOOL.md**.
+
+### Fresh schema injection
+
+When the domain schema can change at runtime (Notion DB options evolve, Linear teams add labels), refetch it on every sub-agent call instead of hardcoding it:
+
+```
+[Execute Workflow Trigger]
+   ↓
+[Notion: Get Database]                  # fetches the live schema
+   ↓
+[Agent]   system prompt template includes:
+   ## Database Schema
+   {{ $('Get a database').first().json.properties.toJsonString() }}
+```
+
+One extra API call per invocation; in exchange the sub-agent never returns "that property doesn't exist" because the prompt is stale. Worth it for low-volume chat assistants. For high-volume hot paths, cache the schema in a Data Table with a TTL.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | What goes wrong | Fix |
+|---|---|---|
+| No bot-user-ID filter at the top of the shell | Bot's own messages re-trigger the workflow — infinite loop | Trigger-level exclusion (Slack `options.userIds`) or a Filter on `$json.user !== '<BOT_USER_ID>'` first |
+| Bot ID in Telegram's `userIds` expecting exclusion | It's an **allowlist** — only the bot would fire, so no human gets through; looks "fixed" but is silent | Telegram bots don't see their own messages; use `userIds` only to allowlist humans |
+| Loading indicator removed only on success | User sees the bot stuck "thinking" forever after any error | `onError: 'continueErrorOutput'` + remove on both branches |
+| User/channel/workspace ID as the session key | Conversations cross threads in the same channel | Use the thread primitive (Slack `thread_ts || ts`) |
+| One workflow when multi-surface/sub-agent/reuse is already needed | Can't reuse, UX leaks into reasoning, hard to test in isolation | Split into shell + core + sub-agents (only once a need is real) |
+| Sub-agent that reads/writes shared memory | Caller can't reason about behavior, not safely retryable | Sub-agents are stateless — full context in `chatInput` |
+| Hardcoded domain schema in a sub-agent's prompt | Schema rots, sub-agent picks invalid options later | Re-fetch and template it at runtime |
+| Passing the bare blocks array to `blocksUi` | Slack posts an empty message, no error | Wrap as `{ "blocks": [...] }` with a real array |
+
+---
+
+## Cross-references
+
+- Tool naming, descriptions, `$fromAI` → **TOOLS.md**
+- The `.toolWorkflow` shape and parameter mapping → **SUBWORKFLOW_AS_TOOL.md**
+- Per-execution context, file injection, prompt storage → **SYSTEM_PROMPT.md**
+- Parser config, autoFix, fixer model → **STRUCTURED_OUTPUT.md**
+- Memory types, `sessionKey` persistence → **MEMORY.md**
+- `onError: 'continueErrorOutput'` and error UX → **n8n-error-handling**
+- Slack node parameter shapes (Block Kit) → **n8n-node-configuration** `NODE_FAMILY_GOTCHAS.md` (Slack section)
+- Receiving uploaded files / returning generated files per surface → **n8n-binary-and-data**

data/skills/n8n-agents/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**

data/skills/n8n-agents/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 |

data/skills/n8n-agents/MEMORY.md

@@ -0,0 +1,139 @@
+# Agent memory
+
+Memory is a sub-node on the agent, wired via `ai_memory`. Without it, every invocation is stateless. With it, the agent holds a conversation across turns — and across executions, depending on type — keyed by whatever expression you bind to `sessionKey`.
+
+Memory node availability shifts between n8n versions, so confirm what's installed with `search_nodes({ query: 'memory' })`.
+
+---
+
+## The two non-negotiables
+
+1. **Plumb a stable key through.** Memory buckets by whatever you bind to `sessionKey`. The Chat Trigger fills `sessionId` automatically. For other triggers, derive a stable identifier (Slack `thread_ts`, a webhook conversation ID, a generated UUID, a multi-tenant composite) and forward it to memory and any session-keyed tools. Without consistency across the same conversation, memory never matches.
+2. **Default to `memoryBufferWindow`.** It persists across executions via n8n's internal store, keyed on `sessionKey`, and is the right choice for nearly every chat agent. Reach for Postgres/Redis only when memory must be read **outside** the agent.
+
+---
+
+## The memory types
+
+### `memoryBufferWindow` (the default)
+
+In-context memory of the last N exchanges, persisted across executions via n8n's store.
+
+```json
+{
+  "parameters": {
+    "sessionIdType": "customKey",
+    "sessionKey": "={{ $json.sessionId }}",
+    "contextWindowLength": 50
+  },
+  "type": "@n8n/n8n-nodes-langchain.memoryBufferWindow",
+  "typeVersion": 1.3,
+  "name": "Simple Memory"
+}
+```
+
+`contextWindowLength` is the number of exchanges retained. **The default is 5 — very low** for modern chat expectations, where users assume a conversation feels close to endless. **50 is a reasonable starting point.** Higher = more context but more tokens per turn.
+
+**Messages past the window are removed entirely.** Once the buffer fills, the oldest exchanges are dropped and the agent can't recall, search, or even know they existed. If a user said something 60 turns ago and the window is 50, that's gone from the agent's perspective. For recall beyond the window, raise `contextWindowLength`, or persist key facts in a Data Table that's read and injected into the system prompt.
+
+The "window" is a sliding cap on how many messages stay in context — **not** a scope on persistence. With `sessionIdType: 'customKey'` you bind the key to any expression (`{{ $json.sessionId }}`, a Slack `thread_ts`, a multi-tenant composite). Each user/thread/context gets its own bucket.
+
+### `memoryPostgresChat` / `memoryRedisChat`
+
+Reach for these only when memory must be queried or read **outside** the agent: displaying conversation history in your own UI, analytics on past chats, sharing memory across systems, or migrating instances cleanly.
+
+```json
+{
+  "parameters": {
+    "sessionIdType": "customKey",
+    "sessionKey": "={{ $json.sessionId }}"
+  },
+  "type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
+  "typeVersion": 1.3,
+  "name": "Postgres Memory"
+}
+```
+
+**Wrong for** the default chat case — `memoryBufferWindow` already survives across executions and is the cleaner pick.
+
+---
+
+## Custom patterns (Chat Memory Manager)
+
+Most agents don't need this. But when a fixed window isn't enough, the `@n8n/n8n-nodes-langchain.memoryManager` node operates against any wired memory backend and exposes three modes:
+
+- **`load`** (default) — read current memory into the workflow (for inspection, branching on size, feeding a summarizer).
+- **`insert`** — append a message. An optional `hideFromUI` flag covers messages that should affect the agent but not show in the chat UI.
+- **`delete`** — remove some or all messages.
+
+### Pattern: rolling summarization
+
+When a conversation runs long and you want the gist of older turns instead of dropping them:
+
+1. After each turn, `load` the buffer.
+2. If it's approaching the cap, route to a summarizer (otherwise no-op).
+3. Summarize the older turns with an LLM.
+4. `delete` the buffer.
+5. `insert` the summary as one message, plus the most recent few turns for continuity.
+
+The agent now sees `[summary of turns 1-40] + [recent 5 turns]`, paying far fewer input tokens while keeping long-history context.
+
+Other patterns built the same way: **prune by relevance** (`load` → filter → `delete` → `insert` the keepers), **inject runtime facts** (`insert` with `hideFromUI: true`), **reset on command** (`delete` all on `/clear`).
+
+The Memory Manager node is more recent than the rest of n8n's memory tooling — verify the modes against your installed version before relying on them in production.
+
+---
+
+## Session ID handling by trigger
+
+### Chat Trigger
+Sets `sessionId` automatically. Wire it everywhere consistently:
+- Memory: `sessionKey: ={{ $('Chat Trigger').first().json.sessionId }}`
+- Tools: `sessionId: ={{ $('Chat Trigger').first().json.sessionId }}` (**NOT** through `$fromAI`)
+- Storage keying: derive bucket keys / filenames from `sessionId` for trivial per-session cleanup.
+
+### Webhook trigger
+You manage it: the caller passes a header or body field (`body.sessionId`) and you forward it, or you issue one on first call and expect it back. Either way, it must be consistent across the whole conversation, including reconnections.
+
+### Manual / scheduled
+Usually no session. Use a stable identifier per "conversation" if one exists (ticket ID, thread ID); otherwise memory adds nothing — omit it.
+
+---
+
+## Memory and tools
+
+When a tool is invoked, the tool's sub-workflow does **NOT** see conversation memory — memory is the agent's context, not the tool's input. Pass needed context through `$fromAI` parameters explicitly. For session-keyed state, plumb `sessionId` and have the tool look up state from a Data Table or storage keyed by session.
+
+---
+
+## Memory and binary
+
+Memory stores **text turns**. Binary uploaded mid-conversation is NOT in memory — it's in the Chat Trigger's `files[]` for that turn only. The text memory captures that "the user mentioned uploading a file," but to actually use the file in a later tool call it must still be in storage and its key must be in **that** turn's system prompt. In practice, inject the session's file inventory into the system prompt every turn (loaded by `sessionId`). → **n8n-binary-and-data**.
+
+---
+
+## Common mistakes
+
+- **Hardcoding `sessionId: 'default'`** — all conversations share one bucket; memory becomes meaningless.
+- **Different `sessionId` on memory vs tools** — memory looks right but tools can't find related state.
+- **Unbounded `memoryBuffer` for chat** — token cost grows until timeout. Use BufferWindow with a sane limit.
+- **Adding memory where there's no session** — a "summarize this article" workflow doesn't need it.
+- **Expecting tools to see memory** — they see only their `$fromAI` parameters and plumbed context.
+- **Drift between the surface and memory** — if anything posts to the conversation outside the agent (a scheduled reply, a human writing directly), the agent operates on an incomplete view and will contradict messages it can't see. Whatever shows on the user-facing surface must also be `insert`ed into memory.
+
+---
+
+## Operational notes
+
+- **Memory size drives token cost.** A 15-turn buffer of 200-token messages is 3000 tokens of input every turn before the user even speaks. Plan for it.
+- **Rate limits.** A model that hits a limit fails mid-conversation; memory holds everything until then, and the next turn resumes (assuming session-id continuity).
+- **Concurrent sessions.** Persistent backends key on `sessionId`, so concurrent conversations don't interfere. Verify with two simultaneous tests.
+
+---
+
+## Cross-references
+
+- Where the agent fits → parent **SKILL.md**
+- Passing session-keyed state into tools → **SUBWORKFLOW_AS_TOOL.md**
+- Threading-as-session on chat surfaces → **CHAT_AGENT_PATTERNS.md**
+- Session-keyed file storage → **n8n-binary-and-data**

data/skills/n8n-agents/RAG.md

@@ -0,0 +1,102 @@
+# RAG (retrieval augmented generation)
+
+RAG in n8n is built on the LangChain primitives — document loaders, text splitters, embeddings, vector stores, retrievers, rerankers. They wire onto agents and chains the same way models and memory do (via `ai_*` connections).
+
+This reference is intentionally **thin**. The pieces work, but opinionated end-to-end recipes ("which vector store, which chunking, when to rerank") depend heavily on data shape and scale. Verify defaults against current n8n docs and your team's choices.
+
+---
+
+## Before you go vector: rule out cheaper lookups
+
+Not every retrieval problem needs a vector store. Three cheaper alternatives to eliminate first:
+
+- **Database or Data Table for exact lookups.** "Look up customer X's record", "fetch issue #1234", "get rows where status = 'open'" are NOT RAG problems — use a query directly. → **n8n-node-configuration** for DB nodes.
+- **Live search for freshness.** Information not in anything you've indexed (current news, live API state, anything time-sensitive) wants a search tool (Tavily, etc.), not RAG.
+- **Grep/file-browse tools for small or structured doc sets.** When the documents are few enough to list (a repo, a docs site, a few hundred markdown files), give the agent list/fetch/search tools and let it navigate. As an example, an agent browsing a GitHub repo can use `githubTool` (list files) plus an HTTP Request Tool against the repo contents endpoint to fetch raw text — no ingest, no embeddings, full source paths in citations.
+
+Reach for vector RAG when there are too many documents to list, queries are semantic rather than navigational, and you need similarity-based retrieval at low latency.
+
+---
+
+## Quickest start: in-memory vector store
+
+The fastest path to a working RAG flow uses `@n8n/n8n-nodes-langchain.vectorStoreInMemory` — no external service, no provisioning, no extra credential beyond whichever embedding / chat-model provider you already use. Data is lost on workflow restart, so it's right for prototypes, learning, and tests, not production.
+
+- **Ingest**: any trigger producing documents → Default Data Loader → Vector Store In-Memory (`mode: 'insert'`) with an Embeddings node wired into `ai_embedding`. A Form Trigger with a file-upload field is a quick way to drop in PDFs/CSVs without scripting.
+- **Query**: Chat Trigger → Agent → Vector Store In-Memory (`mode: 'retrieve-as-tool'`), same `memoryKey` and the same embedding model as ingest.
+
+When the data must survive restarts or scale beyond one instance, swap the in-memory node for a persistent store — the rest of the wiring stays the same.
+
+---
+
+## Vector RAG: the pieces
+
+n8n exposes the LangChain primitives as sub-nodes:
+
+- **Document loaders** (`documentDefaultDataLoader`) — pull from sources, optionally with metadata. Wires into a vector store's `ai_document`.
+- **Text splitters** (`textSplitter*`) — chunk into retrievable pieces. The default loader can do this inline for simple cases.
+- **Embeddings** (`embeddingsOpenAi`, `embeddingsCohere`, …) — turn chunks into vectors. Wires into `ai_embedding` on **both** ingest and query.
+- **Vector stores** — `vectorStoreInMemory`, `vectorStoreQdrant`, `vectorStoreSupabase` (Postgres pgvector), `vectorStorePinecone`. Each has modes: `insert` (ingest), `retrieve-as-tool` (the agent's `ai_tool` slot), and others for direct querying.
+
+The Default Data Loader's `metadata` field is **load-bearing**: anything you want to filter or display alongside results (source URL, document type, tenant ID) goes there. Without it, results are just chunks with no provenance.
+
+---
+
+## Vector RAG: two workflows
+
+### Ingest
+
+```
+[Trigger]
+  →  [Vector Store, mode: 'insert']
+        ai_document   <- [Default Data Loader (with metadata)]
+        ai_embedding  <- [Embeddings]
+```
+
+**Ingest does not have to be a tool.** Most often it's a separate scheduled workflow pre-populating the store on a cadence (e.g. nightly), or a webhook-triggered workflow. Wire it as an agent tool only when the documents change dynamically based on conversation (the agent learns something it should remember). For static or system-managed sets, a standalone workflow is simpler.
+
+### Query
+
+```
+[Chat / webhook trigger]
+  →  [Agent]
+        ai_tool          <- [Vector Store, mode: 'retrieve-as-tool']
+                               ai_embedding <- [Embeddings (SAME model as ingest)]
+        ai_languageModel <- [Chat Model]
+        ai_memory        <- [Memory]
+```
+
+Wired as `ai_tool`, the vector store becomes a tool the agent calls when it judges retrieval relevant. Wire retrieval directly into the main flow (pre-agent) only when **every** turn requires retrieval — rare in practice.
+
+**The embedding model must match.** Whatever embedded the documents on ingest must embed the query. Mismatched models produce garbage retrieval. Change models → re-ingest.
+
+---
+
+## Open decisions (verify per context)
+
+### Vector store selection
+
+- **In-memory** — zero ops, lost on restart. Prototypes and tests.
+- **Qdrant** — open-source, self-hostable, fast, mature in n8n.
+- **Postgres pgvector / Supabase** — ideal if you already run Postgres; SQL-side metadata filters and relational joins compose nicely.
+- **Pinecone** — fully managed, per-request pricing.
+
+### Embedding model
+
+OpenAI `text-embedding-3-large`, Cohere `embed-v3`, and open-source models are common. Cost, dimension count, and quality differ — choose carefully upfront to avoid re-embedding.
+
+### Retrieval-as-tool vs retrieval-before-agent
+
+- **Retrieve-as-tool**: the agent decides when retrieval is relevant AND phrases the query itself (reformulate, decompose, expand vague wording). One extra round trip per retrieval, but fewer wasted retrievals and a better hit rate.
+- **Retrieve-before-agent**: simpler and predictable, but pays the cost every turn AND uses the user's raw input as the query, so vague phrasing ("remind me how that thing works again?") goes straight into the search.
+
+Tool-based composes better in multi-capability agents (retrieval is one tool among several). Always-retrieve is fine for narrow Q&A bots where every question is a knowledge-base question.
+
+---
+
+## Cross-references
+
+- Agent fundamentals → parent **SKILL.md**
+- Wiring sub-workflows (and agentic retrieval tools) → **SUBWORKFLOW_AS_TOOL.md**
+- Tool naming/descriptions on retrieval tools → **TOOLS.md**
+- Data Tables as an alternative to a vector store for small structured data → **n8n-node-configuration**

data/skills/n8n-agents/README.md

@@ -0,0 +1,180 @@
+# n8n Agents Skill
+
+The deep guide to designing n8n AI agents and the LangChain family around them (`@n8n/n8n-nodes-langchain.*`) — the AI Agent node, its model/memory/tools/outputParser slots, and the chains and classifiers you'd reach for instead.
+
+This is the **biggest** skill in the pack. The parent **n8n-workflow-patterns** `ai_agent_workflow.md` gives the high-level "agent in a workflow" shell; this skill goes one level down into *how to build it well*.
+
+---
+
+## Pick the right node first
+
+The most common over-build is reaching for an Agent when the job is one-shot:
+
+| You need to… | Use |
+|---|---|
+| Tools, multi-turn reasoning, or memory | **AI Agent** (`.agent`) |
+| One-shot text in → text out, no tools | **Basic LLM Chain** (`.chainLlm`) |
+| Route a natural-language input to one of N branches | **Text Classifier** (`.textClassifier`) — NOT Agent + Switch |
+| Pull structured fields out of free text | **Information Extractor** (`.informationExtractor`) |
+| Generate an image / audio / video | The provider's **native single-call node** — never wrap media in an Agent |
+
+---
+
+## What This Skill Teaches
+
+### Core Concepts
+1. **The four sub-node slots** — model / memory / tools / outputParser, each on its own `ai_*` connection
+2. **Tool names and descriptions ARE the prompt** — the model picks tools by reading them; generic names degrade routing silently
+3. **`$fromAI()` anatomy** — how agent-filled tool params are declared (name / description / type); JSON only, never binary
+4. **Structured output must parse AND autoFix** — `outputParserStructured` + a coding-capable fixer model
+5. **Memory + sessionId continuity** — `memoryBufferWindow`, keyed on a stable session key
+6. **The binary boundary** — the model can *see* images; tools can't *receive* them
+
+### Common Mistakes This Skill Prevents
+1. Agent + Switch to route on natural language — Text Classifier is one node with N outputs
+2. A tool the agent ignores — generic name (`tool1`) or empty description
+3. Malformed JSON crashing the workflow — `outputParserStructured` without `autoFix`
+4. A chat bot in an infinite loop — no bot-user-ID filter
+5. Wrapping image/audio/video generation in an Agent — binary doesn't flow through
+6. Crossed conversations — hardcoded `sessionId` or `sessionId` behind `$fromAI`
+7. "Max iterations reached" — the low default cap left untouched on a multi-tool agent
+
+---
+
+## Skill Activation
+
+Activates when you:
+- Build or edit any `@n8n/n8n-nodes-langchain.*` AI node
+- Mention AI agents, LLM with tools, tool calling, `$fromAI`, system prompts
+- Mention agent memory, `sessionId`, structured/JSON output, an output parser
+- Mention RAG, a vector store, a chat assistant/bot, or human-in-the-loop review
+- Choose between an Agent, an LLM chain, a Text Classifier, or an Information Extractor
+
+**Example queries**:
+- "My AI agent ignores a tool I named `tool1`. Why?"
+- "Should I use an Agent + Switch to route messages into three branches?"
+- "My agent sometimes returns malformed JSON and the workflow crashes despite an output parser."
+- "How do I keep a Slack bot from triggering itself?"
+- "Where should per-tool instructions go — the system prompt or the tool description?"
+
+---
+
+## File Structure
+
+### SKILL.md
+Main skill content — loaded when the skill activates.
+- Pick the right node (Agent vs chain vs classifier vs extractor vs native media)
+- The four sub-node slots and their `ai_*` connection types
+- Two non-negotiables: tool names/descriptions as prompt; structured output parse + autoFix
+- The four tool types and `$fromAI()` anatomy
+- System prompt vs tool description split
+- Memory mental model; the binary boundary; human review; chat topologies; RAG
+- Anti-patterns, "what's NOT available via the MCP", integration, checklist
+
+### Reference files
+| File | Read when |
+|---|---|
+| **TOOLS.md** | Choosing among the four tool types, writing names/descriptions, `$fromAI` anatomy |
+| **SUBWORKFLOW_AS_TOOL.md** | Wiring a sub-workflow as a tool via `.toolWorkflow` |
+| **SYSTEM_PROMPT.md** | Writing/refactoring a system prompt; the modular split |
+| **STRUCTURED_OUTPUT.md** | Forcing JSON output, autoFix, the fixer model, parse-failure fixes |
+| **MEMORY.md** | Choosing a memory type; persistence and sessionId handling |
+| **HUMAN_REVIEW.md** | Adding human approval; approval-message content; multi-channel approver |
+| **CHAT_AGENT_PATTERNS.md** | Slack/Discord/Teams/Telegram bots; shell + core + sub-agents topology |
+| **RAG.md** | Retrieval-augmented agents (thin by design) |
+| **EXAMPLES.md** | Node-object snippets: stateless agent core, Slack router shell, domain sub-agent |
+
+---
+
+## Quick Reference
+
+### Wiring a sub-node (connection lives on the sub-node)
+```json
+"Main LLM": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] }
+```
+
+### Agent-filled tool parameter
+```
+={{ $fromAI('recipient', 'Email address of the recipient', 'string') }}
+```
+
+### Plumbed (hidden-from-agent) tool parameter
+```
+={{ $('Chat Trigger').first().json.user.id }}
+```
+
+### Memory keyed on a stable session
+```json
+{ "sessionIdType": "customKey", "sessionKey": "={{ $json.threadId }}", "contextWindowLength": 50 }
+```
+
+### Human-review approval message — literal params, never `$fromAI`
+```
+=Refund {{ $tool.parameters.amount }} to {{ $tool.parameters.customerId }}?
+```
+
+### Node-type formats
+- Workflow JSON: long form — `@n8n/n8n-nodes-langchain.agent`
+- `get_node` / `validate_node`: short form — `nodes-langchain.agent`
+
+---
+
+## Integration with Other Skills
+
+**n8n-workflow-patterns** (`ai_agent_workflow.md`): the high-level agent shape. Start there for architecture; this skill is the deep dive.
+
+**n8n-mcp-tools-expert**: node-type formats and tool selection — consult before any MCP call.
+
+**n8n-node-configuration**: `displayOptions`-driven fields on the agent and sub-nodes; Slack/Block Kit message shapes.
+
+**n8n-expression-syntax**: `{{ }}`, `$json.output`, `$now`, `$fromAI`, `$tool.parameters`.
+
+**n8n-code-tool**: the Custom Code Tool's string-in/string-out contract (a different runtime from this skill's tools).
+
+**n8n-subworkflows**: the sub-workflow primitive `.toolWorkflow` builds on.
+
+**n8n-binary-and-data**: owns the agent-tool binary boundary mechanics.
+
+**n8n-validation-expert**: interpreting `validate_workflow`, including AI-connection issues (a tool on `main` instead of `ai_tool` flags as disconnected).
+
+**n8n-error-handling**: `onError: 'continueErrorOutput'` on tool sub-workflows and the agent-core call; error UX on chat shells.
+
+---
+
+## When to Use Which Tool Type
+
+| Need | Use |
+|---|---|
+| One native node + one operation | **Native tool node** |
+| More than one node / reusable / testable | **`.toolWorkflow`** (default when in doubt) |
+| A single external HTTP API the agent orchestrates | **HTTP Request Tool** (`.toolHttpRequest`) |
+| A maintained MCP server / publish n8n logic to many agents | **MCP Client Tool** |
+| Pure inline computation (math, parsing) | **Custom Code Tool** (`.toolCode`, see **n8n-code-tool**) |
+
+**Rule of thumb**: if you want `$fromAI()` inside Code, you want `.toolWorkflow` instead.
+
+---
+
+## Success Metrics
+
+After using this skill, you should be able to:
+
+- [ ] Pick Agent vs Basic LLM Chain vs Text Classifier vs Information Extractor correctly
+- [ ] Wire model/memory/tools/outputParser via the right `ai_*` connection types
+- [ ] Write tool names and descriptions the model actually selects against
+- [ ] Declare `$fromAI()` params well, and plumb identity/limits/sessionId deterministically
+- [ ] Configure `outputParserStructured` with a manual schema + autoFix + a coding-capable fixer
+- [ ] Key memory on a stable session and avoid crossed conversations
+- [ ] Gate destructive tools behind human review using literal `$tool.parameters`
+- [ ] Build a chat bot that doesn't loop on its own messages
+
+---
+
+## Version
+
+**Version**: 1.0.0
+**Compatibility**: n8n with `@n8n/n8n-nodes-langchain.agent` and the LangChain sub-node family. Node versions and model availability shift between releases — verify on the target instance with `search_nodes` / `get_node`.
+
+---
+
+**Remember**: the model can't see your wiring — it sees a system prompt and a list of named, described tools. Design those like an API and most "the agent won't behave" problems disappear.

data/skills/n8n-agents/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: n8n-agents
+description: Design n8n AI agents the right way. Use when building or editing any @n8n/n8n-nodes-langchain.* AI node — an AI Agent, LLM chain, Text Classifier, or Information Extractor — and whenever the user mentions AI agents, LLM with tools, tool calling, $fromAI, system prompts, agent memory, sessionId, structured/JSON output, output parser, RAG, vector store, a chat assistant/bot, or human-in-the-loop review. Covers Agent-vs-chain-vs-classifier choice, the model/memory/tools/outputParser slots, tool names/descriptions as prompt, structured output with autoFix, memory, RAG, human review, and chat topologies.
+---
+
+# n8n Agents
+
+The n8n AI Agent node (`@n8n/n8n-nodes-langchain.agent`) is a multi-turn LLM driver with sub-nodes for the model, memory, tools, and an optional output parser. This skill is the **deep** guide to designing agents and the LangChain family around them. For the high-level "where an agent fits in a workflow" picture, see **n8n-workflow-patterns** `ai_agent_workflow.md` — this skill goes one level down into *how to build it well*.
+
+For node-type formats: in workflow JSON the LangChain nodes use the long `@n8n/n8n-nodes-langchain.*` form (`.agent`, `.lmChatOpenAi`, `.memoryBufferWindow`, `.outputParserStructured`, `.toolWorkflow`, `.toolHttpRequest`, `.toolCode`). When you call `get_node` / `validate_node`, use the **short** form (`nodes-langchain.agent`). See **n8n-mcp-tools-expert** for the format rules.
+
+---
+
+## Pick the right node first
+
+Reaching for an Agent when the task is one-shot classification or extraction is the most common over-build. Decide before you wire anything:
+
+| You need to… | Use | Why |
+|---|---|---|
+| Call tools, reason over multiple turns, or hold memory | **AI Agent** (`.agent`) | The full loop: model + tools + memory + optional parser. Also a fine default when you'd rather standardize. |
+| One-shot text in → text out, no tools | **Basic LLM Chain** (`.chainLlm`) | No agent loop, easier to debug. Still accepts an `outputParserStructured` sub-node. |
+| Route a natural-language input to one of **N branches** | **Text Classifier** (`.textClassifier`) | ONE node, N output handles, downstream wires directly into each. Not Agent + Switch. |
+| Pull structured fields out of free text | **Information Extractor** (`.informationExtractor`) | Purpose-built field extraction with a schema. |
+| 3-way positive/neutral/negative split | **Sentiment Analysis** (`.sentimentAnalysis`) | Built-in branch outputs. |
+| Condense a long document | **Summarization Chain** (`.chainSummarization`) | Map-reduce summarization built in. |
+| Generate an image / audio / video | **The provider's native single-call node** (OpenAI, Gemini, ElevenLabs…) | NEVER wrap media generation in an Agent — see "Binary and the agent boundary". |
+
+**Text Classifier detail (the Agent + Switch anti-pattern):** every category needs both a **name AND a description**. The model routes against the *description*, not the name — a category with no description gets picked by coin-flip. Set `options.enableAutoFixing: true` for robustness on edge inputs. One node, N branches, done. Reaching for an Agent that "decides" then a Switch that "routes" is two nodes plus prompt boilerplate for what Text Classifier does natively.
+
+Chat-model nodes (`.lmChatOpenAi`, `.lmChatAnthropic`, `.lmChatOpenRouter`, …) are **sub-nodes** — they don't run standalone. They wire into a chain, agent, classifier, or extractor via the `ai_languageModel` connection.
+
+---
+
+## The sub-node pattern
+
+The Agent has a **main input** (the prompt / user message) and up to four **sub-node slots**, each wired by its own `ai_*` connection type:
+
+| Slot | Connection type | Required? | Node example |
+|---|---|---|---|
+| **model** | `ai_languageModel` | Yes | `.lmChatOpenAi`, `.lmChatAnthropic`, `.lmChatOpenRouter` |
+| **memory** | `ai_memory` | Optional | `.memoryBufferWindow`, `.memoryPostgresChat` |
+| **tools** | `ai_tool` | Optional (but the point of an agent) | `slackTool`, `.toolWorkflow`, `.toolHttpRequest`, `.toolCode` |
+| **outputParser** | `ai_outputParser` | Optional | `.outputParserStructured` |
+
+A sub-node connects FROM itself TO the agent. In workflow JSON the connection lives on the **sub-node**, keyed by the `ai_*` type:
+
+```json
+"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 customer DB": {
+  "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
+}
+```
+
+Multiple tools all connect into the same `ai_tool` index 0 — they stack, they don't fan into separate indices. With `n8n_update_partial_workflow` you wire each with an `addConnection` op using `sourceOutput: "ai_tool"`. The agent puts its final answer in **`$json.output`** (not `.text`, not `.response`) — downstream nodes read `{{ $json.output }}`.
+
+See **EXAMPLES.md** for a complete stateless agent-core node-object snippet.
+
+---
+
+## Two non-negotiables
+
+1. **Tool names and descriptions ARE part of the prompt.** The model picks a tool by reading its name and description — nothing else. A tool named `tool1` with an empty description is invisible to the model: it skips it, mis-selects it, or hallucinates parameters. There's usually no error — just an agent that "won't use my tool". Treat both like API design. → **TOOLS.md**
+2. **Structured output must parse AND autoFix.** An `outputParserStructured` with `autoFix: true` and a **coding-capable fixer model** is the production pattern. Without autoFix, one malformed JSON response halts the whole workflow. → **STRUCTURED_OUTPUT.md**
+
+---
+
+## Strong defaults
+
+- **Per-tool usage goes in the tool description, not the system prompt.** Anything about *how to call this specific tool* belongs with the tool, so it travels across agents and keeps the system prompt focused. → **SYSTEM_PROMPT.md**
+- **Sub-workflow tools (`.toolWorkflow`) for anything multi-step.** Any workflow becomes a tool with typed `$fromAI()` inputs, and composes with branching, error handling, and reuse. Default here when in doubt. → **SUBWORKFLOW_AS_TOOL.md** and **n8n-subworkflows**.
+- **Wrap tools with user-visible side effects in human review.** Sends, payments, refunds, account changes get gated behind an approval node so a human signs off before the tool fires. → **HUMAN_REVIEW.md**
+- **Raise `maxIterations`.** The default tool-call cap is **low** (single digits on most versions) — fine for a one-tool agent, far too low for a multi-tool agent that chains several calls per turn. It surfaces as "max iterations reached" or empty output. Set `options.maxIterations` to a realistic ceiling (15 for a focused sub-agent, 50-200 for a broad orchestrator).
+- **Put the current date in the system prompt** via `{{ $now }}` (or `{{ $now.format('DDDD') }}`). A hardcoded date is stale immediately.
+
+---
+
+## The four tool types
+
+Pick the lightest option that covers the job:
+
+| Tool type | Node | Use when |
+|---|---|---|
+| **Native tool node** | `slackTool`, `gmailTool`, `toolCalculator`, … | The capability maps to one existing node + one operation. Lowest overhead. |
+| **Sub-workflow as tool** | `.toolWorkflow` | More than one node, reusable logic, or you want independent testability. The canonical n8n way — **default when in doubt**. |
+| **HTTP Request Tool** | `.toolHttpRequest` | A single external HTTP API the agent should orchestrate directly. Reuse the service's predefined credential to cover operations a native node doesn't expose. |
+| **MCP Client Tool** | `.mcpClientTool` | A maintained MCP server already covers it, or you want one published workflow to serve many agents. |
+
+There is also a **Custom Code Tool** (`.toolCode`) for pure inline computation — but its runtime contract (string in / string out, no `$fromAI`, no `$helpers`) is owned by the **n8n-code-tool** skill. Read that before writing one. Rule of thumb: if you find yourself reaching for `$fromAI()` inside the code, you want `.toolWorkflow` instead.
+
+### `$fromAI()`: how the agent fills tool parameters
+
+Tool parameters the agent should decide are wrapped in `$fromAI()`. It is a **real n8n expression helper**, used inside a tool node's parameter expressions:
+
+```
+={{ $fromAI('paramName', 'what to put here — be specific: format, range, example', 'string') }}
+```
+
+- **paramName** — the name the model uses internally (snake_case or camelCase, be consistent).
+- **description** — tells the model what value to produce. **It is part of the prompt** — write it like JSDoc.
+- **type** (optional) — `'string'` (default), `'number'`, `'boolean'`, `'json'`. A wrong-typed value fails the call.
+- **defaultValue** (optional) — used when the model omits it.
+
+`$fromAI()` carries JSON only — it **cannot carry binary** (no base64, no file bytes). And not every parameter has to be `$fromAI`: plumb identity, authority limits, and correlation IDs (`userId`, refund caps, `sessionId`) deterministically from workflow context so the agent can't get them wrong or even see them. → **TOOLS.md** for the full anatomy and the "give the agent a button, not a steering wheel" pattern.
+
+---
+
+## System prompt vs tool description
+
+| Belongs in the **system prompt** | Belongs in the **tool's description** |
+|---|---|
+| Persona, role, voice | What this specific tool does |
+| Global output/format rules ("respond in markdown") | When to use it vs other tools |
+| Refusal / safety behavior | What each parameter means and its shape |
+| Display protocols (`![]()` for images) | Examples of good vs bad invocations |
+| Universal context (current date via `$now`, user role) | Tool-specific gotchas (rate limits, edge cases) |
+| Inter-tool flow ("after generating, always display") | Tool-specific input transformations |
+
+Why split it: a well-described tool works in **any** agent that drops it in, tool details only "load" when the model considers that tool (token efficiency), and you update one tool description instead of a paragraph buried in a 5000-token prompt. → **SYSTEM_PROMPT.md**
+
+---
+
+## Structured output: when and how
+
+Add an `outputParserStructured` sub-node (wired `ai_outputParser`) when downstream needs strict JSON, not free-form text. Two rules:
+
+1. **Use `schemaType: 'manual'` with a real JSON Schema, not `jsonSchemaExample`.** An example can't express required-vs-optional, enums, numeric ranges, or array constraints — you outgrow it the first time the shape gets non-trivial. Reach for `fromJson` + an example only for throwaway shapes.
+2. **`autoFix: true` with a coding-capable fixer model.** Wire a *second* model into the parser's `ai_languageModel` slot. Reconciling broken JSON against a schema is a coding task — a weak fixer just produces another malformed retry and burns tokens.
+
+→ **STRUCTURED_OUTPUT.md** for the schema patterns, the load-bearing "DO NOT wrap in markdown" retry line, and the parse-failure cookbook.
+
+---
+
+## Memory: brief mental model
+
+Memory is a sub-node (`ai_memory`). Without it, every call is stateless — correct for one-shot tasks (classify, summarize). With it, the agent holds a conversation, keyed by whatever expression you bind to `sessionKey`.
+
+- **`memoryBufferWindow`** — keeps the last N exchanges per key and persists across executions via n8n's store. The default for chat. **`contextWindowLength` defaults to 5, which is very low** — 50 is a saner starting point. Messages past the window are gone entirely.
+- **`memoryPostgresChat` / `memoryRedisChat`** — only when memory must be read *outside* the agent (your own UI, analytics, cross-system). Not needed just to survive restarts; BufferWindow already does that.
+
+**Plumb a stable key from the trigger to memory consistently.** Chat triggers fill `sessionId` automatically; for other surfaces derive one (Slack `thread_ts`, a webhook conversation ID). Never hardcode `sessionId: 'default'` and never put `sessionId` behind `$fromAI` (the model will fabricate a UUID). → **MEMORY.md**
+
+---
+
+## Binary and the agent boundary
+
+This is the seam that trips people up:
+
+- **The model CAN see uploaded images** (vision) via `options.passthroughBinaryImages: true` on the agent.
+- **Tools CANNOT receive binary.** `$fromAI()` is JSON-only — no base64, no bytes, even through non-AI bindings.
+- **The agent's output is text-shaped** (or structured-text with a parser). When a model returns image/audio/video bytes, the Agent doesn't surface them at all — there's nothing to recover downstream.
+
+**Workaround:** pre-stage uploads to storage before the agent runs, inject the storage keys into the system prompt, and let tools accept the key as a string parameter and re-fetch internally. For one-shot media generation, skip the agent and call the provider's native single-call node directly.
+
+The binary mechanics (which storage, how to stage, how to re-fetch) are owned by **n8n-binary-and-data** — see its agent-tool binary reference. This skill only marks the boundary; don't re-derive the mechanics here.
+
+---
+
+## Human review (gate destructive tools)
+
+When a tool's effect needs human sign-off before execution (sends, payments, refunds, account changes), wrap it with a review tool node — `slackHitlTool`, `discordHitlTool`, `telegramHitlTool`, `gmailHitlTool`, etc. (n8n names these "Hitl" / human-in-the-loop). The review node sits **between** the wrapped tool and the agent on the `ai_tool` connection: wrapped tool → review node → Agent.
+
+Whether sign-off is needed is a product/policy call — **surface the question to the user**, recommend based on blast radius, and let them decide.
+
+**The critical rule: show the actual parameters the wrapped tool will receive.** Use the literal `{{ $tool.parameters.<name> }}` in the approval message, never a `$fromAI()` paraphrase — otherwise the human approves text the model made up, not the call about to fire. → **HUMAN_REVIEW.md**
+
+---
+
+## Chat agents (Slack, Discord, Teams, Telegram)
+
+**The one non-negotiable, regardless of complexity:** any chat-triggered workflow that posts a reply MUST **filter out the bot's own user ID**, or its own replies re-trigger it in an infinite loop that burns runs and tokens. Prefer trigger-level filtering when available (Slack Trigger's `options.userIds` is an **exclusion list** — put the bot ID there); otherwise filter `$json.user !== '<BOT_USER_ID>'` in the first node after the trigger.
+
+Beyond the filter, a simple bot (trigger → agent → reply) lives fine in one workflow. Split into **shell + core + sub-agents** only once you need loading UX, sub-agents, multi-surface reuse, or robust error handling:
+
+- **Shell** — trigger, anti-loop filter, event-type Switch, loading/error UX, renders the reply. No LLM.
+- **Core** — stateless agent, `chatInput` + `threadId` inputs, memory keyed on `threadId`, tools and sub-agents.
+- **Sub-agents** — one narrow domain each, called via `.toolWorkflow`, **stateless** (full context in `chatInput`).
+
+→ **CHAT_AGENT_PATTERNS.md** for per-surface semantics, threading-as-session, and the full topology.
+
+---
+
+## RAG (retrieval augmented generation)
+
+n8n ships the LangChain RAG primitives (document loaders, splitters, embeddings, vector stores, retrievers). Two opinions worth stating up front:
+
+1. **Rule out cheaper lookups first.** Exact lookups → a database or Data Table query, not RAG. Freshness → a live search tool. A small/structured doc set → give the agent list/fetch tools. Reach for a vector store only when there are too many docs to list and queries are semantic.
+2. **Wire the vector store as a retrieval tool** (`mode: 'retrieve-as-tool'`, `ai_tool`) so the agent decides when retrieval is relevant and can phrase the query itself. Embed query and documents with the **same** model.
+
+→ **RAG.md** (intentionally thin — defaults depend on data shape and scale).
+
+---
+
+## Reference files
+
+| File | Read when |
+|---|---|
+| **TOOLS.md** | Adding tools, choosing among the four types, writing names/descriptions, `$fromAI` anatomy |
+| **SUBWORKFLOW_AS_TOOL.md** | Wiring a sub-workflow as a tool via `.toolWorkflow`, mapping agent-filled vs plumbed params |
+| **SYSTEM_PROMPT.md** | Writing/refactoring a system prompt, the system-prompt-vs-tool-description split |
+| **STRUCTURED_OUTPUT.md** | Forcing JSON output, configuring autoFix, the fixer model, parse-failure fixes |
+| **MEMORY.md** | Choosing a memory type, persistence, sessionId handling |
+| **HUMAN_REVIEW.md** | Adding human approval, approval-message content, multi-channel approver |
+| **CHAT_AGENT_PATTERNS.md** | Building a Slack/Discord/Teams/Telegram bot, shell + core + sub-agents topology |
+| **RAG.md** | Retrieval-augmented agents (thin by design) |
+| **EXAMPLES.md** | Concrete node-object snippets: stateless agent core, Slack router shell, domain sub-agent |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | What goes wrong | Fix |
+|---|---|---|
+| Generic tool names (`tool1`, `doStuff`, `runQuery`) | Model can't tell which tool to pick — skips them or hallucinates params | Verb-first specific names: `Search customer database`, `Generate image with Veo` |
+| Empty or one-line tool descriptions | Model has no idea when to invoke; bad selection, no error | Write a real description: what it does, when to use, what each param means |
+| Cramming per-tool instructions into the system prompt | Bloated prompt, no reuse, per-tool guidance buried | Move tool-specific instructions into tool descriptions |
+| Agent + Switch to route on natural language | Two nodes + prompt boilerplate where Text Classifier is one node | Use Text Classifier — each category gets its own output handle (name **and** description) |
+| Wrapping image/audio/video generation in an Agent | Binary doesn't flow through tools or out of the agent output | Use the provider's native single-call node directly |
+| `outputParserStructured` without `autoFix` | One malformed response halts the workflow | `autoFix: true` + a coding-capable fixer model |
+| Passing binary directly to a tool | Doesn't work — binary can't cross the tool boundary | Pre-stage to storage, pass keys; see **n8n-binary-and-data** |
+| Hardcoded `sessionId` / no sessionId / `sessionId` behind `$fromAI` | Conversations cross, or the model fabricates a UUID | Plumb a stable key from the trigger to memory and tools |
+| Two near-identical tools | Selection is non-deterministic, model gets confused | One tool with internal branching driven by a parameter |
+| Chat bot with no bot-user filter | Its own replies re-trigger it → infinite loop | Exclude the bot user ID at the trigger or first node |
+| `maxIterations` left at the low default on a multi-tool agent | "Max iterations reached" / empty output | Raise `options.maxIterations` |
+| Filling the human-review message via `$fromAI()` | Approver signs off on a paraphrase, not the real call | Use literal `{{ $tool.parameters.<name> }}` |
+
+---
+
+## What's NOT available via the community MCP
+
+| Want to do | Reality |
+|---|---|
+| Run / chat-test the agent end-to-end with live tokens | `n8n_test_workflow` runs the workflow, but a true multi-turn chat session is a UI activity (canvas chat tester). |
+| Set credentials' actual secret values | `n8n_manage_credentials` creates/updates credential records, but the agent provider keys themselves are entered/verified in the UI. |
+| Assign a workflow's Error Workflow | UI only — see **n8n-error-handling**. Build the catch-all, then hand the user the UI step. |
+| Pin the exact model availability per instance | Model lists shift between versions — `search_nodes`/`get_node` reflect what's installed. Verify on the target instance. |
+
+What the MCP **can** do: search and inspect every LangChain node (`search_nodes`, `get_node`), validate node config and the whole graph (`validate_node`, `validate_workflow`), build and patch the agent and its sub-nodes (`n8n_update_partial_workflow` with `addConnection` on `ai_*` outputs), test (`n8n_test_workflow`), and pull the saved JSON to verify wiring (`n8n_get_workflow`). The deep AI-agent guide also lives in `tools_documentation({topic: "ai_agents_guide", depth: "full"})`.
+
+---
+
+## Integration with other skills
+
+- **n8n-workflow-patterns** (`ai_agent_workflow.md`) — the high-level "agent in a workflow" shape. This skill is the deep dive; start there for architecture.
+- **n8n-mcp-tools-expert** — node-type formats (short form for `get_node`, long form in JSON) and tool-selection guidance. Consult before any MCP call.
+- **n8n-node-configuration** — `displayOptions`-driven fields on the agent and sub-nodes; Slack/Block Kit message shapes (`NODE_FAMILY_GOTCHAS.md`, Slack section).
+- **n8n-expression-syntax** — `{{ }}`, `$json.output`, `$now`, and `$fromAI`/`$tool.parameters` all rely on correct expression syntax.
+- **n8n-code-tool** — the Custom Code Tool's runtime contract (string in/out, no `$fromAI`). Read it before writing a `.toolCode`.
+- **n8n-subworkflows** — the sub-workflow primitive that `.toolWorkflow` builds on (Execute Workflow Trigger inputs/outputs, naming, search-before-build).
+- **n8n-binary-and-data** — owns the agent-tool binary boundary mechanics (staging uploads, returning generated files).
+- **n8n-validation-expert** — interpreting `validate_workflow` results, including AI-connection issues (a tool wired into `main` instead of `ai_tool` flags as disconnected).
+- **n8n-error-handling** — `onError: 'continueErrorOutput'` on tool sub-workflows and the agent-core call; error UX on chat shells.
+- **n8n-code-javascript / n8n-code-python** — for Code-node logic *inside* a tool sub-workflow (different sandbox from the Code Tool).
+
+---
+
+## Quick reference checklist
+
+Before shipping an agent:
+
+- [ ] **Right node**: Agent for tools/memory/multi-turn; Text Classifier for routing; Information Extractor for fields; native node for media
+- [ ] **Model** wired via `ai_languageModel`
+- [ ] **Every tool** has a verb-first specific name AND a real description
+- [ ] **`$fromAI()` descriptions** are specific (format, range, example); identity/limits/sessionId plumbed deterministically, not via `$fromAI`
+- [ ] **Per-tool guidance** lives in tool descriptions, not the system prompt
+- [ ] **`$now`** in the system prompt (no hardcoded date)
+- [ ] **`maxIterations`** raised for multi-tool agents
+- [ ] **Memory** keyed on a stable `sessionKey` from the trigger (not `'default'`, not `$fromAI`); `contextWindowLength` raised from 5
+- [ ] **Structured output**: `schemaType: 'manual'` + `autoFix: true` + a coding-capable fixer model
+- [ ] **Destructive tools** wrapped in human review; approval message uses `$tool.parameters`, not `$fromAI`
+- [ ] **Chat bots** filter the bot's own user ID (trigger-level or first node)
+- [ ] **Binary**: model vision via `passthroughBinaryImages`; tools get storage keys, never bytes
+- [ ] **Validated** with `validate_workflow` and verified with `n8n_get_workflow` (sub-nodes on `ai_*`, not `main`)
+
+---
+
+**Remember**: an agent is only as good as its tool names, descriptions, and system-prompt discipline. The model can't see your wiring — it sees a system prompt and a list of named, described tools. Design those like an API and most "the agent won't behave" problems disappear.

data/skills/n8n-agents/STRUCTURED_OUTPUT.md

@@ -0,0 +1,163 @@
+# Structured output
+
+Non-negotiable: the output parser must **parse AND retry on failure**. Without retry, one malformed model response halts the entire workflow.
+
+The parser is the `@n8n/n8n-nodes-langchain.outputParserStructured` node, wired into the agent (or Basic LLM Chain) via the `ai_outputParser` connection.
+
+---
+
+## The pattern (node objects)
+
+The parser, with `autoFix` and its own fixer model:
+
+```json
+{
+  "parameters": {
+    "schemaType": "manual",
+    "inputSchema": "{ \"type\": \"object\", \"properties\": { \"score\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 5 }, \"reason\": { \"type\": \"string\" } }, \"required\": [\"score\", \"reason\"] }",
+    "autoFix": true
+  },
+  "type": "@n8n/n8n-nodes-langchain.outputParserStructured",
+  "typeVersion": 1.3,
+  "name": "Structured Output Parser"
+}
+```
+
+Wire the parser to the agent, and a **coding-capable fixer model** to the parser:
+
+```json
+"Structured Output Parser": {
+  "ai_outputParser": [[{ "node": "AI Agent", "type": "ai_outputParser", "index": 0 }]]
+},
+"Fixer LLM": {
+  "ai_languageModel": [[{ "node": "Structured Output Parser", "type": "ai_languageModel", "index": 0 }]]
+}
+```
+
+On the agent, set `hasOutputParser: true` so the slot is active.
+
+---
+
+## Why a schema, not an example
+
+`schemaType: 'manual'` with a real JSON Schema is the default. `jsonSchemaExample` (`schemaType: 'fromJson'`) looks easier, but an example **cannot** express:
+
+- **Required vs optional fields** — an example is one snapshot; the parser can't tell which keys are mandatory.
+- **Enums** — `"category": "compliance"` doesn't constrain the model to `compliance | history | risk`; it will invent new categories.
+- **Numeric ranges** — `"score": 3` doesn't say `1-5`; the model returns `7` or `0.85` and passes.
+- **Array constraints** — min/max items, item-type uniformity.
+- **String formats** — email, UUID, ISO date, regex.
+
+A schema gives the model clearer rules and the parser real validation:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "decision":   { "type": "string", "enum": ["approve", "reject", "escalate"] },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": { "type": "string", "enum": ["compliance", "history", "risk"] },
+          "weight":   { "type": "number", "minimum": 0, "maximum": 1 },
+          "note":     { "type": "string" }
+        },
+        "required": ["category", "weight"]
+      }
+    },
+    "follow_up_required": { "type": "boolean" }
+  },
+  "required": ["decision", "confidence", "reasons", "follow_up_required"]
+}
+```
+
+Reach for `fromJson` + `jsonSchemaExample` only for one-off shapes you're certain will never grow constraints. Once a field needs to be optional, enum-ed, or range-bounded, you're rewriting the parser anyway — start with the schema.
+
+---
+
+## `autoFix: true` and the fixer model
+
+The model can produce almost-but-not-quite-valid JSON: trailing comma, missing field, wrong type, or JSON wrapped in a markdown code block. Without `autoFix`, the workflow halts. With it, the parser sends the bad output to a model with a "fix this" prompt, retries, and continues.
+
+The fixer is wired as a **separate** sub-node into the parser's `ai_languageModel` slot. **Use a coding-capable model** (Sonnet-class or better). Reconciling broken JSON against a schema with enums, ranges, and required fields is a structured-output / coding task — a weak or generic model routinely produces another malformed retry, defeating the point and burning tokens.
+
+When you want to customize the retry prompt, set `customizeRetryPrompt: true` and provide `prompt`. The placeholders `{instructions}`, `{completion}`, `{error}` are filled at retry time:
+
+```
+Instructions:
+--------------
+{instructions}
+--------------
+Completion:
+--------------
+{completion}
+--------------
+Above, the Completion did not satisfy the constraints in the Instructions.
+Error:
+--------------
+{error}
+--------------
+Please try again with an answer that satisfies the constraints.
+This is a structured output parser tool in n8n. Ensure the output format is correct to pass parsing.
+DO NOT wrap the output in a markdown code block.
+```
+
+Generally, leave the retry prompt as default unless you have a specific reason to override it.
+
+---
+
+## "DO NOT wrap the output in a markdown code block"
+
+This line is **load-bearing**. Models default to wrapping JSON in triple-backtick `json` fences, which breaks the parser. If you see parse failures on output that's clearly valid JSON inside a code block, this instruction is the fix — in both the retry prompt and, if the main model wraps aggressively, the **main** system prompt:
+
+> When responding with structured output, return raw JSON only. DO NOT wrap in markdown code blocks. DO NOT include any prose before or after the JSON.
+
+---
+
+## System prompt + parser: belt and suspenders
+
+The parser tells the model the schema; the system prompt should ALSO state the shape:
+
+```
+## Output Format
+Respond with a JSON object matching this exact shape:
+{ "score": 1-5 integer, "reason": "brief explanation" }
+
+ONLY output the JSON. No prose, no markdown wrapping.
+```
+
+It's repetition, but the model takes the system prompt seriously and reinforcement helps. The parser catches what slips through.
+
+---
+
+## Common parse failures and fixes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| "Failed to parse output" but the text looks like JSON | Wrapped in a markdown code block | Add "DO NOT wrap in markdown" to retry prompt and system prompt |
+| Empty fields where the schema expects values | Model thinks it can omit unknowns | "Use empty string '' or null for unknown fields, never omit" |
+| Wrong types (number as string) | Schema/example wasn't typed clearly | Use a real number in the schema, not a string |
+| Truncated JSON (unclosed brace) | Hit max tokens mid-response | Increase max tokens, tighten the prompt to produce shorter output |
+| Field names paraphrased ("Score" vs "score") | Schema didn't pin the name | "Field names are exactly as shown" in the system prompt |
+| `autoFix` retries forever | Fixer model too weak for the schema | Swap in a coding-capable (Sonnet-class) fixer; tighten the retry prompt |
+
+---
+
+## When NOT to use a parser
+
+- **Free-form chat replies to the user** — conversational text doesn't need parsing.
+- **Tool calls only, no final structured output** — if the user-visible output is text, skip it.
+- **Trivial key-value extraction** — a Set node with `JSON.parse($json.output)` covers it.
+
+The parser is for when downstream nodes must consume strict JSON.
+
+---
+
+## Cross-references
+
+- Why and where to use agents at all → parent **SKILL.md**
+- The system-prompt half of structured output → **SYSTEM_PROMPT.md**
+- Block Kit / adaptive cards need the manual schema even more (union types) → **CHAT_AGENT_PATTERNS.md**

data/skills/n8n-agents/SUBWORKFLOW_AS_TOOL.md

@@ -0,0 +1,199 @@
+# Sub-workflow as agent tool
+
+The default agent-tool shape for anything beyond one node is the Tool Workflow node (`@n8n/n8n-nodes-langchain.toolWorkflow`). Any sub-workflow becomes a tool the agent calls, with typed inputs filled by `$fromAI()`. It composes with everything good about n8n: branching, error handling, sub-workflow reuse, native nodes, custom logic.
+
+For the sub-workflow primitive itself (Execute Workflow Trigger inputs/outputs, stateless design, naming, search-before-build), see **n8n-subworkflows** — this reference only covers the *agent-tool* angle.
+
+---
+
+## Why this is the default in n8n
+
+In raw LangChain a tool is a function. In n8n a tool can be a whole workflow, so it can:
+
+- Branch on input (IF / Switch).
+- Call multiple APIs and aggregate.
+- Have its own retries, fallbacks, error handling.
+- Call other sub-workflows.
+- Read/write Data Tables.
+- Be tested independently with `n8n_test_workflow` and pinned data.
+- Be reused across agents AND non-agent workflows.
+
+A function-as-tool can't do most of that without growing into a workflow anyway. n8n gives you the workflow primitive directly.
+
+---
+
+## The shape: two halves
+
+### 1. The sub-workflow side — an Execute Workflow Trigger with typed inputs
+
+```json
+{
+  "parameters": {
+    "workflowInputs": {
+      "values": [
+        { "name": "imagePrompt", "type": "string" },
+        { "name": "imageName",   "type": "string" },
+        { "name": "sessionId",   "type": "string" }
+      ]
+    }
+  },
+  "type": "n8n-nodes-base.executeWorkflowTrigger",
+  "typeVersion": 1.1,
+  "name": "When Executed by Another Workflow"
+}
+```
+
+Each declared input becomes a parameter the caller can fill. **The trigger must be in "Define Below" mode (typed fields), not passthrough** — passthrough has no schema, so the agent has nothing to fill via `$fromAI`. Two exceptions: (a) the sub-workflow needs binary (it can't be an agent tool directly — pre-stage to storage and pass storage keys as typed string fields, see **n8n-binary-and-data**), or (b) the tool takes no inputs at all (passthrough is the only option, and the tool's only decision is whether to invoke).
+
+Type enforcement happens on the **agent side** via the `type` argument of `$fromAI`, not at the trigger. Allowed types: `string`, `number`, `boolean`, `json`. Match them.
+
+### 2. The Tool Workflow side — points at the sub-workflow, binds params
+
+```json
+{
+  "parameters": {
+    "description": "Use to create a new image from a prompt OR edit an existing image. Pass imageName as the storage key (e.g. \"abc123.png\") to edit; leave empty to generate from scratch. Returns { imageUrl, imageKey }.",
+    "workflowId": { "__rl": true, "value": "<sub-workflow-id>", "mode": "list" },
+    "workflowInputs": {
+      "mappingMode": "defineBelow",
+      "value": {
+        "imagePrompt": "={{ $fromAI('imagePrompt', 'Detailed prompt describing the desired image', 'string') }}",
+        "imageName":   "={{ $fromAI('imageName', 'Storage key of an existing image to edit, or empty for new generation', 'string') }}",
+        "sessionId":   "={{ $('Chat Trigger').first().json.sessionId }}"
+      },
+      "schema": [
+        { "id": "imagePrompt", "displayName": "imagePrompt", "type": "string", "display": true },
+        { "id": "imageName",   "displayName": "imageName",   "type": "string", "display": true },
+        { "id": "sessionId",   "displayName": "sessionId",   "type": "string", "display": true }
+      ]
+    }
+  },
+  "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
+  "typeVersion": 2.2,
+  "name": "Generate or edit image"
+}
+```
+
+Wire it into the agent with `ai_tool`:
+
+```json
+"Generate or edit image": {
+  "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
+}
+```
+
+The mapping is per-input:
+
+- **Agent-filled**: `={{ $fromAI('paramName', 'description', 'string') }}` — the agent decides.
+- **Plumbed**: `={{ $('SourceNode').first().json.field }}` — your workflow fills it.
+
+The `sessionId` line is critical: it is **NOT** an agent decision. Plumb it from the trigger so memory and session-keyed work stay consistent. **Never put `sessionId` behind `$fromAI`** — the agent will fabricate a UUID.
+
+---
+
+## What the agent sees (and doesn't)
+
+The agent sees the tool's **name** (the Tool Workflow node's name) and **description** (a parameter on the node) — both follow the **TOOLS.md** rules: specific, API-doc style, treated as prompt.
+
+It does **not** see: the sub-workflow internals, the sub-workflow's own name, or plumbed values like `sessionId`. Only `$fromAI` parameters appear in the tool schema. So you can refactor the sub-workflow heavily without changing what the agent sees.
+
+---
+
+## Worked example: one tool, two modes
+
+Goal: an agent that can generate or edit images. Both share most logic; they differ only in whether they download an existing image first.
+
+```
+[Execute Workflow Trigger: { imagePrompt, imageName, sessionId }]
+   ↓
+[Crypto: hash for new filename]
+   ↓
+[IF: imageName empty?]
+   ├── empty (generate)     → [Gemini: generate] ──┐
+   └── not empty (edit):                            │
+       [S3: Download by imageName]                  │
+          ↓                                         │
+       [Gemini: edit with downloaded binary] ───────┤
+                                                     ↓
+                                            [S3: Upload result]
+                                                     ↓
+                                            [Set: { imageUrl, imageKey }]
+```
+
+The agent picks the mode by what it puts in `imageName`. Two near-identical tools would have made selection harder — collapse them.
+
+---
+
+## Patterns inside the sub-workflow
+
+### Return a stable shape (it's a contract)
+
+The caller receives whatever the last node outputs. Pick a shape and keep it across modes:
+
+```json
+{ "imageUrl": "https://...", "imageKey": "abc123.png" }
+```
+
+Don't sometimes return `{ url, key }` and other times `{ result: { url, key } }`. The output shape is a contract every caller depends on — agents read it as part of the prompt, deterministic callers wire downstream nodes to specific paths. Drift breaks callers silently.
+
+For calls that fail "expectedly" (search with no results), return a branchable shape:
+
+```json
+{ "ok": false, "error": "no_results", "message": "No matches found for query" }
+```
+
+### When to throw instead: Stop and Error
+
+For unexpected-but-handled errors (auth failure, upstream down, unrecoverable input), use a `Stop and Error` node with a detailed message. It propagates as a thrown error: agents see a tool error and can retry/switch/report; deterministic callers catch it via `onError: 'continueErrorOutput'`. Pick this over `{ ok: false }` when the outcome is a true error, not a normal branch. For the full error story (4xx/5xx mapping, retries, error workflows) → **n8n-error-handling**.
+
+### Wire `onError: 'continueErrorOutput'` on fallible nodes
+
+Inside the sub-workflow, fallible nodes (HTTP, S3, DB) should set `onError: 'continueErrorOutput'` and route to a clean error response, so both agent and deterministic callers receive a structured error instead of a silent halt.
+
+### Treat the input contract as an API and document it
+
+The Execute Workflow Trigger's declared inputs ARE this tool's API. Document them in the sub-workflow's `description`:
+
+```
+Generates or edits an image.
+Inputs:
+  imagePrompt (string, required): detailed image description.
+  imageName   (string, optional): storage key of existing image to edit. Empty = new generation.
+  sessionId   (string, required): chat session ID, used for storage keying.
+Returns:
+  { imageUrl, imageKey }
+```
+
+### Keep tool sub-workflows discoverable
+
+Name them with a standard prefix (`Subworkflow:` or domain-specific). The Tool Workflow node references them by ID (stable), but humans browse the UI by name.
+
+---
+
+## Testing the sub-workflow independently
+
+A sub-workflow tool can be tested without the agent:
+
+1. Pin representative input on the Execute Workflow Trigger.
+2. `n8n_test_workflow` runs it with that pinned data.
+3. Verify the output shape matches what the agent will receive.
+
+---
+
+## When NOT to use sub-workflow as tool
+
+- **Simple one-node wrappers** — "call this endpoint and return" is shorter as an HTTP Request Tool.
+- **One-off code-only logic specific to this agent** — a few lines of pure JS/Python that exist nowhere else work fine as a Custom Code Tool (`.toolCode`, see **n8n-code-tool**). Decision rule: reusable business logic → sub-workflow; one-off agent-specific transform → Code Tool.
+- **Capabilities that already exist as native tool nodes** — don't wrap `slackTool` in a sub-workflow.
+
+For everything else, sub-workflow as tool is the default.
+
+---
+
+## Cross-references
+
+- The four tool types overview → **TOOLS.md**
+- How `$fromAI` descriptions affect behavior → **TOOLS.md** "`$fromAI()`"
+- The sub-workflow primitive (stateless design, naming, I/O) → **n8n-subworkflows**
+- Passing binary into tools → **n8n-binary-and-data**
+- The Custom Code Tool exception → **n8n-code-tool**

data/skills/n8n-agents/SYSTEM_PROMPT.md

@@ -0,0 +1,151 @@
+# System prompts
+
+The system prompt is the load-bearing config of an agent. Most "the agent isn't doing what I want" problems trace back to a system prompt that's too long, too vague, or mixing concerns.
+
+This file is opinionated: keep system prompts on **persona and global behavior**, push tool-specific instructions into tool descriptions, and iterate. The system prompt goes in `options.systemMessage` on the agent node.
+
+---
+
+## What the system prompt is for
+
+1. **Persona / role.** Who, scope, tone.
+2. **Global output rules.** Format conventions, display protocols (e.g. "show images via `![]()` markdown"), language.
+3. **Refusal and safety behavior.** What the agent should NOT do — prefer specific bounds over generic boilerplate.
+4. **Universal context.** Current date, user's name/role, company/product context.
+5. **Inter-tool flow rules.** "After generating, always show via the display protocol", "confirm before destructive operations" — things that touch multiple tools.
+6. **File-handling injection.** When chat includes uploaded files, inject the storage keys so the agent can reference them in tool calls (mechanics → **n8n-binary-and-data**).
+
+What it is NOT for: per-tool usage instructions. Those go in the tool's description.
+
+---
+
+## Always include the current date
+
+A hardcoded date is stale immediately. Inject it at runtime:
+
+```
+Current date: {{ $now }}
+```
+
+or formatted:
+
+```
+The current time is {{ $now.format('DDDD TTTT') }}
+```
+
+---
+
+## The modular split
+
+```
+System prompt    → Persona, global behavior, format rules, file handling
+Tool description → How to use THIS tool, its parameters, when to pick it over others
+$fromAI desc.    → What value to put in this specific parameter
+```
+
+Why this split:
+
+- **Reuse.** A well-described tool works in any agent; the system prompt doesn't re-teach it.
+- **Token efficiency.** Tool details only "load" when the model considers that tool. Per-tool text in the system prompt burns tokens every turn.
+- **Maintainability.** Update one tool description, not a paragraph buried in a 5000-token prompt.
+
+### What to move where
+
+| Was in the system prompt | Better location |
+|---|---|
+| "When using Generate Image, prefer realistic photography over `8k cinematic`" | `Generate Image` tool description |
+| "When the user uploads an image and asks for background changes, edit it, don't generate new" | `Edit Image` tool description (and a "do not use" boundary on `Generate Image`) |
+| "Use 9:16 aspect ratio for video tools" | `Generate Video` tool description |
+| "Respond with markdown image embeds: `![alt](url)`" | **System prompt** (global display rule) |
+| "Refuse to generate images of real people without consent" | **System prompt** (global safety) |
+| "Today is 2026-04-25" | **System prompt** as `{{ $now }}` (universal context, computed) |
+
+The first three move out; the last three stay in.
+
+---
+
+## Storing the prompt
+
+Inline (typed directly into `systemMessage`) is fine for a first agent or any prompt that lives in one place. A 1500-token inline prompt is a normal shape — don't push first-time builders toward externalization.
+
+The real reason to externalize is **piecing**, not length. Reusable chunks of context — `COMPANY_DESCRIPTION`, `BRAND_VOICE`, `CURRENT_PROMOTION` — each get one canonical home, and every prompt that needs them references that home. Suggest this when you see one of:
+
+- Multiple agents share the same context (same product description, same compliance language).
+- Pieces drift on their own cadence (`COMPANY_DESCRIPTION` quarterly, `CURRENT_PROMOTION` weekly).
+- A non-engineer owns part of the prompt (marketing owns brand voice, legal owns disclosures).
+- You want to A/B test one chunk without touching the rest.
+
+If none apply, stay inline. Mid-prompt restructures cost more than they save with no second consumer to pay them back.
+
+### How piecing works
+
+Load each chunk at workflow start (one node per chunk — a Data Table `Get Row`, an HTTP fetch, a Set node), then reference them inline in `systemMessage` where they should appear:
+
+```
+=You are the assistant for {{ $('Company Description').first().json.value }}.
+
+## Market positioning
+{{ $('Market Fit').first().json.value }}
+
+## Brand voice
+{{ $('Brand Voice').first().json.value }}
+
+Current date: {{ $now }}
+User: {{ $('Lookup').first().json.name }}
+```
+
+Mix sources: a **Data Table** (default for shared chunks, editable in UI), **n8n Variables** (`$vars.X`, paid plans — short shared values like a brand name), or **computed at run time** (`$now`, current user, available files).
+
+---
+
+## Common patterns
+
+### Include
+
+- **Display protocols** for output needing specific formatting (markdown image syntax, link format, code-block conventions).
+- **Conversational style cues** for user-facing agents ("ask one clarifying question before destructive actions").
+- **Boundaries** unique to this agent ("only answer questions about domain X, otherwise redirect").
+- **Universal context** that changes per execution (date, user identity, files).
+
+### Exclude
+
+- **Per-tool usage docs** — move to tool descriptions.
+- **Generic safety language** — built in; reinforcing adds tokens without changing behavior. Reserve for specific risks.
+- **"You are a helpful assistant" preamble** — replace with a specific role.
+- **Lengthy examples that aren't earning their tokens** — one sharp example beats five mediocre ones.
+
+---
+
+## Iteration loop
+
+Treat the system prompt like code:
+
+1. Run the agent on representative inputs.
+2. Note where it does the wrong thing.
+3. Decide: system-prompt fix, tool-description fix, or downstream-validation fix?
+4. Make the smallest change that addresses it.
+5. Re-test on the same inputs PLUS one or two new ones.
+6. Watch for regressions on previously-working inputs.
+
+Most "the agent doesn't follow my instructions" issues are conflicts between the system prompt, tool descriptions, and model defaults. Resolve those conflicts first.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Symptom | Fix |
+|---|---|---|
+| "You are a helpful assistant" + no specifics | Generic responses, no identity | Replace with a specific role and scope |
+| 5000-token prompt with a section per tool | Token cost, slow responses, hard to edit | Move tool sections to tool descriptions |
+| Hardcoded date / "current year" | Stale immediately | Inject `{{ $now }}` at runtime |
+| A stack of `DON'T` rules | Model gets defensive, refuses too eagerly | Frame as positive instructions where possible |
+| Multiple pasted "examples" | Cargo-cult, rarely earns its tokens | One sharp example, or none |
+| Per-execution context hardcoded | Hard to update | Build the prompt from a template + variables |
+
+---
+
+## Cross-references
+
+- Tool descriptions as the other half of the split → **TOOLS.md**
+- The system-prompt half of structured output → **STRUCTURED_OUTPUT.md**
+- File-handling injection mechanics → **n8n-binary-and-data**

data/skills/n8n-agents/TOOLS.md

@@ -0,0 +1,199 @@
+# Agent tools
+
+The agent picks tools by reading their **name** and **description** — nothing else. Both are part of the prompt. Treat tool design like API design: what it does, when to use it, what each parameter means, and how it fails.
+
+---
+
+## The four tool types
+
+### 1. Native tool node
+
+Pre-built tool versions of regular nodes: `slackTool`, `gmailTool`, `googleSheetsTool`, `toolCalculator`, `notionTool`, `httpRequestTool`, and so on. Identical to their non-tool counterparts except parameters can be agent-filled via `$fromAI()`.
+
+- **Pros**: minimal config, well-tested, native feel.
+- **Cons**: one node = one operation. Multi-step logic doesn't fit.
+- **Use when**: the capability maps cleanly to one node and one operation.
+
+When a native node is missing an operation or needs a non-standard param shape, point an **HTTP Request Tool** at the service's API with the service's *predefined credential type* — you reuse the existing OAuth/API-key credential and get the full API.
+
+### 2. Sub-workflow as tool (`@n8n/n8n-nodes-langchain.toolWorkflow`)
+
+The default for anything beyond one node. Any workflow becomes a tool with typed `$fromAI()` inputs.
+
+- **Pros**: full power of n8n inside the tool — branching, error handling, sub-sub-workflows, native nodes, custom logic. Reusable across agents. Independently testable.
+- **Cons**: one extra workflow boundary, slight latency.
+- **Use when**: more than one node, logic that might be reused, or you want testability.
+
+The canonical n8n way to build agent capabilities. → **SUBWORKFLOW_AS_TOOL.md**
+
+### 3. HTTP Request Tool (`@n8n/n8n-nodes-langchain.toolHttpRequest`)
+
+A wrapper around the HTTP Request node exposing its parameters to the agent.
+
+- **Pros**: any HTTP API becomes a tool with one node.
+- **Cons**: HTTP only. Auth/retry/error handling are yours to wire.
+- **Use when**: calling a single external API the agent should orchestrate directly.
+
+One thing to know: HTTP Request has its own HTTP-level timeout (default 5 minutes) — bump `options.timeout` for slow endpoints. The agent tool itself has no timeout; the agent waits as long as the tool takes. Pointing it at, say, the Notion API (with the Notion predefined credential) lets the agent compose path, method, and body itself — covering operations the native node doesn't expose. Trade-off: the agent is now writing API requests, which is more error-prone and needs a capable model plus clear endpoint guidance in the description. That widens the blast radius — make sure the user understands.
+
+### 4. MCP Client Tool (`@n8n/n8n-nodes-langchain.mcpClientTool`)
+
+Connects the agent to any MCP server. Two flavors:
+
+- **External MCP servers** — any third-party or self-hosted MCP (GitHub, Linear, Notion, custom internal). One node exposes every tool that server offers.
+- **n8n-hosted MCP** — a workflow on the same instance published with MCP access enabled. Same client node, pointed at an n8n MCP trigger URL. Lets one workflow serve many agents.
+
+- **Cons**: tool descriptions and shapes come from the server, so quality varies and you can't easily tune them. Auth and reachability are yours.
+- **Use when**: a maintained MCP server already covers the capability, or you want one published workflow to serve many agents.
+
+### Plus: Custom Code Tool (`@n8n/n8n-nodes-langchain.toolCode`)
+
+Pure inline computation (math, parsing, formatting). Its runtime contract is **string in / string out, no `$fromAI`, no `$helpers`** and is owned by the **n8n-code-tool** skill — read it before writing one. Rule of thumb: if you want `$fromAI()` in the code, you want `.toolWorkflow` instead.
+
+---
+
+## Decision: which tool type?
+
+```
+Capability the agent needs?
+├── One native node + one operation does it
+│     → native tool node
+├── Native node missing an op / needs custom params for ONE API
+│     → HTTP Request Tool (with the service's predefined credential)
+├── More than one node, or logic that might be reused
+│     → Sub-workflow as tool (.toolWorkflow)   ← default when in doubt
+├── Pure deterministic computation, one-off, inline
+│     → Custom Code Tool (.toolCode)            ← see n8n-code-tool
+└── A maintained MCP server covers it / publish n8n logic to many agents
+      → MCP Client Tool
+```
+
+---
+
+## `$fromAI()`: how the agent fills tool parameters
+
+`$fromAI()` is a **real n8n expression helper**, written inside a tool node's parameter expressions. Parameters the agent should decide get wrapped in it:
+
+```
+sendTo:  ={{ $fromAI('recipient', 'Email address of the recipient', 'string') }}
+subject: ={{ $fromAI('subject', 'Email subject line, concise and informative', 'string') }}
+body:    ={{ $fromAI('body', 'Email body in plain text, professional tone', 'string') }}
+```
+
+Shape: `$fromAI(paramName, description, type?, defaultValue?)`
+
+- **paramName** — the name the model uses internally. snake_case or camelCase, be consistent.
+- **description** — what value to produce. **Part of the prompt.** Be specific: format, range, example.
+- **type** — `'string'` (default), `'number'`, `'boolean'`, `'json'`. Enforced — a wrong-typed value fails the call.
+- **defaultValue** — used when the model omits the parameter.
+
+It carries **JSON only** — it cannot carry binary (no base64, no file bytes), even through a non-AI binding. For binary, pass a storage key as a string and have the tool re-fetch (→ **n8n-binary-and-data**).
+
+A good description vs a useless one:
+
+```
+✅ ={{ $fromAI('imageName', 'Storage key for an existing image to edit, or empty for a new generation. Use the exact key shown in the system prompt; do not reconstruct or guess.', 'string') }}
+
+❌ ={{ $fromAI('imageName', 'image name', 'string') }}   // useless to the model
+```
+
+Treat `$fromAI` descriptions like JSDoc — the model reads them to figure out what to pass.
+
+---
+
+## Plumbed params: hide what the agent shouldn't decide
+
+Not every parameter has to be `$fromAI`. Any parameter can be filled deterministically from workflow context, and **plumbed values are invisible to the agent** — not in the tool schema, not influenceable by anything the model produces:
+
+```
+reason:        ={{ $fromAI('reason', 'Why the user is requesting a refund', 'string') }}   // agent-filled
+customerId:    ={{ $('Chat Trigger').first().json.user.id }}                                 // hidden
+maxRefund:     ={{ $('Get user tier').first().json.refundLimit }}                            // hidden
+idempotencyKey:={{ $('Chat Trigger').first().json.sessionId }}                               // hidden
+```
+
+Plumb anything the agent shouldn't get wrong or see:
+
+- **Identity** — `userId`, `customerId`, authenticated actor, tenant scope.
+- **Authority limits** — refund caps, tier flags, allowed regions.
+- **Correlation IDs** — `sessionId`, idempotency keys, trace IDs.
+
+**Give the agent a button to push, not a steering wheel.** The strongest version is a sensitive tool with **zero `$fromAI` parameters**: a "Refund order" tool takes `orderId` from the trigger, `amount` from the fetched order record, `actor` from the session — all plumbed. The agent literally cannot refund the wrong order; it only chooses whether to fire. Pair with **HUMAN_REVIEW.md** for actions needing both deterministic params and sign-off.
+
+---
+
+## Tool name and description as prompt
+
+Selection process the model runs every turn:
+
+1. It gets the system prompt, conversation, and the list of tools.
+2. For each tool it reads name + description + parameter schema (with `$fromAI` descriptions).
+3. It picks the tool whose description best matches what it needs to do.
+
+**Bad names and descriptions cause bad selection — usually silently.** The model just doesn't call your tool, or calls a different one with garbage parameters. No error.
+
+### Names: verb-first and specific
+
+| Good | Bad | Why |
+|---|---|---|
+| `Search customer database` | `query` / `tool1` | Generic names say nothing |
+| `Generate image with Veo` | `imageGen` | Which generator? |
+| `Edit existing image` | `edit` | Edit what? |
+| `Send Slack message to channel` | `slack` | Name the action, not just the surface |
+| `Lookup user by email` | `getUser` | Lookup how? |
+
+### Descriptions: three parts
+
+1. **What it does** (one sentence).
+2. **When to use it** (one or two sentences, with boundaries / examples).
+3. **Parameter notes** (only if not already covered in `$fromAI` descriptions).
+
+```
+Edit existing image: Modifies an image the user already uploaded, based on a prompt.
+Use when the user uploaded an image and asks for changes (color, style, composition, content).
+Do NOT use for generating new images from scratch — use Generate Image for that.
+The imageName parameter must be the storage key of the existing image as listed in your
+available files; do not pass the original filename or a URL.
+```
+
+That description does work that would otherwise bloat the system prompt — which is exactly the point.
+
+---
+
+## Tool descriptions as modular prompts
+
+Anything specific to *how to call this tool* belongs in the tool's description, not the system prompt:
+
+| In the system prompt (move out) | Better in the tool description |
+|---|---|
+| "When generating images, prefer realistic photography over `8k cinematic`" | `Generate Image`: "Default to realistic photography aesthetics…" |
+| "If the search tool returns nothing, summarize politely" | `Search`: "Returns up to 10 results; if empty, report 'no matches' rather than retrying broader" |
+| "Use 9:16 for video tools" | `Generate Video`: "Defaults to 9:16; pass `aspectRatio: '16:9'` for landscape" |
+
+Three reasons: **reusability** (the tool teaches each new agent how to use it), **token efficiency** (per-tool guidance only loads when the model considers that tool, not every turn), **maintainability** (one description, not a buried paragraph).
+
+---
+
+## Granularity: one tool with branching, not two near-identical tools
+
+The model gets confused choosing between near-identical tools. If two are ~80% the same internally:
+
+- **One tool with a branching parameter.** `Generate Image` vs `Edit Image` share most logic → collapse to one with an `imageName` parameter (empty = generate, populated = edit).
+- **Two tools only when genuinely distinct AND the descriptions clearly differentiate.** `Send DM` vs `Send Channel Message` are distinct.
+
+---
+
+## Operational notes
+
+- **maxIterations.** Agents have a configurable tool-call cap (`options.maxIterations`), and the default is **low**. A multi-tool agent that chains calls hits it and surfaces "max iterations reached" or empty output. Raise it. Build a fallback — don't trust graceful recovery.
+- **Tool-call cost.** Each call is at minimum one extra model round-trip. Frequently-called tools should return **concise** results — bloated returns burn input tokens fast.
+- **Tool failure handling.** Set `onError: 'continueErrorOutput'` on tool sub-workflows where you want the agent to receive an error string instead of halting; the agent can retry, switch tools, or report. → **n8n-error-handling**.
+
+---
+
+## Cross-references
+
+- The sub-workflow tool pattern in detail → **SUBWORKFLOW_AS_TOOL.md**
+- System-prompt-vs-tool-description split → **SYSTEM_PROMPT.md**
+- Passing binary into tools → **n8n-binary-and-data**
+- The Custom Code Tool contract → **n8n-code-tool**

data/skills/n8n-binary-and-data/AGENT_TOOL_BINARY.md

@@ -0,0 +1,227 @@
+# Agent Tools and Binary
+
+The hard wall: an AI Agent and its tools talk to each other in JSON. Binary doesn't fit through that pipe in either direction, and it catches people twice.
+
+1. **Inbound** — a user uploads a file. The agent can *see* an image via vision, but tool calls don't carry the file.
+2. **Outbound** — a tool generates a file. Its result back to the agent is JSON, so it can't return raw bytes.
+
+The workaround has the same shape both ways: **stage the bytes in storage, pass a key or URL through the JSON boundary, fetch on the other side.**
+
+## Contents
+
+- [Why the boundary exists](#why-the-boundary-exists)
+- [Inbound: an uploaded file into a tool](#inbound-an-uploaded-file-into-a-tool)
+- [The two pieces of plumbing that look optional](#the-two-pieces-of-plumbing-that-look-optional)
+- [What the system prompt and the tool argument look like](#what-the-system-prompt-and-the-tool-argument-look-like)
+- [passthroughBinaryImages](#passthroughbinaryimages)
+- [Outbound: a tool that produces a file](#outbound-a-tool-that-produces-a-file)
+- [Storage choices](#storage-choices)
+- [Hashing, cleanup, long-running tools](#hashing-cleanup-long-running-tools)
+- [Surface-specific seams](#surface-specific-seams)
+- [Common mistakes](#common-mistakes)
+
+---
+
+## Why the boundary exists
+
+A tool call is a function call the LLM makes by emitting JSON arguments; the result comes back as a JSON observation. Tool parameters are filled by `$fromAI()`, which only produces strings, numbers, booleans, and objects — never file bytes. And a tool's return is a string/JSON the model reads as text. Base64-stuffing a 2 MB image into a JSON field would bloat every tool call and the agent's context window, and some runtimes reject oversized observations outright. So in practice: **binary never crosses the boundary.**
+
+---
+
+## Inbound: an uploaded file into a tool
+
+The user pastes an image into chat. The chat trigger exposes a `files[]` array. If the agent only needs to *look* at the image, `passthroughBinaryImages: true` on the agent handles that (vision). But the moment a **tool** must operate on the file — OCR, image edit, document parse — the tool can't receive it directly. You pre-stage it.
+
+```
+[Chat Trigger]
+   │ files[]
+   ▼
+[IF: files empty?]
+   ├── empty ────────────────────────────────────────────► [AI Agent]
+   └── not empty:
+         [Split Out files]
+            ↓
+         [Crypto: hash → storage key]
+            ↓
+         [HTTP Request / S3 / Drive: upload to PRIVATE storage by key]
+            ↓
+         [Merge: combineByPosition]  ← synchronization barrier, see below
+            ↓
+         [AI Agent]   ← executeOnce: true; system prompt is told the keys
+              │ tool call:  imageKey = "sess12-abc123.png"
+              ▼
+         [Call n8n Workflow Tool → sub-workflow]
+              ↓
+            [Download from storage by key]
+              ↓
+            [Operate on bytes: edit / OCR / parse]
+              ↓
+            [Upload result, return JSON { key, url }]
+```
+
+Building this with the community MCP server, the wiring goes in as `n8n_update_partial_workflow` operations — `addNode` for each step, `addConnection` to thread them, and `updateNode`/`patchNodeField` to set `executeOnce` and the system prompt. The agent's tool is a `Call n8n Workflow Tool` node pointed at the sub-workflow; the sub-workflow itself is a normal workflow that starts with an Execute Workflow Trigger.
+
+> The Execute Workflow Trigger's input mode matters here. The default typed-input mode carries only named JSON fields and **drops `$binary`** at the boundary; for a sub-workflow that needs to receive binary directly, use the passthrough input mode. (When the sub-workflow downloads by key instead of receiving bytes, this is moot — which is exactly why the key pattern is cleaner.)
+
+---
+
+## The two pieces of plumbing that look optional
+
+Both of these are silent-failure traps — leave them out and the workflow runs, then misbehaves.
+
+**The Merge is a synchronization barrier, not decoration.** The chat trigger fans out to the IF branch and the upload branch in parallel. Without merging the upload branch back before the agent, the agent fires while uploads are still in flight. The system prompt's key template then renders against partial state, the model gets keys that don't exist in storage yet, and the tool's download 404s. The Merge forces the agent to wait for the upload to finish.
+
+**`executeOnce: true` on the AI Agent node.** When files split out and merge back, the merged item count equals the file count. Without `executeOnce`, the agent runs once per file — N agent runs, N replies, N times the token cost — for what is one logical user message. Set it on the agent node:
+
+```json
+{ "executeOnce": true }
+```
+
+(Apply with `patchNodeField` on the agent node, or include it in the `updateNode` payload.)
+
+---
+
+## What the system prompt and the tool argument look like
+
+The agent has to know which keys exist *for this turn*. Inject them into the system prompt, listing both the original name (human context for the model) and the storage key (what the tool needs):
+
+```
+## File Handling
+Files passed in this turn:
+{{ JSON.stringify($('Chat Trigger').first().json.files.map((f, i) => ({
+    originalFileName: f.fileName,
+    storageKey: $('Crypto').all()[i].json.hash + '.' + f.fileExtension
+})), null, 2) }}
+
+CRITICAL: Use EXACTLY the `storageKey` value above when calling a tool. Do not paraphrase or reconstruct it.
+```
+
+Two details earn their keep:
+
+1. **Both names are listed.** The original (`photo.png`) tells the model what kind of file it is; the storage key is what the tool can actually resolve.
+2. **The "use EXACTLY".** Without it, the model paraphrases — "the user's image", "photo.png" — and the tool can't find the file.
+
+On the tool side, the storage-key parameter is bound with `$fromAI` and described so the model fills it correctly:
+
+```
+$fromAI('imageKey', 'Storage key of an existing uploaded image to operate on, taken verbatim from the system prompt (e.g. "sess12-abc123.png"). Leave empty to generate a new image. Do not invent or reconstruct keys.', 'string')
+```
+
+The description is the model's only guidance on the value's shape — match it to the storage backend the workflow actually uses, and name only that one shape (not a menu of possibilities).
+
+**Generate vs edit in one tool.** If the tool serves both "make a new image" and "edit this one", branch inside the sub-workflow on whether `imageKey` is empty — empty means generate, present means download-then-edit. One tool with an internal IF is usually clearer for the model than two near-identical tools. If the model keeps misfiring on that discriminator, the viable alternative is two `Call n8n Workflow Tool` nodes pointing at the **same** sub-workflow with different parameter wiring (one hardcodes an empty key, the other lets the model fill it) — one sub-workflow, two front doors with sharply different descriptions.
+
+---
+
+## passthroughBinaryImages
+
+Set `passthroughBinaryImages: true` on the agent when the model should be able to *see* uploaded images (multimodal vision). It adds the image to the LLM's prompt context.
+
+Two limits to keep straight:
+
+- **Image-only.** It does nothing for PDFs, audio, or video. For those, the model only knows what the system prompt tells it (name, type, storage key) and must call a tool to extract content. For PDFs, that means an OCR/parse tool.
+- **It does not feed tools.** Tools still receive only their `$fromAI` parameters, regardless of this flag. Vision and tool access are separate channels:
+  - `passthroughBinaryImages: true` → the model can *see and reason about* the image.
+  - Pre-staged storage + key in the prompt → the model can ask a tool to *do something* with the file.
+
+You usually want both at once.
+
+---
+
+## Outbound: a tool that produces a file
+
+A tool generates a PDF, image, or document. Its result to the agent is JSON, so it returns a *reference*, not the bytes.
+
+```
+[Agent calls tool]
+   ▼
+[Sub-workflow]
+   ↓ generate or transform binary
+   ↓ (provider AI node: set options.binaryPropertyOutput so bytes land in the slot)
+   [Upload to storage by key]
+   ↓
+   [Respond with JSON: { ok, key, url, mimeType, sizeBytes, expiresAt }]
+   ▼
+[Agent receives JSON — embeds the URL in its reply, or passes the key to another tool]
+```
+
+A useful return shape:
+
+```json
+{
+  "ok": true,
+  "key": "sess12-9f3c1a.png",
+  "url": "https://storage.example.com/files/sess12-9f3c1a.png",
+  "mimeType": "image/png",
+  "sizeBytes": 184320,
+  "expiresAt": "2026-06-25T12:00:00Z"
+}
+```
+
+Then tell the agent how to present it, in the system prompt — and be explicit about images vs video, because the model will copy the image pattern onto video and produce a broken thumbnail:
+
+```
+## Display Protocol
+Show generated images inline using markdown: ![alt text](url)
+Share generated VIDEO as a plain link, NOT an embed: [title](url)
+```
+
+(The `![]()` markdown is the canvas chat trigger's syntax — production surfaces differ; see [Surface-specific seams](#surface-specific-seams).)
+
+**When you don't need any of this:** if one node generates binary and another consumes it *in the same workflow* with no agent involved, just pass binary through normally — there's no boundary. And a plain webhook API that returns a file can use `Respond to Webhook` with binary in the body. The upload-and-return-key dance is specifically for the agent-calls-tool-and-tool-produces-a-file case.
+
+---
+
+## Storage choices
+
+**Ask which service before building.** n8n has native nodes for many backends, and defaulting to S3 is presumptuous.
+
+- **Object storage:** Amazon S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Backblaze B2, Supabase Storage. Most expose S3-compatible APIs (the S3 node with the right endpoint, or HTTP Request with AWS auth) or ship a dedicated node. Keys, optional public buckets, signed URLs, lifecycle rules for TTL.
+- **Drive-style:** Dropbox, Google Drive, OneDrive, Box. File IDs and share links instead of keys, folder permissions instead of bucket ACLs, no built-in TTL (cleanup is its own workflow).
+- **Self-hosted / FTP / SFTP:** when the user has on-prem infrastructure.
+- **Caller-supplied URL:** the agent's caller provides the storage location as input.
+
+A common production split: a **private** bucket/folder for inbound user files, and a **public** (or signed-URL) bucket/folder for outbound results so the agent can return a fetchable URL. The choice changes credential setup, URL shape, and how the tool's `$fromAI` description should explain the key/URL format — don't pick on the user's behalf.
+
+---
+
+## Hashing, cleanup, long-running tools
+
+**Hash strategy differs by direction:**
+
+- **Inbound** files may be referenced repeatedly within a session, so use a stable key — re-uploading the same file lands at the same key and the agent's reference doesn't break. A session-and-filename composite hash works.
+- **Outbound** artifacts are single-use, so use a fresh random key every time, or concurrent generations overwrite each other. Pattern: `<session-suffix>-<random-hex>.<ext>`.
+
+Two `Crypto` nodes in one of these workflows is usually deliberate, not a copy-paste error — one for the inbound stable hash, one for the outbound unique suffix.
+
+**Cleanup** keeps the bill down. Object storage has lifecycle rules (auto-delete after 7–30 days). Drive-style backends need a scheduled cleanup workflow. For precise control, track live keys in a Data Table (the `n8n_manage_datatable` surface — see **n8n-mcp-tools-expert**) and delete unreferenced files.
+
+**Long-running tools** (video generation, large batches): agent tool calls have no agent-layer timeout — a sub-workflow tool returns whenever it returns and the agent waits. The one real timeout is on the **HTTP Request node** itself (default ~5 minutes). If the tool is an HTTP Request Tool calling a slow external API, bump `options.timeout` past the expected duration, or the HTTP call aborts mid-job while the work keeps running and the agent gets nothing. Error-branch these steps so a failed upload or a storage 404 surfaces instead of vanishing — see **n8n-error-handling**.
+
+---
+
+## Surface-specific seams
+
+The examples above use the canvas Chat Trigger's conventions: `$('Chat Trigger').first().json.files[]` inbound, `![]()` markdown outbound. **These shapes are not universal.** Production surfaces (Slack, Discord, Microsoft Teams, Telegram, WhatsApp Business, custom webhooks) each differ on:
+
+- **Inbound file event shape** — where the file lives in the trigger payload, and whether the file URL needs a bearer/bot token to download.
+- **Outbound rendering** — markdown image, Block Kit image block, adaptive card, Discord embed, or a dedicated file-upload API that pushes bytes natively.
+
+Before wiring an inbound or outbound binary path on a real surface, check the platform's official API docs and the n8n node docs for two things: the exact path to the file in the trigger event (and whether downloading it needs auth), and the exact shape the platform expects for an image/file in a reply. Get those right and the patterns here carry over; guess from the canvas examples and the workflow ships looking correct, then fails on real messages.
+
+---
+
+## Common mistakes
+
+| Mistake | Consequence | Fix |
+|---|---|---|
+| Passing binary through `$fromAI()` | Can't carry binary; tool gets nothing | Pass a key/URL, re-fetch on the other side |
+| Forgetting to inject keys into the system prompt | Agent hallucinates names or refuses | List original + storage key, "use EXACTLY" |
+| Skipping the Merge synchronization barrier | Agent fires before uploads finish; tool 404s | Merge the upload branch back before the agent |
+| Forgetting `executeOnce: true` when files split | N files → N agent runs → N replies | Set `executeOnce: true` on the agent |
+| Forgetting `options.binaryPropertyOutput` on provider AI nodes | Produced bytes don't land where upload looks | Set it explicitly on image/audio/video gen nodes |
+| Public bucket for inbound user files | Privacy hole | Private bucket, session-scoped keys, short TTL |
+| Returning binary in the tool response | Bloated context, some runtimes reject | Upload, return `{ key, url }` |
+| Assuming `passthroughBinaryImages` feeds tools | Tools still get only `$fromAI` params | Use the upload-and-pass-key pattern |
+| Default HTTP timeout on a slow generation endpoint | Call aborts mid-job, agent gets nothing | Bump `options.timeout` past expected duration |
+| Embedding video as `![]()` | Broken thumbnail on most surfaces | Use `[title](url)` link form for video |

data/skills/n8n-binary-and-data/BINARY_BASICS.md

@@ -0,0 +1,187 @@
+# Binary Basics
+
+The `$binary` slot in depth: its shape, which nodes fill and read it, how to handle the bytes in a Code node, mime types, size limits, and how to confirm a file actually made it through.
+
+## Contents
+
+- [The slot shape](#the-slot-shape)
+- [Which nodes produce binary](#which-nodes-produce-binary)
+- [Which nodes consume binary](#which-nodes-consume-binary)
+- [Reading binary in a Code node](#reading-binary-in-a-code-node)
+- [Writing binary in a Code node](#writing-binary-in-a-code-node)
+- [Mime types](#mime-types)
+- [File-size limits](#file-size-limits)
+- [Inspecting binary in an execution](#inspecting-binary-in-an-execution)
+- [When binary is the trigger input](#when-binary-is-the-trigger-input)
+
+---
+
+## The slot shape
+
+Every item has two top-level keys. `json` is your data; `binary` is your files. They are independent — a transform that rewrites `json` doesn't automatically carry `binary`, and vice versa.
+
+```json
+{
+  "json": { "customerId": 42, "status": "sent" },
+  "binary": {
+    "invoice": {
+      "data": "<base64-encoded bytes>",
+      "mimeType": "application/pdf",
+      "fileName": "invoice-42.pdf",
+      "fileExtension": "pdf",
+      "fileSize": "12 kB"
+    }
+  }
+}
+```
+
+The key inside `binary` — `invoice` here — is the **binary property name**. It can be anything; `data` is the default that most nodes use. File-handling nodes expose a `binaryPropertyName` parameter that points at this key, so the producer names the slot and every consumer references it by that exact name. Get the name wrong on the consumer and it looks for a slot that doesn't exist.
+
+The four fields that matter:
+
+| Field | What it is |
+|---|---|
+| `data` | The bytes, base64-encoded |
+| `mimeType` | How consumers should interpret the bytes (`application/pdf`, `image/png`, …) |
+| `fileName` | Used by email attachments, uploads, downloads to disk |
+| `fileExtension` | Often derived from `fileName`; some nodes use it directly |
+
+---
+
+## Which nodes produce binary
+
+You almost never assemble the slot by hand — a node populates it:
+
+| Node | What to set | Result |
+|---|---|---|
+| HTTP Request | `responseFormat: "file"` | Response body in `$binary.data` (or the name in `options`) |
+| Read/Write Files from Disk (read) | the file path | File contents in `$binary` |
+| S3 / Google Drive / Dropbox (download) | the file reference | Downloaded file in `$binary.<key>` |
+| Email triggers (IMAP, Gmail trigger) | attachment handling on | Each attachment in `$binary` |
+| Provider AI media nodes (image/audio gen) | `options.binaryPropertyOutput` | Generated bytes in the named slot |
+
+The single most common bug here: an **HTTP Request download left on the default response format**. Without `responseFormat: "file"`, n8n tries to parse the body as JSON or text and you end up with a corrupted string in `$json` instead of clean bytes in `$binary`. Confirm the field with `get_node` on `nodes-base.httpRequest` — the response-handling options sit under different shapes across versions.
+
+Provider AI nodes (image generation, text-to-speech) are the other recurring trap: many don't emit binary unless you set `options.binaryPropertyOutput` explicitly. Without it, the next node has nothing to upload.
+
+---
+
+## Which nodes consume binary
+
+Consumers reference the slot by its property name:
+
+| Node | How it references binary |
+|---|---|
+| Email (Send) | attachment field points at `binaryPropertyName` |
+| Slack (send file) | references the binary property |
+| HTTP Request (multipart/form-data) | references binary in the body parameters |
+| Storage upload (S3, R2, Drive) | references binary as the request body |
+| Write Files to Disk | writes the named binary property to a path |
+
+The pattern is always the same: producer names a property, consumers point at that name. Most "the file didn't attach" bugs are a property-name mismatch between the two ends — verify both with `get_node` and by inspecting the execution.
+
+---
+
+## Reading binary in a Code node
+
+Most workflows never read the bytes — they pass binary straight through to a consumer. When you genuinely need the bytes (hashing, parsing, text extraction), use `getBinaryDataBuffer` in a Code node. Do **not** grab `$binary.<key>.data` and base64-decode it yourself; the helper handles n8n's storage modes (in-memory vs filesystem) for you.
+
+```javascript
+// Code node, "Run Once for Each Item"
+const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); // (itemIndex, propertyName)
+
+const text = buffer.toString('utf-8'); // for text-like files
+const length = buffer.length;
+
+return [{
+  json: { ...$json, length },
+  binary: $input.item.binary,   // ← pass the file through, or it's gone after this node
+}];
+```
+
+`getBinaryDataBuffer(itemIndex, propertyName)` returns a Node `Buffer`. Treat it like any buffer — slice it, hash it, decode it. The language-level specifics (which helpers exist, execution modes, `$input` vs `$json`) belong to the **n8n-code-javascript** skill; the only binary-specific rule is the one in the comment above: **if you don't return `binary`, the file is dropped at this node.**
+
+> Reading a PDF's text is not as simple as `buffer.toString('utf-8')` — PDF is a binary container, not UTF-8 text. You need a real parse step (an OCR/extract node, or a dedicated library in an environment that has one). The buffer gives you the bytes; turning them into readable text is a separate problem.
+
+---
+
+## Writing binary in a Code node
+
+Build the slot yourself: base64 the bytes, then add a mime type and file name so consumers know what they're getting.
+
+```javascript
+const text = 'Hello, world!';
+
+return [{
+  json: { ok: true },
+  binary: {
+    report: {
+      data: Buffer.from(text).toString('base64'),
+      mimeType: 'text/plain',
+      fileName: 'report.txt',
+      fileExtension: 'txt',
+    },
+  },
+}];
+```
+
+Skip `mimeType` and downstream consumers may refuse the file or render it wrong (an email won't attach it cleanly, Slack shows a generic file icon instead of an inline image). Always set it.
+
+---
+
+## Mime types
+
+`mimeType` is the contract between producer and consumer. A wrong value doesn't error — it makes the consumer misbehave: refuse to attach, render as a download instead of inline, or show a broken thumbnail.
+
+| File type | Mime type |
+|---|---|
+| PDF | `application/pdf` |
+| PNG | `image/png` |
+| JPEG | `image/jpeg` |
+| Plain text | `text/plain` |
+| JSON | `application/json` |
+| CSV | `text/csv` |
+| XLSX | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| ZIP | `application/zip` |
+
+When the source doesn't tell you the type, sniff it from the leading bytes — PDF starts with `%PDF-`, PNG with `\x89PNG`, JPEG with `\xFF\xD8\xFF`. A few lines of magic-byte checking in a Code node is a reliable fallback when you can't trust the upstream metadata.
+
+---
+
+## File-size limits
+
+Execution data is stored in n8n's database, and large base64 blobs bloat it and slow the instance down. Rough guidance:
+
+| Size per slot | Verdict |
+|---|---|
+| A few MB | Fine |
+| Tens of MB | Works, but slower; watch instance memory |
+| 100 MB+ | Offload to external storage and pass a URL/ID instead |
+
+For large files, the pattern is: upload to object storage as soon as the bytes exist, thread the URL or key through the workflow as plain JSON, and re-fetch only at the node that actually needs the bytes. This keeps the per-item payload small and the execution fast. (If a self-hosted instance uses filesystem binary-data mode rather than in-memory, the database pressure is lower, but the same offload advice holds for genuinely large files.)
+
+---
+
+## Inspecting binary in an execution
+
+`validate_workflow` will not tell you whether binary survived a node — a dropped slot is a silent failure. The only reliable check is the execution itself:
+
+1. Run the workflow (`n8n_test_workflow`, or trigger it for real).
+2. Pull the execution with `n8n_executions` and look at per-node output for the `binary` slot.
+3. The slot shows presence and metadata (name, mime type, size) even when the base64 is too large to render in full. Its presence or absence on each node is what you're checking.
+
+The node where `binary` last appears, then vanishes on the next, is exactly where a pass-through or a Merge needs to go. (See `MERGE_FOR_CONTEXT.md`.)
+
+---
+
+## When binary is the trigger input
+
+For workflows that receive a file — a multipart webhook upload, an email attachment, a watched folder — the binary arrives at the **trigger's output**:
+
+- Reference it by its binary property name from the trigger onward.
+- Pass it through every downstream node that needs it (each is a potential strip point).
+
+If binary doesn't show up at the trigger output, check:
+
+- **Content-type handling.** A Webhook receiving `multipart/form-data` puts files in `$binary` and form fields in `$json.body`; one receiving JSON has no binary at all. Expression-level detail on `$json.body` for webhooks lives in **n8n-expression-syntax**.
+- **The trigger's binary settings.** Some triggers skip attachments unless explicitly told to download them.

data/skills/n8n-binary-and-data/CDN_REQUIREMENT.md

@@ -0,0 +1,109 @@
+# The CDN / URL Requirement for Chat Surfaces
+
+When a workflow generates an image and the user wants it shown inside a chat message — Slack, Discord, Teams, Telegram, embedded webhook chat — the image in `$binary` is not enough. Chat clients render messages that reference images by **URL** (or push bytes through the platform's own file-upload API). None of them read the `$binary` slot. The bytes have to live somewhere a URL can fetch them over HTTPS, and n8n does not bundle a CDN — the user provides the storage.
+
+## Contents
+
+- [Why $binary doesn't display](#why-binary-doesnt-display)
+- [What the user needs](#what-the-user-needs)
+- [What the workflow does](#what-the-workflow-does)
+- [How to tell the user](#how-to-tell-the-user)
+- [Signing and expiration](#signing-and-expiration)
+- [File naming](#file-naming)
+- [Cleanup](#cleanup)
+
+---
+
+## Why $binary doesn't display
+
+A chat message is HTML or a JSON block. An embedded image is a reference to a URL:
+
+```html
+<img src="https://cdn.example.com/img/abc123.png">
+```
+
+Some surfaces accept bytes directly through a platform file API instead of a URL — Slack's two-step `files.getUploadURLExternal` + `files.completeUploadExternal`, Discord attachments, Telegram `sendPhoto`. Either way, the bytes have to be reachable: either at a URL the client fetches, or handed to the platform's upload endpoint. The raw `$binary` slot inside an n8n execution is neither — it's internal to the workflow run.
+
+---
+
+## What the user needs
+
+A place that serves the image over a fetchable URL. Ask what they already have, but lead with a recommendation:
+
+1. **A real object store / CDN (recommended).** Cloudflare R2, AWS S3 (+ CloudFront), Google Cloud Storage, Azure Blob, Backblaze B2, Vercel Blob, Supabase Storage, Bunny CDN. Direct URL embedding works once the object is public, edge caching keeps latency low, and signed-URL flows are first-class. Cloudflare R2 is the lowest-friction starting point if they have nothing — a few minutes to set up, generous free tier, no egress fees.
+2. **Drive-style services (fallback).** Dropbox, Google Drive, OneDrive, Box can produce shareable links, but the URL shape and whether it renders as an `<img src>` varies, and some need the share link converted to a direct-download URL first. Confirm the service can serve an inline-renderable URL before committing to it.
+3. **Self-hosted.** The user serves from their own domain. Fine if it already exists; don't propose standing one up just for this.
+
+The right choice depends on the user's existing infrastructure, cost tolerance, and how sensitive the content is.
+
+---
+
+## What the workflow does
+
+The shape is always generate → upload → reply-with-URL:
+
+```
+[Generate image] → [Upload to storage] → [Set: imageUrl = response URL] → [Send chat reply referencing imageUrl]
+```
+
+Concretely, uploading to an S3-compatible store (R2 here) via the HTTP Request node:
+
+```
+[AI node: generate image]            ← set options.binaryPropertyOutput so bytes land in $binary
+   ↓ binary on the item
+[HTTP Request: PUT to R2]
+   url: https://<account>.r2.cloudflarestorage.com/<bucket>/<key>
+   authentication: AWS-style signed (or the S3 node with the R2 endpoint)
+   contentType: binaryData
+   binaryPropertyName: data
+   ↓
+[Set: { imageUrl: "https://pub-<id>.r2.dev/<key>" }]
+   ↓
+[Send to chat surface: imageUrl embedded — markdown, Block Kit image block, adaptive card, etc.]
+```
+
+Upload mechanics vary by provider; most expose S3-compatible APIs usable through n8n's S3 node or HTTP Request with AWS auth. Confirm the upload node's field names (`contentType`, `binaryPropertyName`) with `get_node`, and **error-branch the upload** so a failed write surfaces instead of producing a reply that references a URL that was never written — see **n8n-error-handling**. The exact reply shape per platform is surface-specific (see `AGENT_TOOL_BINARY.md`).
+
+---
+
+## How to tell the user
+
+Don't quietly ship a workflow that generates images "but they don't display." Surface the requirement before building:
+
+> "I can generate the image, but the chat surface can't display raw binary — it embeds images by URL. So I'll need to upload the image somewhere that serves a public URL first. What do you use for image/file storage today (R2, S3, GCS, Dropbox, Google Drive, …)? If you don't have anything set up, Cloudflare R2 is the lowest-friction starting point."
+
+There is no fallback that hides this — n8n won't host the file. If the user has no storage, pause until they pick a service and provision a bucket and credentials, then resume. (Posting the URL as a plain link rather than an inline image is a lighter option if inline rendering isn't critical — but that link still has to come from somewhere.)
+
+---
+
+## Signing and expiration
+
+| URL type | Trade-off | Use for |
+|---|---|---|
+| **Public** | Anyone with the URL can fetch it; simplest | Non-sensitive content (already-public assets) |
+| **Signed, with expiry** | Per-request URL that expires (e.g. 1 hour) | Sensitive or user-specific content |
+
+For internal chat with scoped channels, public is usually fine — the URL only lives inside messages a known set of users sees. For compliance-sensitive content, default to signed URLs with a short expiry. A permanently public, unguessable-but-non-expiring URL is a slow leak for anything private.
+
+---
+
+## File naming
+
+| Scheme | Example | Note |
+|---|---|---|
+| UUID / random | `img/abc-123-def-456.png` | Unguessable; good default |
+| Content hash | `img/sha256-abc123….png` | Free deduplication |
+| User-prefixed | `users/<userId>/<name>.png` | Easy per-user cleanup |
+
+Avoid user-controlled filenames (path traversal, collisions) and sequential IDs (predictable, scrapeable).
+
+---
+
+## Cleanup
+
+Without it, storage costs grow:
+
+- **Lifecycle rules** — object stores (S3, R2, GCS, Azure Blob) auto-delete objects after N days. 7–30 days is usually plenty for chat use cases.
+- **Scheduled cleanup workflow** — for drive-style backends that have no TTL, run a workflow that lists and deletes old files.
+
+Ask the user's retention preference rather than picking a window for them — chat artifacts are often disposable, but some surfaces (audit, support transcripts) need them kept.

data/skills/n8n-binary-and-data/MERGE_FOR_CONTEXT.md

@@ -0,0 +1,130 @@
+# Merge for Keeping Binary in Context
+
+A common, maddening bug: an item carries both `json` and `binary`, it runs through a JSON-only node (Edit Fields, Code, IF), the binary slot quietly disappears, and the email node three steps later has nothing to attach. No error, no validation warning — just a missing file.
+
+The fix is to keep the binary on a branch that doesn't touch it, and recombine. This is the same Merge node covered in **n8n-node-configuration**'s gotchas; here it's used specifically to re-attach binary.
+
+## Contents
+
+- [The pattern](#the-pattern)
+- [Wiring it with n8n-mcp](#wiring-it-with-n8n-mcp)
+- [Configuring the Merge](#configuring-the-merge)
+- [Why it works](#why-it-works)
+- [Cheaper alternative: pass-through on the transform](#cheaper-alternative-pass-through-on-the-transform)
+- [When Merge isn't enough](#when-merge-isnt-enough)
+- [Verifying after merge](#verifying-after-merge)
+- [Common mistakes](#common-mistakes)
+
+---
+
+## The pattern
+
+Split the stream at the source: one branch does the JSON work, the other carries the original item (binary intact) untouched. Merge them back.
+
+```
+[Source with binary] ─┬─→ [Edit Fields: change JSON] ─┐
+                      │      (binary stripped here)     │
+                      │                                 ├─→ [Merge: combineByPosition] ─→ [Email: attach]
+                      │                                 │
+                      └──────────────────────────────────┘
+                          (bypass — binary passes through unchanged)
+```
+
+- **Transform branch:** does the JSON work; may lose binary. That's fine — this branch only contributes the JSON.
+- **Bypass branch:** the original item, with binary. No node needed; just route the connection straight into the Merge.
+
+The merged item gets its JSON from the transform branch and its binary from the bypass branch.
+
+---
+
+## Wiring it with n8n-mcp
+
+The source already feeds the transform branch. You add the bypass connection and the Merge with `n8n_update_partial_workflow`:
+
+```json
+{
+  "operations": [
+    { "type": "addNode", "node": {
+        "name": "Merge",
+        "type": "n8n-nodes-base.merge",
+        "parameters": { "mode": "combine", "combineBy": "combineByPosition" }
+    }},
+    { "type": "addConnection", "source": "Edit Fields", "target": "Merge", "targetInput": 0 },
+    { "type": "addConnection", "source": "Source",      "target": "Merge", "targetInput": 1 },
+    { "type": "addConnection", "source": "Merge",       "target": "Send Email" }
+  ]
+}
+```
+
+The exact parameter names (`mode`, `combineBy`, `combineByPosition`, and how `numberOfInputs` is expressed) have shifted across Merge node versions — confirm the current shape with `get_node` on `nodes-base.merge` for the user's version before committing the structure. The principle is stable; the field names move.
+
+Two wiring details that bite (both detailed in **n8n-node-configuration**'s Merge section):
+
+- The Merge defaults to **2 inputs**. If you wire 3+ branches, set the input count to match or the extra branch silently drops.
+- Connection input indexes are **0-based**. The bypass branch above lands on `targetInput: 1` (the second input).
+
+---
+
+## Configuring the Merge
+
+For re-attaching binary, you want position-based combination:
+
+| Mode | What it does | Use for binary re-attach? |
+|---|---|---|
+| `combineByPosition` | Pairs item N from input 1 with item N from input 2 | ✅ Yes |
+| `combineBySql` / `combineByFields` | Joins on a key | Only if the two branches share a join key |
+| `combineAll` | Cartesian product (N×M items) | ❌ No — explodes the item count |
+| `append` | Concatenates inputs end to end | ❌ No — doesn't pair items |
+
+`combineByPosition` is the right default: it keeps the item count at N and pairs each transformed JSON item with its corresponding binary-bearing original. For this to work, both branches must emit items in the same order and count — which they do when they share a single source.
+
+---
+
+## Why it works
+
+A Merge combines both `json` and `binary` from the items it pairs. When one input holds the JSON you want and the other holds the binary you want, the merged item carries both. The binary survives because it traveled on the branch that never touched it.
+
+---
+
+## Cheaper alternative: pass-through on the transform
+
+If the transforming node can preserve binary itself, do that instead — it's one node, not three:
+
+- **Edit Fields (Set):** enable `includeOtherFields` so the node carries unmentioned fields and the binary slot forward.
+- **Code node:** return `binary: $input.item.binary` explicitly in the returned item (see `BINARY_BASICS.md`).
+- **IF / Filter:** these route items rather than rebuild them, and generally preserve binary on the items they pass — but verify in the execution rather than assuming.
+
+Reach for Merge only when the transforming node genuinely can't carry the binary, or when the JSON and binary come from genuinely different upstream nodes.
+
+---
+
+## When Merge isn't enough
+
+If the chain has many strip points, threading binary through all of them — and Merging at each one — becomes more work than it's worth. Two better routes:
+
+- **Upload early.** Push the bytes to object storage as soon as they exist, carry the URL/key as plain JSON through the whole chain (JSON survives every transform trivially), and re-fetch only at the node that needs the bytes. This is also the right move for large files (see `BINARY_BASICS.md`).
+- **Push the binary work into a sub-workflow.** Hand the file to a sub-workflow that does the binary handling and returns the final result. The Execute Workflow Trigger's input mode matters: the default typed-input mode carries only named JSON fields and drops `$binary`, so use the passthrough input mode if the sub-workflow must receive bytes directly.
+
+Past a couple of strip points, one of these is usually less work — and less fragile — than keeping every node in a long chain honest about binary.
+
+---
+
+## Verifying after merge
+
+A merged-but-missing binary won't show in validation. Confirm in the execution:
+
+1. Run with `n8n_test_workflow`, then pull the execution with `n8n_executions`.
+2. On the Merge node's output, check the merged item has the `json` from the transform branch **and** the `binary` from the bypass branch.
+3. If binary is missing: check the Merge mode (some modes don't pair the way you expect) and confirm the bypass branch actually carried binary into the Merge in the first place.
+
+---
+
+## Common mistakes
+
+| Mistake | Symptom | Fix |
+|---|---|---|
+| Noticing the strip too late | The original binary is already gone | Inspect the execution after each node during development |
+| "Merging" a single-source chain with no bypass | Nothing to merge with; binary still missing | Split the stream at the source so binary rides a bypass branch |
+| `combineAll` where you meant `combineByPosition` | N×M items instead of N | Choose the mode deliberately |
+| Bypass branch on the wrong input index | Wrong pairing, or the branch drops | Connections are 0-based; verify with `n8n_get_workflow` |
+| Forgetting to raise the Merge input count past 2 | A third branch silently drops | Set the input count to match the wired branches |

data/skills/n8n-binary-and-data/README.md

@@ -0,0 +1,208 @@
+# n8n Binary and Data Skill
+
+Expert guidance for handling files and binary data in n8n — the `$binary` vs `$json` split, reading and writing bytes, keeping binary alive across transforms, the AI-agent tool boundary, and the CDN/URL requirement for chat surfaces.
+
+---
+
+## ⚠️ File contents live in `$binary`, not `$json`
+
+Every n8n item has two independent slots that flow side by side:
+
+| | `$json` | `$binary` |
+|---|---|---|
+| Holds | Structured data (numbers, strings, objects) | File bytes (base64) plus metadata |
+| Shape | `{ customerId: 42 }` | `{ data, mimeType, fileName, fileExtension }` |
+| Read in Code | `$json.field` | `this.helpers.getBinaryDataBuffer(i, 'data')` |
+| Crosses an agent tool | Yes (JSON args/returns) | **No** — pass a key/URL instead |
+| Renders in a chat surface | n/a | **No** — needs a URL, not raw bytes |
+
+Reading `$json.data` for a downloaded PDF gives you nothing — the bytes are in `$binary.data`. This skill teaches the actual contract for files.
+
+---
+
+## What This Skill Teaches
+
+### Core Concepts
+1. **Two slots per item** — `$json` for data, `$binary` for files; they never mix
+2. **Read bytes via `getBinaryDataBuffer`**, write by building the slot (base64 + mimeType + fileName)
+3. **Binary is silently stripped** by JSON-only transforms — pass it through or Merge it back
+4. **The agent-tool boundary is JSON only** — pre-stage to storage, pass keys/URLs
+5. **Chat surfaces render by URL** — upload to storage/CDN first
+
+### Top issues this skill prevents
+1. Reading file contents from `$json` and getting empty data
+2. HTTP download without `responseFormat: "file"` → mangled text instead of bytes
+3. A Code node dropping the binary slot by not re-attaching it on return
+4. Binary disappearing after an Edit Fields / IF / Code transform
+5. An AI agent tool that receives nothing when handed an uploaded file
+6. A generated image that "doesn't display" in Slack/Discord/Teams
+
+---
+
+## Skill Activation
+
+Activates when you:
+- Work with files, images, PDFs, attachments, uploads, or downloads
+- Mention `$binary`, `binaryPropertyName`, base64, or "read the PDF"
+- Need an AI agent to take a file as tool input or return a generated file
+- Hit Merge losing the binary slot, or vision/multimodal input
+- Ask why a chat-posted image isn't showing, or about a CDN for chat images
+
+**Example queries**:
+- "I downloaded a PDF but `$json.data` is empty — where's the file?"
+- "How do I attach a file generated in a Code node to an email?"
+- "My agent can't pass the uploaded image to its tool."
+- "The workflow generates an image but it never shows up in Slack."
+- "Why did the binary disappear after my Edit Fields node?"
+
+---
+
+## File Structure
+
+### SKILL.md
+Main skill content — loaded when the skill activates.
+- The three rules (read from `$binary`; agent tools are JSON-only; chat needs a URL)
+- The two-slot anatomy and `binaryPropertyName`
+- Producing binary (HTTP `responseFormat: "file"`, Read Files, downloads)
+- Reading/writing binary in a Code node
+- Keeping binary alive across transforms (pass-through, Merge by position)
+- The agent-tool binary boundary, inbound and outbound
+- The CDN requirement for chat surfaces
+- What's NOT available, anti-patterns table, verification, checklist
+
+### BINARY_BASICS.md
+The `$binary` slot in depth.
+- Full slot shape and the property-name convention
+- Which nodes produce and consume binary
+- `getBinaryDataBuffer` read and base64 write recipes
+- Mime types (table + magic-byte sniffing)
+- File-size limits and when to offload to external storage
+- Inspecting the binary slot in an execution
+
+### AGENT_TOOL_BINARY.md
+The JSON-only boundary between an AI Agent and its tools.
+- Inbound: uploads → pre-stage → inject keys → tool fetches by key
+- The Merge synchronization barrier and `executeOnce: true`
+- What the system prompt and the tool argument look like
+- Outbound: generate → upload → return `{ key, url }`
+- `passthroughBinaryImages` (vision only, image only)
+- Storage choice, hash strategy, cleanup, long-running tools
+
+### MERGE_FOR_CONTEXT.md
+Re-attaching binary after a JSON transform strips it.
+- The fan-out + Merge-by-position pattern with wiring
+- Configuring `combineByPosition`
+- Pass-through alternatives on the transforming node
+- When to switch to upload-early or a sub-workflow instead
+- Verifying the merged item, common mistakes
+
+### CDN_REQUIREMENT.md
+Why chat surfaces need a served URL.
+- Why `$binary` doesn't render; how chat clients embed images
+- Storage options (object storage vs drive-style) and how to ask the user
+- The generate → upload → reply flow
+- Signed URLs, file naming, cleanup
+
+---
+
+## Quick Reference
+
+### Read file bytes (Code node)
+```javascript
+const buffer = await this.helpers.getBinaryDataBuffer(0, 'data');
+const text = buffer.toString('utf-8');
+```
+
+### Write a file (Code node) — re-attach on return
+```javascript
+return [{
+  json: { ok: true },
+  binary: {
+    report: {
+      data: Buffer.from(text).toString('base64'),
+      mimeType: 'text/plain',
+      fileName: 'report.txt',
+    },
+  },
+}];
+```
+
+### Keep binary across a JSON transform
+```
+[Source] ─┬─→ [Edit Fields] ─┐
+          └──────────────────┴─→ [Merge: combineByPosition]
+```
+
+### Pass a file to/from an agent tool
+- Inbound: upload → inject storage key in system prompt → tool downloads by key
+- Outbound: tool uploads → returns `{ key, url }` in JSON
+
+---
+
+## Integration with Other Skills
+
+**n8n-code-javascript / n8n-code-python**: own the Code-node sandbox and helpers; this skill owns the rule that binary must be re-attached on return.
+
+**n8n-code-tool**: the Custom Code Tool sandbox has no `$binary`/`getBinaryDataBuffer` — a tool gets files via the storage-key pattern.
+
+**n8n-workflow-patterns**: the agent-tool boundary and the generate → upload → reply flow live inside larger patterns.
+
+**n8n-node-configuration**: `responseFormat`, `binaryPropertyName`, `includeOtherFields`, `binaryPropertyOutput` are conditional fields — confirm names with `get_node`.
+
+**n8n-expression-syntax**: addressing `$binary.<key>` and webhook uploads under `$json.body`.
+
+**n8n-validation-expert**: a stripped binary slot is a silent failure validation won't flag.
+
+**n8n-mcp-tools-expert**: owns `n8n_manage_datatable` (Data Tables) and `n8n_executions` (confirm binary survived).
+
+**n8n-error-handling**: storage uploads/downloads fail — staging steps need error branches.
+
+**using-n8n-mcp-skills**: the index of how these skills fit together.
+
+---
+
+## When to Use This Skill vs Alternatives
+
+| Need | Use |
+|---|---|
+| Where file bytes live, reading/writing binary | **n8n-binary-and-data** |
+| Language-level Code-node logic (arrays, dates, HTTP) | **n8n-code-javascript** / **n8n-code-python** |
+| A tool an AI agent invokes | **n8n-code-tool** |
+| Persistent tabular storage (dedup, state) | **n8n-mcp-tools-expert** (`n8n_manage_datatable`) |
+| Overall workflow shape | **n8n-workflow-patterns** |
+
+---
+
+## Success Metrics
+
+After using this skill, you should be able to:
+
+- [ ] Read file contents from `$binary`, never `$json`
+- [ ] Set `responseFormat: "file"` on HTTP downloads
+- [ ] Re-attach `binary` on a Code node return so the file survives
+- [ ] Keep binary across a JSON transform via pass-through or Merge by position
+- [ ] Move a file in or out of an agent tool using a storage key, not raw bytes
+- [ ] Recognize that `passthroughBinaryImages` is vision-only and doesn't feed tools
+- [ ] Get a generated image to display in a chat surface by serving it from a URL
+- [ ] Confirm binary survived by inspecting the execution, not by validation
+
+---
+
+## Sources
+
+Authoritative facts in this skill come from:
+- [n8n binary data docs](https://docs.n8n.io/data/binary-data/) — the `$binary` slot, property names, storage
+- [n8n Code node docs](https://docs.n8n.io/code/builtin/) — `getBinaryDataBuffer` and the helpers surface
+- [n8n Merge node docs](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/) — `combineByPosition` semantics
+- [n8n AI Agent / LangChain nodes docs](https://docs.n8n.io/advanced-ai/) — the agent ↔ tool JSON boundary and `passthroughBinaryImages`
+
+---
+
+## Version
+
+**Version**: 1.0.0
+**Compatibility**: n8n with `$binary` items; agent-tool patterns require the LangChain AI Agent node.
+
+---
+
+**Remember**: two slots, side by side. Data rides in `$json`, files ride in `$binary` — and the moment a file crosses an agent tool or reaches a chat surface, it travels as a URL, not as bytes.

data/skills/n8n-binary-and-data/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: n8n-binary-and-data
+description: Handle files and binary data in n8n correctly. Use when working with files, images, PDFs, attachments, uploads or downloads, base64, vision/multimodal input, or when an AI agent needs a file as tool input or output — and whenever the user mentions $binary, binaryPropertyName, "read the PDF", "attach the file", "send the image", Merge losing binary, or a CDN for chat images. Covers the $binary vs $json split, reading/writing binary, keeping binary alive across transforms with Merge, the agent-tool binary boundary, and the CDN/URL requirement for chat surfaces.
+---
+
+# n8n Binary and Data
+
+Every n8n item carries two independent slots: `$json` for structured data and `$binary` for file bytes. They travel side by side through the workflow. File contents — the actual PDF, image, or zip — live in `$binary`, never in `$json`. Get that split wrong and you read an empty field, lose a file mid-flow, or hand an AI agent a tool input it can't use.
+
+This skill covers where binary lives, how to read and write it, how to keep it from being silently stripped, the hard wall between binary and the AI-agent tool boundary, and why chat surfaces need a URL instead of raw bytes.
+
+---
+
+## The three rules that prevent 90% of binary bugs
+
+1. **File contents are in `$binary`, not `$json`.** After an HTTP download, a "Read Files", or an email-attachment trigger, the bytes sit in `$binary.<key>`. `$json` holds metadata at most. Reading `$json.data` for file contents gives you nothing.
+
+2. **Binary cannot cross the AI-agent tool boundary — in either direction.** Tool arguments and tool return values are JSON only. An uploaded image can't be passed into a tool as a file, and a tool can't return raw bytes. Pre-stage to storage and pass a key or URL through JSON instead. See `AGENT_TOOL_BINARY.md`.
+
+3. **Chat surfaces render images by URL, not by `$binary`.** Slack, Discord, Teams, Telegram, embedded webhook chat — none of them read the binary slot. The image has to live somewhere a URL can fetch it. See `CDN_REQUIREMENT.md`.
+
+---
+
+## The two slots
+
+Each item is shaped like this:
+
+```json
+{
+  "json": { "customerId": 42, "status": "sent" },
+  "binary": {
+    "invoice": {
+      "data": "<base64-encoded bytes>",
+      "mimeType": "application/pdf",
+      "fileName": "invoice-42.pdf",
+      "fileExtension": "pdf"
+    }
+  }
+}
+```
+
+The key inside `binary` (`invoice` here) is the **binary property name**. Most file-handling nodes have a `binaryPropertyName` parameter that points at it — the producer names the slot, the consumer references it by that name. The default key across most nodes is `data`, so when nothing tells you otherwise, assume `$binary.data`.
+
+`$json` and `$binary` are separate namespaces. An expression like `{{ $binary.invoice.fileName }}` reads file metadata; `{{ $json.customerId }}` reads data. They never mix.
+
+This split also explains a webhook gotcha: a Webhook trigger receiving `multipart/form-data` puts the uploaded file in `$binary` and the accompanying form fields in `$json.body` — so an uploaded file is not somewhere under `$json` at all. (The `$json.body` nesting for webhooks is **n8n-expression-syntax** territory.)
+
+See `BINARY_BASICS.md` for the full slot anatomy, mime types, and size limits.
+
+---
+
+## Producing binary
+
+You rarely build a `$binary` slot by hand — nodes populate it for you:
+
+| Source | How binary appears |
+|---|---|
+| HTTP Request with `responseFormat: "file"` | Response body lands in `$binary.data` (or the name you set) |
+| Read/Write Files from Disk | File contents read into `$binary` |
+| Storage downloads (S3, Google Drive, Dropbox, etc.) | Downloaded file in `$binary.<key>` |
+| Email triggers with attachments | Each attachment arrives in `$binary` |
+| Provider AI media nodes (image/audio gen) | Set `options.binaryPropertyOutput` so the bytes land where the next node looks |
+
+For an HTTP download, the one field that matters is `responseFormat`. Confirm it with `get_node` on `nodes-base.httpRequest` — leaving it as the default JSON/string format is the classic reason a downloaded file ends up as garbled text in `$json` instead of clean bytes in `$binary`.
+
+---
+
+## Reading and writing binary in a Code node
+
+Most workflows never need to crack open the bytes — they just pass binary through to a consumer (email attachment, file upload, Slack file). When you do need the raw bytes, do it in a Code node.
+
+**Read** with `getBinaryDataBuffer` — do not try to base64-decode `$binary.<key>.data` by hand:
+
+```javascript
+// Code node, "Run Once for Each Item"
+const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); // (itemIndex, propertyName)
+const text = buffer.toString('utf-8');
+const length = buffer.length;
+
+return [{
+  json: { ...$json, length },
+  binary: $input.item.binary,   // pass the binary through, or it's gone
+}];
+```
+
+**Write** by building the slot yourself — base64 the bytes plus a mime type and file name:
+
+```javascript
+const text = 'Hello, world!';
+return [{
+  json: { ok: true },
+  binary: {
+    report: {
+      data: Buffer.from(text).toString('base64'),
+      mimeType: 'text/plain',
+      fileName: 'report.txt',
+      fileExtension: 'txt',
+    },
+  },
+}];
+```
+
+The Code-node sandbox, helpers, and execution modes are the domain of **n8n-code-javascript** (and **n8n-code-python**) — use those for the language-level detail. The one binary-specific thing to remember here: a Code node that returns `[{ json: {...} }]` without re-attaching `binary` **silently drops the file**. See `BINARY_BASICS.md`.
+
+---
+
+## Keeping binary alive across transforms
+
+JSON-only nodes — Edit Fields (Set), Code, IF, and others — can drop the `$binary` slot from their output. The workflow validates clean and runs without error; the file just isn't there downstream when the email node goes to attach it.
+
+Two ways to keep it:
+
+- **Pass-through option on the transforming node.** Edit Fields has `includeOtherFields`; a Code node can return `binary: $input.item.binary` explicitly. Cheapest fix when it's available.
+- **Fan out and Merge by position.** Route the source into both the transform and a bypass branch, then recombine with a Merge in `combineByPosition` mode. The JSON comes from the transform side, the binary survives on the bypass side.
+
+```
+[Source with binary] ─┬─→ [Edit Fields: change JSON] ─┐
+                      │      (binary stripped here)     ├─→ [Merge: combineByPosition] ─→ [Email: attach]
+                      └──────────────────────────────────┘
+                          (bypass — binary passes through untouched)
+```
+
+`combineByPosition` pairs item N from each input, so the field counts must line up. The connection wiring and the alternatives for many-strip-point chains (upload-early, sub-workflow) are in `MERGE_FOR_CONTEXT.md`.
+
+---
+
+## The agent-tool binary boundary
+
+This is the sharpest edge. An AI Agent talks to its tools (Custom Code Tool, Call n8n Workflow Tool, HTTP Request Tool, MCP tools) over JSON. Binary does not fit through that pipe in either direction. The fix is the same shape both ways: **stage the bytes in storage, pass a key/URL through JSON, fetch on the other side.**
+
+**Inbound — a user uploads a file the agent's tool must operate on:**
+
+1. The chat trigger gives you a `files[]` array. Split it out and upload each file to private storage under a hashed key.
+2. Re-merge that branch before the agent runs (it's a synchronization barrier, not decoration), and set `executeOnce: true` on the agent so N files don't trigger N agent runs.
+3. Inject the keys into the agent's system prompt, listing both the original name (human context) and the storage key (what the tool needs), with an explicit "use EXACTLY this key".
+4. The tool receives the key as a string argument and downloads the file from storage itself.
+
+**Outbound — a tool generates a file the agent must return:**
+
+1. The tool sub-workflow generates the binary, uploads it to storage, and returns JSON like `{ "ok": true, "key": "...", "url": "https://...", "mimeType": "image/png" }`.
+2. The agent embeds the URL in its reply (or passes the key to another tool).
+
+`passthroughBinaryImages: true` on the agent only changes what the **LLM sees** for vision — it does **not** let tools receive the file, and it's image-only (no PDFs, audio, or video). You still need the upload-and-pass-key pattern for any tool. Full patterns, hash strategy, storage choices, and the long-running-tool variant are in `AGENT_TOOL_BINARY.md`.
+
+> Building the tool itself? See **n8n-code-tool** for the Custom Code Tool contract and **n8n-workflow-patterns** for the AI-Agent-with-tools shape.
+
+---
+
+## The CDN requirement for chat surfaces
+
+When a workflow generates an image and the user wants it shown inside a chat message:
+
+- **Binary on the item isn't enough.** The chat client renders messages that reference images by URL (or pushes bytes through the platform's own file-upload API). It never reads `$binary`.
+- **The bytes have to live somewhere a URL can fetch over HTTPS.** Upload to an object store or drive first, then embed the returned URL.
+- **n8n has no built-in CDN.** The user provides the storage.
+
+Ask which storage they already use rather than defaulting to S3 — object storage (S3, R2, GCS, Azure Blob, Backblaze B2, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box) all work and all change the URL shape. Cloudflare R2 is the lowest-friction starting point if they have nothing. For sensitive content, use a signed URL with an expiry rather than a permanently public one. See `CDN_REQUIREMENT.md`.
+
+---
+
+## What's NOT available
+
+- **`$fromAI()` cannot carry binary.** It fills tool parameters with strings, numbers, booleans, and objects — never file bytes. Pass a storage key instead.
+- **Tool arguments and returns are JSON only.** There is no "binary parameter" on an agent tool, in or out.
+- **n8n ships no CDN or public file host.** Serving a file over a URL is always something the user's storage does, not n8n.
+- **`getBinaryDataBuffer` is a Code-node helper.** It isn't available in the Custom Code Tool sandbox (see **n8n-code-tool**).
+
+---
+
+## Where Data Tables live
+
+For persistent tabular storage — reference-counting staged files, tracking which keys are live, dedup — that's the `n8n_manage_datatable` surface, owned by **n8n-mcp-tools-expert**. This skill does not cover Data Tables.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | What goes wrong | Fix |
+|---|---|---|
+| Reading file contents from `$json` | Bytes live in `$binary`; `$json` is empty or metadata only | Read `$binary.<key>`, or `getBinaryDataBuffer` in a Code node |
+| HTTP download without `responseFormat: "file"` | Bytes arrive as mangled text in `$json`, not clean binary | Set `responseFormat: "file"` on the HTTP Request node |
+| Code node returns `[{json:{...}}]`, no `binary` | The file is silently dropped downstream | Re-attach `binary: $input.item.binary` in the return |
+| JSON transform (Edit Fields/IF) eats the binary | Email/upload node finds nothing to attach | Pass-through option, or fan out + Merge by position |
+| Passing an uploaded file into a tool via `$fromAI` | `$fromAI` can't carry binary; the tool gets nothing | Pre-stage to storage, inject the key in the system prompt, tool fetches by key |
+| Assuming `passthroughBinaryImages` lets tools see the file | It only affects what the LLM sees, and only for images | Still need the upload-and-pass-key pattern for tools |
+| Tool returns raw binary to the agent | Tool output is JSON; bytes don't survive (and bloat context) | Upload, return `{ key, url }` in JSON |
+| Posting `$binary` to a chat surface and expecting an image | Chat clients render by URL, not raw bytes | Upload to storage/CDN, embed the URL or use the platform file API |
+| Hardcoding base64 in a Code node | Huge workflow JSON, slow, leaky | Reference via `$binary`, or upload and reference by URL |
+
+---
+
+## Reference files
+
+| File | Read when |
+|---|---|
+| `BINARY_BASICS.md` | First time handling binary, or reading/writing the `$binary` slot, mime types, size limits |
+| `AGENT_TOOL_BINARY.md` | An agent tool needs an uploaded file, or produces one — the boundary in either direction |
+| `MERGE_FOR_CONTEXT.md` | Binary disappears after a JSON transform and you need to re-attach it |
+| `CDN_REQUIREMENT.md` | Showing images in a chat surface or anywhere that needs URL-referenced images |
+
+---
+
+## Integration with Other Skills
+
+**n8n-code-javascript / n8n-code-python**: the Code node is where you read/write raw bytes (`getBinaryDataBuffer`, `Buffer.from(...).toString('base64')`). Those skills own the sandbox, helpers, and execution-mode detail — this skill owns the rule that binary must be re-attached on return.
+
+**n8n-code-tool**: the Custom Code Tool sandbox is narrower — no `$binary`, no `getBinaryDataBuffer`, no `$fromAI`. When a tool needs a file, this skill's storage-key pattern is how it gets one.
+
+**n8n-workflow-patterns**: the agent-tool binary boundary sits inside the AI-Agent-with-tools pattern; the CDN flow is a generate → upload → reply chain.
+
+**n8n-node-configuration**: `responseFormat`, `binaryPropertyName`, `includeOtherFields`, `binaryPropertyOutput` are all conditional fields — use `get_node` to confirm the exact names on the user's version.
+
+**n8n-expression-syntax**: addressing `$binary.<key>.fileName` vs `$json.body` (webhook uploads in particular) is expression territory.
+
+**n8n-validation-expert**: a dropped binary slot is a silent failure — `validate_workflow` won't flag it. Confirm presence by inspecting the execution.
+
+**n8n-mcp-tools-expert**: owns `n8n_manage_datatable` (Data Tables) and `n8n_executions` — use the latter to confirm a `binary` slot actually survived a given node.
+
+**n8n-error-handling**: storage uploads and downloads fail; the inbound/outbound staging steps need error branches so a missing key doesn't 404 silently.
+
+**using-n8n-mcp-skills**: the index of how these skills fit together.
+
+---
+
+## Verifying binary survived
+
+Validation won't catch a stripped binary slot — it's a silent failure. Confirm it ran correctly:
+
+1. `n8n_test_workflow` (or trigger a real run) to produce an execution.
+2. `n8n_executions` to pull that execution, and inspect per-node output for the `binary` slot — it shows presence and metadata even if the base64 is too large to render.
+3. The node where `binary` last appears is the node before the strip. That's where the pass-through or Merge goes.
+
+---
+
+## Quick Reference Checklist
+
+- [ ] File contents read from `$binary.<key>` — never `$json`
+- [ ] HTTP downloads use `responseFormat: "file"`
+- [ ] Code nodes re-attach `binary` on return when the file must continue
+- [ ] JSON transforms either pass binary through or Merge it back (`combineByPosition`)
+- [ ] No attempt to pass binary into/out of an agent tool — keys/URLs through JSON instead
+- [ ] `passthroughBinaryImages` used only for LLM vision, not as a tool channel
+- [ ] Chat-surface images uploaded to storage; the URL is embedded, not the bytes
+- [ ] Storage backend chosen with the user (not defaulted to S3); signed URLs for sensitive content
+- [ ] Binary presence confirmed by inspecting the execution, not by validation
+
+---
+
+**Remember**: two slots, side by side. Data rides in `$json`, files ride in `$binary` — and the moment a file has to cross an agent tool or reach a chat surface, it travels as a URL, not as bytes.

data/skills/n8n-code-javascript/BUILTIN_FUNCTIONS.md

@@ -0,0 +1,827 @@
+# Built-in Functions - JavaScript Code Node
+
+Complete reference for n8n's built-in JavaScript functions and helpers.
+
+---
+
+## Overview
+
+n8n Code nodes provide powerful built-in functions beyond standard JavaScript. This guide covers:
+
+1. **Sandbox restrictions** - What's blocked and why (READ FIRST)
+2. **this.helpers.httpRequest()** - Make HTTP requests (the bare `$helpers` global is undefined in the task runner)
+3. **DateTime (Luxon)** - Advanced date/time operations
+4. **$jmespath()** - Query JSON structures
+5. **$getWorkflowStaticData()** - Persistent storage
+6. **Standard JavaScript Globals** - Math, JSON, console, etc.
+7. **Available Node.js Modules** - crypto, Buffer, URL
+
+---
+
+## 0. Sandbox Restrictions (Critical)
+
+Since n8n v2.0, Code nodes execute inside a **task runner sandbox** (`JsTaskRunnerSandbox`) which deliberately blocks several APIs. The legacy vm2 sandbox is being removed. Knowing what's blocked saves hours of "why does this throw on activation but not in the editor preview."
+
+### Blocked helpers
+
+```javascript
+// ❌ BLOCKED — throws UnsupportedFunctionError
+await this.helpers.httpRequestWithAuthentication.call(this, 'credType', { ... });
+await this.helpers.requestWithAuthenticationPaginated.call(this, { ... }, 'credType');
+```
+
+n8n's source comment explains why: *"these rely on checking the credentials from the current node type (Code Node), and Code Node doesn't have credentials."* There is **no env var to re-enable them** in the task runner — the deny-list is compiled-in (`packages/@n8n/task-runner/src/runner-types.ts`).
+
+**Workaround**: don't try to authenticate from inside a Code node. Instead, either:
+- Replace the Code node with an HTTP Request node that has the credential attached (the canonical pattern), or
+- Have the Code node prepare a payload and delegate to a sub-workflow whose HTTP Request node holds the credential.
+
+### `$env` may be blocked
+
+`$env` is gated by **`N8N_BLOCK_ENV_ACCESS_IN_NODE`**. When set to `true` (a common production hardening), any reference to `$env.SOMETHING` throws. Since you can't tell from inside the Code node whether it's enabled, **don't rely on `$env` for portable skills** — treat secrets as a credential concern (HTTP Request node) rather than a Code-node concern.
+
+### `require()` is gated by allowlists
+
+```javascript
+// May throw "Cannot find module 'crypto'" — depends on env vars
+const crypto = require('crypto');
+```
+
+Built-in modules need `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` (or legacy `NODE_FUNCTION_ALLOW_BUILTIN`) set to `*` or a comma-list including `crypto`. External npm packages need `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` plus the package being installed in the runner image. On default installs neither is set — `require()` throws.
+
+`Buffer` and `URL` are globals (not `require`'d), so they always work.
+
+### What's always safe
+
+`$input.*`, `$json`, `$node[…]`, `this.helpers.httpRequest()` (without auth), `$jmespath()`, `$getWorkflowStaticData()`, `DateTime` (Luxon), and all standard JavaScript globals (`Math`, `JSON`, `Object`, `Array`, `console`, `Buffer`, `URL`, `URLSearchParams`).
+
+> **Accessor gotcha**: the bare `$helpers` global is **undefined** in the task-runner sandbox — `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`. The working accessor is **`this.helpers.httpRequest()`** (inside a nested async function where `this` is lost, call it as `await fn.call(this, ...)`). The n8n-mcp validator may wrongly suggest `$helpers` — ignore it. And for anything beyond a trivial unauthenticated GET (pagination, retries, credentials), prefer the **HTTP Request node** and keep Code nodes for pure logic.
+
+---
+
+## 1. this.helpers.httpRequest() - HTTP Requests
+
+Make HTTP requests directly from Code nodes without using HTTP Request node. The accessor is `this.helpers.httpRequest()` — the bare `$helpers` global is undefined in the task-runner sandbox and throws `ReferenceError: $helpers is not defined`. For non-trivial calls (pagination, retries, credentials) prefer the HTTP Request node.
+
+### Basic Usage
+
+```javascript
+const response = await this.helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/users'
+});
+
+return [{json: {data: response}}];
+```
+
+### Complete Options
+
+```javascript
+const response = await this.helpers.httpRequest({
+  method: 'POST',  // GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+  url: 'https://api.example.com/users',
+  headers: {
+    'Authorization': 'Bearer token123',
+    'Content-Type': 'application/json',
+    'User-Agent': 'n8n-workflow'
+  },
+  body: {
+    name: 'John Doe',
+    email: 'john@example.com'
+  },
+  qs: {  // Query string parameters
+    page: 1,
+    limit: 10
+  },
+  timeout: 10000,  // Milliseconds (default: no timeout)
+  json: true,  // Auto-parse JSON response (default: true)
+  simple: false,  // Don't throw on HTTP errors (default: true)
+  resolveWithFullResponse: false  // Return only body (default: false)
+});
+```
+
+### GET Request
+
+```javascript
+// Simple GET
+const users = await this.helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/users'
+});
+
+return [{json: {users}}];
+```
+
+```javascript
+// GET with query parameters
+const results = await this.helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/search',
+  qs: {
+    q: 'javascript',
+    page: 1,
+    per_page: 50
+  }
+});
+
+return [{json: results}];
+```
+
+### POST Request
+
+```javascript
+// POST with JSON body
+// NOTE: For authenticated APIs, prefer an HTTP Request node with a credential
+// attached. Embedding the token in a Code node only works when (a) the token
+// arrives as runtime data (e.g. from a previous node), or (b) you're sure
+// $env access is enabled on this instance. See section 0.
+const apiToken = $input.first().json.apiToken;  // passed in from a credential-aware upstream node
+
+const newUser = await this.helpers.httpRequest({
+  method: 'POST',
+  url: 'https://api.example.com/users',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${apiToken}`
+  },
+  body: {
+    name: $json.body.name,
+    email: $json.body.email,
+    role: 'user'
+  }
+});
+
+return [{json: newUser}];
+```
+
+### PUT/PATCH Request
+
+```javascript
+// Update resource
+const updated = await this.helpers.httpRequest({
+  method: 'PATCH',
+  url: `https://api.example.com/users/${userId}`,
+  body: {
+    name: 'Updated Name',
+    status: 'active'
+  }
+});
+
+return [{json: updated}];
+```
+
+### DELETE Request
+
+```javascript
+// Delete resource
+await this.helpers.httpRequest({
+  method: 'DELETE',
+  url: `https://api.example.com/users/${userId}`,
+  headers: {
+    'Authorization': `Bearer ${apiToken}`  // token passed in from upstream node, not $env
+  }
+});
+
+return [{json: {deleted: true, userId}}];
+```
+
+### Authentication Patterns
+
+> **Strong preference**: don't authenticate from inside a Code node. Use an HTTP Request node with a credential attached, or delegate to a sub-workflow whose HTTP Request node holds the credential. The patterns below only apply when the token genuinely flows through the workflow as data.
+
+```javascript
+// Bearer Token (token came from a previous node, not $env)
+const response = await this.helpers.httpRequest({
+  url: 'https://api.example.com/data',
+  headers: {
+    'Authorization': `Bearer ${$input.first().json.token}`
+  }
+});
+```
+
+```javascript
+// API Key in Header (key came from a previous node, not $env)
+const response = await this.helpers.httpRequest({
+  url: 'https://api.example.com/data',
+  headers: {
+    'X-API-Key': $input.first().json.apiKey
+  }
+});
+```
+
+```javascript
+// Basic Auth (manual)
+const credentials = Buffer.from(`${username}:${password}`).toString('base64');
+
+const response = await this.helpers.httpRequest({
+  url: 'https://api.example.com/data',
+  headers: {
+    'Authorization': `Basic ${credentials}`
+  }
+});
+```
+
+### Error Handling
+
+```javascript
+// Handle HTTP errors gracefully
+try {
+  const response = await this.helpers.httpRequest({
+    method: 'GET',
+    url: 'https://api.example.com/users',
+    simple: false  // Don't throw on 4xx/5xx
+  });
+
+  if (response.statusCode >= 200 && response.statusCode < 300) {
+    return [{json: {success: true, data: response.body}}];
+  } else {
+    return [{
+      json: {
+        success: false,
+        status: response.statusCode,
+        error: response.body
+      }
+    }];
+  }
+} catch (error) {
+  return [{
+    json: {
+      success: false,
+      error: error.message
+    }
+  }];
+}
+```
+
+### Full Response Access
+
+```javascript
+// Get full response including headers and status
+const response = await this.helpers.httpRequest({
+  url: 'https://api.example.com/data',
+  resolveWithFullResponse: true
+});
+
+return [{
+  json: {
+    statusCode: response.statusCode,
+    headers: response.headers,
+    body: response.body,
+    rateLimit: response.headers['x-ratelimit-remaining']
+  }
+}];
+```
+
+---
+
+## 2. DateTime (Luxon) - Date & Time Operations
+
+n8n includes Luxon for powerful date/time handling. Access via `DateTime` global.
+
+### Current Date/Time
+
+```javascript
+// Current time
+const now = DateTime.now();
+
+// Current time in specific timezone
+const nowTokyo = DateTime.now().setZone('Asia/Tokyo');
+
+// Today at midnight
+const today = DateTime.now().startOf('day');
+
+return [{
+  json: {
+    iso: now.toISO(),  // "2025-01-20T15:30:00.000Z"
+    formatted: now.toFormat('yyyy-MM-dd HH:mm:ss'),  // "2025-01-20 15:30:00"
+    unix: now.toSeconds(),  // Unix timestamp
+    millis: now.toMillis()  // Milliseconds since epoch
+  }
+}];
+```
+
+### Formatting Dates
+
+```javascript
+const now = DateTime.now();
+
+return [{
+  json: {
+    isoFormat: now.toISO(),  // ISO 8601: "2025-01-20T15:30:00.000Z"
+    sqlFormat: now.toSQL(),  // SQL: "2025-01-20 15:30:00.000"
+    httpFormat: now.toHTTP(),  // HTTP: "Mon, 20 Jan 2025 15:30:00 GMT"
+
+    // Custom formats
+    dateOnly: now.toFormat('yyyy-MM-dd'),  // "2025-01-20"
+    timeOnly: now.toFormat('HH:mm:ss'),  // "15:30:00"
+    readable: now.toFormat('MMMM dd, yyyy'),  // "January 20, 2025"
+    compact: now.toFormat('yyyyMMdd'),  // "20250120"
+    withDay: now.toFormat('EEEE, MMMM dd, yyyy'),  // "Monday, January 20, 2025"
+    custom: now.toFormat('dd/MM/yy HH:mm')  // "20/01/25 15:30"
+  }
+}];
+```
+
+### Parsing Dates
+
+```javascript
+// From ISO string
+const dt1 = DateTime.fromISO('2025-01-20T15:30:00');
+
+// From specific format
+const dt2 = DateTime.fromFormat('01/20/2025', 'MM/dd/yyyy');
+
+// From SQL
+const dt3 = DateTime.fromSQL('2025-01-20 15:30:00');
+
+// From Unix timestamp
+const dt4 = DateTime.fromSeconds(1737384600);
+
+// From milliseconds
+const dt5 = DateTime.fromMillis(1737384600000);
+
+return [{json: {parsed: dt1.toISO()}}];
+```
+
+### Date Arithmetic
+
+```javascript
+const now = DateTime.now();
+
+return [{
+  json: {
+    // Adding time
+    tomorrow: now.plus({days: 1}).toISO(),
+    nextWeek: now.plus({weeks: 1}).toISO(),
+    nextMonth: now.plus({months: 1}).toISO(),
+    inTwoHours: now.plus({hours: 2}).toISO(),
+
+    // Subtracting time
+    yesterday: now.minus({days: 1}).toISO(),
+    lastWeek: now.minus({weeks: 1}).toISO(),
+    lastMonth: now.minus({months: 1}).toISO(),
+    twoHoursAgo: now.minus({hours: 2}).toISO(),
+
+    // Complex operations
+    in90Days: now.plus({days: 90}).toFormat('yyyy-MM-dd'),
+    in6Months: now.plus({months: 6}).toFormat('yyyy-MM-dd')
+  }
+}];
+```
+
+### Time Comparisons
+
+```javascript
+const now = DateTime.now();
+const targetDate = DateTime.fromISO('2025-12-31');
+
+return [{
+  json: {
+    // Comparisons
+    isFuture: targetDate > now,
+    isPast: targetDate < now,
+    isEqual: targetDate.equals(now),
+
+    // Differences
+    daysUntil: targetDate.diff(now, 'days').days,
+    hoursUntil: targetDate.diff(now, 'hours').hours,
+    monthsUntil: targetDate.diff(now, 'months').months,
+
+    // Detailed difference
+    detailedDiff: targetDate.diff(now, ['months', 'days', 'hours']).toObject()
+  }
+}];
+```
+
+### Timezone Operations
+
+```javascript
+const now = DateTime.now();
+
+return [{
+  json: {
+    // Current timezone
+    local: now.toISO(),
+
+    // Convert to different timezone
+    tokyo: now.setZone('Asia/Tokyo').toISO(),
+    newYork: now.setZone('America/New_York').toISO(),
+    london: now.setZone('Europe/London').toISO(),
+    utc: now.toUTC().toISO(),
+
+    // Get timezone info
+    timezone: now.zoneName,  // "America/Los_Angeles"
+    offset: now.offset,  // Offset in minutes
+    offsetFormatted: now.toFormat('ZZ')  // "+08:00"
+  }
+}];
+```
+
+### Start/End of Period
+
+```javascript
+const now = DateTime.now();
+
+return [{
+  json: {
+    startOfDay: now.startOf('day').toISO(),
+    endOfDay: now.endOf('day').toISO(),
+    startOfWeek: now.startOf('week').toISO(),
+    endOfWeek: now.endOf('week').toISO(),
+    startOfMonth: now.startOf('month').toISO(),
+    endOfMonth: now.endOf('month').toISO(),
+    startOfYear: now.startOf('year').toISO(),
+    endOfYear: now.endOf('year').toISO()
+  }
+}];
+```
+
+### Weekday & Month Info
+
+```javascript
+const now = DateTime.now();
+
+return [{
+  json: {
+    // Day info
+    weekday: now.weekday,  // 1 = Monday, 7 = Sunday
+    weekdayShort: now.weekdayShort,  // "Mon"
+    weekdayLong: now.weekdayLong,  // "Monday"
+    isWeekend: now.weekday > 5,  // Saturday or Sunday
+
+    // Month info
+    month: now.month,  // 1-12
+    monthShort: now.monthShort,  // "Jan"
+    monthLong: now.monthLong,  // "January"
+
+    // Year info
+    year: now.year,  // 2025
+    quarter: now.quarter,  // 1-4
+    daysInMonth: now.daysInMonth  // 28-31
+  }
+}];
+```
+
+---
+
+## 3. $jmespath() - JSON Querying
+
+Query and transform JSON structures using JMESPath syntax.
+
+### Basic Queries
+
+```javascript
+const data = $input.first().json;
+
+// Extract specific field
+const names = $jmespath(data, 'users[*].name');
+
+// Filter array
+const adults = $jmespath(data, 'users[?age >= `18`]');
+
+// Get specific index
+const firstUser = $jmespath(data, 'users[0]');
+
+return [{json: {names, adults, firstUser}}];
+```
+
+### Advanced Queries
+
+```javascript
+const data = $input.first().json;
+
+// Sort and slice
+const top5 = $jmespath(data, 'users | sort_by(@, &score) | reverse(@) | [0:5]');
+
+// Extract nested fields
+const emails = $jmespath(data, 'users[*].contact.email');
+
+// Multi-field extraction
+const simplified = $jmespath(data, 'users[*].{name: name, email: contact.email}');
+
+// Conditional filtering
+const premium = $jmespath(data, 'users[?subscription.tier == `premium`]');
+
+return [{json: {top5, emails, simplified, premium}}];
+```
+
+### Common Patterns
+
+```javascript
+// Pattern 1: Filter and project
+const query1 = $jmespath(data, 'products[?price > `100`].{name: name, price: price}');
+
+// Pattern 2: Aggregate functions
+const query2 = $jmespath(data, 'sum(products[*].price)');
+const query3 = $jmespath(data, 'max(products[*].price)');
+const query4 = $jmespath(data, 'length(products)');
+
+// Pattern 3: Nested filtering
+const query5 = $jmespath(data, 'categories[*].products[?inStock == `true`]');
+
+return [{json: {query1, query2, query3, query4, query5}}];
+```
+
+---
+
+## 4. $getWorkflowStaticData() - Persistent Storage
+
+Store data that persists across workflow executions.
+
+### Basic Usage
+
+```javascript
+// Get static data storage
+const staticData = $getWorkflowStaticData();
+
+// Initialize counter if doesn't exist
+if (!staticData.counter) {
+  staticData.counter = 0;
+}
+
+// Increment counter
+staticData.counter++;
+
+return [{
+  json: {
+    executionCount: staticData.counter
+  }
+}];
+```
+
+### Use Cases
+
+```javascript
+// Use Case 1: Rate limiting
+const staticData = $getWorkflowStaticData();
+const now = Date.now();
+
+if (!staticData.lastRun) {
+  staticData.lastRun = now;
+  staticData.runCount = 1;
+} else {
+  const timeSinceLastRun = now - staticData.lastRun;
+
+  if (timeSinceLastRun < 60000) {  // Less than 1 minute
+    return [{json: {error: 'Rate limit: wait 1 minute between runs'}}];
+  }
+
+  staticData.lastRun = now;
+  staticData.runCount++;
+}
+
+return [{json: {allowed: true, totalRuns: staticData.runCount}}];
+```
+
+```javascript
+// Use Case 2: Tracking last processed ID
+const staticData = $getWorkflowStaticData();
+const currentItems = $input.all();
+
+// Get last processed ID
+const lastId = staticData.lastProcessedId || 0;
+
+// Filter only new items
+const newItems = currentItems.filter(item => item.json.id > lastId);
+
+// Update last processed ID
+if (newItems.length > 0) {
+  staticData.lastProcessedId = Math.max(...newItems.map(item => item.json.id));
+}
+
+return newItems;
+```
+
+```javascript
+// Use Case 3: Accumulating results
+const staticData = $getWorkflowStaticData();
+
+if (!staticData.accumulated) {
+  staticData.accumulated = [];
+}
+
+// Add current items to accumulated list
+const currentData = $input.all().map(item => item.json);
+staticData.accumulated.push(...currentData);
+
+return [{
+  json: {
+    currentBatch: currentData.length,
+    totalAccumulated: staticData.accumulated.length,
+    allData: staticData.accumulated
+  }
+}];
+```
+
+---
+
+## 5. Standard JavaScript Globals
+
+### Math Object
+
+```javascript
+return [{
+  json: {
+    // Rounding
+    rounded: Math.round(3.7),  // 4
+    floor: Math.floor(3.7),  // 3
+    ceil: Math.ceil(3.2),  // 4
+
+    // Min/Max
+    max: Math.max(1, 5, 3, 9, 2),  // 9
+    min: Math.min(1, 5, 3, 9, 2),  // 1
+
+    // Random
+    random: Math.random(),  // 0-1
+    randomInt: Math.floor(Math.random() * 100),  // 0-99
+
+    // Other
+    abs: Math.abs(-5),  // 5
+    sqrt: Math.sqrt(16),  // 4
+    pow: Math.pow(2, 3)  // 8
+  }
+}];
+```
+
+### JSON Object
+
+```javascript
+// Parse JSON string
+const jsonString = '{"name": "John", "age": 30}';
+const parsed = JSON.parse(jsonString);
+
+// Stringify object
+const obj = {name: "John", age: 30};
+const stringified = JSON.stringify(obj);
+
+// Pretty print
+const pretty = JSON.stringify(obj, null, 2);
+
+return [{json: {parsed, stringified, pretty}}];
+```
+
+### console Object
+
+```javascript
+// Debug logging (appears in browser console, press F12)
+console.log('Processing items:', $input.all().length);
+console.log('First item:', $input.first().json);
+
+// Other console methods
+console.error('Error message');
+console.warn('Warning message');
+console.info('Info message');
+
+// Continues to return data
+return [{json: {processed: true}}];
+```
+
+### Object Methods
+
+```javascript
+const obj = {name: "John", age: 30, city: "NYC"};
+
+return [{
+  json: {
+    keys: Object.keys(obj),  // ["name", "age", "city"]
+    values: Object.values(obj),  // ["John", 30, "NYC"]
+    entries: Object.entries(obj),  // [["name", "John"], ...]
+
+    // Check property
+    hasName: 'name' in obj,  // true
+
+    // Merge objects
+    merged: Object.assign({}, obj, {country: "USA"})
+  }
+}];
+```
+
+### Array Methods
+
+```javascript
+const arr = [1, 2, 3, 4, 5];
+
+return [{
+  json: {
+    mapped: arr.map(x => x * 2),  // [2, 4, 6, 8, 10]
+    filtered: arr.filter(x => x > 2),  // [3, 4, 5]
+    reduced: arr.reduce((sum, x) => sum + x, 0),  // 15
+    some: arr.some(x => x > 3),  // true
+    every: arr.every(x => x > 0),  // true
+    find: arr.find(x => x > 3),  // 4
+    includes: arr.includes(3),  // true
+    joined: arr.join(', ')  // "1, 2, 3, 4, 5"
+  }
+}];
+```
+
+---
+
+## 6. Available Node.js Modules
+
+### crypto Module
+
+> **Gated**: `require('crypto')` only works if `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` (or legacy `NODE_FUNCTION_ALLOW_BUILTIN`) includes `crypto` (or is `*`). On default installs it throws "Cannot find module 'crypto'". For hashing you control, prefer doing it before reaching the Code node, or — if you must — verify your instance's config first.
+
+```javascript
+const crypto = require('crypto');
+
+// Hash functions
+const hash = crypto.createHash('sha256')
+  .update('my secret text')
+  .digest('hex');
+
+// MD5 hash
+const md5 = crypto.createHash('md5')
+  .update('my text')
+  .digest('hex');
+
+// Random values
+const randomBytes = crypto.randomBytes(16).toString('hex');
+
+return [{json: {hash, md5, randomBytes}}];
+```
+
+### Buffer (built-in)
+
+```javascript
+// Base64 encoding
+const encoded = Buffer.from('Hello World').toString('base64');
+
+// Base64 decoding
+const decoded = Buffer.from(encoded, 'base64').toString();
+
+// Hex encoding
+const hex = Buffer.from('Hello').toString('hex');
+
+return [{json: {encoded, decoded, hex}}];
+```
+
+### URL / URLSearchParams
+
+```javascript
+// Parse URL
+const url = new URL('https://example.com/path?param1=value1&param2=value2');
+
+// Build query string
+const params = new URLSearchParams({
+  search: 'query',
+  page: 1,
+  limit: 10
+});
+
+return [{
+  json: {
+    host: url.host,
+    pathname: url.pathname,
+    search: url.search,
+    queryString: params.toString()  // "search=query&page=1&limit=10"
+  }
+}];
+```
+
+---
+
+## What's NOT Available
+
+**External npm packages are NOT available** (unless explicitly allowlisted via `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` *and* installed in the runner image — rare):
+- ❌ axios
+- ❌ lodash
+- ❌ moment (use DateTime/Luxon instead)
+- ❌ request
+- ❌ Any other npm package
+
+**Authentication helpers are blocked** in the task runner sandbox (see section 0):
+- ❌ `this.helpers.httpRequestWithAuthentication`
+- ❌ `this.helpers.requestWithAuthenticationPaginated`
+
+**Conditionally blocked** (depends on instance config):
+- ⚠️ `$env.*` — blocked when `N8N_BLOCK_ENV_ACCESS_IN_NODE=true`
+- ⚠️ `require('crypto')` / `require('fs')` / etc. — blocked unless `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` includes them
+
+**Workarounds**:
+- HTTP with auth → HTTP Request node with credential attached, or sub-workflow pattern
+- Secrets → arrive as data from an upstream HTTP Request / credential-aware node
+- Hashing/crypto → do it in a service the workflow calls, or get your instance config updated
+
+---
+
+## Summary
+
+**Most Useful Built-ins**:
+1. **this.helpers.httpRequest()** - API calls without HTTP Request node (the bare `$helpers` global is undefined)
+2. **DateTime** - Professional date/time handling
+3. **$jmespath()** - Complex JSON queries
+4. **Math, JSON, Object, Array** - Standard JavaScript utilities
+
+**Common Patterns**:
+- API calls: Use this.helpers.httpRequest() (or, preferably, the HTTP Request node)
+- Date operations: Use DateTime (Luxon)
+- Data filtering: Use $jmespath() or JavaScript .filter()
+- Persistent data: Use $getWorkflowStaticData()
+- Hashing: Use crypto module
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Overview
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Real usage examples
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Error prevention

data/skills/n8n-code-javascript/DATA_ACCESS.md

@@ -0,0 +1,897 @@
+# Data Access Patterns - JavaScript Code Node
+
+Comprehensive guide to accessing data in n8n Code nodes using JavaScript.
+
+---
+
+## Overview
+
+In n8n Code nodes, you access data from previous nodes using built-in variables and methods. Understanding which method to use is critical for correct workflow execution.
+
+**Data Access Priority** (by common usage):
+1. **`$input.all()`** - Most common - Batch operations, aggregations
+2. **`$input.first()`** - Very common - Single item operations
+3. **`$input.item`** - Common - Each Item mode only
+4. **`$node["NodeName"].json`** - Specific node references
+5. **`$json`** - Direct current item (legacy, use `$input` instead)
+
+---
+
+## Pattern 1: $input.all() - Process All Items
+
+**Usage**: Most common pattern for batch processing
+
+**When to use:**
+- Processing multiple records
+- Aggregating data (sum, count, average)
+- Filtering arrays
+- Transforming datasets
+- Comparing items
+- Sorting or ranking
+
+### Basic Usage
+
+```javascript
+// Get all items from previous node
+const allItems = $input.all();
+
+// allItems is an array of objects like:
+// [
+//   {json: {id: 1, name: "Alice"}},
+//   {json: {id: 2, name: "Bob"}}
+// ]
+
+console.log(`Received ${allItems.length} items`);
+
+return allItems;
+```
+
+### Example 1: Filter Active Items
+
+```javascript
+const allItems = $input.all();
+
+// Filter only active items
+const activeItems = allItems.filter(item => item.json.status === 'active');
+
+return activeItems;
+```
+
+### Example 2: Transform All Items
+
+```javascript
+const allItems = $input.all();
+
+// Map to new structure
+const transformed = allItems.map(item => ({
+  json: {
+    id: item.json.id,
+    fullName: `${item.json.firstName} ${item.json.lastName}`,
+    email: item.json.email,
+    processedAt: new Date().toISOString()
+  }
+}));
+
+return transformed;
+```
+
+### Example 3: Aggregate Data
+
+```javascript
+const allItems = $input.all();
+
+// Calculate total
+const total = allItems.reduce((sum, item) => {
+  return sum + (item.json.amount || 0);
+}, 0);
+
+return [{
+  json: {
+    total,
+    count: allItems.length,
+    average: total / allItems.length
+  }
+}];
+```
+
+### Example 4: Sort and Limit
+
+```javascript
+const allItems = $input.all();
+
+// Get top 5 by score
+const topFive = allItems
+  .sort((a, b) => (b.json.score || 0) - (a.json.score || 0))
+  .slice(0, 5);
+
+return topFive.map(item => ({json: item.json}));
+```
+
+### Example 5: Group By Category
+
+```javascript
+const allItems = $input.all();
+
+// Group items by category
+const grouped = {};
+
+for (const item of allItems) {
+  const category = item.json.category || 'Uncategorized';
+
+  if (!grouped[category]) {
+    grouped[category] = [];
+  }
+
+  grouped[category].push(item.json);
+}
+
+// Convert to array format
+return Object.entries(grouped).map(([category, items]) => ({
+  json: {
+    category,
+    items,
+    count: items.length
+  }
+}));
+```
+
+### Example 6: Deduplicate by ID
+
+```javascript
+const allItems = $input.all();
+
+// Remove duplicates by ID
+const seen = new Set();
+const unique = [];
+
+for (const item of allItems) {
+  const id = item.json.id;
+
+  if (!seen.has(id)) {
+    seen.add(id);
+    unique.push(item);
+  }
+}
+
+return unique;
+```
+
+---
+
+## Pattern 2: $input.first() - Get First Item
+
+**Usage**: Very common for single-item operations
+
+**When to use:**
+- Previous node returns single object
+- Working with API responses
+- Getting initial/first data point
+- Configuration or metadata access
+
+### Basic Usage
+
+```javascript
+// Get first item from previous node
+const firstItem = $input.first();
+
+// Access the JSON data
+const data = firstItem.json;
+
+console.log('First item:', data);
+
+return [{json: data}];
+```
+
+### Example 1: Process Single API Response
+
+```javascript
+// Get API response (typically single object)
+const response = $input.first().json;
+
+// Extract what you need
+return [{
+  json: {
+    userId: response.data.user.id,
+    userName: response.data.user.name,
+    status: response.status,
+    fetchedAt: new Date().toISOString()
+  }
+}];
+```
+
+### Example 2: Transform Single Object
+
+```javascript
+const data = $input.first().json;
+
+// Transform structure
+return [{
+  json: {
+    id: data.id,
+    contact: {
+      email: data.email,
+      phone: data.phone
+    },
+    address: {
+      street: data.street,
+      city: data.city,
+      zip: data.zip
+    }
+  }
+}];
+```
+
+### Example 3: Validate Single Item
+
+```javascript
+const item = $input.first().json;
+
+// Validation logic
+const isValid = item.email && item.email.includes('@');
+
+return [{
+  json: {
+    ...item,
+    valid: isValid,
+    validatedAt: new Date().toISOString()
+  }
+}];
+```
+
+### Example 4: Extract Nested Data
+
+```javascript
+const response = $input.first().json;
+
+// Navigate nested structure
+const users = response.data?.users || [];
+
+return users.map(user => ({
+  json: {
+    id: user.id,
+    name: user.profile?.name || 'Unknown',
+    email: user.contact?.email || 'no-email'
+  }
+}));
+```
+
+### Example 5: Combine with Other Methods
+
+```javascript
+// Get first item's data
+const firstData = $input.first().json;
+
+// Use it to filter all items
+const allItems = $input.all();
+const matching = allItems.filter(item =>
+  item.json.category === firstData.targetCategory
+);
+
+return matching;
+```
+
+---
+
+## Pattern 3: $input.item - Current Item (Each Item Mode)
+
+**Usage**: Common in "Run Once for Each Item" mode
+
+**When to use:**
+- Mode is set to "Run Once for Each Item"
+- Need to process items independently
+- Per-item API calls or validations
+- Item-specific error handling
+
+**IMPORTANT**: Only use in "Each Item" mode. Will be undefined in "All Items" mode.
+
+### Basic Usage
+
+```javascript
+// In "Run Once for Each Item" mode
+const currentItem = $input.item;
+const data = currentItem.json;
+
+console.log('Processing item:', data.id);
+
+return [{
+  json: {
+    ...data,
+    processed: true
+  }
+}];
+```
+
+### Example 1: Add Processing Metadata
+
+```javascript
+const item = $input.item;
+
+return [{
+  json: {
+    ...item.json,
+    processed: true,
+    processedAt: new Date().toISOString(),
+    processingDuration: Math.random() * 1000  // Simulated duration
+  }
+}];
+```
+
+### Example 2: Per-Item Validation
+
+```javascript
+const item = $input.item;
+const data = item.json;
+
+// Validate this specific item
+const errors = [];
+
+if (!data.email) errors.push('Email required');
+if (!data.name) errors.push('Name required');
+if (data.age && data.age < 18) errors.push('Must be 18+');
+
+return [{
+  json: {
+    ...data,
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined
+  }
+}];
+```
+
+### Example 3: Item-Specific API Call
+
+```javascript
+const item = $input.item;
+const userId = item.json.userId;
+
+// Make API call specific to this item
+const response = await this.helpers.httpRequest({
+  method: 'GET',
+  url: `https://api.example.com/users/${userId}/details`
+});
+
+return [{
+  json: {
+    ...item.json,
+    details: response
+  }
+}];
+```
+
+> ⚠️ **Use `this.helpers.httpRequest`, not `$helpers`.** In the Code node's task-runner sandbox (default since n8n v2.0) the bare `$helpers` global is undefined — `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`. **For authenticated APIs, don't extend this pattern.** `this.helpers.httpRequestWithAuthentication` is blocked in the task-runner sandbox. Use an HTTP Request node with the credential attached, or delegate to a sub-workflow whose HTTP Request node holds the credential. For anything beyond a trivial unauthenticated GET, prefer the HTTP Request node anyway. See ERROR_PATTERNS.md Error #6.
+
+### Example 4: Conditional Processing
+
+```javascript
+const item = $input.item;
+const data = item.json;
+
+// Process based on item type
+if (data.type === 'premium') {
+  return [{
+    json: {
+      ...data,
+      discount: 0.20,
+      tier: 'premium'
+    }
+  }];
+} else {
+  return [{
+    json: {
+      ...data,
+      discount: 0.05,
+      tier: 'standard'
+    }
+  }];
+}
+```
+
+---
+
+## Pattern 4: $node - Reference Other Nodes
+
+**Usage**: Less common, but powerful for specific scenarios
+
+**When to use:**
+- Need data from specific named node
+- Combining data from multiple nodes
+- Accessing metadata about workflow execution
+
+### Basic Usage
+
+```javascript
+// Get output from specific node
+const webhookData = $node["Webhook"].json;
+const apiData = $node["HTTP Request"].json;
+
+return [{
+  json: {
+    fromWebhook: webhookData,
+    fromAPI: apiData
+  }
+}];
+```
+
+### Example 1: Combine Multiple Sources
+
+```javascript
+// Reference multiple nodes
+const webhook = $node["Webhook"].json;
+const database = $node["Postgres"].json;
+const api = $node["HTTP Request"].json;
+
+return [{
+  json: {
+    combined: {
+      webhook: webhook.body,
+      dbRecords: database.length,
+      apiResponse: api.status
+    },
+    processedAt: new Date().toISOString()
+  }
+}];
+```
+
+### Example 2: Compare Across Nodes
+
+```javascript
+const oldData = $node["Get Old Data"].json;
+const newData = $node["Get New Data"].json;
+
+// Compare
+const changes = {
+  added: newData.filter(n => !oldData.find(o => o.id === n.id)),
+  removed: oldData.filter(o => !newData.find(n => n.id === o.id)),
+  modified: newData.filter(n => {
+    const old = oldData.find(o => o.id === n.id);
+    return old && JSON.stringify(old) !== JSON.stringify(n);
+  })
+};
+
+return [{
+  json: {
+    changes,
+    summary: {
+      added: changes.added.length,
+      removed: changes.removed.length,
+      modified: changes.modified.length
+    }
+  }
+}];
+```
+
+### Example 3: Access Node Metadata
+
+```javascript
+// Get data from specific execution path
+const ifTrueBranch = $node["IF True"].json;
+const ifFalseBranch = $node["IF False"].json;
+
+// Use whichever branch executed
+const result = ifTrueBranch || ifFalseBranch || {};
+
+return [{json: result}];
+```
+
+---
+
+## Critical: Webhook Data Structure
+
+**MOST COMMON MISTAKE**: Forgetting webhook data is nested under `.body`
+
+### The Problem
+
+Webhook node wraps all incoming data under a `body` property. This catches many developers by surprise.
+
+### Structure
+
+```javascript
+// Webhook node output structure:
+{
+  "headers": {
+    "content-type": "application/json",
+    "user-agent": "...",
+    // ... other headers
+  },
+  "params": {},
+  "query": {},
+  "body": {
+    // ← YOUR DATA IS HERE
+    "name": "Alice",
+    "email": "alice@example.com",
+    "message": "Hello!"
+  }
+}
+```
+
+### Wrong vs Right
+
+```javascript
+// ❌ WRONG: Trying to access directly
+const name = $json.name;  // undefined
+const email = $json.email;  // undefined
+
+// ✅ CORRECT: Access via .body
+const name = $json.body.name;  // "Alice"
+const email = $json.body.email;  // "alice@example.com"
+
+// ✅ CORRECT: Extract body first
+const webhookData = $json.body;
+const name = webhookData.name;  // "Alice"
+const email = webhookData.email;  // "alice@example.com"
+```
+
+### Example: Full Webhook Processing
+
+```javascript
+// Get webhook data from previous node
+const webhookOutput = $input.first().json;
+
+// Access the actual payload
+const payload = webhookOutput.body;
+
+// Access headers if needed
+const contentType = webhookOutput.headers['content-type'];
+
+// Access query parameters if needed
+const apiKey = webhookOutput.query.api_key;
+
+// Process the actual data
+return [{
+  json: {
+    // Data from webhook body
+    userName: payload.name,
+    userEmail: payload.email,
+    message: payload.message,
+
+    // Metadata
+    receivedAt: new Date().toISOString(),
+    contentType: contentType,
+    authenticated: !!apiKey
+  }
+}];
+```
+
+### POST Data, Query Params, and Headers
+
+```javascript
+const webhook = $input.first().json;
+
+return [{
+  json: {
+    // POST body data
+    formData: webhook.body,
+
+    // Query parameters (?key=value)
+    queryParams: webhook.query,
+
+    // HTTP headers
+    userAgent: webhook.headers['user-agent'],
+    contentType: webhook.headers['content-type'],
+
+    // Request metadata
+    method: webhook.method,  // POST, GET, etc.
+    url: webhook.url
+  }
+}];
+```
+
+### Common Webhook Scenarios
+
+```javascript
+// Scenario 1: Form submission
+const formData = $json.body;
+const name = formData.name;
+const email = formData.email;
+
+// Scenario 2: JSON API webhook
+const apiPayload = $json.body;
+const eventType = apiPayload.event;
+const data = apiPayload.data;
+
+// Scenario 3: Query parameters
+const apiKey = $json.query.api_key;
+const userId = $json.query.user_id;
+
+// Scenario 4: Headers
+const authorization = $json.headers['authorization'];
+const signature = $json.headers['x-signature'];
+```
+
+---
+
+## Choosing the Right Pattern
+
+### Decision Tree
+
+```
+Do you need ALL items from previous node?
+├─ YES → Use $input.all()
+│
+└─ NO → Do you need just the FIRST item?
+    ├─ YES → Use $input.first()
+    │
+    └─ NO → Are you in "Each Item" mode?
+        ├─ YES → Use $input.item
+        │
+        └─ NO → Do you need specific node data?
+            ├─ YES → Use $node["NodeName"]
+            └─ NO → Use $input.first() (default)
+```
+
+### Quick Reference Table
+
+| Scenario | Use This | Example |
+|----------|----------|---------|
+| Sum all amounts | `$input.all()` | `allItems.reduce((sum, i) => sum + i.json.amount, 0)` |
+| Get API response | `$input.first()` | `$input.first().json.data` |
+| Process each independently | `$input.item` | `$input.item.json` (Each Item mode) |
+| Combine two nodes | `$node["Name"]` | `$node["API"].json` |
+| Filter array | `$input.all()` | `allItems.filter(i => i.json.active)` |
+| Transform single object | `$input.first()` | `{...input.first().json, new: true}` |
+| Webhook data | `$input.first()` | `$input.first().json.body` |
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Using $json Without Context
+
+```javascript
+// ❌ WRONG: $json is ambiguous
+const value = $json.field;
+
+// ✅ CORRECT: Be explicit
+const value = $input.first().json.field;
+```
+
+### Mistake 2: Forgetting .json Property
+
+```javascript
+// ❌ WRONG: Trying to access fields on item object
+const items = $input.all();
+const names = items.map(item => item.name);  // undefined
+
+// ✅ CORRECT: Access via .json
+const names = items.map(item => item.json.name);
+```
+
+### Mistake 3: Using $input.item in All Items Mode
+
+```javascript
+// ❌ WRONG: $input.item is undefined in "All Items" mode
+const data = $input.item.json;  // Error!
+
+// ✅ CORRECT: Use appropriate method
+const data = $input.first().json;  // Or $input.all()
+```
+
+### Mistake 4: Not Handling Empty Arrays
+
+```javascript
+// ❌ WRONG: Crashes if no items
+const first = $input.all()[0].json;
+
+// ✅ CORRECT: Check length first
+const items = $input.all();
+if (items.length === 0) {
+  return [];
+}
+const first = items[0].json;
+
+// ✅ ALSO CORRECT: Use $input.first()
+const first = $input.first().json;  // Built-in safety
+```
+
+### Mistake 5: Modifying Original Data
+
+```javascript
+// ❌ RISKY: Mutating original
+const items = $input.all();
+items[0].json.modified = true;  // Modifies original
+return items;
+
+// ✅ SAFE: Create new objects
+const items = $input.all();
+return items.map(item => ({
+  json: {
+    ...item.json,
+    modified: true
+  }
+}));
+```
+
+---
+
+## Advanced Patterns
+
+### Pattern: Pagination Handling
+
+```javascript
+const currentPage = $input.all();
+const pageNumber = $node["Set Page"].json.page || 1;
+
+// Combine with previous pages
+const allPreviousPages = $node["Accumulator"]?.json.accumulated || [];
+
+return [{
+  json: {
+    accumulated: [...allPreviousPages, ...currentPage],
+    currentPage: pageNumber,
+    totalItems: allPreviousPages.length + currentPage.length
+  }
+}];
+```
+
+### Pattern: Conditional Node Reference
+
+```javascript
+// Access different nodes based on condition
+const condition = $input.first().json.type;
+
+let data;
+if (condition === 'api') {
+  data = $node["API Response"].json;
+} else if (condition === 'database') {
+  data = $node["Database"].json;
+} else {
+  data = $node["Default"].json;
+}
+
+return [{json: data}];
+```
+
+### Pattern: Multi-Node Aggregation
+
+```javascript
+// Collect data from multiple named nodes
+const sources = ['Source1', 'Source2', 'Source3'];
+const allData = [];
+
+for (const source of sources) {
+  const nodeData = $node[source]?.json;
+  if (nodeData) {
+    allData.push({
+      source,
+      data: nodeData
+    });
+  }
+}
+
+return allData.map(item => ({json: item}));
+```
+
+---
+
+## Summary
+
+**Most Common Patterns**:
+1. `$input.all()` - Process multiple items, batch operations
+2. `$input.first()` - Single item, API responses
+3. `$input.item` - Each Item mode processing
+
+**Critical Rule**:
+- Webhook data is under `.body` property
+
+**Best Practice**:
+- Be explicit: Use `$input.first().json.field` instead of `$json.field`
+- Always check for null/undefined
+- Use appropriate method for your mode (All Items vs Each Item)
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Overview and quick start
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Production patterns
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Avoid common mistakes
+
+---
+
+## Mode Performance: Why "All Items" Is Faster
+
+Mode choice is the single biggest performance lever in a Code node, and the reason generalizes to the rest of your workflow. Every time n8n hands items to a *per-item* execution context it pays a setup cost. Measured on an n8n 2.x instance (small records, ~10k items):
+
+| What runs per item | Approx. cost | Why |
+|---|---|---|
+| Code **All Items** (one run for the whole set) | ~0.02 ms/item | one context setup, then plain JS — the loop is free |
+| Expression in any node (IF / Set / etc.) | ~0.2 ms/item | a light eval context per item |
+| Code **Each Item** | ~0.6 ms/item | a full code sandbox per item — ~3× an expression, ~25–30× All Items |
+
+So `Run Once for Each Item` over 10k items is ~6 s of pure overhead vs ~0.2 s for the same logic in `Run Once for All Items`. Use Each Item only when an item genuinely needs isolating (independent error handling, or a per-item API call you can't batch); otherwise loop *inside* one All Items node.
+
+Two corollaries you will hit constantly:
+
+- **Expression complexity is essentially free.** An elaborate `{{ }}` measures the same as a trivial one — ~90% of the cost is n8n building the per-item context, not running your code. Don't simplify expressions for speed; reduce the *number* of per-item boundaries instead.
+- **Every node→node hop re-copies all items** (~0.05 ms/item per hop). Six chained All Items Code nodes cost ~7× a single node doing the same six steps, so consolidate a hot transform chain into one All Items node — and never build a chain of *Each Item* Code nodes, where the per-item tax multiplies by node count (a 6-node Each-Item chain over 2k items ≈ 7 s).
+
+**Scale check:** below a few hundred items this is all sub-100 ms and not worth a thought, and most real workflows are dominated by I/O (HTTP / DB / Sheets round-trips) that dwarfs node overhead. Reach for these rules on the hot path — large item counts with little I/O — not everywhere.
+
+---
+
+## Production Gotchas
+
+Hard-won lessons from real-world n8n workflow deployments.
+
+### SplitInBatches Loop Semantics
+
+The SplitInBatches node has two outputs — and the naming is counterintuitive:
+- `main[0]` = **done** — fires ONCE after all batches are processed
+- `main[1]` = **each batch** — fires for every batch (this is the loop body)
+
+Always add a **Limit 1** node after the done output before downstream processing, as a safety against edge cases where done fires with extra items.
+
+### SplitInBatches: Iteration Count Is the Cost
+
+Each loop iteration re-executes the entire loop body through the workflow engine — ~0.8 ms per iteration of pure overhead, on top of whatever the body does. Total ≈ `⌈items / batchSize⌉ × (~0.8 ms + body cost)`:
+
+- `batchSize: 1` over N items pays that N times — it's the loop equivalent of *Run Once for Each Item* (and if the body has several nodes, each iteration re-pays all of them).
+- Raising `batchSize` cuts iterations proportionally; the body still sees every item. Use the **largest batch your real constraint allows** (API rate limit, page size, memory). If you don't need batching at all, don't loop — process the whole set in one All Items node.
+
+### Cross-Iteration Data Accumulation (CRITICAL)
+
+After a SplitInBatches loop, `$('Node Inside Loop').all()` returns **ONLY the last iteration's items**, not cumulative results. This silently drops data from all but the final batch.
+
+**Fix**: Use workflow static data to accumulate across iterations:
+
+```javascript
+// BEFORE the loop (reset accumulator):
+const staticData = $getWorkflowStaticData('global');
+staticData.results = [];
+return $input.all();
+
+// INSIDE the loop body (accumulate):
+const staticData = $getWorkflowStaticData('global');
+const results = [];
+for (const item of $input.all()) {
+  const processed = { /* ... */ };
+  results.push({ json: processed });
+  staticData.results.push(processed);
+}
+return results;
+
+// AFTER the loop (read accumulated data):
+const staticData = $getWorkflowStaticData('global');
+const allResults = staticData.results || [];
+// Now aggregate across ALL iterations
+```
+
+### pairedItem for New Output Items
+
+When creating new items that don't map 1:1 to input items, include `pairedItem` — otherwise downstream Set nodes fail with `paired_item_no_info`:
+
+```javascript
+const results = [];
+for (let i = 0; i < $input.all().length; i++) {
+  const item = $input.all()[i];
+  results.push({
+    json: { /* new data */ },
+    pairedItem: { item: i }
+  });
+}
+return results;
+```
+
+### Correct Node Reference Syntax
+
+```javascript
+// ❌ WRONG - .json directly on node reference
+const data = $('HTTP Request').json;
+
+// ✅ CORRECT - call .first() then access .json
+const data = $('HTTP Request').first().json;
+
+// ✅ Also correct - get all items
+const allData = $('HTTP Request').all();
+```
+
+### Float Precision for Price/Currency Comparison
+
+When comparing prices or currency values, floating point noise can cause false positives. Round to cents:
+
+```javascript
+// ❌ Unreliable - float comparison
+if (newPrice !== oldPrice) { /* triggers on noise */ }
+
+// ✅ Reliable - compare at cent level
+if (Math.round(newPrice * 100) !== Math.round(oldPrice * 100)) {
+  // Real price change detected
+}
+```

data/skills/n8n-code-javascript/ERROR_PATTERNS.md

@@ -0,0 +1,857 @@
+# Error Patterns - JavaScript Code Node
+
+Complete guide to avoiding the most common Code node errors.
+
+---
+
+## Overview
+
+This guide covers the **top 5 error patterns** encountered in n8n Code nodes. Understanding and avoiding these errors will save you significant debugging time.
+
+**Error frequency (roughly ordered)**:
+1. Empty Code / Missing Return - the dominant error n8n itself rejects
+2. Expression Syntax used as Code - `{{ }}` written where JavaScript belongs
+3. Return Shape - primitive/`null` returns (bare objects auto-wrap)
+4. Broken Strings / Escaping - unbalanced quotes/brackets throw a JS syntax error
+5. Missing Null Checks - common runtime error
+
+---
+
+## Error #1: Empty Code or Missing Return Statement
+
+**Frequency**: Most common error (38% of all validation failures)
+
+**What Happens**:
+- Workflow execution fails
+- Next nodes receive no data
+- Error: "Code cannot be empty" or "Code must return data"
+
+### The Problem
+
+```javascript
+// ❌ ERROR: No code at all
+// (Empty code field)
+```
+
+```javascript
+// ❌ ERROR: Code executes but doesn't return anything
+const items = $input.all();
+
+// Process items
+for (const item of items) {
+  console.log(item.json.name);
+}
+
+// Forgot to return!
+```
+
+```javascript
+// ❌ ERROR: Early return path exists, but not all paths return
+const items = $input.all();
+
+if (items.length === 0) {
+  return [];  // ✅ This path returns
+}
+
+// Process items
+const processed = items.map(item => ({json: item.json}));
+
+// ❌ Forgot to return processed!
+```
+
+### The Solution
+
+```javascript
+// ✅ CORRECT: Always return data
+const items = $input.all();
+
+// Process items
+const processed = items.map(item => ({
+  json: {
+    ...item.json,
+    processed: true
+  }
+}));
+
+return processed;  // ✅ Return statement present
+```
+
+```javascript
+// ✅ CORRECT: Return empty array if no items
+const items = $input.all();
+
+if (items.length === 0) {
+  return [];  // Valid: empty array when no data
+}
+
+// Process and return
+return items.map(item => ({json: item.json}));
+```
+
+```javascript
+// ✅ CORRECT: All code paths return
+const items = $input.all();
+
+if (items.length === 0) {
+  return [];
+} else if (items.length === 1) {
+  return [{json: {single: true, data: items[0].json}}];
+} else {
+  return items.map(item => ({json: item.json}));
+}
+
+// All paths covered
+```
+
+### Checklist
+
+- [ ] Code field is not empty
+- [ ] Return statement exists
+- [ ] ALL code paths return data (if/else branches)
+- [ ] Return format is correct (`[{json: {...}}]`)
+- [ ] Return happens even on errors (use try-catch)
+
+---
+
+## Error #2: Expression Syntax Confusion
+
+**What Happens** — there are two distinct cases, and only one is a syntax error:
+- **`{{ }}` inside a string literal**: valid JavaScript that runs fine, but you get the *literal text* `{{ ... }}` instead of a value — n8n does not evaluate expressions inside Code-node code. A logic bug, not a validation error. (n8n-mcp ≥ 2.63.0 no longer flags `{{ }}` inside string literals — prompt templates, payload placeholders, and `.replace()` tokens are legitimate.)
+- **`{{ }}` written as bare code** (e.g. `return {{ $json.x }}`): a genuine JavaScript syntax error. The validator reports "Expression syntax {{...}} is not valid in Code nodes" and n8n throws "Unexpected token".
+
+### The Problem
+
+n8n has TWO distinct syntaxes:
+1. **Expression syntax** `{{ }}` - Used in OTHER nodes (Set, IF, HTTP Request)
+2. **JavaScript** - Used in CODE nodes
+
+Many developers mistakenly reach for expression syntax inside a Code node when they want a *value*. Putting `{{ }}` in a string does not interpolate it:
+
+```javascript
+// ❌ LOGIC BUG: n8n never evaluates {{ }} in Code-node strings
+const userName = "{{ $json.name }}";
+const userEmail = "{{ $json.body.email }}";
+
+return [{
+  json: {
+    name: userName,
+    email: userEmail
+  }
+}];
+
+// Result: Literal string "{{ $json.name }}", NOT the value!
+// (This runs — it just doesn't do what you meant. Use $json.name directly.)
+```
+
+```javascript
+// ❌ SYNTAX ERROR: {{ }} used as code, not inside a string
+const value = {{ $now.toFormat('yyyy-MM-dd') }};  // "Unexpected token"
+```
+
+### The Solution
+
+```javascript
+// ✅ CORRECT: Use JavaScript directly (no {{ }})
+const userName = $json.name;
+const userEmail = $json.body.email;
+
+return [{
+  json: {
+    name: userName,
+    email: userEmail
+  }
+}];
+```
+
+```javascript
+// ✅ CORRECT: JavaScript template literals (use backticks)
+const message = `Hello, ${$json.name}! Your email is ${$json.email}`;
+
+return [{
+  json: {
+    greeting: message
+  }
+}];
+```
+
+```javascript
+// ✅ CORRECT: Direct variable access
+const item = $input.first().json;
+
+return [{
+  json: {
+    name: item.name,
+    email: item.email,
+    timestamp: new Date().toISOString()  // JavaScript Date, not {{ }}
+  }
+}];
+```
+
+### Comparison Table
+
+| Context | Syntax | Example |
+|---------|--------|---------|
+| Set node | `{{ }}` expressions | `{{ $json.name }}` |
+| IF node | `{{ }}` expressions | `{{ $json.age > 18 }}` |
+| HTTP Request URL | `{{ }}` expressions | `{{ $json.userId }}` |
+| **Code node** | **JavaScript** | `$json.name` |
+| **Code node strings** | **Template literals** | `` `Hello ${$json.name}` `` |
+
+### Quick Fix Guide
+
+```javascript
+// WRONG → RIGHT conversions
+
+// ❌ "{{ $json.field }}"
+// ✅ $json.field
+
+// ❌ "{{ $now }}"
+// ✅ new Date().toISOString()
+
+// ❌ "{{ $node['HTTP Request'].json.data }}"
+// ✅ $node["HTTP Request"].json.data
+
+// ❌ `{{ $json.firstName }} {{ $json.lastName }}`
+// ✅ `${$json.firstName} ${$json.lastName}`
+```
+
+---
+
+## Error #3: Return Shape
+
+**What actually happens** — n8n is more forgiving than the old advice implied:
+- In *Run Once for All Items* mode, n8n **auto-normalizes** a single bare object, or an array of bare objects, by wrapping each under a `json` property. So these run.
+- What genuinely fails, with "Code doesn't return items properly", is returning a **primitive** (string/number/boolean) or **`null`/`undefined`** — there is nothing to wrap.
+
+(n8n-mcp ≥ 2.63.0 no longer errors "Return value must be an array of objects" on a bare-object return; the earlier claim contradicted n8n's auto-wrap behavior.)
+
+### Prefer the Canonical Form
+
+The canonical `[{json: {...}}]` is unambiguous and behaves identically in both execution modes, so make it your default even though looser shapes are auto-wrapped:
+
+```javascript
+// ⚠️ Auto-wrapped → [{json: {result: 'success'}}]. Runs, but prefer the array + json form.
+return {
+  json: {
+    result: 'success'
+  }
+};
+```
+
+```javascript
+// ⚠️ Auto-wrapped → each object gets a json wrapper. Runs, but be explicit.
+return [
+  {id: 1, name: 'Alice'},
+  {id: 2, name: 'Bob'}
+];
+```
+
+```javascript
+// ✅ Fine — input items already carry a json property; returning them unchanged is a valid passthrough
+return $input.all();
+```
+
+```javascript
+// ❌ FAILS: primitive value — nothing to wrap into an item
+return "processed";
+```
+
+```javascript
+// ❌ FAILS: null / undefined — no items to pass on
+return null;
+```
+
+### The Solution
+
+```javascript
+// ✅ CORRECT: Single result
+return [{
+  json: {
+    result: 'success',
+    timestamp: new Date().toISOString()
+  }
+}];
+```
+
+```javascript
+// ✅ CORRECT: Multiple results
+return [
+  {json: {id: 1, name: 'Alice'}},
+  {json: {id: 2, name: 'Bob'}},
+  {json: {id: 3, name: 'Carol'}}
+];
+```
+
+```javascript
+// ✅ CORRECT: Transforming array
+const items = $input.all();
+
+return items.map(item => ({
+  json: {
+    id: item.json.id,
+    name: item.json.name,
+    processed: true
+  }
+}));
+```
+
+```javascript
+// ✅ CORRECT: Empty result
+return [];
+// Valid when no data to return
+```
+
+```javascript
+// ✅ CORRECT: Conditional returns
+if (shouldProcess) {
+  return [{json: {result: 'processed'}}];
+} else {
+  return [];
+}
+```
+
+### Return Format Checklist
+
+- [ ] Return value is an **array** `[...]` (canonical — preferred)
+- [ ] Each array element has a **`json` property**
+- [ ] Structure is `[{json: {...}}]` or `[{json: {...}}, {json: {...}}]`
+- [ ] Not a primitive (string/number/boolean) or `null`/`undefined` — those are the shapes that actually fail
+
+### Common Scenarios
+
+```javascript
+// Scenario 1: Single object from API
+const response = $input.first().json;
+
+// ✅ CANONICAL
+return [{json: response}];
+
+// ⚠️ Auto-wrapped to the same thing — runs, but prefer the array form
+return {json: response};
+
+
+// Scenario 2: Array of objects
+const users = $input.all();
+
+// ✅ CANONICAL
+return users.map(user => ({json: user.json}));
+
+// ✅ Also fine — a passthrough of items that already carry json
+return users;
+
+
+// Scenario 3: Computed result
+const total = $input.all().reduce((sum, item) => sum + item.json.amount, 0);
+
+// ✅ CANONICAL
+return [{json: {total}}];
+
+// ⚠️ Auto-wrapped → [{json: {total}}] in All Items mode — runs, but be explicit
+return {total};
+
+
+// Scenario 4: No results
+// ✅ CORRECT
+return [];
+
+// ❌ FAILS — null has no items to pass on
+return null;
+```
+
+---
+
+## Error #4: Broken Strings & Escaping (JavaScript syntax errors)
+
+**What Happens**:
+- The Code node throws a JavaScript syntax error at execution: "Unexpected token" or "Unexpected end of input"
+- Cause is your own JS — unbalanced quotes or a raw newline inside a plain quoted string
+
+This is a plain JavaScript concern, **not** a validator check. The validator (n8n-mcp ≥ 2.63.0) does not flag balanced apostrophes, `{ }` in regex, or `{{ }}` sitting inside a string literal — those are all valid JavaScript. Only genuinely malformed JS throws, and it throws at runtime.
+
+### The Problem
+
+This happens when:
+1. A quote inside a same-quoted string is left unescaped
+2. A plain (non-template) string spans multiple lines
+3. Backslashes in paths/regex are not escaped
+
+```javascript
+// ✅ FINE: an apostrophe inside a double-quoted string is valid JavaScript
+const message = "It's a nice day";
+
+// ✅ FINE: braces in a regex literal are valid
+const pattern = /\{(\w+)\}/;
+```
+
+```javascript
+// ❌ SYNTAX ERROR: raw newline + unescaped inner double-quotes in a plain string
+const html = "
+  <div class="container">
+    <p>Hello</p>
+  </div>
+";
+```
+
+### The Solution
+
+```javascript
+// ✅ Mix quote styles or escape, whichever reads cleaner
+const message = "It's a nice day";     // double quotes around an apostrophe — fine
+const other   = 'She said "hello"';    // single quotes around double quotes — fine
+```
+
+```javascript
+// ✅ Regex literals need no extra escaping of their own braces
+const pattern = /\{(\w+)\}/;
+```
+
+```javascript
+// ✅ CORRECT: Template literals for multi-line
+const html = `
+  <div class="container">
+    <p>Hello</p>
+  </div>
+`;
+// Backticks handle multi-line and quotes
+```
+
+```javascript
+// ✅ CORRECT: Escape backslashes
+const path = "C:\\\\Users\\\\Documents\\\\file.txt";
+```
+
+### Escaping Guide
+
+| Character | Escape As | Example |
+|-----------|-----------|---------|
+| Single quote in single-quoted string | `\\'` | `'It\\'s working'` |
+| Double quote in double-quoted string | `\\"` | `"She said \\"hello\\""` |
+| Backslash | `\\\\` | `"C:\\\\path"` |
+| Newline | `\\n` | `"Line 1\\nLine 2"` |
+| Tab | `\\t` | `"Column1\\tColumn2"` |
+
+### Best Practices
+
+```javascript
+// ✅ BEST: Use template literals for complex strings
+const message = `User ${name} said: "Hello!"`;
+
+// ✅ BEST: Use template literals for HTML
+const html = `
+  <div class="${className}">
+    <h1>${title}</h1>
+    <p>${content}</p>
+  </div>
+`;
+
+// ✅ BEST: Use template literals for JSON
+const jsonString = `{
+  "name": "${name}",
+  "email": "${email}"
+}`;
+```
+
+---
+
+## Error #5: Missing Null Checks / Undefined Access
+
+**Frequency**: Very common runtime error
+
+**What Happens**:
+- Workflow execution stops
+- Error: "Cannot read property 'X' of undefined"
+- Error: "Cannot read property 'X' of null"
+- Crashes on missing data
+
+### The Problem
+
+```javascript
+// ❌ WRONG: No null check - crashes if user doesn't exist
+const email = item.json.user.email;
+```
+
+```javascript
+// ❌ WRONG: Assumes array has items
+const firstItem = $input.all()[0].json;
+```
+
+```javascript
+// ❌ WRONG: Assumes nested property exists
+const city = $json.address.city;
+```
+
+```javascript
+// ❌ WRONG: No validation before array operations
+const names = $json.users.map(user => user.name);
+```
+
+### The Solution
+
+```javascript
+// ✅ CORRECT: Optional chaining
+const email = item.json?.user?.email || 'no-email@example.com';
+```
+
+```javascript
+// ✅ CORRECT: Check array length
+const items = $input.all();
+
+if (items.length === 0) {
+  return [];
+}
+
+const firstItem = items[0].json;
+```
+
+```javascript
+// ✅ CORRECT: Guard clauses
+const data = $input.first().json;
+
+if (!data.address) {
+  return [{json: {error: 'No address provided'}}];
+}
+
+const city = data.address.city;
+```
+
+```javascript
+// ✅ CORRECT: Default values
+const users = $json.users || [];
+const names = users.map(user => user.name || 'Unknown');
+```
+
+```javascript
+// ✅ CORRECT: Try-catch for risky operations
+try {
+  const email = item.json.user.email.toLowerCase();
+  return [{json: {email}}];
+} catch (error) {
+  return [{
+    json: {
+      error: 'Invalid user data',
+      details: error.message
+    }
+  }];
+}
+```
+
+### Safe Access Patterns
+
+```javascript
+// Pattern 1: Optional chaining (modern, recommended)
+const value = data?.nested?.property?.value;
+
+// Pattern 2: Logical OR with default
+const value = data.property || 'default';
+
+// Pattern 3: Ternary check
+const value = data.property ? data.property : 'default';
+
+// Pattern 4: Guard clause
+if (!data.property) {
+  return [];
+}
+const value = data.property;
+
+// Pattern 5: Try-catch
+try {
+  const value = data.nested.property.value;
+} catch (error) {
+  const value = 'default';
+}
+```
+
+### Webhook Data Safety
+
+```javascript
+// Webhook data requires extra safety
+
+// ❌ RISKY: Assumes all fields exist
+const name = $json.body.user.name;
+const email = $json.body.user.email;
+
+// ✅ SAFE: Check each level
+const body = $json.body || {};
+const user = body.user || {};
+const name = user.name || 'Unknown';
+const email = user.email || 'no-email';
+
+// ✅ BETTER: Optional chaining
+const name = $json.body?.user?.name || 'Unknown';
+const email = $json.body?.user?.email || 'no-email';
+```
+
+### Array Safety
+
+```javascript
+// ❌ RISKY: No length check
+const items = $input.all();
+const firstId = items[0].json.id;
+
+// ✅ SAFE: Check length
+const items = $input.all();
+
+if (items.length > 0) {
+  const firstId = items[0].json.id;
+} else {
+  // Handle empty case
+  return [];
+}
+
+// ✅ BETTER: Use $input.first()
+const firstItem = $input.first();
+const firstId = firstItem.json.id;  // Built-in safety
+```
+
+### Object Property Safety
+
+```javascript
+// ❌ RISKY: Direct access
+const config = $json.settings.advanced.timeout;
+
+// ✅ SAFE: Step by step with defaults
+const settings = $json.settings || {};
+const advanced = settings.advanced || {};
+const timeout = advanced.timeout || 30000;
+
+// ✅ BETTER: Optional chaining
+const timeout = $json.settings?.advanced?.timeout ?? 30000;
+// Note: ?? (nullish coalescing) vs || (logical OR)
+```
+
+---
+
+## Error #6: UnsupportedFunctionError (Auth Helpers Blocked)
+
+**Frequency**: The most common "this worked yesterday in old n8n" error after upgrading to v2.0+
+
+**What Happens**:
+- Error: `UnsupportedFunctionError: The function "helpers.httpRequestWithAuthentication" is not supported in the Code Node`
+- Same for `helpers.requestWithAuthenticationPaginated`
+- Throws on execution, not on save
+
+### The Problem
+
+Since n8n v2.0, Code nodes execute in the **task runner sandbox** which deliberately blocks the auth helpers. The legacy vm2 sandbox used to bind them, which is why old forum posts and tutorials show them working. n8n's source comment explains why: the Code node has no credential of its own, so the helper had nothing to authenticate against — it was always semantically broken, just not always loud about it.
+
+```javascript
+// ❌ BLOCKED in task runner sandbox (default since v2.0)
+const data = await this.helpers.httpRequestWithAuthentication.call(
+  this,
+  'baseLinkerApi',
+  { url: '...', method: 'POST' }
+);
+```
+
+### The Solution
+
+There is **no env flag** to re-enable these in the runner — the deny-list is compiled-in. Pick one of:
+
+**Option A — Replace the Code node with an HTTP Request node** (best):
+
+The HTTP Request node natively supports credential attachment with full expression support for URL/body/headers. Most "Code-node-makes-an-API-call" patterns are leftovers from before HTTP Request had pagination and expression support.
+
+**Option B — Sub-workflow with HTTP Request node** (when you need code-level logic before/after):
+
+```javascript
+// Parent Code node — prepare payloads, then delegate
+return $input.all().map(i => ({ json: {
+  url: 'https://api.example.com/things',
+  method: 'POST',
+  body: { sku: i.json.sku }
+}}));
+```
+
+Then wire to **Execute Workflow** → child workflow with **Execute Workflow Trigger** → **HTTP Request** node using `={{ $json.url }}`, `={{ $json.body }}`, with the credential attached natively.
+
+**Option C — Token as runtime data** (only when the token genuinely flows through the workflow):
+
+```javascript
+// ✅ Works — manual auth header, token came from upstream
+const token = $('Get Token').first().json.access_token;
+
+const data = await this.helpers.httpRequest({
+  url: 'https://api.example.com/data',
+  headers: { 'Authorization': `Bearer ${token}` }
+});
+```
+
+### Decision Guide
+
+| Need | Use |
+|------|-----|
+| Single authenticated API call | HTTP Request node directly |
+| Many API calls + pre/post processing | Sub-workflow pattern (Option B) |
+| Token already in the data flow | Manual `this.helpers.httpRequest()` with header |
+| `httpRequestWithAuthentication` | **Doesn't work — pick A, B, or C above** |
+
+---
+
+## Error #7: $env is not defined / Cannot access $env
+
+**Frequency**: Common in hardened production instances
+
+**What Happens**:
+- Error: `$env is not defined` or `ReferenceError: $env is not defined`
+- Code looks correct, runs fine on dev instance, throws in production
+
+### The Problem
+
+`$env` access is gated by the **`N8N_BLOCK_ENV_ACCESS_IN_NODE`** environment variable. When set to `true` (a common production hardening setting), `$env` is removed from the Code node sandbox entirely. This is increasingly the default in security-conscious deployments.
+
+```javascript
+// ❌ Throws if N8N_BLOCK_ENV_ACCESS_IN_NODE=true
+const apiKey = $env.API_KEY;
+```
+
+### The Solution
+
+Treat secrets as a **credential concern**, not a Code-node concern:
+
+```javascript
+// ✅ Token arrives as data from an upstream node that used a credential
+const apiKey = $('Set Secret').first().json.apiKey;
+
+// Or: secret was attached server-side by an HTTP Request node with the credential
+// — your Code node never sees the raw secret, which is the whole point
+```
+
+For values you genuinely need to inject from outside the workflow (config, not secrets), use:
+- A **Set** node at the top of the workflow with hardcoded constants, or
+- An **n8n credential** referenced by an HTTP Request node, or
+- The **External Secrets** integration (`$secrets`) if your edition supports it.
+
+### Why This Matters
+
+Skills and tutorials written before 2024 routinely use `$env.API_KEY` because it was the path of least resistance. Modern n8n setups block it because letting Code nodes read arbitrary env vars is a privilege escalation surface — any user with workflow-edit access could exfiltrate `DB_PASSWORD`, `N8N_ENCRYPTION_KEY`, etc. Don't fight the restriction; route secrets through credentials.
+
+---
+
+## Error Prevention Checklist
+
+Use this checklist before deploying Code nodes:
+
+### Code Structure
+- [ ] Code field is not empty
+- [ ] Return statement exists
+- [ ] All code paths return data
+
+### Return Format
+- [ ] Returns items, not a primitive/`null`
+- [ ] Canonical shape `[{json: {...}}]` (bare objects auto-wrap, but be explicit)
+
+### Syntax
+- [ ] No `{{ }}` written as code (it's for other nodes' fields; in a string it's just literal text)
+- [ ] Template literals use backticks: `` `${variable}` ``
+- [ ] All quotes and brackets balanced
+- [ ] Strings properly escaped
+
+### Data Safety
+- [ ] Null checks for optional properties
+- [ ] Array length checks before access
+- [ ] Webhook data accessed via `.body`
+- [ ] Try-catch for risky operations
+- [ ] Default values for missing data
+
+### Testing
+- [ ] Test with empty input
+- [ ] Test with missing fields
+- [ ] Test with unexpected data types
+- [ ] Check browser console for errors
+
+---
+
+## Quick Error Reference
+
+| Error Message | Likely Cause | Fix |
+|---------------|--------------|-----|
+| "Code cannot be empty" | Empty code field | Add meaningful code |
+| "Code must return data" | Missing return statement | Add `return [...]` |
+| "Code doesn't return items properly" | Returned a primitive (string/number) or `null` | Return `[{json:{...}}]` (objects/arrays auto-wrap; primitives don't) |
+| "Not all items have a json key" | Mixed return — some items wrapped, some bare | Wrap every item: `{json: {...}}` |
+| "Expression syntax {{...}} is not valid in Code nodes" / "Unexpected token" | `{{ }}` written as code (not inside a string) | Use JavaScript: `$json.x` or `` `${$json.x}` `` |
+| "Cannot read property X of undefined" | Missing null check | Use optional chaining `?.` |
+| "Cannot read property X of null" | Null value access | Add guard clause or default |
+| "Unexpected end of input" | Unbalanced quotes/brackets in your JS | Escape strings or use backtick template literals |
+| "UnsupportedFunctionError ... httpRequestWithAuthentication" | Auth helper blocked in task runner | Use HTTP Request node + credential, or sub-workflow pattern (Error #6) |
+| "$env is not defined" | `N8N_BLOCK_ENV_ACCESS_IN_NODE=true` | Route secrets through credentials, not `$env` (Error #7) |
+| "Cannot find module 'crypto'" | `require()` allowlist not set | Move logic out of Code node, or set `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` |
+
+---
+
+## Debugging Tips
+
+### 1. Use console.log()
+
+```javascript
+const items = $input.all();
+console.log('Items count:', items.length);
+console.log('First item:', items[0]);
+
+// Check browser console (F12) for output
+```
+
+### 2. Return Intermediate Results
+
+```javascript
+// Debug by returning current state
+const items = $input.all();
+const processed = items.map(item => ({json: item.json}));
+
+// Return to see what you have
+return processed;
+```
+
+### 3. Try-Catch for Troubleshooting
+
+```javascript
+try {
+  // Your code here
+  const result = riskyOperation();
+  return [{json: {result}}];
+} catch (error) {
+  // See what failed
+  return [{
+    json: {
+      error: error.message,
+      stack: error.stack
+    }
+  }];
+}
+```
+
+### 4. Validate Input Structure
+
+```javascript
+const items = $input.all();
+
+// Check what you received
+console.log('Input structure:', JSON.stringify(items[0], null, 2));
+
+// Then process
+```
+
+---
+
+## Summary
+
+**Top 7 Errors to Avoid**:
+1. **Empty code / missing return** - Always return data
+2. **Expression syntax as code** - Use JavaScript, not `{{ }}` (in-string `{{ }}` is just literal text)
+3. **Return shape** - prefer `[{json: {...}}]`; primitives/`null` fail (bare objects auto-wrap)
+4. **Broken strings** - unbalanced quotes/brackets throw a JS syntax error; escape or use template literals
+5. **Missing null checks** - Use optional chaining `?.`
+6. **`httpRequestWithAuthentication` blocked** - Use HTTP Request node + credential
+7. **`$env` blocked** - Route secrets through credentials, not env access
+
+**Quick Prevention**:
+- Prefer the canonical `[{json: {...}}]` return; never return a primitive or `null`
+- Write JavaScript — don't put `{{ }}` where code belongs
+- Check for null/undefined before accessing
+- Test with empty and invalid data
+- Use browser console for debugging
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Overview and best practices
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Safe data access patterns
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Working examples

data/skills/n8n-code-javascript/README.md

@@ -0,0 +1,350 @@
+# n8n Code JavaScript
+
+Expert guidance for writing JavaScript code in n8n Code nodes.
+
+---
+
+## Purpose
+
+Teaches how to write effective JavaScript in n8n Code nodes, avoid common errors, and use built-in functions effectively.
+
+---
+
+## Activates On
+
+**Trigger keywords**:
+- "javascript code node"
+- "write javascript in n8n"
+- "code node javascript"
+- "$input syntax"
+- "$json syntax"
+- "this.helpers.httpRequest" / "$helpers.httpRequest"
+- "DateTime luxon"
+- "code node error"
+- "webhook data code"
+- "return format code node"
+
+**Common scenarios**:
+- Writing JavaScript code in Code nodes
+- Troubleshooting Code node errors
+- Making HTTP requests from code
+- Working with dates and times
+- Accessing webhook data
+- Choosing between All Items and Each Item mode
+
+---
+
+## What You'll Learn
+
+### Quick Start
+- Mode selection (All Items vs Each Item)
+- Data access patterns ($input.all(), $input.first(), $input.item)
+- Correct return format: `[{json: {...}}]`
+- Webhook data structure (.body nesting)
+- Built-in functions overview
+
+### Data Access Mastery
+- $input.all() - Batch operations (most common)
+- $input.first() - Single item operations
+- $input.item - Each Item mode processing
+- $node - Reference other workflow nodes
+- **Critical gotcha**: Webhook data under `.body`
+
+### Common Patterns (Production-Tested)
+1. Multi-source Data Aggregation
+2. Regex Filtering & Pattern Matching
+3. Markdown Parsing & Structured Extraction
+4. JSON Comparison & Validation
+5. CRM Data Transformation
+6. Release Information Processing
+7. Array Transformation with Context
+8. Slack Block Kit Formatting
+9. Top N Filtering & Ranking
+10. String Aggregation & Reporting
+
+### Error Prevention
+Top 5 errors to avoid:
+1. **Empty code / missing return** (38% of failures)
+2. **Expression syntax confusion** (using `{{}}` in code)
+3. **Incorrect return format** (missing array wrapper or json property)
+4. **Unmatched brackets** (string escaping issues)
+5. **Missing null checks** (crashes on undefined)
+
+### Built-in Functions
+- **this.helpers.httpRequest()** - Make HTTP requests (the bare `$helpers` global is undefined in the task-runner sandbox; prefer the HTTP Request node for anything beyond a trivial unauthenticated GET)
+- **DateTime (Luxon)** - Advanced date/time operations
+- **$jmespath()** - Query JSON structures
+- **$getWorkflowStaticData()** - Persistent storage
+- Standard JavaScript globals (Math, JSON, console)
+- Available Node.js modules (crypto, Buffer, URL)
+
+---
+
+## File Structure
+
+```
+n8n-code-javascript/
+├── SKILL.md
+│   Overview, quick start, mode selection, best practices
+│   - Mode selection guide (All Items vs Each Item)
+│   - Data access patterns overview
+│   - Return format requirements
+│   - Critical webhook gotcha
+│   - Error prevention overview
+│   - Quick reference checklist
+│
+├── DATA_ACCESS.md
+│   Complete data access patterns
+│   - $input.all() - Most common (26% usage)
+│   - $input.first() - Very common (25% usage)
+│   - $input.item - Each Item mode (19% usage)
+│   - $node - Reference other nodes
+│   - Webhook data structure (.body nesting)
+│   - Choosing the right pattern
+│   - Common mistakes to avoid
+│
+├── COMMON_PATTERNS.md
+│   10 production-tested patterns
+│   - Pattern 1: Multi-source Aggregation
+│   - Pattern 2: Regex Filtering
+│   - Pattern 3: Markdown Parsing
+│   - Pattern 4: JSON Comparison
+│   - Pattern 5: CRM Transformation
+│   - Pattern 6: Release Processing
+│   - Pattern 7: Array Transformation
+│   - Pattern 8: Slack Block Kit
+│   - Pattern 9: Top N Filtering
+│   - Pattern 10: String Aggregation
+│   - Pattern selection guide
+│
+├── ERROR_PATTERNS.md
+│   Top 5 errors with solutions
+│   - Error #1: Empty Code / Missing Return (38%)
+│   - Error #2: Expression Syntax Confusion (8%)
+│   - Error #3: Incorrect Return Wrapper (5%)
+│   - Error #4: Unmatched Brackets (6%)
+│   - Error #5: Missing Null Checks
+│   - Error prevention checklist
+│   - Quick error reference
+│   - Debugging tips
+│
+├── BUILTIN_FUNCTIONS.md
+│   Complete built-in function reference
+│   - this.helpers.httpRequest() API reference
+│   - DateTime (Luxon) complete guide
+│   - $jmespath() JSON querying
+│   - $getWorkflowStaticData() persistent storage
+│   - Standard JavaScript globals
+│   - Available Node.js modules
+│   - What's NOT available
+│
+└── README.md (this file)
+    Skill metadata and overview
+```
+
+**Total**: 6 files
+
+---
+
+## Coverage
+
+### Mode Selection
+- **Run Once for All Items** - Recommended for 95% of use cases
+- **Run Once for Each Item** - Specialized cases only
+- Decision guide and performance implications
+
+### Data Access
+- Most common patterns with usage statistics
+- Webhook data structure (critical .body gotcha)
+- Safe access patterns with null checks
+- When to use which pattern
+
+### Error Prevention
+- Top 5 errors covering 62%+ of all failures
+- Clear wrong vs right examples
+- Error prevention checklist
+- Debugging tips and console.log usage
+
+### Production Patterns
+- 10 patterns from real workflows
+- Complete working examples
+- Use cases and key techniques
+- Pattern selection guide
+
+### Built-in Functions
+- Complete this.helpers.httpRequest() reference
+- DateTime/Luxon operations (formatting, parsing, arithmetic)
+- $jmespath() for JSON queries
+- Persistent storage with $getWorkflowStaticData()
+- Standard JavaScript and Node.js modules
+
+---
+
+## Critical Gotchas Highlighted
+
+### #1: Webhook Data Structure
+**MOST COMMON MISTAKE**: Webhook data is under `.body`
+
+```javascript
+// ❌ WRONG
+const name = $json.name;
+
+// ✅ CORRECT
+const name = $json.body.name;
+```
+
+### #2: Return Format
+**Prefer the canonical `[{json: {...}}]`** — unambiguous in both execution modes. A bare object auto-wraps in *Run Once for All Items* mode, so it runs too; what actually fails is returning a primitive (string/number) or `null`.
+
+```javascript
+// ⚠️ Auto-wrapped in All Items mode → [{json: {result: 'success'}}]. Runs, but prefer the array form.
+return {json: {result: 'success'}};
+
+// ✅ CANONICAL
+return [{json: {result: 'success'}}];
+```
+
+### #3: Expression Syntax
+**Don't use `{{}}` in Code nodes**
+
+```javascript
+// ❌ WRONG
+const value = "{{ $json.field }}";
+
+// ✅ CORRECT
+const value = $json.field;
+```
+
+---
+
+## Integration with Other Skills
+
+### n8n Expression Syntax
+- **Distinction**: Expressions use `{{}}` in OTHER nodes
+- **Code nodes**: Use JavaScript directly (no `{{}}`)
+- **When to use each**: Code vs expressions decision guide
+
+### n8n MCP Tools Expert
+- Find Code node: `search_nodes({query: "code"})`
+- Get configuration: `get_node("nodes-base.code")`
+- Validate code: `validate_node()`
+
+### n8n Node Configuration
+- Mode selection (All Items vs Each Item)
+- Language selection (JavaScript vs Python)
+- Understanding property dependencies
+
+### n8n Workflow Patterns
+- Code nodes in transformation step
+- Webhook → Code → API pattern
+- Error handling in workflows
+
+### n8n Validation Expert
+- Validate Code node configuration
+- Handle validation errors
+- Auto-fix common issues
+
+---
+
+## When to Use Code Node
+
+**Use Code node when:**
+- ✅ Complex transformations requiring multiple steps
+- ✅ Custom calculations or business logic
+- ✅ Recursive operations
+- ✅ API response parsing with complex structure
+- ✅ Multi-step conditionals
+- ✅ Data aggregation across items
+
+**Consider other nodes when:**
+- ❌ Simple field mapping → Use **Set** node
+- ❌ Basic filtering → Use **Filter** node
+- ❌ Simple conditionals → Use **IF** or **Switch** node
+- ❌ HTTP requests only → Use **HTTP Request** node
+
+**Code node excels at**: Complex logic that would require chaining many simple nodes
+
+---
+
+## Success Metrics
+
+**Before this skill**:
+- Users confused by mode selection
+- Frequent return format errors
+- Expression syntax mistakes
+- Webhook data access failures
+- Missing null check crashes
+
+**After this skill**:
+- Clear mode selection guidance
+- Understanding of return format
+- JavaScript vs expression distinction
+- Correct webhook data access
+- Safe null-handling patterns
+- Production-ready code patterns
+
+---
+
+## Quick Reference
+
+### Essential Rules
+1. Choose "All Items" mode (recommended)
+2. Access data: `$input.all()`, `$input.first()`, `$input.item`
+3. **Return** the canonical `[{json: {...}}]` (bare objects auto-wrap in All Items mode; primitives/`null` fail)
+4. **Webhook data**: Under `.body` property
+5. **No `{{}}` syntax**: Use JavaScript directly
+
+### Most Common Patterns
+- Batch processing → $input.all() + map/filter
+- Single item → $input.first()
+- Aggregation → reduce()
+- HTTP requests → this.helpers.httpRequest()
+- Date handling → DateTime (Luxon)
+
+### Error Prevention
+- Always return data
+- Check for null/undefined
+- Use try-catch for risky operations
+- Test with empty input
+- Use console.log() for debugging
+
+---
+
+## Related Documentation
+
+- **n8n Code Node Guide**: https://docs.n8n.io/code/code-node/
+- **Built-in Methods Reference**: https://docs.n8n.io/code-examples/methods-variables-reference/
+- **Luxon Documentation**: https://moment.github.io/luxon/
+
+---
+
+## Evaluations
+
+**5 test scenarios** covering:
+1. Webhook body gotcha (most common mistake)
+2. Return format error (missing array wrapper)
+3. HTTP request with this.helpers.httpRequest()
+4. Aggregation pattern with $input.all()
+5. Expression syntax confusion (using `{{}}`)
+
+Each evaluation tests skill activation, correct guidance, and reference to appropriate documentation files.
+
+---
+
+## Version History
+
+- **v1.0** (2025-01-20): Initial implementation
+  - SKILL.md with comprehensive overview
+  - DATA_ACCESS.md covering all access patterns
+  - COMMON_PATTERNS.md with 10 production patterns
+  - ERROR_PATTERNS.md covering top 5 errors
+  - BUILTIN_FUNCTIONS.md complete reference
+  - 5 evaluation scenarios
+
+---
+
+## Author
+
+Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
+
+Part of the n8n-skills collection.

data/skills/n8n-code-javascript/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: n8n-code-javascript
+description: Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with this.helpers / the $helpers global, working with dates using DateTime, troubleshooting Code node errors, choosing between Code node modes, or doing any custom data transformation in n8n. Always use this skill when a workflow needs a Code node — whether for data aggregation, filtering, API calls, format conversion, batch processing logic, or any custom JavaScript. Covers SplitInBatches loop patterns, cross-iteration data, pairedItem, and real-world production patterns. Also use when asked why a Code node or workflow is slow, which execution mode is faster, or how to cut per-item overhead on large datasets. EXCEPTION — for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode, a tool attached to an AI Agent), use the n8n-code-tool skill instead; it has a different runtime contract.
+---
+
+# JavaScript Code Node
+
+Expert guidance for writing JavaScript code in n8n Code nodes.
+
+---
+
+## Quick Start
+
+```javascript
+// Basic template for Code nodes
+const items = $input.all();
+
+// Process data
+const processed = items.map(item => ({
+  json: {
+    ...item.json,
+    processed: true,
+    timestamp: new Date().toISOString()
+  }
+}));
+
+return processed;
+```
+
+### Essential Rules
+
+1. **Choose "Run Once for All Items" mode** (recommended for most use cases)
+2. **Access data**: `$input.all()`, `$input.first()`, or `$input.item`
+3. **Return `[{json: {...}}]`** — the canonical, mode-portable form. In *Run Once for All Items* mode n8n also auto-wraps a bare `return {…}` object, so that runs too; what genuinely fails is returning a primitive (string/number) or `null`.
+4. **CRITICAL**: Webhook data is under `$json.body` (not `$json` directly)
+5. **Built-ins available**: `this.helpers.httpRequest()` (no auth — the bare `$helpers` global is **undefined** in the task-runner sandbox, so `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`), DateTime (Luxon), $jmespath(). **Not available**: `this.helpers.httpRequestWithAuthentication` (deny-listed), $env (when N8N_BLOCK_ENV_ACCESS_IN_NODE=true), require() (unless allowlisted). For anything beyond a trivial unauthenticated GET (auth, pagination, retries), prefer the **HTTP Request node** and keep Code nodes for pure logic.
+6. **Instance-allowlisted libraries**: Self-hosted instances can allowlist modules via `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` and `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` (legacy: `NODE_FUNCTION_ALLOW_BUILTIN` / `NODE_FUNCTION_ALLOW_EXTERNAL`). If the user says their instance allows specific modules (e.g. `axios`, `lodash`, `crypto`), use them via `require()` — don't refuse. If unsure, ask or default to built-ins only.
+7. **Wrong skill?** If you're writing code for a **Custom Code Tool** attached to an AI Agent (`@n8n/n8n-nodes-langchain.toolCode`), stop — that node has a different contract (input via `query`, must return a string, no `$input`/`$helpers`). Use the **n8n-code-tool** skill.
+
+---
+
+## Mode Selection Guide
+
+The Code node offers two execution modes. Choose based on your use case:
+
+### Run Once for All Items (Recommended - Default)
+
+**Use this mode for:** 95% of use cases
+
+- **How it works**: Code executes **once** regardless of input count
+- **Data access**: `$input.all()` or `items` array
+- **Best for**: Aggregation, filtering, batch processing, transformations, API calls with all data
+- **Performance**: Faster for multiple items (single execution)
+
+```javascript
+// Example: Calculate total from all items
+const allItems = $input.all();
+const total = allItems.reduce((sum, item) => sum + (item.json.amount || 0), 0);
+
+return [{
+  json: {
+    total,
+    count: allItems.length,
+    average: total / allItems.length
+  }
+}];
+```
+
+**When to use:**
+- ✅ Comparing items across the dataset
+- ✅ Calculating totals, averages, or statistics
+- ✅ Sorting or ranking items
+- ✅ Deduplication
+- ✅ Building aggregated reports
+- ✅ Combining data from multiple items
+
+### Run Once for Each Item
+
+**Use this mode for:** Specialized cases only
+
+- **How it works**: Code executes **separately** for each input item
+- **Data access**: `$input.item` or `$item`
+- **Best for**: Item-specific logic, independent operations, per-item validation
+- **Performance**: Slower for large datasets (multiple executions)
+
+```javascript
+// Example: Add processing timestamp to each item
+const item = $input.item;
+
+return [{
+  json: {
+    ...item.json,
+    processed: true,
+    processedAt: new Date().toISOString()
+  }
+}];
+```
+
+**When to use:**
+- ✅ Each item needs independent API call
+- ✅ Per-item validation with different error handling
+- ✅ Item-specific transformations based on item properties
+- ✅ When items must be processed separately for business logic
+
+**Decision Shortcut:**
+- **Need to look at multiple items?** → Use "All Items" mode
+- **Each item completely independent?** → Use "Each Item" mode
+- **Not sure?** → Use "All Items" mode (you can always loop inside)
+
+### Why "All Items" is faster — the per-item boundary
+
+Mode choice is the single biggest performance lever in a Code node. Each *per-item* execution context costs a setup tax (measured on n8n 2.x, small records):
+
+| What runs per item | Approx. cost |
+|---|---|
+| Code **All Items** (one run for the whole set) | ~0.02 ms/item |
+| Expression in any node (IF / Set / etc.) | ~0.2 ms/item |
+| Code **Each Item** (a full sandbox per item) | ~0.6 ms/item — ~25–30× All Items |
+
+So `Run Once for Each Item` over 10k items is ~6 s of pure overhead vs ~0.2 s in `Run Once for All Items`. Use Each Item only when an item genuinely needs isolating (independent error handling, or a per-item API call you can't batch); otherwise loop *inside* one All Items node. Expression complexity itself is essentially free (~90% of the cost is the per-item context, not your code) and every node→node hop re-copies all items — so reduce the *number* of per-item boundaries, don't micro-optimize each one. Below a few hundred items none of this matters; reach for it on the hot path (large item counts, little I/O).
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) → "Mode Performance" for the corollaries, hop costs, and scale check.
+
+---
+
+## Data Access Patterns
+
+Four ways to pull data from upstream nodes. Note `$node["Name"]` and `$('Name')` need `.first().json` or `.all()` — never `.json` directly.
+
+```javascript
+const allItems = $input.all();          // 1. All items — batch ops, aggregation (most common)
+const data = $input.first().json;       // 2. First item — single objects, API responses
+const item = $input.item;               // 3. Current item — "Each Item" mode ONLY (undefined otherwise)
+const other = $node["Webhook"].json;    // 4. Named node — combine data across nodes
+```
+
+Always access fields via `.json` (e.g. `item.json.name`, not `item.name`), and prefer the explicit `$input.first().json.field` over a bare `$json.field`.
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for the full guide — every pattern with examples, a decision tree, and the common mistakes (mutating originals, missing length checks, `$input.item` in the wrong mode).
+
+---
+
+## Critical: Webhook Data Structure
+
+**MOST COMMON MISTAKE**: Webhook data is nested under `.body`
+
+```javascript
+// ❌ WRONG - Will return undefined
+const name = $json.name;
+const email = $json.email;
+
+// ✅ CORRECT - Webhook data is under .body
+const name = $json.body.name;
+const email = $json.body.email;
+
+// Or with $input
+const webhookData = $input.first().json.body;
+const name = webhookData.name;
+```
+
+**Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads.
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details
+
+---
+
+## Return Format Requirements
+
+**Canonical form**: `[{json: {...}}]` — an array of objects each with a `json` property. It is unambiguous and works identically in both execution modes, so make it your default.
+
+In *Run Once for All Items* mode n8n auto-normalizes looser shapes on the way out: a single bare object, or an array of bare objects, gets wrapped under `json` for you. So `return {foo: 1}` runs. What has nothing to wrap — and therefore genuinely fails at runtime with "Code doesn't return items properly" — is a primitive (string/number/boolean) or `null`/`undefined`. (n8n-mcp ≥ 2.63.0 no longer flags a bare-object return as an error; it reflects this auto-wrap behavior.)
+
+### Correct Return Formats
+
+```javascript
+// ✅ Single result
+return [{
+  json: {
+    field1: value1,
+    field2: value2
+  }
+}];
+
+// ✅ Multiple results
+return [
+  {json: {id: 1, data: 'first'}},
+  {json: {id: 2, data: 'second'}}
+];
+
+// ✅ Transformed array
+const transformed = $input.all()
+  .filter(item => item.json.valid)
+  .map(item => ({
+    json: {
+      id: item.json.id,
+      processed: true
+    }
+  }));
+return transformed;
+
+// ✅ Empty result (when no data to return)
+return [];
+
+// ✅ Conditional return
+if (shouldProcess) {
+  return [{json: processedData}];
+} else {
+  return [];
+}
+```
+
+### Non-Canonical Returns (auto-wrapped — prefer the canonical form)
+
+```javascript
+// ⚠️ Auto-wrapped in All Items mode → [{json: {field: value}}]. Runs, but prefer the array form.
+return {
+  json: {field: value}
+};
+
+// ⚠️ Auto-wrapped → [{json: {field: value}}]. Runs, but add the json wrapper for clarity.
+return [{field: value}];
+
+// ✅ Fine — input items already carry a json property, so returning them unchanged is a valid passthrough
+return $input.all();
+```
+
+### Genuinely Broken Returns
+
+```javascript
+// ❌ FAILS: primitive — n8n errors "Code doesn't return items properly"
+return "processed";
+
+// ❌ FAILS: null / undefined — nothing to pass to the next node
+return null;
+```
+
+**Why it matters**: The canonical `[{json: {...}}]` is unambiguous and behaves the same in both modes. n8n auto-normalizes bare objects and arrays-of-objects in All Items mode, but a primitive or `null` return has nothing to wrap and stops execution.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #3 for detailed error solutions
+
+---
+
+## Common Patterns Overview
+
+The most useful Code node shapes from production workflows. One quick example — sum/aggregate across all items:
+
+```javascript
+const items = $input.all();
+const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0);
+return [{ json: { total, count: items.length, average: total / items.length } }];
+```
+
+The full library covers 10 patterns: multi-source aggregation, regex filtering, markdown/structured-text parsing, JSON comparison, CRM/form transformation, release processing, array transformation with computed fields, Slack Block Kit formatting, top-N ranking, and string-aggregation reporting — each with variations.
+
+**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) for the 10 detailed production patterns (and the Best Practices section: validate input, try-catch, filter-early, array methods over loops, console.log debugging).
+
+---
+
+## Error Prevention - Top Mistakes
+
+The recurring Code node failures, in rough frequency order:
+
+1. **Empty code / missing return** — always end with `return [...]`, and make sure *every* branch returns.
+2. **Expression syntax as code** — don't write `{{ }}` where JavaScript belongs (`return {{ $json.x }}` is a syntax error). Use `` `${$json.field}` `` or `$input.first().json.field`. `{{ }}` *inside a string literal* is fine — it's just literal text n8n won't evaluate.
+3. **Return shape** — prefer `return [{json:{...}}]`. A bare `return {…}` auto-wraps in All Items mode, but returning a primitive (string/number) or `null` is what actually fails.
+4. **Missing null checks** — use optional chaining: `item.json?.user?.email || 'fallback'`.
+5. **Webhook body nesting** — `$json.email` is undefined; use `$json.body.email`.
+6. **Auth helpers blocked** (`httpRequestWithAuthentication`) and `$env` blocked — route secrets through credentials/HTTP Request node, not the Code node sandbox.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for the comprehensive guide — each error with wrong/right code, escaping rules, the sandbox restrictions (Errors #6–#7), a prevention checklist, and a quick error-message lookup table.
+
+---
+
+## Built-in Functions & Helpers
+
+```javascript
+// HTTP requests (no auth — see sandbox note below)
+const res = await this.helpers.httpRequest({ method: 'GET', url: 'https://api.example.com/data' });
+
+// DateTime (Luxon): now, formatting, arithmetic
+const now = DateTime.now();
+const formatted = now.toFormat('yyyy-MM-dd');
+const tomorrow = now.plus({ days: 1 });
+
+// $jmespath() — query JSON structures
+const adults = $jmespath($input.first().json, 'users[?age >= `18`]');
+
+// $getWorkflowStaticData() — data that persists across executions
+```
+
+**Sandbox (since n8n v2.0, JsTaskRunnerSandbox):** the accessor is `this.helpers.httpRequest()` — the bare `$helpers` global is **undefined** here (`$helpers.httpRequest()` throws `ReferenceError`). Inside a nested async function where `this` is lost, call it as `await fn.call(this, ...)`. `this.helpers.httpRequestWithAuthentication` and `this.helpers.requestWithAuthenticationPaginated` are deny-listed (→ `UnsupportedFunctionError`); for authenticated calls use an **HTTP Request node** with the credential (preferred), a sub-workflow, or a manual `Authorization: Bearer ${token}` header on `this.helpers.httpRequest()` only when the token already flows through the workflow as data. `$env` is blocked when `N8N_BLOCK_ENV_ACCESS_IN_NODE=true`; `require()` works only for allowlisted modules. `Buffer`, `URL`, and standard JS globals (Math, JSON, Object, Array) always work.
+
+**See**: [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) for the complete reference — full httpRequest options, all DateTime/Luxon operations, JMESPath patterns, static-data use cases, and the sandbox-restriction details.
+
+---
+
+## Best Practices
+
+- **Validate input first** — guard for empty arrays / missing `.json` before processing.
+- **Try-catch risky work** (HTTP calls) and return an error object instead of crashing.
+- **Prefer array methods** (`filter`/`map`/`reduce`) over manual loops.
+- **Filter early, transform late** — shrink the dataset before expensive work.
+- **Descriptive names** and `console.log()` for debugging (output goes to the browser console).
+
+**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) → "Best Practices" for code examples of each.
+
+---
+
+## Production Gotchas
+
+Hard-won lessons from real deployments — summarized here, with code in [DATA_ACCESS.md](DATA_ACCESS.md) → "Production Gotchas":
+
+- **SplitInBatches outputs are counterintuitive**: `main[0]` = **done** (fires once, after all batches), `main[1]` = **each batch** (the loop body). Add a **Limit 1** node after the done output as a safety.
+- **Iteration count is the cost**: each loop iteration re-runs the whole body through the engine (~0.8 ms overhead each). `batchSize: 1` is the loop equivalent of *Each Item* — use the largest batch your real constraint (rate limit, page size, memory) allows, or don't loop at all.
+- **Cross-iteration accumulation (CRITICAL)**: after the loop, `$('Node Inside Loop').all()` returns ONLY the last iteration's items. Accumulate via `$getWorkflowStaticData('global')` (reset before, push inside, read after).
+- **pairedItem**: when emitting items that don't map 1:1 to input, set `pairedItem: { item: i }` or downstream Set nodes fail with `paired_item_no_info`.
+- **Node reference syntax**: `$('Node').first().json` or `$('Node').all()` — never `.json` directly on the reference.
+- **Float precision**: compare currency at the cent level — `Math.round(a*100) !== Math.round(b*100)` — to avoid false positives from float noise.
+
+---
+
+## When to Use Code Node
+
+> **Before reaching for a Code node, walk the transform gatekeeper** in the n8n Expression Syntax skill: expression → arrow-function IIFE inside an Edit Fields field → Code node, in that order. The first two paths cover most "transform this data" tasks at ~1–10ms each, versus the Code node's sandboxed ~500–1000ms — a ~100x gap on pure single-item shaping, with no functional difference. The Code node earns its place only for whole-dataset aggregation (`$input.all()`), allowlisted libraries, or async work. And before writing code for crypto (HMAC, hashing, signing) or XML/SOAP/RSS parsing, check for a **native node** — n8n has a Crypto node (`nodes-base.crypto`) and an XML node (`nodes-base.xml`) that cover those without any JavaScript. Dropping into Code for something a native node already does is one of the most common false positives.
+
+Use Code node when:
+- ✅ Complex transformations requiring multiple steps
+- ✅ Custom calculations or business logic
+- ✅ Recursive operations
+- ✅ API response parsing with complex structure
+- ✅ Multi-step conditionals
+- ✅ Data aggregation across items
+
+Consider other nodes when:
+- ❌ Simple field mapping → Use **Set** node
+- ❌ Basic filtering → Use **Filter** node
+- ❌ Simple conditionals → Use **IF** or **Switch** node
+- ❌ HTTP requests only → Use **HTTP Request** node
+
+**Code node excels at**: Complex logic that would require chaining many simple nodes
+
+---
+
+## Integration with Other Skills
+
+### Works With:
+
+**n8n Expression Syntax**:
+- Expressions use `{{ }}` syntax in other nodes
+- Code nodes use JavaScript directly (no `{{ }}`)
+- When to use expressions vs code
+
+**n8n MCP Tools Expert**:
+- How to find Code node: `search_nodes({query: "code"})`
+- Get configuration help: `get_node({nodeType: "nodes-base.code"})`
+- Validate code: `validate_node({nodeType: "nodes-base.code", config: {...}})`
+
+**n8n Node Configuration**:
+- Mode selection (All Items vs Each Item)
+- Language selection (JavaScript vs Python)
+- Understanding property dependencies
+
+**n8n Workflow Patterns**:
+- Code nodes in transformation step
+- Webhook → Code → API pattern
+- Error handling in workflows
+
+**n8n Validation Expert**:
+- Validate Code node configuration
+- Handle validation errors
+- Auto-fix common issues
+
+---
+
+## Quick Reference Checklist
+
+Before deploying Code nodes, verify:
+
+- [ ] **Code is not empty** - Must have meaningful logic
+- [ ] **Return statement exists** - Returns items, not a primitive/`null`
+- [ ] **Canonical return format** - Each item: `{json: {...}}` (bare objects auto-wrap, but be explicit)
+- [ ] **Data access correct** - Using `$input.all()`, `$input.first()`, or `$input.item`
+- [ ] **No `{{ }}` written as code** - Use JavaScript template literals: `` `${value}` ``
+- [ ] **Error handling** - Guard clauses for null/undefined inputs
+- [ ] **Webhook data** - Access via `.body` if from webhook
+- [ ] **Mode selection** - "All Items" for most cases
+- [ ] **Performance** - Prefer map/filter over manual loops
+- [ ] **Output consistent** - All code paths return same structure
+
+---
+
+## Additional Resources
+
+### Related Files
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive data access patterns
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 production-tested patterns
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions
+- [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) - Complete built-in reference
+
+### n8n Documentation
+- Code Node Guide: https://docs.n8n.io/code/code-node/
+- Built-in Methods: https://docs.n8n.io/code-examples/methods-variables-reference/
+- Luxon Documentation: https://moment.github.io/luxon/
+
+---
+
+**Ready to write JavaScript in n8n Code nodes!** Start with simple transformations, use the error patterns guide to avoid common mistakes, and reference the pattern library for production-ready examples.

data/skills/n8n-code-python/COMMON_PATTERNS.md

@@ -0,0 +1,917 @@
+# Common Patterns - Python Code Node
+
+Production-tested Python patterns for n8n Code nodes.
+
+---
+
+## ⚠️ Important: JavaScript First
+
+**Use JavaScript for 95% of use cases.**
+
+Python in n8n has **NO external libraries** (no requests, pandas, numpy).
+
+Only use Python when:
+- You have complex Python-specific logic
+- You need Python's standard library features
+- You're more comfortable with Python than JavaScript
+
+For most workflows, **JavaScript is the better choice**.
+
+---
+
+## Pattern Overview
+
+These 10 patterns cover common n8n Code node scenarios using Python:
+
+1. **Multi-Source Data Aggregation** - Combine data from multiple nodes
+2. **Regex-Based Filtering** - Filter items using pattern matching
+3. **Markdown to Structured Data** - Parse markdown into structured format
+4. **JSON Object Comparison** - Compare two JSON objects for changes
+5. **CRM Data Transformation** - Transform CRM data to standard format
+6. **Release Notes Processing** - Parse and categorize release notes
+7. **Array Transformation** - Reshape arrays and extract fields
+8. **Dictionary Lookup** - Create and use lookup dictionaries
+9. **Top N Filtering** - Get top items by score/value
+10. **String Aggregation** - Aggregate strings with formatting
+
+---
+
+## Pattern 1: Multi-Source Data Aggregation
+
+**Use case**: Combine data from multiple sources (APIs, webhooks, databases).
+
+**Scenario**: Aggregate news articles from multiple sources.
+
+### Implementation
+
+```python
+from datetime import datetime
+
+all_items = _input.all()
+processed_articles = []
+
+for item in all_items:
+    source_name = item["json"].get("name", "Unknown")
+    source_data = item["json"]
+
+    # Process Hacker News source
+    if source_name == "Hacker News" and source_data.get("hits"):
+        for hit in source_data["hits"]:
+            processed_articles.append({
+                "title": hit.get("title", "No title"),
+                "url": hit.get("url", ""),
+                "summary": hit.get("story_text") or "No summary",
+                "source": "Hacker News",
+                "score": hit.get("points", 0),
+                "fetched_at": datetime.now().isoformat()
+            })
+
+    # Process Reddit source
+    elif source_name == "Reddit" and source_data.get("data"):
+        for post in source_data["data"].get("children", []):
+            post_data = post.get("data", {})
+            processed_articles.append({
+                "title": post_data.get("title", "No title"),
+                "url": post_data.get("url", ""),
+                "summary": post_data.get("selftext", "")[:200],
+                "source": "Reddit",
+                "score": post_data.get("score", 0),
+                "fetched_at": datetime.now().isoformat()
+            })
+
+# Sort by score descending
+processed_articles.sort(key=lambda x: x["score"], reverse=True)
+
+# Return as n8n items
+return [{"json": article} for article in processed_articles]
+```
+
+### Key Techniques
+
+- Process multiple data sources in one loop
+- Normalize different data structures
+- Use datetime for timestamps
+- Sort by criteria
+- Return properly formatted items
+
+---
+
+## Pattern 2: Regex-Based Filtering
+
+**Use case**: Filter items based on pattern matching in text fields.
+
+**Scenario**: Filter support tickets by priority keywords.
+
+### Implementation
+
+```python
+import re
+
+all_items = _input.all()
+priority_tickets = []
+
+# High priority keywords pattern
+high_priority_pattern = re.compile(
+    r'\b(urgent|critical|emergency|asap|down|outage|broken)\b',
+    re.IGNORECASE
+)
+
+for item in all_items:
+    ticket = item["json"]
+
+    # Check subject and description
+    subject = ticket.get("subject", "")
+    description = ticket.get("description", "")
+    combined_text = f"{subject} {description}"
+
+    # Find matches
+    matches = high_priority_pattern.findall(combined_text)
+
+    if matches:
+        priority_tickets.append({
+            "json": {
+                **ticket,
+                "priority": "high",
+                "matched_keywords": list(set(matches)),
+                "keyword_count": len(matches)
+            }
+        })
+    else:
+        priority_tickets.append({
+            "json": {
+                **ticket,
+                "priority": "normal",
+                "matched_keywords": [],
+                "keyword_count": 0
+            }
+        })
+
+# Sort by keyword count (most urgent first)
+priority_tickets.sort(key=lambda x: x["json"]["keyword_count"], reverse=True)
+
+return priority_tickets
+```
+
+### Key Techniques
+
+- Use re.compile() for reusable patterns
+- re.IGNORECASE for case-insensitive matching
+- Combine multiple text fields for searching
+- Extract and deduplicate matches
+- Sort by priority indicators
+
+---
+
+## Pattern 3: Markdown to Structured Data
+
+**Use case**: Parse markdown text into structured data.
+
+**Scenario**: Extract tasks from markdown checklist.
+
+### Implementation
+
+```python
+import re
+
+markdown_text = _input.first()["json"]["body"].get("markdown", "")
+
+# Parse markdown checklist
+tasks = []
+lines = markdown_text.split("\n")
+
+for line in lines:
+    # Match: - [ ] Task or - [x] Task
+    match = re.match(r'^\s*-\s*\[([ x])\]\s*(.+)$', line, re.IGNORECASE)
+
+    if match:
+        checked = match.group(1).lower() == 'x'
+        task_text = match.group(2).strip()
+
+        # Extract priority if present (e.g., [P1], [HIGH])
+        priority_match = re.search(r'\[(P\d|HIGH|MEDIUM|LOW)\]', task_text, re.IGNORECASE)
+        priority = priority_match.group(1).upper() if priority_match else "NORMAL"
+
+        # Remove priority tag from text
+        clean_text = re.sub(r'\[(P\d|HIGH|MEDIUM|LOW)\]', '', task_text, flags=re.IGNORECASE).strip()
+
+        tasks.append({
+            "text": clean_text,
+            "completed": checked,
+            "priority": priority,
+            "original_line": line.strip()
+        })
+
+return [{
+    "json": {
+        "tasks": tasks,
+        "total": len(tasks),
+        "completed": sum(1 for t in tasks if t["completed"]),
+        "pending": sum(1 for t in tasks if not t["completed"])
+    }
+}]
+```
+
+### Key Techniques
+
+- Line-by-line parsing
+- Multiple regex patterns for extraction
+- Extract metadata from text
+- Calculate summary statistics
+- Return structured data
+
+---
+
+## Pattern 4: JSON Object Comparison
+
+**Use case**: Compare two JSON objects to find differences.
+
+**Scenario**: Compare old and new user profile data.
+
+### Implementation
+
+```python
+import json
+
+all_items = _input.all()
+
+# Assume first item is old data, second is new data
+old_data = all_items[0]["json"] if len(all_items) > 0 else {}
+new_data = all_items[1]["json"] if len(all_items) > 1 else {}
+
+changes = {
+    "added": {},
+    "removed": {},
+    "modified": {},
+    "unchanged": {}
+}
+
+# Find all unique keys
+all_keys = set(old_data.keys()) | set(new_data.keys())
+
+for key in all_keys:
+    old_value = old_data.get(key)
+    new_value = new_data.get(key)
+
+    if key not in old_data:
+        # Added field
+        changes["added"][key] = new_value
+    elif key not in new_data:
+        # Removed field
+        changes["removed"][key] = old_value
+    elif old_value != new_value:
+        # Modified field
+        changes["modified"][key] = {
+            "old": old_value,
+            "new": new_value
+        }
+    else:
+        # Unchanged field
+        changes["unchanged"][key] = old_value
+
+return [{
+    "json": {
+        "changes": changes,
+        "summary": {
+            "added_count": len(changes["added"]),
+            "removed_count": len(changes["removed"]),
+            "modified_count": len(changes["modified"]),
+            "unchanged_count": len(changes["unchanged"]),
+            "has_changes": len(changes["added"]) > 0 or len(changes["removed"]) > 0 or len(changes["modified"]) > 0
+        }
+    }
+}]
+```
+
+### Key Techniques
+
+- Set operations for key comparison
+- Dictionary .get() for safe access
+- Categorize changes by type
+- Create summary statistics
+- Return detailed comparison
+
+---
+
+## Pattern 5: CRM Data Transformation
+
+**Use case**: Transform CRM data to standard format.
+
+**Scenario**: Normalize data from different CRM systems.
+
+### Implementation
+
+```python
+from datetime import datetime
+import re
+
+all_items = _input.all()
+normalized_contacts = []
+
+for item in all_items:
+    raw_contact = item["json"]
+    source = raw_contact.get("source", "unknown")
+
+    # Normalize email
+    email = raw_contact.get("email", "").lower().strip()
+
+    # Normalize phone (remove non-digits)
+    phone_raw = raw_contact.get("phone", "")
+    phone = re.sub(r'\D', '', phone_raw)
+
+    # Parse name
+    if "full_name" in raw_contact:
+        name_parts = raw_contact["full_name"].split(" ", 1)
+        first_name = name_parts[0] if len(name_parts) > 0 else ""
+        last_name = name_parts[1] if len(name_parts) > 1 else ""
+    else:
+        first_name = raw_contact.get("first_name", "")
+        last_name = raw_contact.get("last_name", "")
+
+    # Normalize status
+    status_raw = raw_contact.get("status", "").lower()
+    status = "active" if status_raw in ["active", "enabled", "true", "1"] else "inactive"
+
+    # Create normalized contact
+    normalized_contacts.append({
+        "json": {
+            "id": raw_contact.get("id", ""),
+            "first_name": first_name.strip(),
+            "last_name": last_name.strip(),
+            "full_name": f"{first_name} {last_name}".strip(),
+            "email": email,
+            "phone": phone,
+            "status": status,
+            "source": source,
+            "normalized_at": datetime.now().isoformat(),
+            "original_data": raw_contact
+        }
+    })
+
+return normalized_contacts
+```
+
+### Key Techniques
+
+- Multiple field name variations handling
+- String cleaning and normalization
+- Regex for phone number cleaning
+- Name parsing logic
+- Status normalization
+- Preserve original data
+
+---
+
+## Pattern 6: Release Notes Processing
+
+**Use case**: Parse release notes and categorize changes.
+
+**Scenario**: Extract features, fixes, and breaking changes from release notes.
+
+### Implementation
+
+```python
+import re
+
+release_notes = _input.first()["json"]["body"].get("notes", "")
+
+categories = {
+    "features": [],
+    "fixes": [],
+    "breaking": [],
+    "other": []
+}
+
+# Split into lines
+lines = release_notes.split("\n")
+
+for line in lines:
+    line = line.strip()
+
+    # Skip empty lines and headers
+    if not line or line.startswith("#"):
+        continue
+
+    # Remove bullet points
+    clean_line = re.sub(r'^[\*\-\+]\s*', '', line)
+
+    # Categorize
+    if re.search(r'\b(feature|add|new)\b', clean_line, re.IGNORECASE):
+        categories["features"].append(clean_line)
+    elif re.search(r'\b(fix|bug|patch|resolve)\b', clean_line, re.IGNORECASE):
+        categories["fixes"].append(clean_line)
+    elif re.search(r'\b(breaking|deprecated|remove)\b', clean_line, re.IGNORECASE):
+        categories["breaking"].append(clean_line)
+    else:
+        categories["other"].append(clean_line)
+
+return [{
+    "json": {
+        "categories": categories,
+        "summary": {
+            "features": len(categories["features"]),
+            "fixes": len(categories["fixes"]),
+            "breaking": len(categories["breaking"]),
+            "other": len(categories["other"]),
+            "total": sum(len(v) for v in categories.values())
+        }
+    }
+}]
+```
+
+### Key Techniques
+
+- Line-by-line parsing
+- Pattern-based categorization
+- Bullet point removal
+- Skip headers and empty lines
+- Summary statistics
+
+---
+
+## Pattern 7: Array Transformation
+
+**Use case**: Reshape arrays and extract specific fields.
+
+**Scenario**: Transform user data array to extract specific fields.
+
+### Implementation
+
+```python
+all_items = _input.all()
+
+# Extract and transform
+transformed = []
+
+for item in all_items:
+    user = item["json"]
+
+    # Extract nested fields
+    profile = user.get("profile", {})
+    settings = user.get("settings", {})
+
+    transformed.append({
+        "json": {
+            "user_id": user.get("id"),
+            "email": user.get("email"),
+            "name": profile.get("name", "Unknown"),
+            "avatar": profile.get("avatar_url"),
+            "bio": profile.get("bio", "")[:100],  # Truncate to 100 chars
+            "notifications_enabled": settings.get("notifications", True),
+            "theme": settings.get("theme", "light"),
+            "created_at": user.get("created_at"),
+            "last_login": user.get("last_login_at")
+        }
+    })
+
+return transformed
+```
+
+### Key Techniques
+
+- Field extraction from nested objects
+- Default values with .get()
+- String truncation
+- Flattening nested structures
+
+---
+
+## Pattern 8: Dictionary Lookup
+
+**Use case**: Create lookup dictionary for fast data access.
+
+**Scenario**: Look up user details by ID.
+
+### Implementation
+
+```python
+all_items = _input.all()
+
+# Build lookup dictionary
+users_by_id = {}
+
+for item in all_items:
+    user = item["json"]
+    user_id = user.get("id")
+
+    if user_id:
+        users_by_id[user_id] = {
+            "name": user.get("name"),
+            "email": user.get("email"),
+            "status": user.get("status")
+        }
+
+# Example: Look up specific users
+lookup_ids = [1, 3, 5]
+looked_up = []
+
+for user_id in lookup_ids:
+    if user_id in users_by_id:
+        looked_up.append({
+            "json": {
+                "id": user_id,
+                **users_by_id[user_id],
+                "found": True
+            }
+        })
+    else:
+        looked_up.append({
+            "json": {
+                "id": user_id,
+                "found": False
+            }
+        })
+
+return looked_up
+```
+
+### Key Techniques
+
+- Dictionary comprehension alternative
+- O(1) lookup time
+- Handle missing keys gracefully
+- Preserve lookup order
+
+---
+
+## Pattern 9: Top N Filtering
+
+**Use case**: Get top items by score or value.
+
+**Scenario**: Get top 10 products by sales.
+
+### Implementation
+
+```python
+all_items = _input.all()
+
+# Extract products with sales
+products = []
+
+for item in all_items:
+    product = item["json"]
+    products.append({
+        "id": product.get("id"),
+        "name": product.get("name"),
+        "sales": product.get("sales", 0),
+        "revenue": product.get("revenue", 0.0),
+        "category": product.get("category")
+    })
+
+# Sort by sales descending
+products.sort(key=lambda p: p["sales"], reverse=True)
+
+# Get top 10
+top_10 = products[:10]
+
+return [
+    {
+        "json": {
+            **product,
+            "rank": index + 1
+        }
+    }
+    for index, product in enumerate(top_10)
+]
+```
+
+### Key Techniques
+
+- List sorting with custom key
+- Slicing for top N
+- Add ranking information
+- Enumerate for index
+
+---
+
+## Pattern 10: String Aggregation
+
+**Use case**: Aggregate strings with formatting.
+
+**Scenario**: Create summary text from multiple items.
+
+### Implementation
+
+```python
+all_items = _input.all()
+
+# Collect messages
+messages = []
+
+for item in all_items:
+    data = item["json"]
+
+    user = data.get("user", "Unknown")
+    message = data.get("message", "")
+    timestamp = data.get("timestamp", "")
+
+    # Format each message
+    formatted = f"[{timestamp}] {user}: {message}"
+    messages.append(formatted)
+
+# Join with newlines
+summary = "\n".join(messages)
+
+# Create statistics
+total_length = sum(len(msg) for msg in messages)
+average_length = total_length / len(messages) if messages else 0
+
+return [{
+    "json": {
+        "summary": summary,
+        "message_count": len(messages),
+        "total_characters": total_length,
+        "average_length": round(average_length, 2)
+    }
+}]
+```
+
+### Key Techniques
+
+- String formatting with f-strings
+- Join lists with separator
+- Calculate string statistics
+- Handle empty lists
+
+---
+
+## Pattern Comparison: Python vs JavaScript
+
+### Data Access
+
+```python
+# Python
+all_items = _input.all()
+first_item = _input.first()
+current = _input.item
+webhook_data = _json["body"]
+
+# JavaScript
+const allItems = $input.all();
+const firstItem = $input.first();
+const current = $input.item;
+const webhookData = $json.body;
+```
+
+### Dictionary/Object Access
+
+```python
+# Python - Dictionary key access
+name = user["name"]           # May raise KeyError
+name = user.get("name", "?")  # Safe with default
+
+# JavaScript - Object property access
+const name = user.name;              // May be undefined
+const name = user.name || "?";       // Safe with default
+```
+
+### Array Operations
+
+```python
+# Python - List comprehension
+filtered = [item for item in items if item["active"]]
+
+# JavaScript - Array methods
+const filtered = items.filter(item => item.active);
+```
+
+### Sorting
+
+```python
+# Python
+items.sort(key=lambda x: x["score"], reverse=True)
+
+# JavaScript
+items.sort((a, b) => b.score - a.score);
+```
+
+---
+
+## Best Practices
+
+### 1. Use .get() for Safe Access
+
+```python
+# ✅ SAFE: Use .get() with defaults
+name = user.get("name", "Unknown")
+email = user.get("email", "no-email@example.com")
+
+# ❌ RISKY: Direct key access
+name = user["name"]  # KeyError if missing!
+```
+
+### 2. Handle Empty Lists
+
+```python
+# ✅ SAFE: Check before processing
+items = _input.all()
+if items:
+    first = items[0]
+else:
+    return [{"json": {"error": "No items"}}]
+
+# ❌ RISKY: Assume items exist
+first = items[0]  # IndexError if empty!
+```
+
+### 3. Use List Comprehensions
+
+```python
+# ✅ PYTHONIC: List comprehension
+active = [item for item in items if item["json"].get("active")]
+
+# ❌ VERBOSE: Traditional loop
+active = []
+for item in items:
+    if item["json"].get("active"):
+        active.append(item)
+```
+
+### 4. Return Proper Format
+
+```python
+# ✅ CORRECT: Array of objects with "json" key
+return [{"json": {"field": "value"}}]
+
+# ❌ WRONG: Just the data
+return {"field": "value"}
+
+# ❌ WRONG: Array without "json" wrapper
+return [{"field": "value"}]
+```
+
+### 5. Use Standard Library
+
+```python
+# ✅ GOOD: Use standard library
+import statistics
+average = statistics.mean(numbers)
+
+# ✅ ALSO GOOD: Built-in functions
+average = sum(numbers) / len(numbers) if numbers else 0
+
+# ❌ CAN'T DO: External libraries
+import numpy as np  # ModuleNotFoundError!
+```
+
+---
+
+## Quick Pattern Snippets
+
+Condensed, copy-ready versions of the most common Python operations. Use these as starting points before reaching for the full patterns above.
+
+### 1. Data Transformation
+
+Transform all items with list comprehensions.
+
+```python
+items = _input.all()
+
+return [
+    {
+        "json": {
+            "id": item["json"].get("id"),
+            "name": item["json"].get("name", "Unknown").upper(),
+            "processed": True
+        }
+    }
+    for item in items
+]
+```
+
+### 2. Filtering & Aggregation
+
+Sum, filter, count with built-in functions.
+
+```python
+items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in items)
+valid_items = [item for item in items if item["json"].get("amount", 0) > 0]
+
+return [{
+    "json": {
+        "total": total,
+        "count": len(valid_items)
+    }
+}]
+```
+
+### 3. String Processing with Regex
+
+Extract patterns from text.
+
+```python
+import re
+
+items = _input.all()
+email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
+
+all_emails = []
+for item in items:
+    text = item["json"].get("text", "")
+    emails = re.findall(email_pattern, text)
+    all_emails.extend(emails)
+
+# Remove duplicates
+unique_emails = list(set(all_emails))
+
+return [{
+    "json": {
+        "emails": unique_emails,
+        "count": len(unique_emails)
+    }
+}]
+```
+
+### 4. Data Validation
+
+Validate and clean data.
+
+```python
+items = _input.all()
+validated = []
+
+for item in items:
+    data = item["json"]
+    errors = []
+
+    # Validate fields
+    if not data.get("email"):
+        errors.append("Email required")
+    if not data.get("name"):
+        errors.append("Name required")
+
+    validated.append({
+        "json": {
+            **data,
+            "valid": len(errors) == 0,
+            "errors": errors if errors else None
+        }
+    })
+
+return validated
+```
+
+### 5. Statistical Analysis
+
+Calculate statistics with the statistics module.
+
+```python
+from statistics import mean, median, stdev
+
+items = _input.all()
+values = [item["json"].get("value", 0) for item in items if "value" in item["json"]]
+
+if values:
+    return [{
+        "json": {
+            "mean": mean(values),
+            "median": median(values),
+            "stdev": stdev(values) if len(values) > 1 else 0,
+            "min": min(values),
+            "max": max(values),
+            "count": len(values)
+        }
+    }]
+else:
+    return [{"json": {"error": "No values found"}}]
+```
+
+---
+
+## When to Use Each Pattern
+
+| Pattern | When to Use |
+|---------|-------------|
+| Multi-Source Aggregation | Combining data from different nodes/sources |
+| Regex Filtering | Text pattern matching, validation, extraction |
+| Markdown Parsing | Processing formatted text into structured data |
+| JSON Comparison | Detecting changes between objects |
+| CRM Transformation | Normalizing data from different systems |
+| Release Notes | Categorizing text by keywords |
+| Array Transformation | Reshaping data, extracting fields |
+| Dictionary Lookup | Fast ID-based lookups |
+| Top N Filtering | Getting best/worst items by criteria |
+| String Aggregation | Creating formatted text summaries |
+
+---
+
+## Summary
+
+**Key Takeaways**:
+- Use `.get()` for safe dictionary access
+- List comprehensions are pythonic and efficient
+- Handle empty lists/None values
+- Use standard library (json, datetime, re)
+- Return proper n8n format: `[{"json": {...}}]`
+
+**Remember**:
+- JavaScript is recommended for 95% of use cases
+- Python has NO external libraries
+- Use n8n nodes for complex operations
+- Code node is for data transformation, not API calls
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Python Code overview
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Data access patterns
+- [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) - Available modules
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Avoid common mistakes

data/skills/n8n-code-python/DATA_ACCESS.md

@@ -0,0 +1,702 @@
+# Data Access Patterns - Python Code Node
+
+Complete guide to accessing data in n8n Code nodes using Python.
+
+---
+
+## Overview
+
+In n8n Python Code nodes, you access data using **underscore-prefixed** variables: `_input`, `_json`, `_node`.
+
+**Data Access Priority** (by common usage):
+1. **`_input.all()`** - Most common - Batch operations, aggregations
+2. **`_input.first()`** - Very common - Single item operations
+3. **`_input.item`** - Common - Each Item mode only
+4. **`_node["NodeName"]["json"]`** - Specific node references
+5. **`_json`** - Direct current item (use `_input` instead)
+
+**Python vs JavaScript**:
+| JavaScript | Python (Beta) | Python (Native) |
+|------------|---------------|-----------------|
+| `$input.all()` | `_input.all()` | `_items` |
+| `$input.first()` | `_input.first()` | `_items[0]` |
+| `$input.item` | `_input.item` | `_item` |
+| `$json` | `_json` | `_item["json"]` |
+| `$node["Name"]` | `_node["Name"]` | Not available |
+
+---
+
+## Pattern 1: _input.all() - Process All Items
+
+**Usage**: Most common pattern for batch processing
+
+**When to use:**
+- Processing multiple records
+- Aggregating data (sum, count, average)
+- Filtering lists
+- Transforming datasets
+
+### Basic Usage
+
+```python
+# Get all items from previous node
+all_items = _input.all()
+
+# all_items is a list of dictionaries like:
+# [
+#   {"json": {"id": 1, "name": "Alice"}},
+#   {"json": {"id": 2, "name": "Bob"}}
+# ]
+
+print(f"Received {len(all_items)} items")
+
+return all_items
+```
+
+### Example 1: Filter Active Items
+
+```python
+all_items = _input.all()
+
+# Filter only active items
+active_items = [
+    item for item in all_items
+    if item["json"].get("status") == "active"
+]
+
+return active_items
+```
+
+### Example 2: Transform All Items
+
+```python
+all_items = _input.all()
+
+# Transform to new structure
+transformed = []
+for item in all_items:
+    transformed.append({
+        "json": {
+            "id": item["json"].get("id"),
+            "full_name": f"{item['json'].get('first_name', '')} {item['json'].get('last_name', '')}",
+            "email": item["json"].get("email"),
+            "processed_at": datetime.now().isoformat()
+        }
+    })
+
+return transformed
+```
+
+### Example 3: Aggregate Data
+
+```python
+all_items = _input.all()
+
+# Calculate total
+total = sum(item["json"].get("amount", 0) for item in all_items)
+
+return [{
+    "json": {
+        "total": total,
+        "count": len(all_items),
+        "average": total / len(all_items) if all_items else 0
+    }
+}]
+```
+
+### Example 4: Sort and Limit
+
+```python
+all_items = _input.all()
+
+# Get top 5 by score
+sorted_items = sorted(
+    all_items,
+    key=lambda item: item["json"].get("score", 0),
+    reverse=True
+)
+top_five = sorted_items[:5]
+
+return [{"json": item["json"]} for item in top_five]
+```
+
+### Example 5: Group By Category
+
+```python
+all_items = _input.all()
+
+# Group items by category
+grouped = {}
+for item in all_items:
+    category = item["json"].get("category", "Uncategorized")
+
+    if category not in grouped:
+        grouped[category] = []
+
+    grouped[category].append(item["json"])
+
+# Convert to list format
+return [
+    {
+        "json": {
+            "category": category,
+            "items": items,
+            "count": len(items)
+        }
+    }
+    for category, items in grouped.items()
+]
+```
+
+### Example 6: Deduplicate by ID
+
+```python
+all_items = _input.all()
+
+# Remove duplicates by ID
+seen = set()
+unique = []
+
+for item in all_items:
+    item_id = item["json"].get("id")
+
+    if item_id and item_id not in seen:
+        seen.add(item_id)
+        unique.append(item)
+
+return unique
+```
+
+---
+
+## Pattern 2: _input.first() - Get First Item
+
+**Usage**: Very common for single-item operations
+
+**When to use:**
+- Previous node returns single object
+- Working with API responses
+- Getting initial/first data point
+
+### Basic Usage
+
+```python
+# Get first item from previous node
+first_item = _input.first()
+
+# Access the JSON data
+data = first_item["json"]
+
+print(f"First item: {data}")
+
+return [{"json": data}]
+```
+
+### Example 1: Process Single API Response
+
+```python
+# Get API response (typically single object)
+response = _input.first()["json"]
+
+# Extract what you need
+return [{
+    "json": {
+        "user_id": response.get("data", {}).get("user", {}).get("id"),
+        "user_name": response.get("data", {}).get("user", {}).get("name"),
+        "status": response.get("status"),
+        "fetched_at": datetime.now().isoformat()
+    }
+}]
+```
+
+### Example 2: Transform Single Object
+
+```python
+data = _input.first()["json"]
+
+# Transform structure
+return [{
+    "json": {
+        "id": data.get("id"),
+        "contact": {
+            "email": data.get("email"),
+            "phone": data.get("phone")
+        },
+        "address": {
+            "street": data.get("street"),
+            "city": data.get("city"),
+            "zip": data.get("zip")
+        }
+    }
+}]
+```
+
+### Example 3: Validate Single Item
+
+```python
+item = _input.first()["json"]
+
+# Validation logic
+is_valid = bool(item.get("email") and "@" in item.get("email", ""))
+
+return [{
+    "json": {
+        **item,
+        "valid": is_valid,
+        "validated_at": datetime.now().isoformat()
+    }
+}]
+```
+
+### Example 4: Extract Nested Data
+
+```python
+response = _input.first()["json"]
+
+# Navigate nested structure
+users = response.get("data", {}).get("users", [])
+
+return [
+    {
+        "json": {
+            "id": user.get("id"),
+            "name": user.get("profile", {}).get("name", "Unknown"),
+            "email": user.get("contact", {}).get("email", "no-email")
+        }
+    }
+    for user in users
+]
+```
+
+---
+
+## Pattern 3: _input.item - Current Item (Each Item Mode)
+
+**Usage**: Common in "Run Once for Each Item" mode
+
+**When to use:**
+- Mode is set to "Run Once for Each Item"
+- Need to process items independently
+- Per-item API calls or validations
+
+**IMPORTANT**: Only use in "Each Item" mode. Will be undefined in "All Items" mode.
+
+### Basic Usage
+
+```python
+# In "Run Once for Each Item" mode
+current_item = _input.item
+data = current_item["json"]
+
+print(f"Processing item: {data.get('id')}")
+
+return [{
+    "json": {
+        **data,
+        "processed": True
+    }
+}]
+```
+
+### Example 1: Add Processing Metadata
+
+```python
+item = _input.item
+
+return [{
+    "json": {
+        **item["json"],
+        "processed": True,
+        "processed_at": datetime.now().isoformat(),
+        "processing_duration": random.random() * 1000  # Simulated
+    }
+}]
+```
+
+### Example 2: Per-Item Validation
+
+```python
+item = _input.item
+data = item["json"]
+
+# Validate this specific item
+errors = []
+
+if not data.get("email"):
+    errors.append("Email required")
+if not data.get("name"):
+    errors.append("Name required")
+if data.get("age") and data["age"] < 18:
+    errors.append("Must be 18+")
+
+return [{
+    "json": {
+        **data,
+        "valid": len(errors) == 0,
+        "errors": errors if errors else None
+    }
+}]
+```
+
+### Example 3: Conditional Processing
+
+```python
+item = _input.item
+data = item["json"]
+
+# Process based on item type
+if data.get("type") == "premium":
+    return [{
+        "json": {
+            **data,
+            "discount": 0.20,
+            "tier": "premium"
+        }
+    }]
+else:
+    return [{
+        "json": {
+            **data,
+            "discount": 0.05,
+            "tier": "standard"
+        }
+    }]
+```
+
+---
+
+## Pattern 4: _node - Reference Other Nodes
+
+**Usage**: Less common, but powerful for specific scenarios
+
+**When to use:**
+- Need data from specific named node
+- Combining data from multiple nodes
+
+### Basic Usage
+
+```python
+# Get output from specific node
+webhook_data = _node["Webhook"]["json"]
+api_data = _node["HTTP Request"]["json"]
+
+return [{
+    "json": {
+        "from_webhook": webhook_data,
+        "from_api": api_data
+    }
+}]
+```
+
+### Example 1: Combine Multiple Sources
+
+```python
+# Reference multiple nodes
+webhook = _node["Webhook"]["json"]
+database = _node["Postgres"]["json"]
+api = _node["HTTP Request"]["json"]
+
+return [{
+    "json": {
+        "combined": {
+            "webhook": webhook.get("body", {}),
+            "db_records": len(database) if isinstance(database, list) else 1,
+            "api_response": api.get("status")
+        },
+        "processed_at": datetime.now().isoformat()
+    }
+}]
+```
+
+### Example 2: Compare Across Nodes
+
+```python
+old_data = _node["Get Old Data"]["json"]
+new_data = _node["Get New Data"]["json"]
+
+# Simple comparison
+changes = {
+    "added": [n for n in new_data if n.get("id") not in [o.get("id") for o in old_data]],
+    "removed": [o for o in old_data if o.get("id") not in [n.get("id") for n in new_data]]
+}
+
+return [{
+    "json": {
+        "changes": changes,
+        "summary": {
+            "added": len(changes["added"]),
+            "removed": len(changes["removed"])
+        }
+    }
+}]
+```
+
+---
+
+## Critical: Webhook Data Structure
+
+**MOST COMMON MISTAKE**: Forgetting webhook data is nested under `["body"]`
+
+### The Problem
+
+Webhook node wraps all incoming data under a `"body"` property.
+
+### Structure
+
+```python
+# Webhook node output structure:
+{
+    "headers": {
+        "content-type": "application/json",
+        "user-agent": "..."
+    },
+    "params": {},
+    "query": {},
+    "body": {
+        # ← YOUR DATA IS HERE
+        "name": "Alice",
+        "email": "alice@example.com",
+        "message": "Hello!"
+    }
+}
+```
+
+### Wrong vs Right
+
+```python
+# ❌ WRONG: Trying to access directly
+name = _json["name"]  # KeyError!
+email = _json["email"]  # KeyError!
+
+# ✅ CORRECT: Access via ["body"]
+name = _json["body"]["name"]  # "Alice"
+email = _json["body"]["email"]  # "alice@example.com"
+
+# ✅ SAFER: Use .get() for safe access
+webhook_data = _json.get("body", {})
+name = webhook_data.get("name")  # None if missing
+email = webhook_data.get("email", "no-email")  # Default value
+```
+
+### Example: Full Webhook Processing
+
+```python
+# Get webhook data from previous node
+webhook_output = _input.first()["json"]
+
+# Access the actual payload
+payload = webhook_output.get("body", {})
+
+# Access headers if needed
+content_type = webhook_output.get("headers", {}).get("content-type")
+
+# Access query parameters if needed
+api_key = webhook_output.get("query", {}).get("api_key")
+
+# Process the actual data
+return [{
+    "json": {
+        # Data from webhook body
+        "user_name": payload.get("name"),
+        "user_email": payload.get("email"),
+        "message": payload.get("message"),
+
+        # Metadata
+        "received_at": datetime.now().isoformat(),
+        "content_type": content_type,
+        "authenticated": bool(api_key)
+    }
+}]
+```
+
+### POST Data, Query Params, and Headers
+
+```python
+webhook = _input.first()["json"]
+
+return [{
+    "json": {
+        # POST body data
+        "form_data": webhook.get("body", {}),
+
+        # Query parameters (?key=value)
+        "query_params": webhook.get("query", {}),
+
+        # HTTP headers
+        "user_agent": webhook.get("headers", {}).get("user-agent"),
+        "content_type": webhook.get("headers", {}).get("content-type"),
+
+        # Request metadata
+        "method": webhook.get("method"),  # POST, GET, etc.
+        "url": webhook.get("url")
+    }
+}]
+```
+
+---
+
+## Choosing the Right Pattern
+
+### Decision Tree
+
+```
+Do you need ALL items from previous node?
+├─ YES → Use _input.all()
+│
+└─ NO → Do you need just the FIRST item?
+    ├─ YES → Use _input.first()
+    │
+    └─ NO → Are you in "Each Item" mode?
+        ├─ YES → Use _input.item
+        │
+        └─ NO → Do you need specific node data?
+            ├─ YES → Use _node["NodeName"]
+            └─ NO → Use _input.first() (default)
+```
+
+### Quick Reference Table
+
+| Scenario | Use This | Example |
+|----------|----------|---------|
+| Sum all amounts | `_input.all()` | `sum(i["json"].get("amount", 0) for i in items)` |
+| Get API response | `_input.first()` | `_input.first()["json"].get("data")` |
+| Process each independently | `_input.item` | `_input.item["json"]` (Each Item mode) |
+| Combine two nodes | `_node["Name"]` | `_node["API"]["json"]` |
+| Filter list | `_input.all()` | `[i for i in items if i["json"].get("active")]` |
+| Transform single object | `_input.first()` | `{**_input.first()["json"], "new": True}` |
+| Webhook data | `_input.first()` | `_input.first()["json"]["body"]` |
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Using _json Without Context
+
+```python
+# ❌ RISKY: _json is ambiguous
+value = _json["field"]
+
+# ✅ CLEAR: Be explicit
+value = _input.first()["json"]["field"]
+```
+
+### Mistake 2: Forgetting ["json"] Property
+
+```python
+# ❌ WRONG: Trying to access fields on item dictionary
+items = _input.all()
+names = [item["name"] for item in items]  # KeyError!
+
+# ✅ CORRECT: Access via ["json"]
+names = [item["json"]["name"] for item in items]
+```
+
+### Mistake 3: Using _input.item in All Items Mode
+
+```python
+# ❌ WRONG: _input.item is None in "All Items" mode
+data = _input.item["json"]  # AttributeError!
+
+# ✅ CORRECT: Use appropriate method
+data = _input.first()["json"]  # Or _input.all()
+```
+
+### Mistake 4: Not Handling Empty Lists
+
+```python
+# ❌ WRONG: Crashes if no items
+first = _input.all()[0]["json"]  # IndexError!
+
+# ✅ CORRECT: Check length first
+items = _input.all()
+if items:
+    first = items[0]["json"]
+else:
+    return []
+
+# ✅ ALSO CORRECT: Use _input.first()
+first = _input.first()["json"]  # Built-in safety
+```
+
+### Mistake 5: Direct Dictionary Access (KeyError)
+
+```python
+# ❌ RISKY: Crashes if key missing
+value = item["json"]["field"]  # KeyError!
+
+# ✅ SAFE: Use .get()
+value = item["json"].get("field", "default")
+```
+
+---
+
+## Advanced Patterns
+
+### Pattern: Safe Nested Access
+
+```python
+# Deep nested access with .get()
+value = (
+    _input.first()["json"]
+    .get("level1", {})
+    .get("level2", {})
+    .get("level3", "default")
+)
+```
+
+### Pattern: List Comprehension with Filtering
+
+```python
+items = _input.all()
+
+# Filter and transform in one step
+result = [
+    {
+        "json": {
+            "id": item["json"]["id"],
+            "name": item["json"]["name"].upper()
+        }
+    }
+    for item in items
+    if item["json"].get("active") and item["json"].get("verified")
+]
+
+return result
+```
+
+### Pattern: Dictionary Comprehension
+
+```python
+items = _input.all()
+
+# Create lookup dictionary
+lookup = {
+    item["json"]["id"]: item["json"]
+    for item in items
+    if "id" in item["json"]
+}
+
+return [{"json": lookup}]
+```
+
+---
+
+## Summary
+
+**Most Common Patterns**:
+1. `_input.all()` - Process multiple items, batch operations
+2. `_input.first()` - Single item, API responses
+3. `_input.item` - Each Item mode processing
+
+**Critical Rule**:
+- Webhook data is under `["body"]` property
+
+**Best Practice**:
+- Use `.get()` for dictionary access to avoid KeyError
+- Always check for empty lists
+- Be explicit: Use `_input.first()["json"]["field"]` instead of `_json["field"]`
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Overview and quick start
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Python-specific patterns
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Avoid common mistakes

data/skills/n8n-code-python/ERROR_PATTERNS.md

@@ -0,0 +1,601 @@
+# Error Patterns - Python Code Node
+
+Common Python Code node errors and how to fix them.
+
+---
+
+## Error Overview
+
+**Top 5 Python Code Node Errors**:
+
+1. **ModuleNotFoundError** - Trying to import external libraries (Python-specific)
+2. **Empty Code / Missing Return** - No code or return statement
+3. **KeyError** - Dictionary access without .get()
+4. **IndexError** - List access without bounds checking
+5. **Incorrect Return Format** - Wrong data structure returned
+
+These 5 errors cover the majority of Python Code node failures.
+
+---
+
+## Error #1: ModuleNotFoundError (MOST CRITICAL)
+
+**Frequency**: Very common in Python Code nodes
+
+**What it is**: Attempting to import external libraries that aren't available.
+
+### The Problem
+
+```python
+# ❌ WRONG: External libraries not available
+import requests  # ModuleNotFoundError: No module named 'requests'
+import pandas    # ModuleNotFoundError: No module named 'pandas'
+import numpy     # ModuleNotFoundError: No module named 'numpy'
+import bs4       # ModuleNotFoundError: No module named 'bs4'
+import pymongo   # ModuleNotFoundError: No module named 'pymongo'
+import psycopg2  # ModuleNotFoundError: No module named 'psycopg2'
+
+# This code will FAIL - these libraries are not installed!
+response = requests.get("https://api.example.com/data")
+```
+
+### The Solution
+
+**Option 1: Use JavaScript Instead** (Recommended for 95% of cases)
+
+```javascript
+// ✅ JavaScript Code node with this.helpers.httpRequest()
+const response = await this.helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/data'
+});
+
+return [{json: response}];
+```
+
+**Option 2: Use n8n HTTP Request Node**
+
+```python
+# ✅ Add HTTP Request node BEFORE Python Code node
+# Access the response in Python Code node
+
+response = _input.first()["json"]
+
+return [{
+    "json": {
+        "status": response.get("status"),
+        "data": response.get("body"),
+        "processed": True
+    }
+}]
+```
+
+**Option 3: Use Standard Library Only**
+
+```python
+# ✅ Use urllib from standard library (limited functionality)
+from urllib.request import urlopen
+from urllib.parse import urlencode
+import json
+
+# Simple GET request (no headers, no auth)
+url = "https://api.example.com/data"
+with urlopen(url) as response:
+    data = json.loads(response.read())
+
+return [{"json": data}]
+```
+
+### Common Library Replacements
+
+| Need | ❌ External Library | ✅ Alternative |
+|------|-------------------|----------------|
+| HTTP requests | `requests` | Use HTTP Request node or JavaScript |
+| Data analysis | `pandas` | Use Python list comprehensions |
+| Database | `psycopg2`, `pymongo` | Use n8n database nodes |
+| Web scraping | `beautifulsoup4` | Use HTML Extract node |
+| Excel | `openpyxl` | Use Spreadsheet File node |
+| Image processing | `pillow` | Use external API or node |
+
+### Available Standard Library Modules
+
+```python
+# ✅ THESE WORK - Standard library only
+import json          # JSON parsing
+import datetime      # Date/time operations
+import re            # Regular expressions
+import base64        # Base64 encoding
+import hashlib       # Hashing (MD5, SHA256)
+import urllib.parse  # URL parsing and encoding
+import math          # Math functions
+import random        # Random numbers
+import statistics    # Statistical functions
+import collections   # defaultdict, Counter, etc.
+```
+
+---
+
+## Error #2: Empty Code / Missing Return
+
+**Frequency**: Common across all Code nodes
+
+**What it is**: Code node has no code or no return statement.
+
+### The Problem
+
+```python
+# ❌ WRONG: Empty code
+# (nothing here)
+
+# ❌ WRONG: Code but no return
+items = _input.all()
+processed = [item for item in items if item["json"].get("active")]
+# Forgot to return!
+
+# ❌ WRONG: Return in wrong scope
+if _input.all():
+    return [{"json": {"result": "success"}}]
+# Return is inside if block - may not execute!
+```
+
+### The Solution
+
+```python
+# ✅ CORRECT: Always return
+all_items = _input.all()
+
+if not all_items:
+    # Return empty array or error
+    return [{"json": {"error": "No items"}}]
+
+# Process items
+processed = [item for item in all_items if item["json"].get("active")]
+
+# Always return at the end
+return processed if processed else [{"json": {"message": "No active items"}}]
+```
+
+### Best Practice
+
+```python
+# ✅ GOOD: Return at end of function (unconditional)
+def process_items():
+    items = _input.all()
+
+    if not items:
+        return [{"json": {"error": "Empty input"}}]
+
+    # Process
+    result = []
+    for item in items:
+        result.append({"json": item["json"]})
+
+    return result
+
+# Call function and return result
+return process_items()
+```
+
+---
+
+## Error #3: KeyError
+
+**Frequency**: Very common in Python Code nodes
+
+**What it is**: Accessing dictionary key that doesn't exist.
+
+### The Problem
+
+```python
+# ❌ WRONG: Direct key access
+item = _input.first()["json"]
+
+name = item["name"]        # KeyError if "name" doesn't exist!
+email = item["email"]      # KeyError if "email" doesn't exist!
+age = item["age"]          # KeyError if "age" doesn't exist!
+
+return [{
+    "json": {
+        "name": name,
+        "email": email,
+        "age": age
+    }
+}]
+```
+
+### Error Message
+
+```
+KeyError: 'name'
+```
+
+### The Solution
+
+```python
+# ✅ CORRECT: Use .get() with defaults
+item = _input.first()["json"]
+
+name = item.get("name", "Unknown")
+email = item.get("email", "no-email@example.com")
+age = item.get("age", 0)
+
+return [{
+    "json": {
+        "name": name,
+        "email": email,
+        "age": age
+    }
+}]
+```
+
+### Nested Dictionary Access
+
+```python
+# ❌ WRONG: Nested key access
+webhook = _input.first()["json"]
+name = webhook["body"]["user"]["name"]  # Multiple KeyErrors possible!
+
+# ✅ CORRECT: Safe nested access
+webhook = _input.first()["json"]
+body = webhook.get("body", {})
+user = body.get("user", {})
+name = user.get("name", "Unknown")
+
+# ✅ ALSO CORRECT: Chained .get()
+name = (
+    webhook
+    .get("body", {})
+    .get("user", {})
+    .get("name", "Unknown")
+)
+
+return [{"json": {"name": name}}]
+```
+
+### Webhook Body Access (Critical!)
+
+```python
+# ❌ WRONG: Forgetting webhook data is under "body"
+webhook = _input.first()["json"]
+name = webhook["name"]        # KeyError!
+email = webhook["email"]      # KeyError!
+
+# ✅ CORRECT: Access via ["body"]
+webhook = _input.first()["json"]
+body = webhook.get("body", {})
+name = body.get("name", "Unknown")
+email = body.get("email", "no-email")
+
+return [{
+    "json": {
+        "name": name,
+        "email": email
+    }
+}]
+```
+
+---
+
+## Error #4: IndexError
+
+**Frequency**: Common when processing arrays/lists
+
+**What it is**: Accessing list index that doesn't exist.
+
+### The Problem
+
+```python
+# ❌ WRONG: Assuming items exist
+all_items = _input.all()
+first_item = all_items[0]        # IndexError if list is empty!
+second_item = all_items[1]       # IndexError if only 1 item!
+
+return [{
+    "json": {
+        "first": first_item["json"],
+        "second": second_item["json"]
+    }
+}]
+```
+
+### Error Message
+
+```
+IndexError: list index out of range
+```
+
+### The Solution
+
+```python
+# ✅ CORRECT: Check length first
+all_items = _input.all()
+
+if len(all_items) >= 2:
+    first_item = all_items[0]["json"]
+    second_item = all_items[1]["json"]
+
+    return [{
+        "json": {
+            "first": first_item,
+            "second": second_item
+        }
+    }]
+else:
+    return [{
+        "json": {
+            "error": f"Expected 2+ items, got {len(all_items)}"
+        }
+    }]
+```
+
+### Safe First Item Access
+
+```python
+# ✅ CORRECT: Use _input.first() instead of [0]
+# This is safer than manual indexing
+first_item = _input.first()["json"]
+
+return [{"json": first_item}]
+
+# ✅ ALSO CORRECT: Check before accessing
+all_items = _input.all()
+if all_items:
+    first_item = all_items[0]["json"]
+else:
+    first_item = {}
+
+return [{"json": first_item}]
+```
+
+### Slice Instead of Index
+
+```python
+# ✅ CORRECT: Use slicing (never raises IndexError)
+all_items = _input.all()
+
+# Get first 5 items (won't fail if fewer than 5)
+first_five = all_items[:5]
+
+# Get items after first (won't fail if empty)
+rest = all_items[1:]
+
+return [{"json": item["json"]} for item in first_five]
+```
+
+---
+
+## Error #5: Incorrect Return Format
+
+**Frequency**: Common for new users
+
+**What it is**: Returning data in wrong format (n8n expects array of objects with "json" key).
+
+### The Problem
+
+```python
+# ❌ WRONG: Returning plain dictionary
+return {"name": "Alice", "age": 30}
+
+# ❌ WRONG: Returning array without "json" wrapper
+return [{"name": "Alice"}, {"name": "Bob"}]
+
+# ❌ WRONG: Returning None
+return None
+
+# ❌ WRONG: Returning string
+return "success"
+
+# ❌ WRONG: Returning single item (not array)
+return {"json": {"name": "Alice"}}
+```
+
+### The Solution
+
+```python
+# ✅ CORRECT: Array of objects with "json" key
+return [{"json": {"name": "Alice", "age": 30}}]
+
+# ✅ CORRECT: Multiple items
+return [
+    {"json": {"name": "Alice"}},
+    {"json": {"name": "Bob"}}
+]
+
+# ✅ CORRECT: Transform items
+all_items = _input.all()
+return [
+    {"json": item["json"]}
+    for item in all_items
+]
+
+# ✅ CORRECT: Empty array (valid)
+return []
+
+# ✅ CORRECT: Single item still needs array wrapper
+return [{"json": {"result": "success"}}]
+```
+
+### Common Scenarios
+
+**Scenario 1: Aggregation (Return Single Result)**
+
+```python
+# Calculate total
+all_items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in all_items)
+
+# ✅ CORRECT: Wrap in array with "json"
+return [{
+    "json": {
+        "total": total,
+        "count": len(all_items)
+    }
+}]
+```
+
+**Scenario 2: Filtering (Return Multiple Results)**
+
+```python
+# Filter active items
+all_items = _input.all()
+active = [item for item in all_items if item["json"].get("active")]
+
+# ✅ CORRECT: Already in correct format
+return active
+
+# ✅ ALSO CORRECT: If transforming
+return [
+    {"json": {**item["json"], "filtered": True}}
+    for item in active
+]
+```
+
+**Scenario 3: No Results**
+
+```python
+# ✅ CORRECT: Return empty array
+return []
+
+# ✅ ALSO CORRECT: Return error message
+return [{"json": {"error": "No results found"}}]
+```
+
+---
+
+## Bonus Error: AttributeError
+
+**What it is**: Using _input.item in wrong mode.
+
+### The Problem
+
+```python
+# ❌ WRONG: Using _input.item in "All Items" mode
+current = _input.item        # None in "All Items" mode
+data = current["json"]       # AttributeError: 'NoneType' object has no attribute '__getitem__'
+```
+
+### The Solution
+
+```python
+# ✅ CORRECT: Check mode or use appropriate method
+# In "All Items" mode, use:
+all_items = _input.all()
+
+# In "Each Item" mode, use:
+current_item = _input.item
+
+# ✅ SAFE: Check if item exists
+current = _input.item
+if current:
+    data = current["json"]
+    return [{"json": data}]
+else:
+    # Running in "All Items" mode
+    return _input.all()
+```
+
+---
+
+## Error Prevention Checklist
+
+Before running your Python Code node, verify:
+
+- [ ] **No external imports**: Only standard library (json, datetime, re, etc.)
+- [ ] **Code returns data**: Every code path ends with `return`
+- [ ] **Correct format**: Returns `[{"json": {...}}]` (array with "json" key)
+- [ ] **Safe dictionary access**: Uses `.get()` instead of `[]` for dictionaries
+- [ ] **Safe list access**: Checks length before indexing or uses slicing
+- [ ] **Webhook body access**: Accesses webhook data via `_json["body"]`
+- [ ] **No None returns**: Returns empty array `[]` instead of `None`
+- [ ] **Mode awareness**: Uses `_input.all()`, `_input.first()`, or `_input.item` appropriately
+
+---
+
+## Quick Fix Reference
+
+| Error | Quick Fix |
+|-------|-----------|
+| `ModuleNotFoundError` | Use JavaScript or HTTP Request node instead |
+| `KeyError: 'field'` | Change `data["field"]` to `data.get("field", default)` |
+| `IndexError: list index out of range` | Check `if len(items) > 0:` before `items[0]` |
+| Empty output | Add `return [{"json": {...}}]` at end |
+| `AttributeError: 'NoneType'` | Check mode setting or verify `_input.item` exists |
+| Wrong format error | Wrap result: `return [{"json": result}]` |
+| Webhook KeyError | Access via `_json.get("body", {})` |
+
+---
+
+## Testing Your Code
+
+### Test Pattern 1: Handle Empty Input
+
+```python
+# ✅ Always test with empty input
+all_items = _input.all()
+
+if not all_items:
+    return [{"json": {"message": "No items to process"}}]
+
+# Continue with processing
+# ...
+```
+
+### Test Pattern 2: Test with Missing Fields
+
+```python
+# ✅ Use .get() with defaults
+item = _input.first()["json"]
+
+# These won't fail even if fields missing
+name = item.get("name", "Unknown")
+email = item.get("email", "no-email")
+age = item.get("age", 0)
+
+return [{"json": {"name": name, "email": email, "age": age}}]
+```
+
+### Test Pattern 3: Test Both Modes
+
+```python
+# ✅ Code that works in both modes
+try:
+    # Try "Each Item" mode first
+    current = _input.item
+    if current:
+        return [{"json": current["json"]}]
+except:
+    pass
+
+# Fall back to "All Items" mode
+all_items = _input.all()
+return all_items if all_items else [{"json": {"message": "No data"}}]
+```
+
+---
+
+## Summary
+
+**Top 5 Errors to Avoid**:
+1. **ModuleNotFoundError** - Use JavaScript or n8n nodes instead
+2. **Missing return** - Always end with `return [{"json": {...}}]`
+3. **KeyError** - Use `.get()` for dictionary access
+4. **IndexError** - Check length before indexing
+5. **Wrong format** - Return `[{"json": {...}}]`, not plain objects
+
+**Golden Rules**:
+- NO external libraries (use JavaScript instead)
+- ALWAYS use `.get()` for dictionaries
+- ALWAYS return `[{"json": {...}}]` format
+- CHECK lengths before list access
+- ACCESS webhook data via `["body"]`
+
+**Remember**:
+- JavaScript is recommended for 95% of use cases
+- Python has limitations (no requests, pandas, numpy)
+- Use n8n nodes for complex operations
+
+**See Also**:
+- [SKILL.md](SKILL.md) - Python Code overview
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Data access patterns
+- [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) - Available modules
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Production patterns

data/skills/n8n-code-python/README.md

@@ -0,0 +1,386 @@
+# n8n Code Python Skill
+
+Expert guidance for writing Python code in n8n Code nodes.
+
+---
+
+## ⚠️ Important: JavaScript First
+
+**Use JavaScript for 95% of use cases.**
+
+Python in n8n has **NO external libraries** (no requests, pandas, numpy).
+
+**When to use Python**:
+- You have complex Python-specific logic
+- You need Python's standard library features
+- You're more comfortable with Python than JavaScript
+
+**When to use JavaScript** (recommended):
+- HTTP requests (this.helpers.httpRequest available)
+- Date/time operations (Luxon library included)
+- Most data transformations
+- When in doubt
+
+---
+
+## What This Skill Teaches
+
+### Core Concepts
+
+1. **Critical Limitation**: No external libraries
+2. **Data Access**: `_input.all()`, `_input.first()`, `_input.item`
+3. **Webhook Gotcha**: Data is under `_json["body"]`
+4. **Return Format**: Must return `[{"json": {...}}]`
+5. **Standard Library**: json, datetime, re, base64, hashlib, etc.
+
+### Top 5 Error Prevention
+
+This skill emphasizes **error prevention**:
+
+1. **ModuleNotFoundError** (trying to import external libraries)
+2. **Empty code / missing return**
+3. **KeyError** (dictionary access without .get())
+4. **IndexError** (list access without bounds checking)
+5. **Incorrect return format**
+
+These 5 errors are the most common in Python Code nodes.
+
+---
+
+## Skill Activation
+
+This skill activates when you:
+- Write Python in Code nodes
+- Ask about Python limitations
+- Need to know available standard library
+- Troubleshoot Python Code node errors
+- Work with Python data structures
+
+**Example queries**:
+- "Can I use pandas in Python Code node?"
+- "How do I access webhook data in Python?"
+- "What Python libraries are available?"
+- "Write Python code to process JSON"
+- "Why is requests module not found?"
+
+---
+
+## File Structure
+
+### SKILL.md
+**Quick start** and overview
+- When to use Python vs JavaScript
+- Critical limitation (no external libraries)
+- Mode selection (All Items vs Each Item)
+- Data access overview
+- Return format requirements
+- Standard library overview
+
+### DATA_ACCESS.md
+**Complete data access patterns**
+- `_input.all()` - Process all items
+- `_input.first()` - Get first item
+- `_input.item` - Current item (Each Item mode)
+- `_node["Name"]` - Reference other nodes
+- Webhook body structure (critical gotcha!)
+- Pattern selection guide
+
+### STANDARD_LIBRARY.md
+**Available Python modules**
+- json - JSON parsing
+- datetime - Date/time operations
+- re - Regular expressions
+- base64 - Encoding/decoding
+- hashlib - Hashing
+- urllib.parse - URL operations
+- math, random, statistics
+- What's NOT available (requests, pandas, numpy)
+- Workarounds for missing libraries
+
+### COMMON_PATTERNS.md
+**10 production-tested patterns**
+1. Multi-source data aggregation
+2. Regex-based filtering
+3. Markdown to structured data
+4. JSON object comparison
+5. CRM data transformation
+6. Release notes processing
+7. Array transformation
+8. Dictionary lookup
+9. Top N filtering
+10. String aggregation
+
+### ERROR_PATTERNS.md
+**Top 5 errors with solutions**
+1. ModuleNotFoundError (external libraries)
+2. Empty code / missing return
+3. KeyError (dictionary access)
+4. IndexError (list access)
+5. Incorrect return format
+- Error prevention checklist
+- Quick fix reference
+- Testing patterns
+
+---
+
+## Integration with Other Skills
+
+This skill works with:
+
+### n8n Expression Syntax
+- Python uses code syntax, not {{}} expressions
+- Data access patterns differ ($ vs _)
+
+### n8n MCP Tools Expert
+- Use MCP tools to validate Code node configurations
+- Check node setup with `get_node`
+
+### n8n Workflow Patterns
+- Code nodes fit into larger workflow patterns
+- Often used after HTTP Request or Webhook nodes
+
+### n8n Code JavaScript
+- Compare Python vs JavaScript approaches
+- Understand when to use which language
+- JavaScript recommended for 95% of cases
+
+### n8n Node Configuration
+- Configure Code node mode (All Items vs Each Item)
+- Set up proper connections
+
+---
+
+## Success Metrics
+
+After using this skill, you should be able to:
+
+- [ ] **Know the limitation**: Python has NO external libraries
+- [ ] **Choose language**: JavaScript for 95% of cases, Python when needed
+- [ ] **Access data**: Use `_input.all()`, `_input.first()`, `_input.item`
+- [ ] **Handle webhooks**: Access data via `_json["body"]`
+- [ ] **Return properly**: Always return `[{"json": {...}}]`
+- [ ] **Avoid KeyError**: Use `.get()` for dictionary access
+- [ ] **Use standard library**: Know what's available (json, datetime, re, etc.)
+- [ ] **Prevent errors**: Avoid top 5 common errors
+- [ ] **Choose alternatives**: Use n8n nodes when libraries needed
+- [ ] **Write production code**: Use proven patterns
+
+---
+
+## Quick Reference
+
+### Data Access
+```python
+all_items = _input.all()
+first_item = _input.first()
+current_item = _input.item  # Each Item mode only
+other_node = _node["NodeName"]
+```
+
+### Webhook Data
+```python
+webhook = _input.first()["json"]
+body = webhook.get("body", {})
+name = body.get("name")
+```
+
+### Safe Dictionary Access
+```python
+# ✅ Use .get() with defaults
+value = data.get("field", "default")
+
+# ❌ Risky - may raise KeyError
+value = data["field"]
+```
+
+### Return Format
+```python
+# ✅ Correct format
+return [{"json": {"result": "success"}}]
+
+# ❌ Wrong - plain dict
+return {"result": "success"}
+```
+
+### Standard Library
+```python
+# ✅ Available
+import json
+import datetime
+import re
+import base64
+import hashlib
+
+# ❌ NOT available
+import requests  # ModuleNotFoundError!
+import pandas    # ModuleNotFoundError!
+import numpy     # ModuleNotFoundError!
+```
+
+---
+
+## Common Use Cases
+
+### Use Case 1: Process Webhook Data
+```python
+webhook = _input.first()["json"]
+body = webhook.get("body", {})
+
+return [{
+    "json": {
+        "name": body.get("name"),
+        "email": body.get("email"),
+        "processed": True
+    }
+}]
+```
+
+### Use Case 2: Filter and Transform
+```python
+all_items = _input.all()
+
+active = [
+    {"json": {**item["json"], "filtered": True}}
+    for item in all_items
+    if item["json"].get("status") == "active"
+]
+
+return active
+```
+
+### Use Case 3: Aggregate Statistics
+```python
+import statistics
+
+all_items = _input.all()
+amounts = [item["json"].get("amount", 0) for item in all_items]
+
+return [{
+    "json": {
+        "total": sum(amounts),
+        "average": statistics.mean(amounts) if amounts else 0,
+        "count": len(amounts)
+    }
+}]
+```
+
+### Use Case 4: Parse JSON String
+```python
+import json
+
+data = _input.first()["json"]["body"]
+json_string = data.get("payload", "{}")
+
+try:
+    parsed = json.loads(json_string)
+    return [{"json": parsed}]
+except json.JSONDecodeError:
+    return [{"json": {"error": "Invalid JSON"}}]
+```
+
+---
+
+## Limitations and Workarounds
+
+### Limitation 1: No HTTP Requests Library
+**Problem**: No `requests` library
+**Workaround**: Use HTTP Request node or JavaScript
+
+### Limitation 2: No Data Analysis Library
+**Problem**: No `pandas` or `numpy`
+**Workaround**: Use list comprehensions and standard library
+
+### Limitation 3: No Database Drivers
+**Problem**: No `psycopg2`, `pymongo`, etc.
+**Workaround**: Use n8n database nodes (Postgres, MySQL, MongoDB)
+
+### Limitation 4: No Web Scraping
+**Problem**: No `beautifulsoup4` or `selenium`
+**Workaround**: Use HTML Extract node
+
+---
+
+## Best Practices
+
+1. **Use JavaScript for most cases** (95% recommendation)
+2. **Use .get() for dictionaries** (avoid KeyError)
+3. **Check lengths before indexing** (avoid IndexError)
+4. **Always return proper format**: `[{"json": {...}}]`
+5. **Access webhook data via ["body"]**
+6. **Use standard library only** (no external imports)
+7. **Handle empty input** (check `if items:`)
+8. **Test both modes** (All Items and Each Item)
+
+---
+
+## When Python is the Right Choice
+
+Use Python when:
+- Complex text processing (re module)
+- Mathematical calculations (math, statistics)
+- Date/time manipulation (datetime)
+- Cryptographic operations (hashlib)
+- You have existing Python logic to reuse
+- Team is more comfortable with Python
+
+Use JavaScript instead when:
+- Making HTTP requests
+- Working with dates (Luxon included)
+- Most data transformations
+- When in doubt
+
+---
+
+## Learning Path
+
+**Beginner**:
+1. Read SKILL.md - Understand the limitation
+2. Try DATA_ACCESS.md examples - Learn `_input` patterns
+3. Practice safe dictionary access with `.get()`
+
+**Intermediate**:
+4. Study STANDARD_LIBRARY.md - Know what's available
+5. Try COMMON_PATTERNS.md examples - Use proven patterns
+6. Learn ERROR_PATTERNS.md - Avoid common mistakes
+
+**Advanced**:
+7. Combine multiple patterns
+8. Use standard library effectively
+9. Know when to switch to JavaScript
+10. Write production-ready code
+
+---
+
+## Support
+
+**Questions?**
+- Check ERROR_PATTERNS.md for common issues
+- Review COMMON_PATTERNS.md for examples
+- Consider using JavaScript instead
+
+**Related Skills**:
+- n8n Code JavaScript - Alternative (recommended for 95% of cases)
+- n8n Expression Syntax - For {{}} expressions in other nodes
+- n8n Workflow Patterns - Bigger picture workflow design
+
+---
+
+## Version
+
+**Version**: 1.0.0
+**Status**: Production Ready
+**Compatibility**: n8n Code node (Python mode)
+
+---
+
+## Credits
+
+Part of the n8n-skills project.
+
+**Conceived by Romuald Członkowski**
+- Website: [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
+- Part of [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp)
+
+---
+
+**Remember**: JavaScript is recommended for 95% of use cases. Use Python only when you specifically need Python's standard library features.

data/skills/n8n-code-python/SKILL.md

@@ -0,0 +1,501 @@
+---
+name: n8n-code-python
+description: Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes. Use this skill when the user specifically requests Python for an n8n Code node. Note — JavaScript is recommended for 95% of use cases — only use Python when the user explicitly prefers it or the task requires Python-specific standard library capabilities (regex, hashlib, statistics). EXCEPTION — for Python in the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode), use the n8n-code-tool skill instead (input is _query, return must be a string).
+---
+
+# Python Code Node (Beta)
+
+Expert guidance for writing Python code in n8n Code nodes.
+
+---
+
+## ⚠️ Important: JavaScript First
+
+**Recommendation**: Use **JavaScript for 95% of use cases**. Only use Python when:
+- You need specific Python standard library functions
+- You're significantly more comfortable with Python syntax
+- You're doing data transformations better suited to Python
+
+**Why JavaScript is preferred:**
+- Full n8n helper functions (`this.helpers.httpRequest`, etc.)
+- Luxon DateTime library for advanced date/time operations
+- No external library limitations
+- Better n8n documentation and community support
+
+---
+
+## Quick Start
+
+```python
+# Basic template for Python Code nodes
+items = _input.all()
+
+# Process data
+processed = []
+for item in items:
+    processed.append({
+        "json": {
+            **item["json"],
+            "processed": True,
+            "timestamp": datetime.now().isoformat()
+        }
+    })
+
+return processed
+```
+
+### Essential Rules
+
+1. **Consider JavaScript first** - Use Python only when necessary
+2. **Access data**: `_input.all()`, `_input.first()`, or `_input.item`
+3. **CRITICAL**: Must return `[{"json": {...}}]` format
+4. **CRITICAL**: Webhook data is under `_json["body"]` (not `_json` directly)
+5. **CRITICAL LIMITATION**: **No external libraries** (no requests, pandas, numpy)
+6. **Standard library only**: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics
+
+---
+
+## Mode Selection Guide
+
+Same as JavaScript - choose based on your use case:
+
+### Run Once for All Items (Recommended - Default)
+
+**Use this mode for:** 95% of use cases
+
+- **How it works**: Code executes **once** regardless of input count
+- **Data access**: `_input.all()` or `_items` array (Native mode)
+- **Best for**: Aggregation, filtering, batch processing, transformations
+- **Performance**: Faster for multiple items (single execution)
+
+```python
+# Example: Calculate total from all items
+all_items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in all_items)
+
+return [{
+    "json": {
+        "total": total,
+        "count": len(all_items),
+        "average": total / len(all_items) if all_items else 0
+    }
+}]
+```
+
+### Run Once for Each Item
+
+**Use this mode for:** Specialized cases only
+
+- **How it works**: Code executes **separately** for each input item
+- **Data access**: `_input.item` or `_item` (Native mode)
+- **Best for**: Item-specific logic, independent operations, per-item validation
+- **Performance**: Slower for large datasets (multiple executions)
+
+```python
+# Example: Add processing timestamp to each item
+item = _input.item
+
+return [{
+    "json": {
+        **item["json"],
+        "processed": True,
+        "processed_at": datetime.now().isoformat()
+    }
+}]
+```
+
+---
+
+## Python Modes: Beta vs Native
+
+n8n offers two Python execution modes:
+
+### Python (Beta) - Recommended
+- **Use**: `_input`, `_json`, `_node` helper syntax
+- **Best for**: Most Python use cases
+- **Helpers available**: `_now`, `_today`, `_jmespath()`
+- **Import**: `from datetime import datetime`
+
+```python
+# Python (Beta) example
+items = _input.all()
+now = _now  # Built-in datetime object
+
+return [{
+    "json": {
+        "count": len(items),
+        "timestamp": now.isoformat()
+    }
+}]
+```
+
+### Python (Native) (Beta)
+- **Use**: `_items`, `_item` variables only
+- **No helpers**: No `_input`, `_now`, etc.
+- **More limited**: Standard Python only
+- **Use when**: Need pure Python without n8n helpers
+
+```python
+# Python (Native) example
+processed = []
+
+for item in _items:
+    processed.append({
+        "json": {
+            "id": item["json"].get("id"),
+            "processed": True
+        }
+    })
+
+return processed
+```
+
+**Recommendation**: Use **Python (Beta)** for better n8n integration.
+
+---
+
+## Data Access Patterns
+
+Access input data through underscore-prefixed variables. Each item is a dict shaped `{"json": {...}}`, so the actual fields live under `["json"]`.
+
+```python
+# Pattern 1: _input.all() - Most common. Arrays, batch ops, aggregations
+all_items = _input.all()            # list of {"json": {...}} dicts
+
+# Pattern 2: _input.first() - Very common. Single objects, API responses
+data = _input.first()["json"]       # built-in safety vs all_items[0]
+
+# Pattern 3: _input.item - "Run Once for Each Item" mode ONLY
+current = _input.item["json"]       # None/error in All Items mode
+
+# Pattern 4: _node - Reference a specific named node
+webhook_data = _node["Webhook"]["json"]
+http_data = _node["HTTP Request"]["json"]
+```
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for the comprehensive guide — six `_input.all()` recipes (filter, transform, aggregate, sort, group, deduplicate), `_input.first()` and `_input.item` examples, multi-node combining, the JS-vs-Python variable table, and the decision tree.
+
+---
+
+## Critical: Webhook Data Structure
+
+**MOST COMMON MISTAKE**: Webhook data is nested under `["body"]`
+
+```python
+# ❌ WRONG - Will raise KeyError
+name = _json["name"]
+email = _json["email"]
+
+# ✅ CORRECT - Webhook data is under ["body"]
+name = _json["body"]["name"]
+email = _json["body"]["email"]
+
+# ✅ SAFER - Use .get() for safe access
+webhook_data = _json.get("body", {})
+name = webhook_data.get("name")
+```
+
+**Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads.
+
+**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details
+
+---
+
+## Return Format Requirements
+
+**CRITICAL RULE**: Always return list of dictionaries with `"json"` key
+
+### Correct Return Formats
+
+```python
+# ✅ Single result
+return [{
+    "json": {
+        "field1": value1,
+        "field2": value2
+    }
+}]
+
+# ✅ Multiple results
+return [
+    {"json": {"id": 1, "data": "first"}},
+    {"json": {"id": 2, "data": "second"}}
+]
+
+# ✅ List comprehension
+transformed = [
+    {"json": {"id": item["json"]["id"], "processed": True}}
+    for item in _input.all()
+    if item["json"].get("valid")
+]
+return transformed
+
+# ✅ Empty result (when no data to return)
+return []
+
+# ✅ Conditional return
+if should_process:
+    return [{"json": processed_data}]
+else:
+    return []
+```
+
+### Incorrect Return Formats
+
+```python
+# ❌ WRONG: Dictionary without list wrapper
+return {
+    "json": {"field": value}
+}
+
+# ❌ WRONG: List without json wrapper
+return [{"field": value}]
+
+# ❌ WRONG: Plain string
+return "processed"
+
+# ❌ WRONG: Incomplete structure
+return [{"data": value}]  # Should be {"json": value}
+```
+
+**Why it matters**: Next nodes expect list format. Incorrect format causes workflow execution to fail.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #2 for detailed error solutions
+
+---
+
+## Critical Limitation: No External Libraries
+
+**MOST IMPORTANT PYTHON LIMITATION**: Cannot import external packages on default installs.
+
+> **Self-hosted exception**: external package availability depends entirely on the instance's Python runner configuration. If the user states their self-hosted instance has specific packages available in the Python runner environment, use them — don't refuse. When unsure, ask or write standard-library-only code.
+
+**❌ NOT available** (raise `ModuleNotFoundError`): `requests`, `pandas`, `numpy`, `scipy`, `bs4`/BeautifulSoup, `lxml`.
+
+**✅ Available** (standard library only): `json`, `datetime`, `re`, `base64`, `hashlib`, `urllib.parse`, `math`, `random`, `statistics`.
+
+### Workarounds
+
+**Need HTTP requests?**
+- ✅ Use **HTTP Request node** before Code node
+- ✅ Or switch to **JavaScript** and use `this.helpers.httpRequest()` (the bare `$helpers` global is undefined in the task-runner sandbox)
+
+**Need data analysis (pandas/numpy)?**
+- ✅ Use Python **statistics** module for basic stats
+- ✅ Or switch to **JavaScript** for most operations
+- ✅ Manual calculations with lists and dictionaries
+
+**Need web scraping (BeautifulSoup)?**
+- ✅ Use **HTTP Request node** + **HTML Extract node**
+- ✅ Or switch to **JavaScript** with regex/string methods
+
+**See**: [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) for complete reference
+
+---
+
+## Common Patterns Overview
+
+Based on production workflows, the most useful Python patterns are:
+
+1. **Data Transformation** - Transform all items with list comprehensions
+2. **Filtering & Aggregation** - Sum, filter, count with built-in functions
+3. **String Processing with Regex** - Extract patterns from text with `re`
+4. **Data Validation** - Validate and clean data, attach error lists
+5. **Statistical Analysis** - Calculate mean/median/stdev with the `statistics` module
+
+Copy-ready snippets for all five live in [COMMON_PATTERNS.md](COMMON_PATTERNS.md#quick-pattern-snippets), alongside 10 fully detailed production patterns (multi-source aggregation, markdown parsing, JSON comparison, CRM normalization, dictionary lookup, top-N filtering, and more).
+
+---
+
+## Error Prevention - Top 5 Mistakes
+
+1. **Importing external libraries** (Python-specific) → `import requests` raises `ModuleNotFoundError`. Use the HTTP Request node or JavaScript instead.
+2. **Empty code or missing return** → every path must end with `return [{"json": ...}]`.
+3. **Incorrect return format** → wrap in a list: `{"json": {...}}` becomes `[{"json": {...}}]`.
+4. **KeyError on dictionary access** → use `.get()`: `_json.get("user", {}).get("name", "Unknown")`.
+5. **Webhook body nesting** → read via `["body"]`: `_json.get("body", {}).get("email", "no-email")`.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for the comprehensive guide — each error with wrong-vs-right code, error messages, nested-access fixes, an `AttributeError` bonus case, a prevention checklist, and a quick-fix table.
+
+---
+
+## Standard Library Reference
+
+Most useful modules: `json` (parse/generate), `datetime` (dates + `timedelta`), `re` (regex), `base64` (encode/decode), `hashlib` (hashing), `urllib.parse` (URL ops), and `statistics` (mean/median/stdev). Also available: `math`, `random`, `collections`, `itertools`, `functools`.
+
+For a condensed cheat sheet plus full per-module examples, see [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md#quick-reference-most-useful-modules).
+
+---
+
+## Best Practices
+
+### 1. Always Use .get() for Dictionary Access
+
+```python
+# ✅ SAFE: Won't crash if field missing
+value = item["json"].get("field", "default")
+
+# ❌ RISKY: Crashes if field doesn't exist
+value = item["json"]["field"]
+```
+
+### 2. Handle None/Null Values Explicitly
+
+```python
+# ✅ GOOD: Default to 0 if None
+amount = item["json"].get("amount") or 0
+
+# ✅ GOOD: Check for None explicitly
+text = item["json"].get("text")
+if text is None:
+    text = ""
+```
+
+### 3. Use List Comprehensions for Filtering
+
+```python
+# ✅ PYTHONIC: List comprehension
+valid = [item for item in items if item["json"].get("active")]
+
+# ❌ VERBOSE: Manual loop
+valid = []
+for item in items:
+    if item["json"].get("active"):
+        valid.append(item)
+```
+
+### 4. Return Consistent Structure
+
+```python
+# ✅ CONSISTENT: Always list with "json" key
+return [{"json": result}]  # Single result
+return results  # Multiple results (already formatted)
+return []  # No results
+```
+
+### 5. Debug with print() Statements
+
+```python
+# Debug statements appear in browser console (F12)
+items = _input.all()
+print(f"Processing {len(items)} items")
+print(f"First item: {items[0] if items else 'None'}")
+```
+
+---
+
+## Production Gotchas
+
+### SplitInBatches Loop Semantics
+
+The SplitInBatches node has two outputs:
+- `main[0]` = **done** — fires ONCE after all batches complete
+- `main[1]` = **each batch** — fires for every batch (the loop body)
+
+Always add a **Limit 1** node after the done output.
+
+### Correct Node Reference Syntax
+
+```python
+# ❌ WRONG
+data = _node['HTTP Request']['json']
+
+# ✅ CORRECT - call .first() then access json
+data = _node['HTTP Request'].first()['json']
+```
+
+### Cross-Iteration Data Not Available in Python
+
+`$getWorkflowStaticData('global')` may not be available in Python Beta mode. If you need to accumulate data across SplitInBatches iterations, use a JavaScript Code node for the accumulation logic instead.
+
+---
+
+## When to Use Python vs JavaScript
+
+### Use Python When:
+- ✅ You need `statistics` module for statistical operations
+- ✅ You're significantly more comfortable with Python syntax
+- ✅ Your logic maps well to list comprehensions
+- ✅ You need specific standard library functions
+
+### Use JavaScript When:
+- ✅ You need HTTP requests (`this.helpers.httpRequest()`)
+- ✅ You need advanced date/time (DateTime/Luxon)
+- ✅ You want better n8n integration
+- ✅ **For 95% of use cases** (recommended)
+
+### Consider Other Nodes When:
+- ❌ Simple field mapping → Use **Set** node
+- ❌ Basic filtering → Use **Filter** node
+- ❌ Simple conditionals → Use **IF** or **Switch** node
+- ❌ HTTP requests only → Use **HTTP Request** node
+
+---
+
+## Integration with Other Skills
+
+### Works With:
+
+**n8n Expression Syntax**:
+- Expressions use `{{ }}` syntax in other nodes
+- Code nodes use Python directly (no `{{ }}`)
+- When to use expressions vs code
+
+**n8n MCP Tools Expert**:
+- How to find Code node: `search_nodes({query: "code"})`
+- Get configuration help: `get_node({nodeType: "nodes-base.code"})`
+- Validate code: `validate_node({nodeType: "nodes-base.code", config: {...}})`
+
+**n8n Node Configuration**:
+- Mode selection (All Items vs Each Item)
+- Language selection (Python vs JavaScript)
+- Understanding property dependencies
+
+**n8n Workflow Patterns**:
+- Code nodes in transformation step
+- When to use Python vs JavaScript in patterns
+
+**n8n Validation Expert**:
+- Validate Code node configuration
+- Handle validation errors
+- Auto-fix common issues
+
+**n8n Code JavaScript**:
+- When to use JavaScript instead
+- Comparison of JavaScript vs Python features
+- Migration from Python to JavaScript
+
+---
+
+## Quick Reference Checklist
+
+Before deploying Python Code nodes, verify:
+
+- [ ] **Considered JavaScript first** - Using Python only when necessary
+- [ ] **Code is not empty** - Must have meaningful logic
+- [ ] **Return statement exists** - Must return list of dictionaries
+- [ ] **Proper return format** - Each item: `{"json": {...}}`
+- [ ] **Data access correct** - Using `_input.all()`, `_input.first()`, or `_input.item`
+- [ ] **No external imports** - Only standard library (json, datetime, re, etc.)
+- [ ] **Safe dictionary access** - Using `.get()` to avoid KeyError
+- [ ] **Webhook data** - Access via `["body"]` if from webhook
+- [ ] **Mode selection** - "All Items" for most cases
+- [ ] **Output consistent** - All code paths return same structure
+
+---
+
+## Additional Resources
+
+### Related Files
+- [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive Python data access patterns
+- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 Python patterns for n8n
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions
+- [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) - Complete standard library reference
+
+### n8n Documentation
+- Code Node Guide: https://docs.n8n.io/code/code-node/
+- Python in n8n: https://docs.n8n.io/code/builtin/python-modules/
+
+---
+
+**Ready to write Python in n8n Code nodes - but consider JavaScript first!** Use Python for specific needs, reference the error patterns guide to avoid common mistakes, and leverage the standard library effectively.

data/skills/n8n-code-tool/ERROR_PATTERNS.md

@@ -0,0 +1,178 @@
+# Code Tool Error Patterns
+
+The most common failure modes for `@n8n/n8n-nodes-langchain.toolCode`, with exact error strings, root causes, and fixes.
+
+---
+
+## Error 1: `"Cannot assign to read only property 'name' of object: Error: No execution data available"`
+
+**Full message (wrapped by n8n):**
+> There was an error: "Cannot assign to read only property 'name' of object 'Error: No execution data available'"
+
+**Cause**: Calling `$fromAI()` inside the Code Tool sandbox. `$fromAI()` is a helper intended for *other* tool-enabled nodes (HTTP Request Tool, SendGrid Tool, `toolWorkflow`) where AI-supplied values flow through workflow execution data. The Code Tool sandbox has no execution data — it receives input directly via `query`. The helper throws, n8n tries to annotate the error's `name` property, and that assignment fails because the error object is frozen.
+
+**Fix**: remove `$fromAI()`. Read from `query` (or define an input schema, see [INPUT_SCHEMA.md](INPUT_SCHEMA.md)).
+
+```javascript
+// ❌ Broken
+const price = $fromAI('price', 'Car price in SEK', 'number');
+
+// ✅ Unstructured — parse a JSON string
+const params = JSON.parse(query);
+const price = Number(params.price);
+
+// ✅ Structured — with specifyInputSchema: true
+const { price } = query;
+```
+
+---
+
+## Error 2: `"Wrong output type returned"`
+
+**Cause**: You returned the workflow item format (`[{json: {...}}]`) from the Code Tool. That format is for regular Code **nodes**; tools follow the LangChain contract and must return a string.
+
+**Fix**: return a string. For structured output, stringify:
+
+```javascript
+// ❌ Broken
+return [{ json: { monthly_payment: 5405 } }];
+
+// ✅ Fixed
+return JSON.stringify({ monthly_payment: 5405 });
+```
+
+---
+
+## Error 3: `"The response property should be a string, but it is an <type>"`
+
+Where `<type>` is `object`, `undefined`, `function`, etc.
+
+**Cause**: You returned a bare object, array, or nothing at all.
+
+| Returned value | Error says | Fix |
+|---|---|---|
+| `{ result: 42 }` | `...is an object` | `JSON.stringify({ result: 42 })` |
+| `[1, 2, 3]` | `...is an object` | `JSON.stringify([1, 2, 3])` |
+| *(no `return`)* | `...is an undefined` | Add a `return` |
+| `undefined` | `...is an undefined` | Return something |
+
+**Numbers are fine** — n8n auto-converts them to strings:
+```javascript
+return 42;  // ✅ becomes "42"
+```
+
+**Booleans are NOT auto-converted** — stringify explicitly:
+```javascript
+return String(someBoolean);  // ✅
+return JSON.stringify(someBoolean);  // ✅
+```
+
+---
+
+## Error 4: AI never calls the tool
+
+**Symptom**: the agent answers from its own reasoning and ignores the tool. No tool invocation shows up in the execution trace.
+
+**Common causes and fixes**:
+
+1. **Generic name**. Default names like `Code Tool` or `My Tool` give the LLM no signal.
+   - Fix: rename to verb-y, domain-specific snake_case: `calculate_car_loan`, `search_orders`, `lookup_customer`.
+
+2. **Description doesn't state the trigger**. "Calculates things" is too vague.
+   - Fix: explicitly list the user intents that should invoke the tool. `"Use this whenever the user asks about monthly cost, loan breakdown, or total interest."`
+
+3. **Tool isn't wired**. The node sits in the canvas but isn't connected to the AI Agent's `ai_tool` input.
+   - Fix: connect it. Check the workflow JSON `connections` block has `"<tool_name>": { "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]] }`.
+
+4. **Name violates `[A-Za-z0-9_]+`**. Spaces, hyphens, and emoji in the tool name cause silent skip on v1.1+.
+   - Fix: rename to `snake_case_only`.
+
+---
+
+## Error 5: LLM sends malformed `query`
+
+**Symptom**: your `JSON.parse(query)` throws, or fields come through as wrong types.
+
+**Causes**:
+- You're in unstructured mode and the description is ambiguous, so the LLM invents a format.
+- You asked for a JSON string but the LLM sent a natural-language sentence.
+- Numeric fields arrive as strings because the LLM serialized them that way.
+
+**Fixes**, in order of preference:
+
+1. **Switch to structured mode**. Set `specifyInputSchema: true` and define fields. The LLM now gets a typed schema and n8n validates before your code runs.
+
+2. **Give a concrete example in the description**. LLMs imitate examples well:
+   ```
+   Call with a single JSON string. Example:
+   {"price":439900,"down_payment":87980,"interest_rate":6.95}
+   ```
+
+3. **Coerce defensively**:
+   ```javascript
+   const params = JSON.parse(query);
+   const price = Number(params.price);
+   if (!isFinite(price)) throw new Error('price must be numeric');
+   ```
+
+---
+
+## Error 6: `"$helpers is not defined"` / `"$input is not defined"`
+
+**Cause**: you assumed the Code Tool sandbox exposes the same helpers as the Code node. It doesn't.
+
+**Unavailable in Code Tool**:
+- `$input`, `$json`, `$binary`
+- `$node["OtherNode"]`
+- `$helpers.httpRequest()`
+- `$jmespath()`
+- `this.getContext(...)`, `$getWorkflowStaticData(...)`
+- `$fromAI()`
+
+**Fix**:
+- Pure computation? Stay in Code Tool, use plain JS.
+- Need HTTP? Move to **HTTP Request Tool** (with `$fromAI()` in URL/body).
+- Need other-node data or credentials? Move to **Call Sub-workflow Tool (`toolWorkflow`)** — its sub-workflow has a full Code node sandbox.
+- Need state across calls? Not possible in Code Tool. Use a sub-workflow that reads/writes a Data Table, Redis, etc.
+
+---
+
+## Error 7: Python-specific — `"name 'query' is not defined"`
+
+**Cause**: in Python, the input variable is `_query` (underscore prefix), not `query`.
+
+```python
+# ❌ Broken
+result = process(query)
+
+# ✅ Fixed
+result = process(_query)
+```
+
+---
+
+## Error Prevention Checklist
+
+Before saving a Code Tool:
+
+- [ ] Tool **name** is snake_case, descriptive, and unique
+- [ ] **Description** tells the LLM when to call it, with an example if unstructured
+- [ ] **No `$fromAI()`** in the code body
+- [ ] **No `$input`, `$json`, `$helpers`** — not in this sandbox
+- [ ] Input read from `query` (JS) or `_query` (Python)
+- [ ] All code paths `return` a string (or a number that auto-converts)
+- [ ] If returning structured data, wrapped in `JSON.stringify(...)`
+- [ ] Wired to an AI Agent via `ai_tool` connection
+- [ ] For multi-field input: either example JSON in description, or `specifyInputSchema: true`
+
+---
+
+## Debugging tips
+
+- **Use the Execution view**, not just the test output. The agent's tool invocation and raw input/output are visible there — you can see exactly what `query` the LLM sent.
+- **Log inside the tool** by including fields in the returned JSON:
+  ```javascript
+  return JSON.stringify({ received_query: query, result: /* ... */ });
+  ```
+  The LLM sees the echo, and you can spot malformed input.
+- **Test the tool without the LLM** by temporarily turning the tool node into a standalone Code node with hard-coded `query`, running it manually, then swapping back.

data/skills/n8n-code-tool/INPUT_SCHEMA.md

@@ -0,0 +1,132 @@
+# Input Schema for Code Tool (Structured Mode)
+
+How to turn `@n8n/n8n-nodes-langchain.toolCode` into a **DynamicStructuredTool** so the LLM passes typed arguments instead of a free-form string.
+
+---
+
+## Why use a schema?
+
+Without a schema, the Code Tool is a LangChain `DynamicTool`:
+- LLM sees: "one string argument called query"
+- You must parse whatever the LLM sends
+- Typos, missing fields, wrong types are your problem at runtime
+
+With a schema, the Code Tool becomes a `DynamicStructuredTool`:
+- LLM sees: a typed object with named fields and descriptions
+- Runtime rejects invalid calls before your code runs
+- Numeric fields stay numeric (no more `Number(params.price)` for every field)
+- Tool calls are more reliable — most modern LLMs handle structured tools better than "here's a JSON string please"
+
+**Cost**: a little config to define the schema, and the node must be on a version that supports it.
+
+---
+
+## Enabling the schema
+
+Set `specifyInputSchema: true` on the `toolCode` parameters. Two schema-definition styles:
+
+### Style A: `fromJson` — paste a representative example (v≥1.3, recommended)
+
+The easiest. Give n8n an example JSON, and it infers the schema for you.
+
+```json
+{
+  "parameters": {
+    "name": "calculate_car_loan",
+    "description": "Computes monthly car-loan payment using an annuity formula with optional balloon.",
+    "language": "javaScript",
+    "specifyInputSchema": true,
+    "schemaType": "fromJson",
+    "jsonSchemaExample": "{\n  \"price\": 439900,\n  \"down_payment\": 87980,\n  \"interest_rate\": 6.95,\n  \"months\": 36,\n  \"residual_percent\": 50,\n  \"setup_fee\": 695,\n  \"monthly_admin_fee\": 59\n}",
+    "jsCode": "// query is now a validated OBJECT, not a string\nconst { price, down_payment, interest_rate, months, residual_percent, setup_fee = 0, monthly_admin_fee = 0 } = query;\n\nconst principal = price - down_payment;\nconst residual  = price * (residual_percent / 100);\nconst r = interest_rate / 100 / 12;\nconst growth = Math.pow(1 + r, months);\nconst base = r === 0\n  ? (principal - residual) / months\n  : (principal - residual / growth) * r / (1 - 1 / growth);\nconst monthly_payment = base + monthly_admin_fee;\n\nreturn JSON.stringify({\n  monthly_payment_sek: Math.round(monthly_payment),\n  loan_amount: Math.round(principal)\n});"
+  },
+  "type": "@n8n/n8n-nodes-langchain.toolCode",
+  "typeVersion": 1.3,
+  "name": "calculate_car_loan"
+}
+```
+
+**How it works**: n8n looks at the example, infers `{price: number, down_payment: number, ...}`, and generates a JSON Schema. The LLM sees that schema and passes a validated object.
+
+### Style B: `manual` — write the JSON Schema yourself
+
+Use when you need descriptions per field, enums, min/max constraints, or optional fields.
+
+```json
+{
+  "parameters": {
+    "name": "calculate_car_loan",
+    "description": "Computes monthly car-loan payment.",
+    "language": "javaScript",
+    "specifyInputSchema": true,
+    "schemaType": "manual",
+    "inputSchema": "{\n  \"type\": \"object\",\n  \"required\": [\"price\", \"down_payment\", \"interest_rate\", \"months\", \"residual_percent\"],\n  \"properties\": {\n    \"price\": { \"type\": \"number\", \"description\": \"Car price in SEK\" },\n    \"down_payment\": { \"type\": \"number\", \"description\": \"Down payment in SEK\" },\n    \"interest_rate\": { \"type\": \"number\", \"description\": \"Annual nominal rate in percent, e.g. 6.95\" },\n    \"months\": { \"type\": \"integer\", \"minimum\": 1, \"description\": \"Loan term in months\" },\n    \"residual_percent\": { \"type\": \"number\", \"minimum\": 0, \"maximum\": 99, \"description\": \"Balloon as % of price\" },\n    \"setup_fee\": { \"type\": \"number\", \"default\": 0 },\n    \"monthly_admin_fee\": { \"type\": \"number\", \"default\": 0 }\n  }\n}",
+    "jsCode": "const { price, down_payment, interest_rate, months, residual_percent, setup_fee = 0, monthly_admin_fee = 0 } = query;\n// ... same computation as above ...\nreturn JSON.stringify({ monthly_payment_sek: /*...*/ });"
+  },
+  "type": "@n8n/n8n-nodes-langchain.toolCode",
+  "typeVersion": 1.3,
+  "name": "calculate_car_loan"
+}
+```
+
+**When `manual` is worth it**:
+- You want per-field `description` strings (the LLM reads these)
+- You need `enum` values (e.g. currency: `["SEK", "EUR", "USD"]`)
+- You need numeric constraints (`minimum`, `maximum`)
+- You want to mark fields as optional cleanly
+
+---
+
+## How `query` behaves with a schema
+
+Source of truth from the ToolCode sandbox:
+
+```typescript
+const sandbox = new JsTaskRunnerSandbox(workflowMode, ctx, undefined, { query });
+```
+
+The sandbox always receives `{ query }`. The difference is what `query` holds:
+
+| Mode | Type of `query` | How to use |
+|---|---|---|
+| No schema | `string` | `JSON.parse(query)` if you want structure |
+| With schema | `object` (validated) | Destructure: `const { price, months } = query;` |
+
+In Python, the same applies — `_query` is a string without schema, a dict with schema.
+
+---
+
+## Schema version compatibility
+
+- `specifyInputSchema` and `schemaType: "manual"` with `inputSchema`: available in v1.2
+- `schemaType: "fromJson"` with `jsonSchemaExample`: requires v≥1.3
+
+Set `typeVersion: 1.3` on the node if you want `fromJson`. Older installs should use `manual`.
+
+---
+
+## Picking a pattern
+
+```
+Does your tool need more than one input field?
+├─ No (just a URL, question, text blob)
+│  └─ Unstructured — skip the schema
+├─ Yes, and fields are all typed (numbers, bools, enums)
+│  └─ Structured with fromJson (easiest)
+├─ Yes, and you need constraints or rich descriptions
+│  └─ Structured with manual
+└─ Yes, and fields are complex / reusable across agents
+   └─ Use toolWorkflow (sub-workflow tool) instead of toolCode
+```
+
+---
+
+## Gotcha: schema must be valid JSON
+
+`jsonSchemaExample` and `inputSchema` are **strings containing JSON**, not objects. Watch the escaping when you paste them into workflow JSON. If the node won't save or the LLM doesn't see the fields, validate the JSON separately first.
+
+---
+
+## Gotcha: schema changes don't retroactively fix old agent runs
+
+If an agent was already started with an unstructured tool and you flip it to structured, the agent's system prompt may still reflect the old contract until it's reloaded. Force a re-run / re-open the agent node after changing schema settings.

data/skills/n8n-code-tool/README.md

@@ -0,0 +1,192 @@
+# n8n Code Tool Skill
+
+Expert guidance for writing code inside the n8n **Custom Code Tool** (`@n8n/n8n-nodes-langchain.toolCode`) — the AI-agent-callable tool, not the regular Code node.
+
+---
+
+## ⚠️ This is NOT the Code node
+
+Same editor UI, completely different contract:
+
+| | Code **node** | Code **Tool** |
+|---|---|---|
+| Node type | `n8n-nodes-base.code` | `@n8n/n8n-nodes-langchain.toolCode` |
+| Invoked by | Previous node | AI Agent (LangChain) |
+| Input | `$input.all()` | `query` variable |
+| Return | `[{json: {...}}]` | **A string** |
+| `$fromAI()` | N/A | **Not available** |
+| `$helpers` | Via `this.helpers` (bare `$helpers` global is undefined) | Not exposed |
+
+If you carry over Code-node habits, it fails with cryptic errors. This skill teaches the Code Tool's actual contract.
+
+---
+
+## What This Skill Teaches
+
+### Core Concepts
+1. **Return a string** — `JSON.stringify()` for structured output
+2. **Input lives in `query`** (JS) or `_query` (Python)
+3. **No `$fromAI()`** — doesn't exist in this sandbox
+4. **Unstructured vs structured input** — when to add a JSON Schema
+5. **Tool name and description** are the LLM-facing contract, not docs
+
+### Top 5 Errors This Skill Prevents
+1. `"Cannot assign to read only property 'name'..."` — `$fromAI()` misuse
+2. `"Wrong output type returned"` — returning `[{json:{...}}]`
+3. `"The response property should be a string, but it is an object"` — unstringified object
+4. AI never calls the tool — generic name or vague description
+5. LLM sends malformed `query` — no schema, no example
+
+---
+
+## Skill Activation
+
+Activates when you:
+- Build a Code Tool attached to an AI Agent
+- Get `"Wrong output type returned"` or `"No execution data available"` errors
+- Decide between unstructured `query` parsing and `specifyInputSchema`
+- Wonder why `$fromAI()` or `$helpers.httpRequest()` don't work
+- Choose between Code Tool, HTTP Request Tool, and `toolWorkflow`
+
+**Example queries**:
+- "Why is my Code Tool throwing 'Wrong output type returned'?"
+- "How do I pass multiple parameters to a Code Tool?"
+- "Does `$fromAI` work in `@n8n/n8n-nodes-langchain.toolCode`?"
+- "What's the difference between Code Tool and the Code node?"
+- "How do I use `specifyInputSchema` for structured tool input?"
+
+---
+
+## File Structure
+
+### SKILL.md
+Main skill content — loaded when the skill activates.
+- Why Code Tool ≠ Code node (the cheat-sheet table)
+- Quick-start JS and Python examples
+- The two input modes: unstructured `query` vs structured schema
+- Return-format rules
+- Tool name and description as prompt engineering
+- What's NOT in the sandbox (`$input`, `$helpers`, `$fromAI`, state)
+- When to choose Code Tool vs `toolWorkflow` vs HTTP Request Tool
+- Complete working example
+- Quick-reference checklist
+
+### INPUT_SCHEMA.md
+Structured-input deep dive — `specifyInputSchema: true`.
+- Why schemas help (`DynamicStructuredTool` vs `DynamicTool`)
+- Style A: `fromJson` (infer schema from an example, v≥1.3)
+- Style B: `manual` (write the JSON Schema yourself)
+- How `query` behaves with vs without schema
+- Version compatibility
+- Decision tree: when to stay unstructured, go structured, or jump to `toolWorkflow`
+
+### ERROR_PATTERNS.md
+Full error catalog with exact strings, causes, and fixes.
+- The three signature runtime errors
+- AI-never-calls-tool diagnostic
+- LLM-sends-malformed-query fixes
+- Sandbox-missing-helper error
+- Python-specific `query` vs `_query`
+- Debugging tips
+
+---
+
+## Quick Reference
+
+### Minimal JavaScript Code Tool
+```javascript
+return `You asked: ${query}`;
+```
+
+### Minimal Python Code Tool
+```python
+return f"You asked: {_query}"
+```
+
+### Return a structured result
+```javascript
+return JSON.stringify({
+  result: 42,
+  currency: "SEK"
+});
+```
+
+### Parse a JSON-string input (unstructured mode)
+```javascript
+const params = typeof query === 'string' ? JSON.parse(query) : query;
+const price = Number(params.price);
+```
+
+### Use a typed input (structured mode, `specifyInputSchema: true`)
+```javascript
+const { price, months, residual_percent } = query;
+```
+
+### Tool name rules
+- `[A-Za-z0-9_]+` — snake_case, no spaces/hyphens/emoji
+- Verb-y and domain-specific: `calculate_car_loan`, not `Code Tool`
+
+---
+
+## Integration with Other Skills
+
+**n8n-code-javascript** (Code *node*): most JS patterns transfer, but **I/O is different** — don't copy `$input.all()` or `[{json:{...}}]` return.
+
+**n8n-node-configuration**: `specifyInputSchema` is a typical conditional-field pattern — use `get_node({detail: "standard"})` on `toolCode` to explore.
+
+**n8n-workflow-patterns**: Code Tool sits inside the AI-Agent-with-tools pattern. Usually alongside HTTP Request Tool, `toolWorkflow`, and memory.
+
+**n8n-validation-expert**: the three signature errors have exact strings that map cleanly to fixes — if you see them in validation output, the fix is mechanical.
+
+---
+
+## When to Use Code Tool vs Alternatives
+
+| Need | Use |
+|---|---|
+| Pure computation (math, parsing, formatting) | **Code Tool** |
+| Multiple typed params with `$fromAI()` | **`toolWorkflow`** (sub-workflow tool) |
+| Single API call | **HTTP Request Tool** |
+| Access to `this.helpers`, credentials, other nodes | **`toolWorkflow`** |
+| Persistent state across calls | **`toolWorkflow`** with Data Table / Redis |
+| Reusable logic across multiple agents | **`toolWorkflow`** |
+
+**Rule of thumb**: if you catch yourself reaching for `$fromAI()`, you want `toolWorkflow` instead.
+
+---
+
+## Success Metrics
+
+After using this skill, you should be able to:
+
+- [ ] Distinguish Code Tool from Code node by node type and contract
+- [ ] Return a string (or `JSON.stringify()` result) — never a bare object or items array
+- [ ] Read input from `query`/`_query` without reaching for `$fromAI`
+- [ ] Decide between unstructured (JSON-in-string) and structured (`specifyInputSchema`) patterns
+- [ ] Write tool names/descriptions that the LLM will actually invoke
+- [ ] Diagnose the three signature errors by message alone
+- [ ] Pick the right tool type (Code Tool vs `toolWorkflow` vs HTTP Request Tool)
+
+---
+
+## Sources
+
+Authoritative facts in this skill come from:
+- [ToolCode source](https://github.com/n8n-io/n8n/blob/master/packages/%40n8n/nodes-langchain/nodes/tools/ToolCode/ToolCode.node.ts) — sandbox contract, `query` binding, return handling
+- [n8n Custom Code Tool docs](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolcode/)
+- [LangChain tool docs](https://js.langchain.com/docs/modules/agents/tools/) — `DynamicTool` / `DynamicStructuredTool` semantics
+
+---
+
+## Version
+
+**Version**: 1.0.0
+**Compatibility**: n8n with `@n8n/n8n-nodes-langchain.toolCode` v1.1+; structured `fromJson` requires v≥1.3.
+
+---
+
+## Credits
+
+Part of the n8n-skills project.
+
+**Remember**: Code Tool is a LangChain tool wearing a Code-node UI. Contract is **string in, string out**. Everything else follows from that.

data/skills/n8n-code-tool/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: n8n-code-tool
+description: Write JavaScript or Python for the n8n Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) — the AI-agent-callable tool, NOT the workflow Code node. Use when building a Code Tool attached to an AI Agent, writing code that an LLM will invoke, parsing the `query` input, returning a string result, defining an input schema for structured arguments (specifyInputSchema, jsonSchemaExample, DynamicStructuredTool), or troubleshooting errors like "Wrong output type returned", "No execution data available", "The response property should be a string, but it is an object", "Cannot assign to read only property 'name'", or an AI agent that refuses to call the tool. Covers the critical differences between Code node and Code Tool: return format (string vs `[{json:{...}}]`), unavailability of `$fromAI`/`$input`/`$helpers` in the Code Tool sandbox, naming rules for AI invocation, and when to use `toolWorkflow`/HTTP Request Tool instead.
+---
+
+# n8n Custom Code Tool
+
+Expert guidance for writing code inside `@n8n/n8n-nodes-langchain.toolCode` — the tool an AI Agent can invoke, **not** the regular workflow Code node.
+
+---
+
+## ⚠️ This is NOT the Code node
+
+The Custom Code Tool looks like a Code node in the editor — same JavaScript editor, similar layout — but it is a **completely different node** from a different package with a **different runtime contract**.
+
+| | Code node | Custom Code Tool |
+|---|---|---|
+| **Node type** | `n8n-nodes-base.code` | `@n8n/n8n-nodes-langchain.toolCode` |
+| **Package** | `n8n-nodes-base` | `@n8n/n8n-nodes-langchain` |
+| **Invoked by** | Previous node (workflow flow) | AI Agent (LangChain) |
+| **Input** | `$input.all()` — item stream | `query` — string or object from LLM |
+| **Return** | `[{json: {...}}]` (items array) | **A string** |
+| **`$fromAI()`** | N/A | **Not available** (see Errors) |
+| **HTTP helper** | `this.helpers.httpRequest` (auth helpers blocked) | Not exposed to the tool sandbox |
+| **State** | Per-run execution data | No `getContext`, no `$getWorkflowStaticData` |
+
+**If you treat it like a Code node, it fails.** The rest of this skill covers the Code Tool's actual contract.
+
+---
+
+## Quick Start
+
+### Minimal JavaScript Code Tool
+
+```javascript
+// `query` is whatever the AI sent (a string by default)
+return `You asked: ${query}`;
+```
+
+### Minimal Python Code Tool
+
+```python
+# `_query` is whatever the AI sent (a string by default)
+return f"You asked: {_query}"
+```
+
+### Essential Rules
+
+1. **Return a string.** Numbers are auto-converted. Anything else throws `"The response property should be a string, but it is an object"`.
+2. **Input variable is fixed**: `query` (JS), `_query` (Python). You cannot rename it.
+3. **Do NOT use `$fromAI()`** inside the Code Tool sandbox — it throws `"No execution data available"`.
+4. **Do NOT use `[{json: {...}}]`** return format — that's for Code nodes. Throws `"Wrong output type returned"`.
+5. **Use a descriptive tool name** (letters/numbers/underscores, v1.1+). The agent calls the tool by its name.
+6. **Write a precise description** — the LLM decides whether to invoke the tool based on it.
+
+---
+
+## The Two Input Modes
+
+The Code Tool has two input shapes, controlled by `specifyInputSchema`:
+
+### Mode 1: Unstructured (default, `specifyInputSchema: false`)
+
+The AI passes **a single string** as `query`. If you need multiple fields, the AI has to stuff them into that one string and you parse them out. In practice, LLMs will happily pass a JSON string if your description tells them to.
+
+```javascript
+// Parse a JSON string the AI sent
+let params;
+try {
+  params = typeof query === 'string' ? JSON.parse(query) : query;
+} catch (e) {
+  throw new Error('Expected a JSON object. Parser said: ' + e.message);
+}
+const price = Number(params.price);
+const months = Number(params.months);
+// ...
+return JSON.stringify({ monthly_payment: /* ... */ });
+```
+
+**Pros**: simplest to set up, one field to describe.
+**Cons**: no schema validation — if the LLM forgets a field, the tool throws at runtime.
+
+**Best for**: quick prototypes, tools with one natural input (a question, a URL, a text blob).
+
+### Mode 2: Structured (`specifyInputSchema: true`)
+
+The tool becomes a LangChain `DynamicStructuredTool`. The LLM sees a typed argument schema and passes a **validated object** as `query`. You access fields directly.
+
+```javascript
+// query is now an object matching your schema
+const price = query.price;
+const months = query.months;
+const residual_percent = query.residual_percent;
+
+const monthly = computeAnnuity(price, months, residual_percent);
+return JSON.stringify({ monthly_payment: monthly });
+```
+
+Schema is defined via either:
+- `schemaType: "fromJson"` + `jsonSchemaExample` (n8n v≥1.3) — paste an example JSON, n8n infers the schema
+- `schemaType: "manual"` + `inputSchema` — write a full JSON Schema yourself
+
+**Pros**: LLM gets type hints, invalid calls rejected before your code runs, cleaner code.
+**Cons**: a little more setup; requires n8n version with schema support.
+
+**Best for**: production tools with multiple typed parameters (calculators, API wrappers, anything with numeric fields the LLM tends to stringify).
+
+**See**: [INPUT_SCHEMA.md](INPUT_SCHEMA.md) for complete schema setup.
+
+---
+
+## Return Format
+
+**The return value must be a string.** The LLM reads it as the tool's observation.
+
+```javascript
+// ✅ String
+return "42";
+
+// ✅ Number (auto-converted to string by n8n)
+return 42;
+
+// ✅ JSON-encoded structured result (recommended for rich output)
+return JSON.stringify({ result: 42, currency: "SEK" });
+
+// ❌ Raw object → "The response property should be a string, but it is an object"
+return { result: 42 };
+
+// ❌ Workflow item format → "Wrong output type returned"
+return [{ json: { result: 42 } }];
+
+// ❌ Array → "The response property should be a string, but it is an object"
+return [1, 2, 3];
+```
+
+### Best practice: JSON-stringify structured results
+
+When your tool has more than a trivial scalar output, return a JSON string:
+
+```javascript
+return JSON.stringify({
+  monthly_payment_sek: 5405,
+  loan_amount: 351920,
+  total_cost_of_credit: 63295
+});
+```
+
+The LLM parses JSON reliably and can pick the fields it needs to present to the user.
+
+### Error handling: the agent reads your failures
+
+Errors don't just stop the workflow — they go back to the LLM, which usually corrects its call and retries. Use that:
+
+```javascript
+// Option A: throw — n8n surfaces the message to the agent
+if (!isFinite(price)) throw new Error('price must be a number, e.g. 439900');
+
+// Option B: return an error string — agent reads it like any tool result
+if (!isFinite(price)) return JSON.stringify({ error: 'price must be a number, e.g. 439900' });
+```
+
+Either way, write error messages **for the LLM**: state what was wrong and what a valid call looks like. A bare `throw new Error('invalid input')` wastes the retry; an instructive message usually fixes the next call.
+
+---
+
+## Tool Name and Description
+
+These fields are NOT documentation — they are the **tool contract the LLM sees**. Treat them as prompt engineering.
+
+### Name
+- Must match `[A-Za-z0-9_]+` (v1.1+). No spaces, no hyphens, no emoji.
+- Use a verb-y descriptive name: `calculate_car_loan`, `get_weather`, `search_orders`.
+- The agent calls the tool by this name. `Code Tool` (the default) is useless — the agent won't know when to call it.
+
+### Description
+- Explain **when** to use it and **what** to send.
+- If unstructured mode, **include an example of the JSON string** the LLM should send.
+- If structured mode, the schema speaks for itself — just describe purpose.
+
+**Unstructured example (JSON-in-string pattern):**
+```
+Deterministiskt beräknar månadskostnad för billån. Anropa med EN JSON-sträng:
+{"price":439900,"down_payment":87980,"interest_rate":6.95,"months":36,"residual_percent":50}
+Fält: price (SEK), down_payment (SEK), interest_rate (% per år), months, residual_percent (0-99).
+```
+
+**Structured example (schema-defined):**
+```
+Deterministically computes the monthly car-loan payment given price, down payment, 
+annual interest rate, term, and residual percent. Use whenever the user asks for 
+monthly cost, total credit cost, or loan breakdown.
+```
+
+---
+
+## Top Errors and Fixes
+
+### Error 1: `"There was an error: 'Cannot assign to read only property \"name\" of object: Error: No execution data available'"`
+
+**Cause**: you called `$fromAI()` inside the Code Tool sandbox.
+
+**Fix**: `$fromAI()` is a helper for **other** tool-enabled nodes (HTTP Request Tool, SendGrid Tool, `toolWorkflow`, etc.) — it's not exposed inside `toolCode`. Read the AI's input from `query` directly (or use `specifyInputSchema` for structured fields).
+
+### Error 2: `"Wrong output type returned"`
+
+**Cause**: you returned a workflow-style array like `[{ json: { ... } }]`. That's the Code **node** contract, not the Code **Tool** contract.
+
+**Fix**: return a string. For structured data, `return JSON.stringify(output)`.
+
+### Error 3: `"The response property should be a string, but it is an object"`
+
+**Cause**: you returned a plain object or array.
+
+**Fix**: `JSON.stringify()` the result, or coerce to a string.
+
+### Error 4: AI never calls the tool
+
+**Cause**: tool name is generic (`Code Tool`, `My Tool`) or description doesn't clearly state when to use it.
+
+**Fix**: rename to a verb-y name (`calculate_car_loan`), and rewrite the description to explicitly state the trigger conditions (e.g. "Use this whenever the user asks about monthly cost").
+
+### Error 5: AI sends garbage into `query`
+
+**Cause**: unstructured tool with a vague description. The LLM guesses at the format.
+
+**Fix**: either (a) include a concrete JSON example in the description, or (b) switch to `specifyInputSchema: true` so the LLM gets a typed schema.
+
+**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for full catalog with reproductions.
+
+---
+
+## What's NOT Available in the Sandbox
+
+The Code Tool sandbox is **narrower** than the Code node sandbox. Don't assume helpers carry over:
+
+| Helper | Code node | Code Tool |
+|---|---|---|
+| `$input.all()`, `$input.first()`, `$input.item` | ✅ | ❌ |
+| `$node["NodeName"]` | ✅ | ❌ |
+| `$json`, `$binary` | ✅ | ❌ |
+| `$fromAI()` | ❌ | ❌ (despite sitting next to an AI agent) |
+| `this.helpers.httpRequest()` | ✅ | ❌ |
+| `DateTime` (Luxon) | ✅ | ✅ (standard in JS sandbox) |
+| `$jmespath()` | ✅ | ❌ |
+| `this.getContext(...)` | ✅ | ❌ |
+| `$getWorkflowStaticData(...)` | ✅ | ❌ |
+
+**Implication**: the Code Tool is for **pure computation**. If you need an HTTP call, an API lookup, or cross-invocation state, use a different tool node:
+- HTTP Request Tool for external API calls
+- `toolWorkflow` (Call Sub-workflow Tool) for multi-step logic with access to the full Code node sandbox
+- MCP / database tools for persistent state
+
+---
+
+## When to Use Code Tool vs Alternatives
+
+Use **Code Tool** when:
+- ✅ Pure deterministic computation (math, parsing, formatting, validation)
+- ✅ Lightweight transformations the LLM shouldn't do itself (precision math, regex)
+- ✅ You want the code inline in the workflow, not in a separate sub-workflow
+
+Use **`toolWorkflow`** (Call Sub-workflow Tool) when:
+- ✅ You need multiple parameters with clean `$fromAI()` typing
+- ✅ You need access to `this.helpers`, credentials, or other nodes
+- ✅ Logic is reusable across agents
+- ✅ You want structured typed inputs WITHOUT writing a JSON Schema
+
+Use **HTTP Request Tool** when:
+- ✅ The tool is fundamentally a single API call
+- ✅ You want per-parameter `$fromAI()` bindings in URL/query/body
+
+**Rule of thumb**: if you find yourself wanting `$fromAI()`, you probably want `toolWorkflow` instead of `toolCode`.
+
+---
+
+## Complete Working Example
+
+A production calculator tool (unstructured, JSON-in-string pattern):
+
+```json
+{
+  "parameters": {
+    "name": "calculate_car_loan",
+    "description": "Computes monthly car-loan payment using an annuity formula with residual/balloon. Call with a single JSON string. Example: {\"price\":439900,\"down_payment\":87980,\"interest_rate\":6.95,\"months\":36,\"residual_percent\":50,\"setup_fee\":695,\"monthly_admin_fee\":59}. Required: price, down_payment, interest_rate, months, residual_percent. Optional: setup_fee, monthly_admin_fee (default 0).",
+    "language": "javaScript",
+    "jsCode": "let params;\ntry {\n  params = typeof query === 'string' ? JSON.parse(query) : query;\n} catch (e) {\n  throw new Error('Invalid JSON: ' + e.message);\n}\n\nconst price           = Number(params.price);\nconst down_payment    = Number(params.down_payment);\nconst interest_rate   = Number(params.interest_rate);\nconst months          = Number(params.months);\nconst residual_percent= Number(params.residual_percent);\nconst setup_fee       = Number(params.setup_fee ?? 0) || 0;\nconst monthly_admin_fee = Number(params.monthly_admin_fee ?? 0) || 0;\n\nif (!isFinite(price) || price <= 0) throw new Error('price must be > 0');\nif (down_payment < 0 || down_payment >= price) throw new Error('down_payment must be in [0, price)');\n\nconst principal = price - down_payment;\nconst residual  = price * (residual_percent / 100);\nconst r = interest_rate / 100 / 12;\nconst growth = Math.pow(1 + r, months);\nconst base = r === 0\n  ? (principal - residual) / months\n  : (principal - residual / growth) * r / (1 - 1 / growth);\nconst monthly_payment = base + monthly_admin_fee;\n\nreturn JSON.stringify({\n  monthly_payment_sek: Math.round(monthly_payment),\n  loan_amount: Math.round(principal),\n  residual_value_sek: Math.round(residual),\n  total_cost_of_credit: Math.round(monthly_payment * months + residual + setup_fee - principal)\n});"
+  },
+  "type": "@n8n/n8n-nodes-langchain.toolCode",
+  "typeVersion": 1.3,
+  "name": "calculate_car_loan"
+}
+```
+
+Wire it into an AI Agent via the `ai_tool` connection type.
+
+---
+
+## Integration with Other Skills
+
+**n8n-code-javascript**: the Code **node** skill. Most JavaScript patterns (arrays, map/filter, DateTime) transfer — but I/O contract is different. Don't copy data-access code.
+
+**n8n-node-configuration**: `specifyInputSchema` is a classic displayOptions-driven conditional field. Use `get_node({detail: "standard"})` on `@n8n/n8n-nodes-langchain.toolCode` to see schema-related properties.
+
+**n8n-workflow-patterns**: Code Tool sits inside the "AI Agent with tools" pattern. An agent typically has several tools; Code Tool is the "local compute" option.
+
+**n8n-validation-expert**: the three Code Tool errors listed above have clear signatures — if validation surfaces "Wrong output type returned", you know to switch from array-of-items to a string.
+
+---
+
+## Quick Reference Checklist
+
+Before deploying a Code Tool:
+
+- [ ] **Node type** is `@n8n/n8n-nodes-langchain.toolCode` (not `nodes-base.code`)
+- [ ] **Tool name** is descriptive, verb-y, snake_case (e.g. `calculate_car_loan`)
+- [ ] **Description** states when to use the tool and (if unstructured) shows a JSON example
+- [ ] **Input** read from `query` (JS) or `_query` (Python)
+- [ ] **No `$fromAI()`** in the code body
+- [ ] **No `$input` / `$json` / `$helpers`** — those aren't in the sandbox
+- [ ] **Return** is a string (use `JSON.stringify()` for structured output)
+- [ ] **Wired** into an AI Agent via `ai_tool` connection
+- [ ] **Tested** with the exact kind of input the LLM will send (JSON in a string, or schema-validated object)
+
+---
+
+## Additional Resources
+
+- [INPUT_SCHEMA.md](INPUT_SCHEMA.md) — structured input (DynamicStructuredTool) in depth
+- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) — full error catalog with causes and fixes
+
+### Official sources
+- [n8n Custom Code Tool docs](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolcode/)
+- [ToolCode source](https://github.com/n8n-io/n8n/blob/master/packages/%40n8n/nodes-langchain/nodes/tools/ToolCode/ToolCode.node.ts) — the sandbox contract
+- [LangChain tool docs](https://js.langchain.com/docs/modules/agents/tools/) — DynamicTool / DynamicStructuredTool
+
+---
+
+**Remember**: the Code Tool is a LangChain tool wearing a Code-node UI. Contract is: **string in, string out**. Everything else follows from that.

data/skills/n8n-error-handling/API_WORKFLOWS.md

@@ -0,0 +1,256 @@
+# API Workflows
+
+When a workflow is an HTTP API — a Webhook trigger that ends at a `Respond to Webhook` — error handling stops being optional. The caller is a machine waiting on a response, and the failure modes are unforgiving: a hanging branch becomes a timeout, a wrong status code breaks the caller's error handling, a leaked stack trace becomes a security finding.
+
+This file covers wiring that pattern so it behaves under failure, not just on the happy path. For the per-node mechanics, see **NODE_ERROR_OUTPUTS.md**; for body conventions and status codes, **RESPONSE_SHAPES.md**.
+
+---
+
+## The shape
+
+```
+Webhook (responseMode: "responseNode")
+  → validate input ──valid──→ process ──→ Respond (200, success body)
+  │                └─invalid─→ Respond (400, validation_error body)
+  └── (any fallible node's error output, sourceIndex 1)
+            → Respond (5xx, structured error body)
+            → optional: Log full error privately / notify
+```
+
+The non-negotiable: **every path ends at a Respond node.** Success, validation failure, execution failure — all of them. A path that doesn't reach a Respond is a hanging branch, and a hanging branch is a caller timeout.
+
+Set `responseMode: "responseNode"` on the Webhook trigger — without it the trigger acknowledges immediately (`onReceived`) and the caller never sees your computed response. (See **n8n-node-configuration** NODE_FAMILY_GOTCHAS.md for the Webhook/Respond traps.)
+
+---
+
+## Wiring every fallible node
+
+For each fallible node (HTTP, DB, third-party, file op), the two-step setup from NODE_ERROR_OUTPUTS.md:
+
+1. `onError: "continueErrorOutput"` on the node.
+2. `addConnection` from its `sourceIndex: 1` to your error Respond (directly, or via a logger).
+
+A two-node processing chain, both fallible, both routing to one responder:
+
+```javascript
+// Turn on error outputs
+{ type: "updateNode", nodeName: "Fetch User",    changes: { onError: "continueErrorOutput" } }
+{ type: "updateNode", nodeName: "Call External", changes: { onError: "continueErrorOutput" } }
+
+// Success path
+{ type: "addConnection", source: "Webhook",      target: "Fetch User",      sourceIndex: 0 }
+{ type: "addConnection", source: "Fetch User",   target: "Call External",   sourceIndex: 0 }
+{ type: "addConnection", source: "Call External",target: "Respond Success", sourceIndex: 0 }
+
+// Error paths — both fan in to one responder
+{ type: "addConnection", source: "Fetch User",   target: "Respond Error",   sourceIndex: 1 }
+{ type: "addConnection", source: "Call External",target: "Respond Error",   sourceIndex: 1 }
+```
+
+Three things to notice:
+
+1. **One `Respond Error` for many sources.** Fan-in keeps it readable.
+2. **Both nodes have `onError` set.** Miss it on either and that node's failure halts the workflow instead of routing — and the caller times out.
+3. **If you surface the error message in the body, sanitize it.** See "Don't leak internals" below.
+
+The error Respond node, in JSON:
+
+```json
+{
+  "type": "n8n-nodes-base.respondToWebhook",
+  "name": "Respond Error",
+  "parameters": {
+    "respondWith": "json",
+    "responseCode": 502,
+    "responseBody": "={{ JSON.stringify({ error: 'upstream_error', message: 'External service failed' }) }}",
+    "options": {
+      "responseHeaders": { "entries": [{ "name": "Content-Type", "value": "application/json" }] }
+    }
+  }
+}
+```
+
+Always set `Content-Type: application/json` explicitly — the default depends on the body shape and isn't reliable.
+
+---
+
+## 4xx lives upstream, 5xx comes out of error outputs
+
+This is the structural rule that keeps an API honest:
+
+- **Validation / auth / not-found failures are *expected outcomes with a known response*.** They aren't nodes crashing. Check them **before** the work, with IF/Switch + a dedicated Respond, and return the right 4xx directly. Do not route them through error outputs.
+- **Execution failures (a node actually throwing) are *unexpected*.** Those come out of error outputs as 5xx.
+
+A real API usually needs several upstream checks, each its own IF/Switch + Respond, *before* the processing stage:
+
+```
+Webhook
+  → Auth present & valid?      ── no ──→ Respond 401 unauthorized
+  → Input valid?               ── no ──→ Respond 400 validation_error (with details)
+  → Caller allowed this op?    ── no ──→ Respond 403 forbidden
+  → Target resource exists?    ── no ──→ Respond 404 not_found
+  → Processing stage (HTTP / DB / etc.) ←── this is where 5xx errors originate
+```
+
+That's not over-engineering — it's the difference between the caller getting an actionable `validation_error` and getting a generic 500 they can't act on.
+
+---
+
+## Input validation: the Set-node schema validator
+
+For structured input validation, don't hand-roll an IF chain per field. Run the whole check as an **IIFE inside a single Set node**, branch on its result with one IF, and respond. One node does the work, and it's far faster than a recursive validator running in a Code node + sub-workflow (the sub-workflow invocation dominates that cost).
+
+The validator node assigns one object field, `result`, computed by the expression below. The expression is **schema-specific** — edit the `REQUIRED_SCHEMA` constant and the per-field checks for your endpoint. The *output keys* are a contract the Respond node consumes — don't rename them.
+
+```json
+{
+  "type": "n8n-nodes-base.set",
+  "name": "Validate Schema",
+  "parameters": {
+    "mode": "manual",
+    "assignments": {
+      "assignments": [
+        {
+          "id": "a1",
+          "name": "result",
+          "type": "object",
+          "value": "={{ (() => { const body = $json.body || {}; const errors = []; const REQUIRED_SCHEMA = { type: 'object', properties: { name: { type: 'string', minLength: 1, description: 'Customer full name' }, email: { type: 'string', pattern: '^\\\\S+@\\\\S+\\\\.\\\\S+$', description: 'Contact email address' }, plan: { type: 'string', enum: ['starter','pro','enterprise'], description: 'Subscription plan' }, seat_count: { type: 'integer', minimum: 1, maximum: 500, description: 'Number of licensed seats' } }, required: ['name','email','plan','seat_count'], additionalProperties: false }; if (!('name' in body)) errors.push({ p: 'name', m: 'Missing required field \"name\"', d: 'Customer full name' }); else if (typeof body.name !== 'string') errors.push({ p: 'name', m: 'Expected type \"string\"', d: 'Customer full name' }); if (!('email' in body)) errors.push({ p: 'email', m: 'Missing required field \"email\"', d: 'Contact email address' }); else if (!/^\\S+@\\S+\\.\\S+$/.test(body.email)) errors.push({ p: 'email', m: '\"' + body.email + '\" is not valid', d: 'Contact email address' }); if (!('plan' in body)) errors.push({ p: 'plan', m: 'Missing required field \"plan\"', d: 'Subscription plan' }); else if (['starter','pro','enterprise'].indexOf(body.plan) === -1) errors.push({ p: 'plan', m: '\"' + body.plan + '\" is not allowed. Must be one of: starter, pro, enterprise', d: 'Subscription plan' }); if (!('seat_count' in body)) errors.push({ p: 'seat_count', m: 'Missing required field \"seat_count\"', d: 'Number of licensed seats' }); else { const v = body.seat_count; if (typeof v !== 'number' || !Number.isFinite(v) || Math.floor(v) !== v) errors.push({ p: 'seat_count', m: 'Expected type \"integer\"', d: 'Number of licensed seats' }); else if (v < 1 || v > 500) errors.push({ p: 'seat_count', m: 'Must be between 1 and 500', d: 'Number of licensed seats' }); } if (errors.length === 0) return { valid: true, validationError: null }; const lines = errors.map(e => '• ' + e.p + ': ' + e.m + (e.d ? ' - ' + e.d : '')); const details = {}; errors.forEach(e => { if (!(e.p in details)) details[e.p] = e.m; }); return { valid: false, validationError: 'Validation failed (' + errors.length + ' issue' + (errors.length > 1 ? 's' : '') + '):\\n' + lines.join('\\n'), details: details, requiredSchema: REQUIRED_SCHEMA }; })() }}"
+        }
+      ]
+    },
+    "options": {}
+  }
+}
+```
+
+Then an IF on `={{ $json.result.valid }}` (boolean → true) routes to your business logic (200) on the true branch, and to a 400 Respond on the false branch:
+
+```json
+{
+  "type": "n8n-nodes-base.respondToWebhook",
+  "name": "Respond 400",
+  "parameters": {
+    "respondWith": "json",
+    "responseCode": 400,
+    "responseBody": "={{ JSON.stringify({ error: 'validation_error', message: $json.result.validationError, details: $json.result.details, request_schema: $json.result.requiredSchema }) }}"
+  }
+}
+```
+
+### The procedure for adapting it
+
+1. **Lift the three-node shape** (Webhook → Validate Schema → IF → success/400 Respond) into your endpoint. Don't reinvent the graph.
+2. **Edit `REQUIRED_SCHEMA` and the per-field checks** for your input. The pattern per field is mechanical: presence check → type check → constraint check → `errors.push(...)`.
+3. **Leave the output keys alone.** The IIFE returns `{ valid, validationError, details, requiredSchema }` and the Respond node reads exactly those names. Rename one and the response body breaks.
+
+The output contract:
+
+- Valid: `{ valid: true, validationError: null }`
+- Invalid: `{ valid: false, validationError: <summary string>, details: { <field>: <message> }, requiredSchema: <schema echoed back> }`
+
+Echoing the schema back lets the caller — or an LLM driving the call — self-correct.
+
+### Constraint cookbook
+
+| Need | Inline check |
+|---|---|
+| Required field present | `if (!("name" in body)) errors.push(...)` |
+| Type check | `else if (typeof body.name !== "string") errors.push(...)` |
+| String length / regex | `body.name.length < N`, `/regex/.test(body.email)` |
+| Number range | `body.seat_count < min`, `> max` |
+| Integer | `Math.floor(v) !== v` (also reject non-numbers) |
+| Enum | `["a","b","c"].indexOf(body.plan) === -1` |
+| Array | `Array.isArray(body.tags)`, `body.tags.length < N` |
+| Conditional | nest inside `if (body.type === "X") { ... }` |
+
+### The escaping gotcha (regex backslashes)
+
+Inside a JSON `responseBody`/`value` string, a regex like `\S` in the `REQUIRED_SCHEMA` literal needs **four** backslashes (`^\\\\S+...`) because it survives two layers of escaping — JSON string → JS string. The regex literal *executed* inside the IIFE (`/^\\S+@\\S+\\.\\S+$/`) needs only two per `\S`. If your email validation silently never matches, this is why.
+
+---
+
+## 5xx: differentiate the body, but keep it one responder
+
+A single error responder for all 5xx is fine. Differentiate the *body* (and code) by inspecting which failure happened, with an expression instead of a Switch:
+
+```javascript
+// responseBody on one Respond node:
+{{ (() => {
+    const err = $json.error ?? {};
+    const msg = err.message ?? '';
+    if (/timeout/i.test(msg))     return JSON.stringify({ error: 'upstream_timeout',   message: 'External service did not respond in time' });
+    if (/rate limit/i.test(msg))  return JSON.stringify({ error: 'service_unavailable', message: 'Upstream rate limit hit' });
+    return JSON.stringify({ error: 'internal_error', message: 'An internal error occurred' });
+})() }}
+
+// responseCode on the same node:
+{{ /timeout/i.test($json.error?.message ?? '') ? 504
+   : (/rate limit/i.test($json.error?.message ?? '') ? 503 : 500) }}
+```
+
+Reach for Switch + multiple Respond nodes only when the responses diverge *structurally* (different headers, redirect, different body shape). Same shape, different number = one expression-driven Respond.
+
+---
+
+## Don't leak internals
+
+The tempting one-liner:
+
+```javascript
+responseBody: "={{ JSON.stringify({ error: 'internal_error', details: $json.error }) }}"  // ❌
+```
+
+`$json.error` can carry stack traces, internal node names, connection strings, and upstream response bodies with embedded tokens. Surfacing it hands attackers a map and gives callers nothing useful.
+
+Instead: log the full error privately, return a sanitized message.
+
+```javascript
+// Error output → Log node (sends full $json.error to Sentry/Slack/your logger)
+{ type: "addConnection", source: "Call External", target: "Log Full Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Log Full Error", target: "Respond Error",  sourceIndex: 0 }
+```
+
+```json
+// Respond Error keeps the body clean:
+{ "responseCode": 502,
+  "responseBody": "={{ JSON.stringify({ error: 'upstream_error', message: 'External service failed' }) }}" }
+```
+
+The caller sees a clean message; the detail stays internal. Full do-not-leak list in **RESPONSE_SHAPES.md**.
+
+---
+
+## Correlation IDs (optional)
+
+If you run distributed tracing or log correlation, add a `request_id` consistently across **every** success and error response (partial coverage is worse than none). Two sources:
+
+- **Caller-supplied** — read an `X-Request-ID` header, pass it through. Better for tracing across systems.
+- **Generated** — use `{{ $execution.id }}` or a UUID. Easier.
+
+Don't conflate this with the `job_id` an async (202) endpoint returns — that's how the caller polls for work later, not a correlation field.
+
+---
+
+## Async / 202 pattern
+
+If the work takes longer than the caller wants to wait, respond 202 immediately and continue async:
+
+```
+Webhook → validate → Respond (202, { job_id }) → continue processing → callback / queue / email on completion
+```
+
+It has its own gotchas (idempotency, callback retries, status tracking) — build it deliberately. The `job_id` is intrinsic (it's how the work is found later), distinct from the optional `request_id`.
+
+---
+
+## Verifying the API workflow
+
+Before activating:
+
+1. **Test the success path** with `n8n_test_workflow`. Confirm shape and code. **API workflows almost always have side effects (DB writes, third-party calls, comms) — ask the user before running a test that triggers them.**
+2. **Trigger an error path** — feed input that breaks a processing node, run, confirm the error Respond fires with the right code and body.
+3. **Verify connections** with `n8n_get_workflow`: every fallible node has `onError: "continueErrorOutput"` AND `main[1]` wired. (NODE_ERROR_OUTPUTS.md.)
+4. **Confirm no internal detail leaks** in the error body.
+5. **Inspect real failures** afterward with `n8n_executions` to confirm the codes you expected are what actually went out.
+
+If any check fails, fix before activating.

data/skills/n8n-error-handling/ERROR_WORKFLOWS.md

@@ -0,0 +1,178 @@
+# Workflow-Level Error Workflows
+
+Per-node error outputs handle the failures you anticipated on the nodes you remembered to wire. A **workflow-level error workflow** is the catch-all for everything else — and for an unattended workflow (scheduled, cron, queue worker), it's the difference between "the job silently stopped three days ago" and "an alert arrived the moment it broke".
+
+What per-node outputs **don't** catch:
+
+- Failures on nodes you forgot to wire.
+- Crashes between nodes.
+- Whole-workflow timeouts.
+- Trigger failures.
+
+When an unhandled error escapes any of those, n8n invokes the designated **error workflow** with the failure context. You build that workflow once; it serves every workflow that points at it.
+
+---
+
+## What the error workflow receives
+
+It starts with an **Error Trigger** node, which fires with roughly this payload:
+
+```json
+{
+  "execution": {
+    "id": "...",
+    "url": "https://your-n8n/workflow/<wfId>/executions/<execId>",
+    "retryOf": "...",
+    "error": {
+      "name": "NodeApiError",
+      "message": "...",
+      "description": "...",
+      "timestamp": 1715000000000
+    },
+    "lastNodeExecuted": "Fetch order",
+    "mode": "trigger"
+  },
+  "workflow": { "id": "...", "name": "Sync Stripe customers" }
+}
+```
+
+Note what's **not** there: the payload carries the error message and the failed node's *name* (`lastNodeExecuted`), but **not the input data** that caused the failure. Recovering that takes an extra step (below).
+
+---
+
+## Minimal error workflow (capture → notify)
+
+For most workflows, this is enough:
+
+```
+Error Trigger → Set (build alert message) → Slack / email (post to #incidents)
+```
+
+Three nodes. Fast, hard to get wrong, and it turns silence into a message. Build it with `n8n_create_workflow` (or the partial-update ops), then assign it in the UI (see "Assigning it" below).
+
+---
+
+## What to put in the alert
+
+A good notification lets on-call act without opening n8n first. Pull these from the payload:
+
+| Field | Expression |
+|---|---|
+| Workflow name | `{{ $json.workflow.name }}` |
+| Workflow ID | `{{ $json.workflow.id }}` |
+| Editor link | `{{ $json.execution.url.split('/executions/')[0] }}` |
+| Execution ID | `{{ $json.execution.id }}` |
+| Execution link | `{{ $json.execution.url }}` |
+| Failed node | `{{ $json.execution.lastNodeExecuted }}` |
+| Error message | `{{ $json.execution.error.message }}` |
+| Error description | `{{ $json.execution.error.description }}` (often empty, useful when set) |
+| Timestamp | `{{ DateTime.fromMillis($json.execution.error.timestamp).toISO() }}` |
+
+The `timestamp` is a Unix-ms number — format it with Luxon's `DateTime.fromMillis(...)`. The execution `url` is `{base}/workflow/{id}/executions/{execId}`, so stripping the `/executions/...` tail gives the editor URL.
+
+A useful Slack body:
+
+```
+Workflow failure: *{{ $json.workflow.name }}* (`{{ $json.workflow.id }}`)
+Open editor: {{ $json.execution.url.split('/executions/')[0] }}
+Failed node: `{{ $json.execution.lastNodeExecuted }}`
+Error: {{ $json.execution.error.message }}
+Execution: {{ $json.execution.url }}
+Time: {{ DateTime.fromMillis($json.execution.error.timestamp).toISO() }}
+```
+
+Two links matter: the **editor link** so on-call can start fixing, and the **execution link** so they can see the exact failed run. Skipping either costs a step. "Workflow failed." is not an alert — it's a notification that you'll have to investigate from scratch.
+
+---
+
+## Featureful version: recover the failing input
+
+The Error Trigger payload tells you *which* node failed, not *what data* broke it. To get the offending payload, fetch the execution with the **n8n** node:
+
+```
+Error Trigger
+  → n8n  (resource: Execution, operation: Get,
+          Execution ID: {{ $json.execution.id }},
+          Include Execution Details: true)
+  → Set  (extract failed-node input from the execution data)
+  → Switch (route by severity)
+        ├── high → PagerDuty
+        ├── med  → Slack #incidents
+        └── low  → Slack #monitoring
+  → Data Table (log for tracking)
+```
+
+"Include Execution Details: true" hits `GET /executions/{id}?includeData=true` and returns the full run data, so you can pluck the failed node's input out of `data.resultData.runData[<lastNodeExecuted>]`. Now the on-call message can carry the actual offending payload (which customer, which order id), not just "node X errored".
+
+Caveats, all of which can turn the error workflow itself into a *new* silent failure:
+
+- **Requires an n8n API credential** on this workflow (Settings → API → personal access token, then attach it to the n8n node). Without it the node throws a 401 — an unhandled error *inside the error workflow*.
+- **Requires the failing workflow to persist execution data** (Save Execution Data, instance default or per-workflow). If it doesn't, the API returns metadata only.
+- **The n8n node call can itself fail** (API down, rate-limited). Wire its error output (`sourceIndex: 1`) to a fallback that still notifies, or the original error vanishes behind a fetch failure.
+
+Minimal is enough most of the time. The featureful version earns its keep on production-critical workflows where on-call minutes matter.
+
+---
+
+## Assigning it (UI only — the MCP can't)
+
+> The error workflow is assigned in the n8n **UI**: per workflow under **Workflow Settings → Error Workflow**, or as an instance-wide default. There is **no community-MCP tool** to set this assignment. `n8n_update_partial_workflow` exposes an `updateSettings` op, but the error-workflow setting is not reliably writable through it — confirm in the UI.
+
+So the agent's job is: **build the error workflow with the MCP, then hand the user the exact UI step** — "Open the failing workflow → Settings → Error Workflow → select '<name>'" — and remind them to do it for *every* unattended workflow (or set the instance default once). Building the workflow without assigning it does nothing; the trigger only fires for workflows that point at it.
+
+---
+
+## When the error workflow fires (and when it doesn't)
+
+**Fires** when:
+
+- A node throws unhandled (not routed via a wired per-node error output).
+- The workflow itself fails (timeout, OOM).
+- A trigger fails (rare, possible for non-webhook triggers).
+
+**Does NOT fire** when:
+
+- A node's error output is wired — even if the handler does nothing. n8n considers the error *handled*.
+- You manually stop an execution.
+- The workflow is paused / inactive.
+
+That second case is the subtle one: **a per-node error output wired to a no-op that drops the data will *suppress* the error workflow.** From n8n's perspective the error was handled, even though it was swallowed. So only catch per-node when you're genuinely acting on the error; if you want a failure to bubble up to the catch-all, leave it unwired.
+
+---
+
+## What the error workflow should NOT do
+
+- **Make external calls that can themselves fail without a fallback.** If the error workflow fails, the original error disappears — you've added a second silent failure on top of the first.
+- **Take significant time.** It runs synchronously; a slow error workflow compounds the original failure's impact.
+
+Keep it fast: parse, notify, return.
+
+---
+
+## The recursion trap
+
+If your monitored workflows alert Slack, and the *error* workflow also alerts Slack, then a Slack outage takes out both — the error workflow fails and the failure goes nowhere. n8n won't re-trigger on its own failure (no infinite loop), but you've lost the alert.
+
+Mitigations:
+
+- **Use a different channel than the monitored workflows.** If everything notifies Slack, the error workflow should use email (or vice versa).
+- **Add a fallback** — write to a Data Table (`n8n_manage_datatable`) if the primary notification fails, so there's always a trace.
+- **Lean on instance-level logging** (server logs, Sentry) so even an error-workflow failure surfaces somewhere outside n8n.
+
+---
+
+## Verifying it works
+
+After building and assigning:
+
+1. Make a throwaway workflow that always fails — e.g. an HTTP Request to an invalid URL, with **no** error output wired so the failure is unhandled.
+2. Run it.
+3. Confirm the error workflow fires and the notification arrives.
+
+This catches the setup mistakes that otherwise stay invisible until a real incident: wrong workflow assigned, wrong channel, missing API credential. Do it once before you rely on the alerting.
+
+---
+
+## Drift watch
+
+The Error Trigger payload shape can shift between n8n versions. If a field isn't where this file says, check current n8n docs and update your expressions — a renamed field fails silently as an empty alert, not a thrown error.

data/skills/n8n-error-handling/NODE_ERROR_OUTPUTS.md

@@ -0,0 +1,171 @@
+# Per-Node Error Outputs
+
+This file is about the **error output on a single node** — the second `main` output that fires when that node throws — and the two-step setup that trips up nearly everyone. For the workflow-level catch-all (Error Trigger workflows) and the webhook/Respond shape, see the rest of `n8n-error-handling`.
+
+The whole point: a node failing should route somewhere *you* control, instead of halting the run. The cost of forgetting half the setup is one of the worst silent-failure modes in n8n — a run that shows green while quietly dropping its work.
+
+---
+
+## The two-step setup (both are required)
+
+Routing a node's failure takes exactly two changes. Either one alone looks finished and misbehaves.
+
+### Step 1 — create the error output
+
+Set `onError: "continueErrorOutput"` on the node. This is what *adds* the second output. Until you do, `main[1]` does not exist and nothing you wire to it can fire.
+
+```javascript
+{ type: "updateNode", nodeName: "Google Sheets",
+  changes: { onError: "continueErrorOutput" } }
+```
+
+Surgical alternative if you're touching only this field:
+
+```javascript
+{ type: "patchNodeField", nodeName: "Google Sheets",
+  fieldPath: "onError", value: "continueErrorOutput" }
+```
+
+The valid `onError` values:
+
+| Value | Effect |
+|---|---|
+| `"stopWorkflow"` (default) | Error halts the whole workflow. The right default for runs you watch. |
+| `"continueRegularOutput"` | The error item flows out the **normal** output (`main[0]`) alongside successes. Rare and usually a mistake — downstream gets error-shaped data and keeps going. |
+| `"continueErrorOutput"` | The error item flows out a **separate** error output (`main[1]`). This is the one you wire below. |
+
+### Step 2 — wire the error output
+
+With `onError: "continueErrorOutput"`, the node has two outputs:
+
+- `main[0]` → success path (`sourceIndex: 0`)
+- `main[1]` → error path (`sourceIndex: 1`)
+
+Wire the error output to a real handler:
+
+```javascript
+{ type: "addConnection",
+  source: "Google Sheets",
+  target: "Handle Error",
+  sourceIndex: 1 }
+```
+
+`sourceIndex: 1` is the error output. (IF nodes accept the friendly aliases `branch: "true"`/`branch: "false"` for index 0/1; a generic fallible node has no such alias — use the explicit `sourceIndex: 1`.)
+
+---
+
+## Failure modes — why "one of two" is so dangerous
+
+### `onError` set, error output NOT wired
+
+```javascript
+// onError: "continueErrorOutput" set on the node,
+// but no addConnection from sourceIndex 1.
+```
+
+On failure the node emits to `main[1]`, which has **no targets**. The error data is silently discarded, downstream never fires, and — this is the trap — the execution is recorded as **succeeded**, because from n8n's perspective the error was "handled" by a branch that happens to go nowhere. No failed execution logged, nothing in the dashboard. The integration "just stops working" and there's no trail.
+
+**Fix:** wire `sourceIndex: 1` to a real handler, *or* set `onError` back to `"stopWorkflow"` so the failure is loud again.
+
+### Error output wired, `onError` NOT set
+
+```javascript
+// addConnection from "Some Node" sourceIndex 1 → "Handle Error" exists,
+// but the node still has the default onError: "stopWorkflow".
+```
+
+The connection sits in the JSON, but the slot it feeds from never fires. The handler is unreachable. On failure the workflow simply **halts** (default behavior). Less dangerous than the first mode — at least it's loud — but the handler you built does nothing.
+
+**Fix:** set `onError: "continueErrorOutput"` on the node.
+
+### Why validation won't save you
+
+A half-wired error output **validates clean**. `validate_workflow` and `n8n_validate_workflow` don't flag "`onError` is set but `main[1]` is empty" or vice versa — both are structurally legal. This is a runtime behavior, not a schema violation. The only reliable check is to read the workflow back (see Verification below).
+
+---
+
+## Common wiring shapes
+
+### Single fallible node → error handler
+
+```javascript
+// Node config: onError: "continueErrorOutput"
+{ type: "addConnection", source: "HTTP Request", target: "Respond Error", sourceIndex: 1 }
+```
+
+### Success path fans out, error path goes elsewhere
+
+```javascript
+{ type: "addConnection", source: "HTTP Request", target: "Save Result",  sourceIndex: 0 }
+{ type: "addConnection", source: "HTTP Request", target: "Notify Slack",  sourceIndex: 0 }
+{ type: "addConnection", source: "HTTP Request", target: "Respond Error", sourceIndex: 1 }
+```
+
+### Multiple fallible nodes → one shared error handler (fan-in)
+
+```javascript
+// Each of these nodes needs onError: "continueErrorOutput" on its own config.
+{ type: "addConnection", source: "Fetch User",     target: "Respond Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Call External",  target: "Respond Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Write Database", target: "Respond Error", sourceIndex: 1 }
+```
+
+Fan-in keeps the graph readable: one error responder, many sources. The handler can inspect which node failed (the error payload carries the failing node's name) to differentiate the response.
+
+### Both log AND respond on the same failure
+
+Wiring the error output to two targets composes without conflict — both receive the error data:
+
+```javascript
+{ type: "addConnection", source: "Call External", target: "Log Full Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Call External", target: "Respond Error",  sourceIndex: 1 }
+```
+
+Useful when you want a sanitized response *and* a private full-detail log on the same failure. (Or chain them: error output → Log → Respond, so the log runs first.)
+
+---
+
+## What counts as "fallible"
+
+Wire an error output on anything that can throw at runtime:
+
+- Network calls — HTTP Request, third-party API nodes, databases.
+- Auth failures — expired credential, rotated token.
+- Schema mismatches — missing DB column, JSON parse failure.
+- Rate limits — 429 from upstream (configure `retryOnFail` first so these self-heal).
+- File/binary operations — missing path, permission denied (see **n8n-binary-and-data**).
+- Code nodes that can throw.
+
+Usually **not** worth an error output:
+
+- Set / Edit Fields on already-validated data.
+- IF / Switch with simple expressions — if those throw it's a bug to fix, not a path to catch.
+- Pure transformations with no I/O.
+
+When unsure, wire it. The cost is one connection; the cost of not wiring it is a silent halt.
+
+---
+
+## Verification (do this every time)
+
+After any create/update, pull the workflow with `n8n_get_workflow` and check **both halves** on each fallible node:
+
+1. **Node config** — `onError` is `"continueErrorOutput"` (or whatever you intended).
+2. **Connections** — `connections["<node>"].main[1]` contains the expected handler(s).
+
+If either half is missing, you have a silent-failure setup. Fix before activating.
+
+`n8n_autofix_workflow` can repair some structural issues, but it won't infer that you *meant* to wire an error path — the intent to handle a given node's failure is yours to express. Treat the read-back as mandatory.
+
+---
+
+## When to use an error workflow instead
+
+Per-node outputs handle the failure of *one node you remembered to wire*. They do **not** catch:
+
+- Failures on nodes you forgot to wire.
+- Crashes between nodes.
+- Whole-workflow timeouts.
+- Trigger failures.
+
+For those, you need a workflow-level **error workflow** (Error Trigger node). And note the inverse: a per-node error output that's wired to a no-op which drops the data counts as "handled" — so it will *suppress* the error workflow. Only catch per-node when you're genuinely acting on the error. See **ERROR_WORKFLOWS.md**.