{"owner":"n8n-io","repo":"n8n","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":6715,"categories":["root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"n8n":{"command":"npx","args":["-y","@modelcontextprotocol/server-n8n"]}}},"found":["AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance on how to work with the n8n repository.\n\n## Project Overview\n\nn8n is a workflow automation platform written in TypeScript, using a monorepo\nstructure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js\nfrontend, and extensible node-based workflow engine.\n\n## General Guidelines\n\n- Always use pnpm\n- Write all technical text (code comments, PR descriptions, issue and ticket\n  descriptions, docs) in ASD-STE100 Simplified Technical English: use short\n  sentences, the active voice, and one instruction for each sentence\n- **JSDoc on `@Env(...)` config properties is public documentation.** The\n  docs team exports these comments into the environment variable reference on\n  docs.n8n.io. Write them for a self-hosting operator and follow the\n  `n8n:env-var-docs` skill, which applies the n8n docs style guide and\n  overrides the ASD-STE100 rule above for these comments\n- **Secrets on the command line:** if a developer opted into anonymous dev\n  metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments\n  of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a\n  subcommand or baked into a flag — are dropped, and the home dir is stripped from\n  paths, but other args are sent as-is — so never put secrets in a command. Pass\n  sensitive values via environment variables, which are never captured.\n- When adding comments, keep them concise and to the point - explain the \"why\"\n  in a line or two; don't be overly verbose. Comments should be scoped and\n  relevant to the surrounding code, not just to the current task\n- We use Linear as a ticket tracking system\n- We use Posthog for feature flags\n- To find registered telemetry events (names, descriptions, properties), run\n  `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The\n  registry is being adopted incrementally, so search call sites if the catalog\n  has no match. The `n8n:telemetry` skill covers adding or changing events\n- When starting to work on a new ticket – create a new branch from fresh\n  master with the name specified in Linear ticket\n- When creating a new branch for a ticket in Linear - use the branch name\n  suggested by Linear, **unless it is a security fix** (see Security Fix\n  Hygiene below)\n- Use mermaid diagrams in MD files when you need to visualise something\n- Write an ADR only when asked. When a change makes a decision that an\n  engineer could challenge in 12 months, say so in one line and let the\n  human decide. Read [docs/adr/README.md](docs/adr/README.md) before you\n  write one. CI enforces its conventions\n- **Developing v3 features:** land normal feature work on `master` behind an\n  opt-in flag; introduce breaking changes only on the `3.x` branch. See\n  [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).\n- The AI gateway feature is **\"Gateway credits\"** in user-facing text (UI copy,\n  error messages, prompts). Only internal identifiers, i18n keys, telemetry, and\n  comments keep the historical `n8nConnect` / `n8n credits` / AI Gateway names\n- **Shared utilities:** before you hand-roll a utility (`isRecord`, secret or\n  PII redaction, JSON extraction from LLM output, Zod to JSON Schema, model-id\n  parsing, AI client HTTP transport and response-size limiting, …), you MUST\n  check the shared packages for an existing\n  implementation and use it: `@n8n/utils` (generic helpers, redaction),\n  `@n8n/ai-utilities` (AI- and LLM-specific helpers) and `n8n-workflow`\n  (workflow graph and traversal). A new shared helper usually belongs in one of\n  these packages too; domain logic stays in the package that owns the domain.\n\n## Agent Skills and Claude Code Plugin\n\nn8n shared skills live in `.agents/skills/`. Claude Code consumes them through\nsymlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`\ndirectly. Harness-specific overrides remain real directories in the harness\npath, such as `.opencode/skills/setup-mcps/`. See\n[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.\n\nn8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and\nare namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.\n`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See\n[plugin README](.claude/plugins/n8n/README.md) for structure and details.\n\n## Essential Commands\n\nFor routine pre-commit checks, follow [Verify changes](#verify-changes).\nFor focused tests, use `pnpm agent:test` or `pnpm agent:playwright`.\nPass test files and worker limits after `--`. Run each command with `--help`\nfor its options.\n\n`pnpm agent:lint` and `pnpm agent:typecheck` run full-repo checks by default.\nWith `--filter <package>`, they still check the whole package. These wrappers\nsave logs and reduce console output. They do not reduce CPU or memory use.\nDo not use them as routine pre-commit checks.\n\n### Fresh checkout / agent setup\n\nFor a fresh checkout (cat-bot, a new hire, any agent verifying the repo\nbuilds), prefer `pnpm agent:setup` over running install + build + tests by\nhand. It chains them in one process, caps per-process memory and turbo\nconcurrency so a 6GB box doesn't OOM, streams all output to\n`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary\nper step plus the tail of the failing log. A machine-readable\n`.agent-setup/summary.json` is always written so a backgrounded run is\nreadable in a single shot — no polling, no scrolling logs.\n\n```bash\npnpm agent:setup                 # install → build → test (full suite)\npnpm agent:setup install         # one step at a time\npnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)\n```\n\n### Building\nUse `pnpm build` to build all packages. ALWAYS redirect the output of the\nbuild command to a file:\n\n```bash\npnpm build > build.log 2>&1\n```\n\nYou can inspect the last few lines of the build log file to check for errors:\n```bash\ntail -n 20 build.log\n```\n\nIf build outputs or the turbo cache are stale (e.g. after switching branches\nor worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight\nby default) for a fast recovery: it cleans build outputs and force-rebuilds\n(keeping `node_modules` and untracked files). If that doesn't fix your issue,\nuse `pnpm reset --full`, which also wipes untracked files and reinstalls\ndependencies.\n\n### Seeding a local instance\n\nAn empty instance is a bad place to test anything that reads a user's work.\nThese commands fill one. They are dev tooling on the private root package, so\nthey never reach a user.\n\n```bash\nN8N_API_KEY=<jwt> pnpm seed:preference   # 10 workflows in one house style, plus history\nN8N_API_KEY=<jwt> pnpm seed:account      # ~500 varied workflows across 30 projects\npnpm inspect:activity                    # read-only activity_event viewer on 127.0.0.1\n```\n\nBoth seed profiles delete their own prior output, so a re-run replaces it.\nThat clear step deletes anything named `[seed]` and any empty team project,\nwhoever made them, so do not point either at a shared instance. The viewer is\nunauthenticated and serves the whole table: keep it on loopback.\n\nSee [scripts/instance-seeding/AGENTS.md](scripts/instance-seeding/AGENTS.md) for\nprofiles, tokens, determinism, and the other commands.\n\n## Architecture Overview\n\n**Monorepo Structure:** pnpm workspaces with Turbo build orchestration\n\n### Package Structure\n\nThe monorepo is organized into these key packages:\n\n- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend\n- **`packages/workflow`**: Core workflow interfaces and types\n- **`packages/core`**: Workflow execution engine\n- **`packages/cli`**: Express server, REST API, and CLI commands\n- **`packages/frontend/editor-ui`**: Vue 3 frontend application\n- **`packages/frontend/@n8n/i18n`**: Internationalization for UI text\n- **`packages/nodes-base`**: Built-in nodes for integrations\n- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes\n- **`packages/@n8n/instance-ai`**: \"n8n Assistant\" in the UI, \"Instance AI\" in code — n8n Assistant backend. See its `CLAUDE.md` for architecture docs.\n- **`@n8n/design-system`**: Vue component library for UI consistency\n- **`@n8n/config`**: Centralized configuration management\n\n## Technology Stack\n\n- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library\n- **Backend:** Node.js + TypeScript + Express + TypeORM\n- **Testing:** Vitest (unit) + Playwright (UI, API, infrastructure, lifecycle, performance, and E2E orchestration)\n- **Database:** TypeORM with SQLite/PostgreSQL support\n- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks\n\n### Key Architectural Patterns\n\n1. **Dependency Injection**: Uses `@n8n/di` for IoC container\n2. **Controller-Service-Repository**: Backend follows MVC-like pattern\n3. **Event-Driven**: Internal event bus for decoupled communication\n4. **Context-Based Execution**: Different contexts for different node types\n5. **State Management**: Frontend uses Pinia stores\n6. **Design System**: Reusable components and design tokens are centralized in\n   `@n8n/design-system`, where all pure Vue components should be placed to\n   ensure consistency and reusability\n\n## Key Development Patterns\n\n- Each package has isolated build configuration and can be developed independently\n- Hot reload works across the full stack during development\n- Node development uses dedicated `node-dev` CLI tool\n- Workflow tests are JSON-based for integration testing\n- AI features have dedicated development workflow (`pnpm dev:ai`)\n\n### Workflow Traversal Utilities\n\nThe `n8n-workflow` package exports graph traversal utilities from\n`packages/workflow/src/common/`. Use these instead of custom traversal logic.\n\n**Key concept:** `workflow.connections` is indexed by **source node**.\nTo find parent nodes, use `mapConnectionsByDestination()` to invert it first.\n\n```typescript\nimport { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';\n\n// Finding parent nodes (predecessors) - requires inverted connections\nconst connectionsByDestination = mapConnectionsByDestination(workflow.connections);\nconst parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);\n\n// Finding child nodes (successors) - uses connections directly\nconst children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);\n```\n\n### TypeScript Best Practices\n- **NEVER use `any` type** - use proper types or `unknown`\n- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)\n- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication\n- **Lazy-load heavy modules** — if a module is only used in a specific code\n  path (not every request), use `await import()` at point of use instead of\n  top-level `import`. Applies especially to native modules and large parsers.\n\n### Error Handling\n- Don't use the deprecated `ApplicationError` class anywhere — it's a\n  compatibility shim kept only so community nodes keep resolving. Use one of\n  these instead, picking by cause:\n  - `UserError` — the user caused it (invalid input, unauthorized action,\n    business-rule violation).\n  - `OperationalError` — a transient, expected issue (network request failing,\n    DB query timing out) that should be handled gracefully.\n  - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,\n    failed assertion) that developers need to fix.\n- Import from appropriate error classes in each package\n\n### Persistence layer & the TypeORM boundary\n\nTypeORM (`@n8n/typeorm`) must stay in the **persistence layer**. The shared\n`@n8n/db` package and backend persistence adapters can import it. A module can\ncolocate or group its entities and repositories according to its domain.\nBusiness logic — services, controllers, handlers, commands, factories — must not\nimport from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). The\n`typeorm-persistence-boundary` Code Health rule recognizes entity and repository\ndeclarations. It scans backend packages that depend on `@n8n/db` or\n`@n8n/typeorm`. Tests, migrations, and explicit helper-only adapters are\nexceptions. Existing business-logic imports stay in the shrink-only Code Health\nbaseline. A new business-logic import fails CI.\n\n- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,\n  `FindOptionsWhere`, …), put it behind a **use-case-named repository method**\n  that takes plain parameters and returns domain-shaped values — not a generic\n  `find(options)` passthrough.\n- **Transactions:** transaction orchestration belongs in the persistence layer.\n  Don't reach for `.manager` / `.manager.transaction(...)` or\n  `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in\n  `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in\n  `txRunner.run(ctx, async (ctx) => …)`. The callback receives an\n  `OperationContext` carrying the active transaction; thread that `ctx` into the\n  repository methods you call. `run` **requires** a context — pass an empty `{}`\n  at the operation entry point, and reuse the one you were handed everywhere\n  below it (a context that already carries a transaction is joined, not nested).\n  The `Transaction` handle is opaque and never exposes a driver type to\n  business logic. See `oauth-token.service.ts` for a worked service example\n  (its repositories predate the composition rule below; do not copy their shape).\n- **Repositories compose, they don't extend.** A repository is the boundary\n  that keeps TypeORM out of business logic. If it extended `BaseRepository`,\n  every service that injects it would also get `find`, `save`, `delete`,\n  `createQueryBuilder` and `.manager` for free, and TypeORM would leak through\n  inferred types that no lint rule can see. So a repository is a plain\n  `@Service()` class that holds a **file-private `BaseRepository` subclass (the\n  table)** as a private field and resolves the manager with\n  `this.table.managerFor(ctx)`. The table is never exported or registered with\n  DI. Every data access is a named use-case method on the repository that\n  calls the table internally; there is no generic `find`/`save`/`delete`\n  unless you write it for one operation. See\n  `packages/cli/src/modules/inbound-auth-core/database/repositories/trusted-source.repository.ts`\n  for a worked example. The existing `extends BaseRepository` / `extends\n  Repository` repositories are legacy. Do not copy them, and do not convert them\n  in unrelated PRs. This rule is not yet lint-enforced.\n- **Anti-patterns reviewers reject** — they hide the dependency instead of\n  removing it:\n  - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.\n  - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule\n    (`@n8n/db` re-exports several operators/types, but this relabels the\n    dependency rather than removing it).\n  - Pushing `.manager` / `createQueryBuilder` / `repo.managerFor(ctx)` into\n    business logic to avoid an operator import — trades a visible leak for an\n    invisible one.\n  - A repository that `extends BaseRepository` / `extends Repository`, or that\n    exposes its table (public property, getter, or a `find(options)`\n    passthrough) — the inherited TypeORM surface must stay private to the table.\n\n### ESLint configuration layers\n\nRule policy lives in four shared configs in `@n8n/eslint-config`, and a package\nconfig picks exactly one:\n\n| layer | subpath | for |\n|---|---|---|\n| `baseConfig` | `@n8n/eslint-config/base` | runtime-agnostic libraries |\n| `backendConfig` | `@n8n/eslint-config/backend` | anything that runs on Node; adds the network and encryption boundaries |\n| `frontendConfig` | `@n8n/eslint-config/frontend` | Vue packages |\n| `nodesConfig` | `@n8n/eslint-config/nodes` | `n8n-nodes-base` and `@n8n/nodes-langchain`; adds the node and credential file rules |\n\nA package config may add `ignores`, an additive plugin config, a block that\nraises rules to `error`, and blocks scoped to `files`. It must not turn a rule\ndown for the whole package: every lint script runs with `--quiet`, so a `warn`\nenforces nothing and reads as if it did. The code-health rule\n`lint-config-layering` enforces this, with existing debt in\n`.code-health-baseline.json`, which only shrinks.\n\nTo stop enforcing a rule everywhere, retire it in `base.ts` with the count\nbehind the decision. To enforce one again in a package that is ready, set it to\n`error` there. `node scripts/lint-parity/majority.mjs` prints how many packages\ndowngrade each rule, and `scripts/lint-parity/snapshot.mjs` plus `diff.mjs`\nprove a config change only altered what you meant it to.\n\n### Encryption boundary\n\nNew code encrypts and decrypts only through `cipher.encryptV2()` /\n`cipher.decryptV2()` — the key-manager module decides which key is used and in\nwhich output format. Enforced in CI by the rules in\n`packages/@n8n/eslint-config/src/configs/encryption-boundary.ts` (part of\n`backendConfig`, and so of `nodesConfig`; every package that runs on Node\nextends one of those layers):\n\n- `Cipher` does not expose the legacy or explicit-key methods.\n- The raw AES classes stay inside `packages/core/src/encryption/`.\n- **Deployment keys are never deleted** — data encrypted with a key becomes\n  unreadable without it. Deactivate keys instead; the repository does not expose\n  deletion and database triggers reject direct deletion.\n- Inline disables that name these rules, and bare line-form disables, are\n  themselves lint errors. The code-health rule `encryption-boundary` (CI\n  \"Static Analysis\") is the enforcement layer: it checks that every package\n  that depends on `n8n-core` or `@n8n/db` extends `backendConfig` (or\n  `nodesConfig`) at `error` severity, and rejects every directive form that\n  would silence the\n  rules in non-test code (`eslint-disable*` and inline `eslint` configuration\n  comments). Widening the boundary happens in `encryption-boundary.ts` only;\n  that file and the rule files require security (IAM) approval via OWNERS.\n\n### Frontend Development\n- Refer to `packages/frontend/AGENTS.md`\n- **All UI text must use i18n** - add translations to `@n8n/i18n` package\n- **Use CSS variables directly** - never hardcode spacing as px values\n- **data-testid must be a single value** (no spaces or multiple values)\n- Always use the `design-system` skill in reviews\n\n### Verify changes\n\n- Before committing, run formatting and lint checks on changed files. Use\n  the package's configured tools through `pnpm exec` with explicit file paths.\n  Do not append file paths to `pnpm lint`; package scripts can still check\n  the whole package.\n- Run tests that cover the changed behavior from the owning package:\n  `pnpm test <test-file> --maxWorkers=1`. Or use the root wrapper:\n  `pnpm agent:test --filter <package> -- <test-file> --maxWorkers=1`.\n  For Playwright, use `pnpm agent:playwright -- <spec-file> --workers=1`.\n- For routine commits, run checks one at a time. Use one test worker by\n  default. Do not run full frontend typechecks locally. Use CI for\n  comprehensive lint, typechecks, and test suites.\n- For documentation-only changes, review the diff and run `git diff --check`.\n  Skip code tests when no behavior changed.\n- Report which checks ran and which checks were left to CI.\n- Use Vitest for unit tests. Use\n  [Playwright](packages/quality/testing/playwright/AGENTS.md) when a test needs its\n  browser, fixtures, or managed containers.\n- For Vitest packages with `@n8n/di` decorators, use\n  `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`.\n- Check import and mock side effects before running tests. Keep tests out of\n  user-owned directories. Set `N8N_USER_FOLDER` to a test-owned directory before\n  importing n8n settings. Clean up only paths that the test created.\n- CI runs [`@n8n/code-health`](packages/quality/policy/code-health/README.md) static\n  analysis on PRs. It checks monorepo rules, including dependency hygiene and\n  encryption-boundary coverage.\n\n### Local development\n\n| Goal | Command |\n|------|---------|\n| Run product E2E against a local instance | `pnpm --filter=n8n-playwright test:local` |\n| Run backend with PostgreSQL, Redis, email, and proxy services | `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`, then `pnpm dev:be` |\n| Add editor hot reload | `pnpm dev:fe:editor` |\n| Start a Codespace backend and share its port | `pnpm dev:up` |\n\nThe root `pnpm dev` command does not start a server. See the\n[Playwright guide](packages/quality/testing/playwright/README.md) and the\n[Codespaces guide](.devcontainer/codespaces/README.md) for details.\n\n### Common Development Tasks\n\nWhen implementing features:\n1. Define API types in `packages/@n8n/api-types`\n2. Implement backend logic in `packages/cli` module, follow\n   `scripts/backend-module/backend-module-guide.md`\n3. Add API endpoints via controllers\n4. Update frontend in `packages/frontend/editor-ui` with i18n support. For a\n   frontend feature module, obey\n   `packages/@n8n/module-cli/frontend-module-guide.md`\n5. Write tests with proper mocks\n\n## Design Principles\n\n### Security Must Not Degrade the Building Experience\n\nSecurity improvements, whether driven by enterprise requirements or internal\nstandards, must NEVER add friction to the common-case building experience. When\ndesigning security-related features (defaults, behaviors, flows, error\nhandling), apply these checks:\n\n- **No friction for the common case:** A community builder's workflow should\n  remain intuitive. Security should be invisible when it can be.\n- **Migration and upgrade paths:** Existing users must have a clear,\n  non-disruptive path forward when defaults or behaviors change.\n- **Security layers on top, not in competition:** Great UX and strong security\n  are not trade-offs. They're both required. If a design forces a choice\n  between them, the design needs more work.\n\n### Security Fix Hygiene\n\n**This is a public repository.** When working on security fixes, never expose\nthe attack vector or vulnerability type in any public-facing artifact. Attackers\nmonitor open-source repos for signals like branch names, commit messages, PR\ntitles, test descriptions, and Linear URLs.\n\n**Rules for security fixes:**\n\n- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals\n  the vulnerability. Rename to describe the fix neutrally\n  (e.g. `node-1234-improve-request-handling`, not\n  `node-1234-fix-ddos-vulnerability`).\n- **Commit messages:** Describe what the code now does, not the threat it\n  prevents (e.g. `fix: add payload size validation`, not\n  `fix: prevent denial of service`).\n- **Test descriptions:** Use neutral, functional language\n  (e.g. `'should sanitize query parameters'`, not\n  `'should prevent SQL injection'`).\n- **Code comments:** Do not describe the attack scenario in comments.\n- **Linear references:** Never include the URL slug\n  (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).\n\n### Customer Confidentiality\n\n**This is a public repository.** Never mention customer names in any\npublic-facing artifact — not all customers have agreed to be named publicly,\nand naming them can reveal security-relevant details about their setup.\n\nThis applies to PR titles and descriptions, branch names, commit messages,\ncode, code comments, test names and test data, and fixtures. When implementing\na customer request, describe the use case neutrally (e.g. \"a customer with a\nlarge multi-main setup\", not the company name) and use generic placeholder\nnames (e.g. `Acme Corp`) in tests and examples.\n\n## Github Guidelines\n- When creating a PR, use the conventions in\n  `.github/pull_request_template.md` and\n  `.github/pull_request_title_conventions.md`.\n- Use `gh pr create --draft` to create draft PRs.\n- If there is a corresponding Linear ticket, reference it in the PR\n  description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not\n  create a Linear ticket on your own — ask first.\n- always link to the github issue if mentioned in the linear ticket.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance on how to work with the n8n repository.\n\n## Project Overview\n\nn8n is a workflow automation platform written in TypeScript, using a monorepo\nstructure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js\nfrontend, and extensible node-based workflow engine.\n\n## General Guidelines\n\n- Always use pnpm\n- Write all technical text (code comments, PR descriptions, issue and ticket\n  descriptions, docs) in ASD-STE100 Simplified Technical English: use short\n  sentences, the active voice, and one instruction for each sentence\n- **JSDoc on `@Env(...)` config properties is public documentation.** The\n  docs team exports these comments into the environment variable reference on\n  docs.n8n.io. Write them for a self-hosting operator and follow the\n  `n8n:env-var-docs` skill, which applies the n8n docs style guide and\n  overrides the ASD-STE100 rule above for these comments\n- **Secrets on the command line:** if a developer opted into anonymous dev\n  metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments\n  of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a\n  subcommand or baked into a flag — are dropped, and the home dir is stripped from\n  paths, but other args are sent as-is — so never put secrets in a command. Pass\n  sensitive values via environment variables, which are never captured.\n- When adding comments, keep them concise and to the point - explain the \"why\"\n  in a line or two; don't be overly verbose. Comments should be scoped and\n  relevant to the surrounding code, not just to the current task\n- We use Linear as a ticket tracking system\n- We use Posthog for feature flags\n- To find registered telemetry events (names, descriptions, properties), run\n  `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The\n  registry is being adopted incrementally, so search call sites if the catalog\n  has no match. The `n8n:telemetry` skill covers adding or changing events\n- When starting to work on a new ticket – create a new branch from fresh\n  master with the name specified in Linear ticket\n- When creating a new branch for a ticket in Linear - use the branch name\n  suggested by Linear, **unless it is a security fix** (see Security Fix\n  Hygiene below)\n- Use mermaid diagrams in MD files when you need to visualise something\n- Write an ADR only when asked. When a change makes a decision that an\n  engineer could challenge in 12 months, say so in one line and let the\n  human decide. Read [docs/adr/README.md](docs/adr/README.md) before you\n  write one. CI enforces its conventions\n- **Developing v3 features:** land normal feature work on `master` behind an\n  opt-in flag; introduce breaking changes only on the `3.x` branch. See\n  [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).\n- The AI gateway feature is **\"Gateway credits\"** in user-facing text (UI copy,\n  error messages, prompts). Only internal identifiers, i18n keys, telemetry, and\n  comments keep the historical `n8nConnect` / `n8n credits` / AI Gateway names\n- **Shared utilities:** before you hand-roll a utility (`isRecord`, secret or\n  PII redaction, JSON extraction from LLM output, Zod to JSON Schema, model-id\n  parsing, AI client HTTP transport and response-size limiting, …), you MUST\n  check the shared packages for an existing\n  implementation and use it: `@n8n/utils` (generic helpers, redaction),\n  `@n8n/ai-utilities` (AI- and LLM-specific helpers) and `n8n-workflow`\n  (workflow graph and traversal). A new shared helper usually belongs in one of\n  these packages too; domain logic stays in the package that owns the domain.\n\n## Agent Skills and Claude Code Plugin\n\nn8n shared skills live in `.agents/skills/`. Claude Code consumes them through\nsymlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`\ndirectly. Harness-specific overrides remain real directories in the harness\npath, such as `.opencode/skills/setup-mcps/`. See\n[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.\n\nn8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and\nare namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.\n`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See\n[plugin README](.claude/plugins/n8n/README.md) for structure and details.\n\n## Essential Commands\n\nFor routine pre-commit checks, follow [Verify changes](#verify-changes).\nFor focused tests, use `pnpm agent:test` or `pnpm agent:playwright`.\nPass test files and worker limits after `--`. Run each command with `--help`\nfor its options.\n\n`pnpm agent:lint` and `pnpm agent:typecheck` run full-repo checks by default.\nWith `--filter <package>`, they still check the whole package. These wrappers\nsave logs and reduce console output. They do not reduce CPU or memory use.\nDo not use them as routine pre-commit checks.\n\n### Fresh checkout / agent setup\n\nFor a fresh checkout (cat-bot, a new hire, any agent verifying the repo\nbuilds), prefer `pnpm agent:setup` over running install + build + tests by\nhand. It chains them in one process, caps per-process memory and turbo\nconcurrency so a 6GB box doesn't OOM, streams all output to\n`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary\nper step plus the tail of the failing log. A machine-readable\n`.agent-setup/summary.json` is always written so a backgrounded run is\nreadable in a single shot — no polling, no scrolling logs.\n\n```bash\npnpm agent:setup                 # install → build → test (full suite)\npnpm agent:setup install         # one step at a time\npnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)\n```\n\n### Building\nUse `pnpm build` to build all packages. ALWAYS redirect the output of the\nbuild command to a file:\n\n```bash\npnpm build > build.log 2>&1\n```\n\nYou can inspect the last few lines of the build log file to check for errors:\n```bash\ntail -n 20 build.log\n```\n\nIf build outputs or the turbo cache are stale (e.g. after switching branches\nor worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight\nby default) for a fast recovery: it cleans build outputs and force-rebuilds\n(keeping `node_modules` and untracked files). If that doesn't fix your issue,\nuse `pnpm reset --full`, which also wipes untracked files and reinstalls\ndependencies.\n\n### Seeding a local instance\n\nAn empty instance is a bad place to test anything that reads a user's work.\nThese commands fill one. They are dev tooling on the private root package, so\nthey never reach a user.\n\n```bash\nN8N_API_KEY=<jwt> pnpm seed:preference   # 10 workflows in one house style, plus history\nN8N_API_KEY=<jwt> pnpm seed:account      # ~500 varied workflows across 30 projects\npnpm inspect:activity                    # read-only activity_event viewer on 127.0.0.1\n```\n\nBoth seed profiles delete their own prior output, so a re-run replaces it.\nThat clear step deletes anything named `[seed]` and any empty team project,\nwhoever made them, so do not point either at a shared instance. The viewer is\nunauthenticated and serves the whole table: keep it on loopback.\n\nSee [scripts/instance-seeding/AGENTS.md](scripts/instance-seeding/AGENTS.md) for\nprofiles, tokens, determinism, and the other commands.\n\n## Architecture Overview\n\n**Monorepo Structure:** pnpm workspaces with Turbo build orchestration\n\n### Package Structure\n\nThe monorepo is organized into these key packages:\n\n- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend\n- **`packages/workflow`**: Core workflow interfaces and types\n- **`packages/core`**: Workflow execution engine\n- **`packages/cli`**: Express server, REST API, and CLI commands\n- **`packages/frontend/editor-ui`**: Vue 3 frontend application\n- **`packages/frontend/@n8n/i18n`**: Internationalization for UI text\n- **`packages/nodes-base`**: Built-in nodes for integrations\n- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes\n- **`packages/@n8n/instance-ai`**: \"n8n Assistant\" in the UI, \"Instance AI\" in code — n8n Assistant backend. See its `CLAUDE.md` for architecture docs.\n- **`@n8n/design-system`**: Vue component library for UI consistency\n- **`@n8n/config`**: Centralized configuration management\n\n## Technology Stack\n\n- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library\n- **Backend:** Node.js + TypeScript + Express + TypeORM\n- **Testing:** Vitest (unit) + Playwright (UI, API, infrastructure, lifecycle, performance, and E2E orchestration)\n- **Database:** TypeORM with SQLite/PostgreSQL support\n- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks\n\n### Key Architectural Patterns\n\n1. **Dependency Injection**: Uses `@n8n/di` for IoC container\n2. **Controller-Service-Repository**: Backend follows MVC-like pattern\n3. **Event-Driven**: Internal event bus for decoupled communication\n4. **Context-Based Execution**: Different contexts for different node types\n5. **State Management**: Frontend uses Pinia stores\n6. **Design System**: Reusable components and design tokens are centralized in\n   `@n8n/design-system`, where all pure Vue components should be placed to\n   ensure consistency and reusability\n\n## Key Development Patterns\n\n- Each package has isolated build configuration and can be developed independently\n- Hot reload works across the full stack during development\n- Node development uses dedicated `node-dev` CLI tool\n- Workflow tests are JSON-based for integration testing\n- AI features have dedicated development workflow (`pnpm dev:ai`)\n\n### Workflow Traversal Utilities\n\nThe `n8n-workflow` package exports graph traversal utilities from\n`packages/workflow/src/common/`. Use these instead of custom traversal logic.\n\n**Key concept:** `workflow.connections` is indexed by **source node**.\nTo find parent nodes, use `mapConnectionsByDestination()` to invert it first.\n\n```typescript\nimport { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';\n\n// Finding parent nodes (predecessors) - requires inverted connections\nconst connectionsByDestination = mapConnectionsByDestination(workflow.connections);\nconst parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);\n\n// Finding child nodes (successors) - uses connections directly\nconst children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);\n```\n\n### TypeScript Best Practices\n- **NEVER use `any` type** - use proper types or `unknown`\n- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)\n- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication\n- **Lazy-load heavy modules** — if a module is only used in a specific code\n  path (not every request), use `await import()` at point of use instead of\n  top-level `import`. Applies especially to native modules and large parsers.\n\n### Error Handling\n- Don't use the deprecated `ApplicationError` class anywhere — it's a\n  compatibility shim kept only so community nodes keep resolving. Use one of\n  these instead, picking by cause:\n  - `UserError` — the user caused it (invalid input, unauthorized action,\n    business-rule violation).\n  - `OperationalError` — a transient, expected issue (network request failing,\n    DB query timing out) that should be handled gracefully.\n  - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,\n    failed assertion) that developers need to fix.\n- Import from appropriate error classes in each package\n\n### Persistence layer & the TypeORM boundary\n\nTypeORM (`@n8n/typeorm`) must stay in the **persistence layer**. The shared\n`@n8n/db` package and backend persistence adapters can import it. A module can\ncolocate or group its entities and repositories according to its domain.\nBusiness logic — services, controllers, handlers, commands, factories — must not\nimport from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). The\n`typeorm-persistence-boundary` Code Health rule recognizes entity and repository\ndeclarations. It scans backend packages that depend on `@n8n/db` or\n`@n8n/typeorm`. Tests, migrations, and explicit helper-only adapters are\nexceptions. Existing business-logic imports stay in the shrink-only Code Health\nbaseline. A new business-logic import fails CI.\n\n- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,\n  `FindOptionsWhere`, …), put it behind a **use-case-named repository method**\n  that takes plain parameters and returns domain-shaped values — not a generic\n  `find(options)` passthrough.\n- **Transactions:** transaction orchestration belongs in the persistence layer.\n  Don't reach for `.manager` / `.manager.transaction(...)` or\n  `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in\n  `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in\n  `txRunner.run(ctx, async (ctx) => …)`. The callback receives an\n  `OperationContext` carrying the active transaction; thread that `ctx` into the\n  repository methods you call. `run` **requires** a context — pass an empty `{}`\n  at the operation entry point, and reuse the one you were handed everywhere\n  below it (a context that already carries a transaction is joined, not nested).\n  The `Transaction` handle is opaque and never exposes a driver type to\n  business logic. See `oauth-token.service.ts` for a worked service example\n  (its repositories predate the composition rule below; do not copy their shape).\n- **Repositories compose, they don't extend.** A repository is the boundary\n  that keeps TypeORM out of business logic. If it extended `BaseRepository`,\n  every service that injects it would also get `find`, `save`, `delete`,\n  `createQueryBuilder` and `.manager` for free, and TypeORM would leak through\n  inferred types that no lint rule can see. So a repository is a plain\n  `@Service()` class that holds a **file-private `BaseRepository` subclass (the\n  table)** as a private field and resolves the manager with\n  `this.table.managerFor(ctx)`. The table is never exported or registered with\n  DI. Every data access is a named use-case method on the repository that\n  calls the table internally; there is no generic `find`/`save`/`delete`\n  unless you write it for one operation. See\n  `packages/cli/src/modules/inbound-auth-core/database/repositories/trusted-source.repository.ts`\n  for a worked example. The existing `extends BaseRepository` / `extends\n  Repository` repositories are legacy. Do not copy them, and do not convert them\n  in unrelated PRs. This rule is not yet lint-enforced.\n- **Anti-patterns reviewers reject** — they hide the dependency instead of\n  removing it:\n  - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.\n  - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule\n    (`@n8n/db` re-exports several operators/types, but this relabels the\n    dependency rather than removing it).\n  - Pushing `.manager` / `createQueryBuilder` / `repo.managerFor(ctx)` into\n    business logic to avoid an operator import — trades a visible leak for an\n    invisible one.\n  - A repository that `extends BaseRepository` / `extends Repository`, or that\n    exposes its table (public property, getter, or a `find(options)`\n    passthrough) — the inherited TypeORM surface must stay private to the table.\n\n### ESLint configuration layers\n\nRule policy lives in four shared configs in `@n8n/eslint-config`, and a package\nconfig picks exactly one:\n\n| layer | subpath | for |\n|---|---|---|\n| `baseConfig` | `@n8n/eslint-config/base` | runtime-agnostic libraries |\n| `backendConfig` | `@n8n/eslint-config/backend` | anything that runs on Node; adds the network and encryption boundaries |\n| `frontendConfig` | `@n8n/eslint-config/frontend` | Vue packages |\n| `nodesConfig` | `@n8n/eslint-config/nodes` | `n8n-nodes-base` and `@n8n/nodes-langchain`; adds the node and credential file rules |\n\nA package config may add `ignores`, an additive plugin config, a block that\nraises rules to `error`, and blocks scoped to `files`. It must not turn a rule\ndown for the whole package: every lint script runs with `--quiet`, so a `warn`\nenforces nothing and reads as if it did. The code-health rule\n`lint-config-layering` enforces this, with existing debt in\n`.code-health-baseline.json`, which only shrinks.\n\nTo stop enforcing a rule everywhere, retire it in `base.ts` with the count\nbehind the decision. To enforce one again in a package that is ready, set it to\n`error` there. `node scripts/lint-parity/majority.mjs` prints how many packages\ndowngrade each rule, and `scripts/lint-parity/snapshot.mjs` plus `diff.mjs`\nprove a config change only altered what you meant it to.\n\n### Encryption boundary\n\nNew code encrypts and decrypts only through `cipher.encryptV2()` /\n`cipher.decryptV2()` — the key-manager module decides which key is used and in\nwhich output format. Enforced in CI by the rules in\n`packages/@n8n/eslint-config/src/configs/encryption-boundary.ts` (part of\n`backendConfig`, and so of `nodesConfig`; every package that runs on Node\nextends one of those layers):\n\n- `Cipher` does not expose the legacy or explicit-key methods.\n- The raw AES classes stay inside `packages/core/src/encryption/`.\n- **Deployment keys are never deleted** — data encrypted with a key becomes\n  unreadable without it. Deactivate keys instead; the repository does not expose\n  deletion and database triggers reject direct deletion.\n- Inline disables that name these rules, and bare line-form disables, are\n  themselves lint errors. The code-health rule `encryption-boundary` (CI\n  \"Static Analysis\") is the enforcement layer: it checks that every package\n  that depends on `n8n-core` or `@n8n/db` extends `backendConfig` (or\n  `nodesConfig`) at `error` severity, and rejects every directive form that\n  would silence the\n  rules in non-test code (`eslint-disable*` and inline `eslint` configuration\n  comments). Widening the boundary happens in `encryption-boundary.ts` only;\n  that file and the rule files require security (IAM) approval via OWNERS.\n\n### Frontend Development\n- Refer to `packages/frontend/AGENTS.md`\n- **All UI text must use i18n** - add translations to `@n8n/i18n` package\n- **Use CSS variables directly** - never hardcode spacing as px values\n- **data-testid must be a single value** (no spaces or multiple values)\n- Always use the `design-system` skill in reviews\n\n### Verify changes\n\n- Before committing, run formatting and lint checks on changed files. Use\n  the package's configured tools through `pnpm exec` with explicit file paths.\n  Do not append file paths to `pnpm lint`; package scripts can still check\n  the whole package.\n- Run tests that cover the changed behavior from the owning package:\n  `pnpm test <test-file> --maxWorkers=1`. Or use the root wrapper:\n  `pnpm agent:test --filter <package> -- <test-file> --maxWorkers=1`.\n  For Playwright, use `pnpm agent:playwright -- <spec-file> --workers=1`.\n- For routine commits, run checks one at a time. Use one test worker by\n  default. Do not run full frontend typechecks locally. Use CI for\n  comprehensive lint, typechecks, and test suites.\n- For documentation-only changes, review the diff and run `git diff --check`.\n  Skip code tests when no behavior changed.\n- Report which checks ran and which checks were left to CI.\n- Use Vitest for unit tests. Use\n  [Playwright](packages/quality/testing/playwright/AGENTS.md) when a test needs its\n  browser, fixtures, or managed containers.\n- For Vitest packages with `@n8n/di` decorators, use\n  `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`.\n- Check import and mock side effects before running tests. Keep tests out of\n  user-owned directories. Set `N8N_USER_FOLDER` to a test-owned directory before\n  importing n8n settings. Clean up only paths that the test created.\n- CI runs [`@n8n/code-health`](packages/quality/policy/code-health/README.md) static\n  analysis on PRs. It checks monorepo rules, including dependency hygiene and\n  encryption-boundary coverage.\n\n### Local development\n\n| Goal | Command |\n|------|---------|\n| Run product E2E against a local instance | `pnpm --filter=n8n-playwright test:local` |\n| Run backend with PostgreSQL, Redis, email, and proxy services | `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`, then `pnpm dev:be` |\n| Add editor hot reload | `pnpm dev:fe:editor` |\n| Start a Codespace backend and share its port | `pnpm dev:up` |\n\nThe root `pnpm dev` command does not start a server. See the\n[Playwright guide](packages/quality/testing/playwright/README.md) and the\n[Codespaces guide](.devcontainer/codespaces/README.md) for details.\n\n### Common Development Tasks\n\nWhen implementing features:\n1. Define API types in `packages/@n8n/api-types`\n2. Implement backend logic in `packages/cli` module, follow\n   `scripts/backend-module/backend-module-guide.md`\n3. Add API endpoints via controllers\n4. Update frontend in `packages/frontend/editor-ui` with i18n support. For a\n   frontend feature module, obey\n   `packages/@n8n/module-cli/frontend-module-guide.md`\n5. Write tests with proper mocks\n\n## Design Principles\n\n### Security Must Not Degrade the Building Experience\n\nSecurity improvements, whether driven by enterprise requirements or internal\nstandards, must NEVER add friction to the common-case building experience. When\ndesigning security-related features (defaults, behaviors, flows, error\nhandling), apply these checks:\n\n- **No friction for the common case:** A community builder's workflow should\n  remain intuitive. Security should be invisible when it can be.\n- **Migration and upgrade paths:** Existing users must have a clear,\n  non-disruptive path forward when defaults or behaviors change.\n- **Security layers on top, not in competition:** Great UX and strong security\n  are not trade-offs. They're both required. If a design forces a choice\n  between them, the design needs more work.\n\n### Security Fix Hygiene\n\n**This is a public repository.** When working on security fixes, never expose\nthe attack vector or vulnerability type in any public-facing artifact. Attackers\nmonitor open-source repos for signals like branch names, commit messages, PR\ntitles, test descriptions, and Linear URLs.\n\n**Rules for security fixes:**\n\n- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals\n  the vulnerability. Rename to describe the fix neutrally\n  (e.g. `node-1234-improve-request-handling`, not\n  `node-1234-fix-ddos-vulnerability`).\n- **Commit messages:** Describe what the code now does, not the threat it\n  prevents (e.g. `fix: add payload size validation`, not\n  `fix: prevent denial of service`).\n- **Test descriptions:** Use neutral, functional language\n  (e.g. `'should sanitize query parameters'`, not\n  `'should prevent SQL injection'`).\n- **Code comments:** Do not describe the attack scenario in comments.\n- **Linear references:** Never include the URL slug\n  (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).\n\n### Customer Confidentiality\n\n**This is a public repository.** Never mention customer names in any\npublic-facing artifact — not all customers have agreed to be named publicly,\nand naming them can reveal security-relevant details about their setup.\n\nThis applies to PR titles and descriptions, branch names, commit messages,\ncode, code comments, test names and test data, and fixtures. When implementing\na customer request, describe the use case neutrally (e.g. \"a customer with a\nlarge multi-main setup\", not the company name) and use generic placeholder\nnames (e.g. `Acme Corp`) in tests and examples.\n\n## Github Guidelines\n- When creating a PR, use the conventions in\n  `.github/pull_request_template.md` and\n  `.github/pull_request_title_conventions.md`.\n- Use `gh pr create --draft` to create draft PRs.\n- If there is a corresponding Linear ticket, reference it in the PR\n  description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not\n  create a Linear ticket on your own — ask first.\n- always link to the github issue if mentioned in the linear ticket.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/n8n-io/n8n/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\nThis file provides guidance on how to work with the n8n repository.\n\n## Project Overview\n\nn8n is a workflow automation platform written in TypeScript, using a monorepo\nstructure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js\nfrontend, and extensible node-based workflow engine.\n\n## General Guidelines\n\n- Always use pnpm\n- Write all technical text (code comments, PR descriptions, issue and ticket\n  descriptions, docs) in ASD-STE100 Simplified Technical English: use short\n  sentences, the active voice, and one instruction for each sentence\n- **JSDoc on `@Env(...)` config properties is public documentation.** The\n  docs team exports these comments into the environment variable reference on\n  docs.n8n.io. Write them for a self-hosting operator and follow the\n  `n8n:env-var-docs` skill, which applies the n8n docs style guide and\n  overrides the ASD-STE100 rule above for these comments\n- **Secrets on the command line:** if a developer opted into anonymous dev\n  metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments\n  of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a\n  subcommand or baked into a flag — are dropped, and the home dir is stripped from\n  paths, but other args are sent as-is — so never put secrets in a command. Pass\n  sensitive values via environment variables, which are never captured.\n- When adding comments, keep them concise and to the point - explain the \"why\"\n  in a line or two; don't be overly verbose. Comments should be scoped and\n  relevant to the surrounding code, not just to the current task\n- We use Linear as a ticket tracking system\n- We use Posthog for feature flags\n- To find registered telemetry events (names, descriptions, properties), run\n  `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The\n  registry is being adopted incrementally, so search call sites if the catalog\n  has no match. The `n8n:telemetry` skill covers adding or changing events\n- When starting to work on a new ticket – create a new branch from fresh\n  master with the name specified in Linear ticket\n- When creating a new branch for a ticket in Linear - use the branch name\n  suggested by Linear, **unless it is a security fix** (see Security Fix\n  Hygiene below)\n- Use mermaid diagrams in MD files when you need to visualise something\n- Write an ADR only when asked. When a change makes a decision that an\n  engineer could challenge in 12 months, say so in one line and let the\n  human decide. Read [docs/adr/README.md](docs/adr/README.md) before you\n  write one. CI enforces its conventions\n- **Developing v3 features:** land normal feature work on `master` behind an\n  opt-in flag; introduce breaking changes only on the `3.x` branch. See\n  [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).\n- The AI gateway feature is **\"Gateway credits\"** in user-facing text (UI copy,\n  error messages, prompts). Only internal identifiers, i18n keys, telemetry, and\n  comments keep the historical `n8nConnect` / `n8n credits` / AI Gateway names\n- **Shared utilities:** before you hand-roll a utility (`isRecord`, secret or\n  PII redaction, JSON extraction from LLM output, Zod to JSON Schema, model-id\n  parsing, AI client HTTP transport and response-size limiting, …), you MUST\n  check the shared packages for an existing\n  implementation and use it: `@n8n/utils` (generic helpers, redaction),\n  `@n8n/ai-utilities` (AI- and LLM-specific helpers) and `n8n-workflow`\n  (workflow graph and traversal). A new shared helper usually belongs in one of\n  these packages too; domain logic stays in the package that owns the domain.\n\n## Agent Skills and Claude Code Plugin\n\nn8n shared skills live in `.agents/skills/`. Claude Code consumes them through\nsymlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`\ndirectly. Harness-specific overrides remain real directories in the harness\npath, such as `.opencode/skills/setup-mcps/`. See\n[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.\n\nn8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and\nare namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.\n`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See\n[plugin README](.claude/plugins/n8n/README.md) for structure and details.\n\n## Essential Commands\n\nFor routine pre-commit checks, follow [Verify changes](#verify-changes).\nFor focused tests, use `pnpm agent:test` or `pnpm agent:playwright`.\nPass test files and worker limits after `--`. Run each command with `--help`\nfor its options.\n\n`pnpm agent:lint` and `pnpm agent:typecheck` run full-repo checks by default.\nWith `--filter <package>`, they still check the whole package. These wrappers\nsave logs and reduce console output. They do not reduce CPU or memory use.\nDo not use them as routine pre-commit checks.\n\n### Fresh checkout / agent setup\n\nFor a fresh checkout (cat-bot, a new hire, any agent verifying the repo\nbuilds), prefer `pnpm agent:setup` over running install + build + tests by\nhand. It chains them in one process, caps per-process memory and turbo\nconcurrency so a 6GB box doesn't OOM, streams all output to\n`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary\nper step plus the tail of the failing log. A machine-readable\n`.agent-setup/summary.json` is always written so a backgrounded run is\nreadable in a single shot — no polling, no scrolling logs.\n\n```bash\npnpm agent:setup                 # install → build → test (full suite)\npnpm agent:setup install         # one step at a time\npnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)\n```\n\n### Building\nUse `pnpm build` to build all packages. ALWAYS redirect the output of the\nbuild command to a file:\n\n```bash\npnpm build > build.log 2>&1\n```\n\nYou can inspect the last few lines of the build log file to check for errors:\n```bash\ntail -n 20 build.log\n```\n\nIf build outputs or the turbo cache are stale (e.g. after switching branches\nor worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight\nby default) for a fast recovery: it cleans build outputs and force-rebuilds\n(keeping `node_modules` and untracked files). If that doesn't fix your issue,\nuse `pnpm reset --full`, which also wipes untracked files and reinstalls\ndependencies.\n\n### Seeding a local instance\n\nAn empty instance is a bad place to test anything that reads a user's work.\nThese commands fill one. They are dev tooling on the private root package, so\nthey never reach a user.\n\n```bash\nN8N_API_KEY=<jwt> pnpm seed:preference   # 10 workflows in one house style, plus history\nN8N_API_KEY=<jwt> pnpm seed:account      # ~500 varied workflows across 30 projects\npnpm inspect:activity                    # read-only activity_event viewer on 127.0.0.1\n```\n\nBoth seed profiles delete their own prior output, so a re-run replaces it.\nThat clear step deletes anything named `[seed]` and any empty team project,\nwhoever made them, so do not point either at a shared instance. The viewer is\nunauthenticated and serves the whole table: keep it on loopback.\n\nSee [scripts/instance-seeding/AGENTS.md](scripts/instance-seeding/AGENTS.md) for\nprofiles, tokens, determinism, and the other commands.\n\n## Architecture Overview\n\n**Monorepo Structure:** pnpm workspaces with Turbo build orchestration\n\n### Package Structure\n\nThe monorepo is organized into these key packages:\n\n- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend\n- **`packages/workflow`**: Core workflow interfaces and types\n- **`packages/core`**: Workflow execution engine\n- **`packages/cli`**: Express server, REST API, and CLI commands\n- **`packages/frontend/editor-ui`**: Vue 3 frontend application\n- **`packages/frontend/@n8n/i18n`**: Internationalization for UI text\n- **`packages/nodes-base`**: Built-in nodes for integrations\n- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes\n- **`packages/@n8n/instance-ai`**: \"n8n Assistant\" in the UI, \"Instance AI\" in code — n8n Assistant backend. See its `CLAUDE.md` for architecture docs.\n- **`@n8n/design-system`**: Vue component library for UI consistency\n- **`@n8n/config`**: Centralized configuration management\n\n## Technology Stack\n\n- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library\n- **Backend:** Node.js + TypeScript + Express + TypeORM\n- **Testing:** Vitest (unit) + Playwright (UI, API, infrastructure, lifecycle, performance, and E2E orchestration)\n- **Database:** TypeORM with SQLite/PostgreSQL support\n- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks\n\n### Key Architectural Patterns\n\n1. **Dependency Injection**: Uses `@n8n/di` for IoC container\n2. **Controller-Service-Repository**: Backend follows MVC-like pattern\n3. **Event-Driven**: Internal event bus for decoupled communication\n4. **Context-Based Execution**: Different contexts for different node types\n5. **State Management**: Frontend uses Pinia stores\n6. **Design System**: Reusable components and design tokens are centralized in\n   `@n8n/design-system`, where all pure Vue components should be placed to\n   ensure consistency and reusability\n\n## Key Development Patterns\n\n- Each package has isolated build configuration and can be developed independently\n- Hot reload works across the full stack during development\n- Node development uses dedicated `node-dev` CLI tool\n- Workflow tests are JSON-based for integration testing\n- AI features have dedicated development workflow (`pnpm dev:ai`)\n\n### Workflow Traversal Utilities\n\nThe `n8n-workflow` package exports graph traversal utilities from\n`packages/workflow/src/common/`. Use these instead of custom traversal logic.\n\n**Key concept:** `workflow.connections` is indexed by **source node**.\nTo find parent nodes, use `mapConnectionsByDestination()` to invert it first.\n\n```typescript\nimport { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';\n\n// Finding parent nodes (predecessors) - requires inverted connections\nconst connectionsByDestination = mapConnectionsByDestination(workflow.connections);\nconst parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);\n\n// Finding child nodes (successors) - uses connections directly\nconst children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);\n```\n\n### TypeScript Best Practices\n- **NEVER use `any` type** - use proper types or `unknown`\n- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)\n- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication\n- **Lazy-load heavy modules** — if a module is only used in a specific code\n  path (not every request), use `await import()` at point of use instead of\n  top-level `import`. Applies especially to native modules and large parsers.\n\n### Error Handling\n- Don't use the deprecated `ApplicationError` class anywhere — it's a\n  compatibility shim kept only so community nodes keep resolving. Use one of\n  these instead, picking by cause:\n  - `UserError` — the user caused it (invalid input, unauthorized action,\n    business-rule violation).\n  - `OperationalError` — a transient, expected issue (network request failing,\n    DB query timing out) that should be handled gracefully.\n  - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,\n    failed assertion) that developers need to fix.\n- Import from appropriate error classes in each package\n\n### Persistence layer & the TypeORM boundary\n\nTypeORM (`@n8n/typeorm`) must stay in the **persistence layer**. The shared\n`@n8n/db` package and backend persistence adapters can import it. A module can\ncolocate or group its entities and repositories according to its domain.\nBusiness logic — services, controllers, handlers, commands, factories — must not\nimport from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). The\n`typeorm-persistence-boundary` Code Health rule recognizes entity and repository\ndeclarations. It scans backend packages that depend on `@n8n/db` or\n`@n8n/typeorm`. Tests, migrations, and explicit helper-only adapters are\nexceptions. Existing business-logic imports stay in the shrink-only Code Health\nbaseline. A new business-logic import fails CI.\n\n- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,\n  `FindOptionsWhere`, …), put it behind a **use-case-named repository method**\n  that takes plain parameters and returns domain-shaped values — not a generic\n  `find(options)` passthrough.\n- **Transactions:** transaction orchestration belongs in the persistence layer.\n  Don't reach for `.manager` / `.manager.transaction(...)` or\n  `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in\n  `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in\n  `txRunner.run(ctx, async (ctx) => …)`. The callback receives an\n  `OperationContext` carrying the active transaction; thread that `ctx` into the\n  repository methods you call. `run` **requires** a context — pass an empty `{}`\n  at the operation entry point, and reuse the one you were handed everywhere\n  below it (a context that already carries a transaction is joined, not nested).\n  The `Transaction` handle is opaque and never exposes a driver type to\n  business logic. See `oauth-token.service.ts` for a worked service example\n  (its repositories predate the composition rule below; do not copy their shape).\n- **Repositories compose, they don't extend.** A repository is the boundary\n  that keeps TypeORM out of business logic. If it extended `BaseRepository`,\n  every service that injects it would also get `find`, `save`, `delete`,\n  `createQueryBuilder` and `.manager` for free, and TypeORM would leak through\n  inferred types that no lint rule can see. So a repository is a plain\n  `@Service()` class that holds a **file-private `BaseRepository` subclass (the\n  table)** as a private field and resolves the manager with\n  `this.table.managerFor(ctx)`. The table is never exported or registered with\n  DI. Every data access is a named use-case method on the repository that\n  calls the table internally; there is no generic `find`/`save`/`delete`\n  unless you write it for one operation. See\n  `packages/cli/src/modules/inbound-auth-core/database/repositories/trusted-source.repository.ts`\n  for a worked example. The existing `extends BaseRepository` / `extends\n  Repository` repositories are legacy. Do not copy them, and do not convert them\n  in unrelated PRs. This rule is not yet lint-enforced.\n- **Anti-patterns reviewers reject** — they hide the dependency instead of\n  removing it:\n  - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.\n  - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule\n    (`@n8n/db` re-exports several operators/types, but this relabels the\n    dependency rather than removing it).\n  - Pushing `.manager` / `createQueryBuilder` / `repo.managerFor(ctx)` into\n    business logic to avoid an operator import — trades a visible leak for an\n    invisible one.\n  - A repository that `extends BaseRepository` / `extends Repository`, or that\n    exposes its table (public property, getter, or a `find(options)`\n    passthrough) — the inherited TypeORM surface must stay private to the table.\n\n### ESLint configuration layers\n\nRule policy lives in four shared configs in `@n8n/eslint-config`, and a package\nconfig picks exactly one:\n\n| layer | subpath | for |\n|---|---|---|\n| `baseConfig` | `@n8n/eslint-config/base` | runtime-agnostic libraries |\n| `backendConfig` | `@n8n/eslint-config/backend` | anything that runs on Node; adds the network and encryption boundaries |\n| `frontendConfig` | `@n8n/eslint-config/frontend` | Vue packages |\n| `nodesConfig` | `@n8n/eslint-config/nodes` | `n8n-nodes-base` and `@n8n/nodes-langchain`; adds the node and credential file rules |\n\nA package config may add `ignores`, an additive plugin config, a block that\nraises rules to `error`, and blocks scoped to `files`. It must not turn a rule\ndown for the whole package: every lint script runs with `--quiet`, so a `warn`\nenforces nothing and reads as if it did. The code-health rule\n`lint-config-layering` enforces this, with existing debt in\n`.code-health-baseline.json`, which only shrinks.\n\nTo stop enforcing a rule everywhere, retire it in `base.ts` with the count\nbehind the decision. To enforce one again in a package that is ready, set it to\n`error` there. `node scripts/lint-parity/majority.mjs` prints how many packages\ndowngrade each rule, and `scripts/lint-parity/snapshot.mjs` plus `diff.mjs`\nprove a config change only altered what you meant it to.\n\n### Encryption boundary\n\nNew code encrypts and decrypts only through `cipher.encryptV2()` /\n`cipher.decryptV2()` — the key-manager module decides which key is used and in\nwhich output format. Enforced in CI by the rules in\n`packages/@n8n/eslint-config/src/configs/encryption-boundary.ts` (part of\n`backendConfig`, and so of `nodesConfig`; every package that runs on Node\nextends one of those layers):\n\n- `Cipher` does not expose the legacy or explicit-key methods.\n- The raw AES classes stay inside `packages/core/src/encryption/`.\n- **Deployment keys are never deleted** — data encrypted with a key becomes\n  unreadable without it. Deactivate keys instead; the repository does not expose\n  deletion and database triggers reject direct deletion.\n- Inline disables that name these rules, and bare line-form disables, are\n  themselves lint errors. The code-health rule `encryption-boundary` (CI\n  \"Static Analysis\") is the enforcement layer: it checks that every package\n  that depends on `n8n-core` or `@n8n/db` extends `backendConfig` (or\n  `nodesConfig`) at `error` severity, and rejects every directive form that\n  would silence the\n  rules in non-test code (`eslint-disable*` and inline `eslint` configuration\n  comments). Widening the boundary happens in `encryption-boundary.ts` only;\n  that file and the rule files require security (IAM) approval via OWNERS.\n\n### Frontend Development\n- Refer to `packages/frontend/AGENTS.md`\n- **All UI text must use i18n** - add translations to `@n8n/i18n` package\n- **Use CSS variables directly** - never hardcode spacing as px values\n- **data-testid must be a single value** (no spaces or multiple values)\n- Always use the `design-system` skill in reviews\n\n### Verify changes\n\n- Before committing, run formatting and lint checks on changed files. Use\n  the package's configured tools through `pnpm exec` with explicit file paths.\n  Do not append file paths to `pnpm lint`; package scripts can still check\n  the whole package.\n- Run tests that cover the changed behavior from the owning package:\n  `pnpm test <test-file> --maxWorkers=1`. Or use the root wrapper:\n  `pnpm agent:test --filter <package> -- <test-file> --maxWorkers=1`.\n  For Playwright, use `pnpm agent:playwright -- <spec-file> --workers=1`.\n- For routine commits, run checks one at a time. Use one test worker by\n  default. Do not run full frontend typechecks locally. Use CI for\n  comprehensive lint, typechecks, and test suites.\n- For documentation-only changes, review the diff and run `git diff --check`.\n  Skip code tests when no behavior changed.\n- Report which checks ran and which checks were left to CI.\n- Use Vitest for unit tests. Use\n  [Playwright](packages/quality/testing/playwright/AGENTS.md) when a test needs its\n  browser, fixtures, or managed containers.\n- For Vitest packages with `@n8n/di` decorators, use\n  `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`.\n- Check import and mock side effects before running tests. Keep tests out of\n  user-owned directories. Set `N8N_USER_FOLDER` to a test-owned directory before\n  importing n8n settings. Clean up only paths that the test created.\n- CI runs [`@n8n/code-health`](packages/quality/policy/code-health/README.md) static\n  analysis on PRs. It checks monorepo rules, including dependency hygiene and\n  encryption-boundary coverage.\n\n### Local development\n\n| Goal | Command |\n|------|---------|\n| Run product E2E against a local instance | `pnpm --filter=n8n-playwright test:local` |\n| Run backend with PostgreSQL, Redis, email, and proxy services | `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`, then `pnpm dev:be` |\n| Add editor hot reload | `pnpm dev:fe:editor` |\n| Start a Codespace backend and share its port | `pnpm dev:up` |\n\nThe root `pnpm dev` command does not start a server. See the\n[Playwright guide](packages/quality/testing/playwright/README.md) and the\n[Codespaces guide](.devcontainer/codespaces/README.md) for details.\n\n### Common Development Tasks\n\nWhen implementing features:\n1. Define API types in `packages/@n8n/api-types`\n2. Implement backend logic in `packages/cli` module, follow\n   `scripts/backend-module/backend-module-guide.md`\n3. Add API endpoints via controllers\n4. Update frontend in `packages/frontend/editor-ui` with i18n support. For a\n   frontend feature module, obey\n   `packages/@n8n/module-cli/frontend-module-guide.md`\n5. Write tests with proper mocks\n\n## Design Principles\n\n### Security Must Not Degrade the Building Experience\n\nSecurity improvements, whether driven by enterprise requirements or internal\nstandards, must NEVER add friction to the common-case building experience. When\ndesigning security-related features (defaults, behaviors, flows, error\nhandling), apply these checks:\n\n- **No friction for the common case:** A community builder's workflow should\n  remain intuitive. Security should be invisible when it can be.\n- **Migration and upgrade paths:** Existing users must have a clear,\n  non-disruptive path forward when defaults or behaviors change.\n- **Security layers on top, not in competition:** Great UX and strong security\n  are not trade-offs. They're both required. If a design forces a choice\n  between them, the design needs more work.\n\n### Security Fix Hygiene\n\n**This is a public repository.** When working on security fixes, never expose\nthe attack vector or vulnerability type in any public-facing artifact. Attackers\nmonitor open-source repos for signals like branch names, commit messages, PR\ntitles, test descriptions, and Linear URLs.\n\n**Rules for security fixes:**\n\n- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals\n  the vulnerability. Rename to describe the fix neutrally\n  (e.g. `node-1234-improve-request-handling`, not\n  `node-1234-fix-ddos-vulnerability`).\n- **Commit messages:** Describe what the code now does, not the threat it\n  prevents (e.g. `fix: add payload size validation`, not\n  `fix: prevent denial of service`).\n- **Test descriptions:** Use neutral, functional language\n  (e.g. `'should sanitize query parameters'`, not\n  `'should prevent SQL injection'`).\n- **Code comments:** Do not describe the attack scenario in comments.\n- **Linear references:** Never include the URL slug\n  (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).\n\n### Customer Confidentiality\n\n**This is a public repository.** Never mention customer names in any\npublic-facing artifact — not all customers have agreed to be named publicly,\nand naming them can reveal security-relevant details about their setup.\n\nThis applies to PR titles and descriptions, branch names, commit messages,\ncode, code comments, test names and test data, and fixtures. When implementing\na customer request, describe the use case neutrally (e.g. \"a customer with a\nlarge multi-main setup\", not the company name) and use generic placeholder\nnames (e.g. `Acme Corp`) in tests and examples.\n\n## Github Guidelines\n- When creating a PR, use the conventions in\n  `.github/pull_request_template.md` and\n  `.github/pull_request_title_conventions.md`.\n- Use `gh pr create --draft` to create draft PRs.\n- If there is a corresponding Linear ticket, reference it in the PR\n  description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not\n  create a Linear ticket on your own — ask first.\n- always link to the github issue if mentioned in the linear ticket.\n","isInternal":false,"tokens":5815,"sizeBytes":24071},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":189},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":175},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":168}],"systemPromptSnippet":"<yakaai_skills repo=\"n8n-io/n8n\">\n<!-- File: AGENTS.md (Tokens: ~5815 | Category: root-instruction) -->\n# AGENTS.md\n\nThis file provides guidance on how to work with the n8n repository.\n\n## Project Overview\n\nn8n is a workflow automation platform written in TypeScript, using a monorepo\nstructure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js\nfrontend, and extensible node-based workflow engine.\n\n## General Guidelines\n\n- Always use pnpm\n- Write all technical text (code comments, PR descriptions, issue and ticket\n  descriptions, docs) in ASD-STE100 Simplified Technical English: use short\n  sentences, the active voice, and one instruction for each sentence\n- **JSDoc on `@Env(...)` config properties is public documentation.** The\n  docs team exports these comments into the environment variable reference on\n  docs.n8n.io. Write them for a self-hosting operator and follow the\n  `n8n:env-var-docs` skill, which applies the n8n docs style guide and\n  overrides the ASD-STE100 rule above for these comments\n- **Secrets on the command line:** if a developer opted into anonymous dev\n  metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments\n  of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a\n  subcommand or baked into a flag — are dropped, and the home dir is stripped from\n  paths, but other args are sent as-is — so never put secrets in a command. Pass\n  sensitive values via environment variables, which are never captured.\n- When adding comments, keep them concise and to the point - explain the \"why\"\n  in a line or two; don't be overly verbose. Comments should be scoped and\n  relevant to the surrounding code, not just to the current task\n- We use Linear as a ticket tracking system\n- We use Posthog for feature flags\n- To find registered telemetry events (names, descriptions, properties), run\n  `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The\n  registry is being adopted incrementally, so search call sites if the catalog\n  has no match. The `n8n:telemetry` skill covers adding or changing events\n- When starting to work on a new ticket – create a new branch from fresh\n  master with the name specified in Linear ticket\n- When creating a new branch for a ticket in Linear - use the branch name\n  suggested by Linear, **unless it is a security fix** (see Security Fix\n  Hygiene below)\n- Use mermaid diagrams in MD files when you need to visualise something\n- Write an ADR only when asked. When a change makes a decision that an\n  engineer could challenge in 12 months, say so in one line and let the\n  human decide. Read [docs/adr/README.md](docs/adr/README.md) before you\n  write one. CI enforces its conventions\n- **Developing v3 features:** land normal feature work on `master` behind an\n  opt-in flag; introduce breaking changes only on the `3.x` branch. See\n  [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).\n- The AI gateway feature is **\"Gateway credits\"** in user-facing text (UI copy,\n  error messages, prompts). Only internal identifiers, i18n keys, telemetry, and\n  comments keep the historical `n8nConnect` / `n8n credits` / AI Gateway names\n- **Shared utilities:** before you hand-roll a utility (`isRecord`, secret or\n  PII redaction, JSON extraction from LLM output, Zod to JSON Schema, model-id\n  parsing, AI client HTTP transport and response-size limiting, …), you MUST\n  check the shared packages for an existing\n  implementation and use it: `@n8n/utils` (generic helpers, redaction),\n  `@n8n/ai-utilities` (AI- and LLM-specific helpers) and `n8n-workflow`\n  (workflow graph and traversal). A new shared helper usually belongs in one of\n  these packages too; domain logic stays in the package that owns the domain.\n\n## Agent Skills and Claude Code Plugin\n\nn8n shared skills live in `.agents/skills/`. Claude Code consumes them through\nsymlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`\ndirectly. Harness-specific overrides remain real directories in the harness\npath, such as `.opencode/skills/setup-mcps/`. See\n[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.\n\nn8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and\nare namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.\n`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See\n[plugin README](.claude/plugins/n8n/README.md) for structure and details.\n\n## Essential Commands\n\nFor routine pre-commit checks, follow [Verify changes](#verify-changes).\nFor focused tests, use `pnpm agent:test` or `pnpm agent:playwright`.\nPass test files and worker limits after `--`. Run each command with `--help`\nfor its options.\n\n`pnpm agent:lint` and `pnpm agent:typecheck` run full-repo checks by default.\nWith `--filter <package>`, they still check the whole package. These wrappers\nsave logs and reduce console output. They do not reduce CPU or memory use.\nDo not use them as routine pre-commit checks.\n\n### Fresh checkout / agent setup\n\nFor a fresh checkout (cat-bot, a new hire, any agent verifying the repo\nbuilds), prefer `pnpm agent:setup` over running install + build + tests by\nhand. It chains them in one process, caps per-process memory and turbo\nconcurrency so a 6GB box doesn't OOM, streams all output to\n`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary\nper step plus the tail of the failing log. A machine-readable\n`.agent-setup/summary.json` is always written so a backgrounded run is\nreadable in a single shot — no polling, no scrolling logs.\n\n```bash\npnpm agent:setup                 # install → build → test (full suite)\npnpm agent:setup install         # one step at a time\npnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)\n```\n\n### Building\nUse `pnpm build` to build all packages. ALWAYS redirect the output of the\nbuild command to a file:\n\n```bash\npnpm build > build.log 2>&1\n```\n\nYou can inspect the last few lines of the build log file to check for errors:\n```bash\ntail -n 20 build.log\n```\n\nIf build outputs or the turbo cache are stale (e.g. after switching branches\nor worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight\nby default) for a fast recovery: it cleans build outputs and force-rebuilds\n(keeping `node_modules` and untracked files). If that doesn't fix your issue,\nuse `pnpm reset --full`, which also wipes untracked files and reinstalls\ndependencies.\n\n### Seeding a local instance\n\nAn empty instance is a bad place to test anything that reads a user's work.\nThese commands fill one. They are dev tooling on the private root package, so\nthey never reach a user.\n\n```bash\nN8N_API_KEY=<jwt> pnpm seed:preference   # 10 workflows in one house style, plus history\nN8N_API_KEY=<jwt> pnpm seed:account      # ~500 varied workflows across 30 projects\npnpm inspect:activity                    # read-only activity_event viewer on 127.0.0.1\n```\n\nBoth seed profiles delete their own prior output, so a re-run replaces it.\nThat clear step deletes anything named `[seed]` and any empty team project,\nwhoever made them, so do not point either at a shared instance. The viewer is\nunauthenticated and serves the whole table: keep it on loopback.\n\nSee [scripts/instance-seeding/AGENTS.md](scripts/instance-seeding/AGENTS.md) for\nprofiles, tokens, determinism, and the other commands.\n\n## Architecture Overview\n\n**Monorepo Structure:** pnpm workspaces with Turbo build orchestration\n\n### Package Structure\n\nThe monorepo is organized into these key packages:\n\n- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend\n- **`packages/workflow`**: Core workflow interfaces and types\n- **`packages/core`**: Workflow execution engine\n- **`packages/cli`**: Express server, REST API, and CLI commands\n- **`packages/frontend/editor-ui`**: Vue 3 frontend application\n- **`packages/frontend/@n8n/i18n`**: Internationalization for UI text\n- **`packages/nodes-base`**: Built-in nodes for integrations\n- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes\n- **`packages/@n8n/instance-ai`**: \"n8n Assistant\" in the UI, \"Instance AI\" in code — n8n Assistant backend. See its `CLAUDE.md` for architecture docs.\n- **`@n8n/design-system`**: Vue component library for UI consistency\n- **`@n8n/config`**: Centralized configuration management\n\n## Technology Stack\n\n- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library\n- **Backend:** Node.js + TypeScript + Express + TypeORM\n- **Testing:** Vitest (unit) + Playwright (UI, API, infrastructure, lifecycle, performance, and E2E orchestration)\n- **Database:** TypeORM with SQLite/PostgreSQL support\n- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks\n\n### Key Architectural Patterns\n\n1. **Dependency Injection**: Uses `@n8n/di` for IoC container\n2. **Controller-Service-Repository**: Backend follows MVC-like pattern\n3. **Event-Driven**: Internal event bus for decoupled communication\n4. **Context-Based Execution**: Different contexts for different node types\n5. **State Management**: Frontend uses Pinia stores\n6. **Design System**: Reusable components and design tokens are centralized in\n   `@n8n/design-system`, where all pure Vue components should be placed to\n   ensure consistency and reusability\n\n## Key Development Patterns\n\n- Each package has isolated build configuration and can be developed independently\n- Hot reload works across the full stack during development\n- Node development uses dedicated `node-dev` CLI tool\n- Workflow tests are JSON-based for integration testing\n- AI features have dedicated development workflow (`pnpm dev:ai`)\n\n### Workflow Traversal Utilities\n\nThe `n8n-workflow` package exports graph traversal utilities from\n`packages/workflow/src/common/`. Use these instead of custom traversal logic.\n\n**Key concept:** `workflow.connections` is indexed by **source node**.\nTo find parent nodes, use `mapConnectionsByDestination()` to invert it first.\n\n```typescript\nimport { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';\n\n// Finding parent nodes (predecessors) - requires inverted connections\nconst connectionsByDestination = mapConnectionsByDestination(workflow.connections);\nconst parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);\n\n// Finding child nodes (successors) - uses connections directly\nconst children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);\n```\n\n### TypeScript Best Practices\n- **NEVER use `any` type** - use proper types or `unknown`\n- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)\n- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication\n- **Lazy-load heavy modules** — if a module is only used in a specific code\n  path (not every request), use `await import()` at point of use instead of\n  top-level `import`. Applies especially to native modules and large parsers.\n\n### Error Handling\n- Don't use the deprecated `ApplicationError` class anywhere — it's a\n  compatibility shim kept only so community nodes keep resolving. Use one of\n  these instead, picking by cause:\n  - `UserError` — the user caused it (invalid input, unauthorized action,\n    business-rule violation).\n  - `OperationalError` — a transient, expected issue (network request failing,\n    DB query timing out) that should be handled gracefully.\n  - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,\n    failed assertion) that developers need to fix.\n- Import from appropriate error classes in each package\n\n### Persistence layer & the TypeORM boundary\n\nTypeORM (`@n8n/typeorm`) must stay in the **persistence layer**. The shared\n`@n8n/db` package and backend persistence adapters can import it. A module can\ncolocate or group its entities and repositories according to its domain.\nBusiness logic — services, controllers, handlers, commands, factories — must not\nimport from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). The\n`typeorm-persistence-boundary` Code Health rule recognizes entity and repository\ndeclarations. It scans backend packages that depend on `@n8n/db` or\n`@n8n/typeorm`. Tests, migrations, and explicit helper-only adapters are\nexceptions. Existing business-logic imports stay in the shrink-only Code Health\nbaseline. A new business-logic import fails CI.\n\n- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,\n  `FindOptionsWhere`, …), put it behind a **use-case-named repository method**\n  that takes plain parameters and returns domain-shaped values — not a generic\n  `find(options)` passthrough.\n- **Transactions:** transaction orchestration belongs in the persistence layer.\n  Don't reach for `.manager` / `.manager.transaction(...)` or\n  `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in\n  `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in\n  `txRunner.run(ctx, async (ctx) => …)`. The callback receives an\n  `OperationContext` carrying the active transaction; thread that `ctx` into the\n  repository methods you call. `run` **requires** a context — pass an empty `{}`\n  at the operation entry point, and reuse the one you were handed everywhere\n  below it (a context that already carries a transaction is joined, not nested).\n  The `Transaction` handle is opaque and never exposes a driver type to\n  business logic. See `oauth-token.service.ts` for a worked service example\n  (its repositories predate the composition rule below; do not copy their shape).\n- **Repositories compose, they don't extend.** A repository is the boundary\n  that keeps TypeORM out of business logic. If it extended `BaseRepository`,\n  every service that injects it would also get `find`, `save`, `delete`,\n  `createQueryBuilder` and `.manager` for free, and TypeORM would leak through\n  inferred types that no lint rule can see. So a repository is a plain\n  `@Service()` class that holds a **file-private `BaseRepository` subclass (the\n  table)** as a private field and resolves the manager with\n  `this.table.managerFor(ctx)`. The table is never exported or registered with\n  DI. Every data access is a named use-case method on the repository that\n  calls the table internally; there is no generic `find`/`save`/`delete`\n  unless you write it for one operation. See\n  `packages/cli/src/modules/inbound-auth-core/database/repositories/trusted-source.repository.ts`\n  for a worked example. The existing `extends BaseRepository` / `extends\n  Repository` repositories are legacy. Do not copy them, and do not convert them\n  in unrelated PRs. This rule is not yet lint-enforced.\n- **Anti-patterns reviewers reject** — they hide the dependency instead of\n  removing it:\n  - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.\n  - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule\n    (`@n8n/db` re-exports several operators/types, but this relabels the\n    dependency rather than removing it).\n  - Pushing `.manager` / `createQueryBuilder` / `repo.managerFor(ctx)` into\n    business logic to avoid an operator import — trades a visible leak for an\n    invisible one.\n  - A repository that `extends BaseRepository` / `extends Repository`, or that\n    exposes its table (public property, getter, or a `find(options)`\n    passthrough) — the inherited TypeORM surface must stay private to the table.\n\n### ESLint configuration layers\n\nRule policy lives in four shared configs in `@n8n/eslint-config`, and a package\nconfig picks exactly one:\n\n| layer | subpath | for |\n|---|---|---|\n| `baseConfig` | `@n8n/eslint-config/base` | runtime-agnostic libraries |\n| `backendConfig` | `@n8n/eslint-config/backend` | anything that runs on Node; adds the network and encryption boundaries |\n| `frontendConfig` | `@n8n/eslint-config/frontend` | Vue packages |\n| `nodesConfig` | `@n8n/eslint-config/nodes` | `n8n-nodes-base` and `@n8n/nodes-langchain`; adds the node and credential file rules |\n\nA package config may add `ignores`, an additive plugin config, a block that\nraises rules to `error`, and blocks scoped to `files`. It must not turn a rule\ndown for the whole package: every lint script runs with `--quiet`, so a `warn`\nenforces nothing and reads as if it did. The code-health rule\n`lint-config-layering` enforces this, with existing debt in\n`.code-health-baseline.json`, which only shrinks.\n\nTo stop enforcing a rule everywhere, retire it in `base.ts` with the count\nbehind the decision. To enforce one again in a package that is ready, set it to\n`error` there. `node scripts/lint-parity/majority.mjs` prints how many packages\ndowngrade each rule, and `scripts/lint-parity/snapshot.mjs` plus `diff.mjs`\nprove a config change only altered what you meant it to.\n\n### Encryption boundary\n\nNew code encrypts and decrypts only through `cipher.encryptV2()` /\n`cipher.decryptV2()` — the key-manager module decides which key is used and in\nwhich output format. Enforced in CI by the rules in\n`packages/@n8n/eslint-config/src/configs/encryption-boundary.ts` (part of\n`backendConfig`, and so of `nodesConfig`; every package that runs on Node\nextends one of those layers):\n\n- `Cipher` does not expose the legacy or explicit-key methods.\n- The raw AES classes stay inside `packages/core/src/encryption/`.\n- **Deployment keys are never deleted** — data encrypted with a key becomes\n  unreadable without it. Deactivate keys instead; the repository does not expose\n  deletion and database triggers reject direct deletion.\n- Inline disables that name these rules, and bare line-form disables, are\n  themselves lint errors. The code-health rule `encryption-boundary` (CI\n  \"Static Analysis\") is the enforcement layer: it checks that every package\n  that depends on `n8n-core` or `@n8n/db` extends `backendConfig` (or\n  `nodesConfig`) at `error` severity, and rejects every directive form that\n  would silence the\n  rules in non-test code (`eslint-disable*` and inline `eslint` configuration\n  comments). Widening the boundary happens in `encryption-boundary.ts` only;\n  that file and the rule files require security (IAM) approval via OWNERS.\n\n### Frontend Development\n- Refer to `packages/frontend/AGENTS.md`\n- **All UI text must use i18n** - add translations to `@n8n/i18n` package\n- **Use CSS variables directly** - never hardcode spacing as px values\n- **data-testid must be a single value** (no spaces or multiple values)\n- Always use the `design-system` skill in reviews\n\n### Verify changes\n\n- Before committing, run formatting and lint checks on changed files. Use\n  the package's configured tools through `pnpm exec` with explicit file paths.\n  Do not append file paths to `pnpm lint`; package scripts can still check\n  the whole package.\n- Run tests that cover the changed behavior from the owning package:\n  `pnpm test <test-file> --maxWorkers=1`. Or use the root wrapper:\n  `pnpm agent:test --filter <package> -- <test-file> --maxWorkers=1`.\n  For Playwright, use `pnpm agent:playwright -- <spec-file> --workers=1`.\n- For routine commits, run checks one at a time. Use one test worker by\n  default. Do not run full frontend typechecks locally. Use CI for\n  comprehensive lint, typechecks, and test suites.\n- For documentation-only changes, review the diff and run `git diff --check`.\n  Skip code tests when no behavior changed.\n- Report which checks ran and which checks were left to CI.\n- Use Vitest for unit tests. Use\n  [Playwright](packages/quality/testing/playwright/AGENTS.md) when a test needs its\n  browser, fixtures, or managed containers.\n- For Vitest packages with `@n8n/di` decorators, use\n  `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`.\n- Check import and mock side effects before running tests. Keep tests out of\n  user-owned directories. Set `N8N_USER_FOLDER` to a test-owned directory before\n  importing n8n settings. Clean up only paths that the test created.\n- CI runs [`@n8n/code-health`](packages/quality/policy/code-health/README.md) static\n  analysis on PRs. It checks monorepo rules, including dependency hygiene and\n  encryption-boundary coverage.\n\n### Local development\n\n| Goal | Command |\n|------|---------|\n| Run product E2E against a local instance | `pnpm --filter=n8n-playwright test:local` |\n| Run backend with PostgreSQL, Redis, email, and proxy services | `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`, then `pnpm dev:be` |\n| Add editor hot reload | `pnpm dev:fe:editor` |\n| Start a Codespace backend and share its port | `pnpm dev:up` |\n\nThe root `pnpm dev` command does not start a server. See the\n[Playwright guide](packages/quality/testing/playwright/README.md) and the\n[Codespaces guide](.devcontainer/codespaces/README.md) for details.\n\n### Common Development Tasks\n\nWhen implementing features:\n1. Define API types in `packages/@n8n/api-types`\n2. Implement backend logic in `packages/cli` module, follow\n   `scripts/backend-module/backend-module-guide.md`\n3. Add API endpoints via controllers\n4. Update frontend in `packages/frontend/editor-ui` with i18n support. For a\n   frontend feature module, obey\n   `packages/@n8n/module-cli/frontend-module-guide.md`\n5. Write tests with proper mocks\n\n## Design Principles\n\n### Security Must Not Degrade the Building Experience\n\nSecurity improvements, whether driven by enterprise requirements or internal\nstandards, must NEVER add friction to the common-case building experience. When\ndesigning security-related features (defaults, behaviors, flows, error\nhandling), apply these checks:\n\n- **No friction for the common case:** A community builder's workflow should\n  remain intuitive. Security should be invisible when it can be.\n- **Migration and upgrade paths:** Existing users must have a clear,\n  non-disruptive path forward when defaults or behaviors change.\n- **Security layers on top, not in competition:** Great UX and strong security\n  are not trade-offs. They're both required. If a design forces a choice\n  between them, the design needs more work.\n\n### Security Fix Hygiene\n\n**This is a public repository.** When working on security fixes, never expose\nthe attack vector or vulnerability type in any public-facing artifact. Attackers\nmonitor open-source repos for signals like branch names, commit messages, PR\ntitles, test descriptions, and Linear URLs.\n\n**Rules for security fixes:**\n\n- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals\n  the vulnerability. Rename to describe the fix neutrally\n  (e.g. `node-1234-improve-request-handling`, not\n  `node-1234-fix-ddos-vulnerability`).\n- **Commit messages:** Describe what the code now does, not the threat it\n  prevents (e.g. `fix: add payload size validation`, not\n  `fix: prevent denial of service`).\n- **Test descriptions:** Use neutral, functional language\n  (e.g. `'should sanitize query parameters'`, not\n  `'should prevent SQL injection'`).\n- **Code comments:** Do not describe the attack scenario in comments.\n- **Linear references:** Never include the URL slug\n  (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).\n\n### Customer Confidentiality\n\n**This is a public repository.** Never mention customer names in any\npublic-facing artifact — not all customers have agreed to be named publicly,\nand naming them can reveal security-relevant details about their setup.\n\nThis applies to PR titles and descriptions, branch names, commit messages,\ncode, code comments, test names and test data, and fixtures. When implementing\na customer request, describe the use case neutrally (e.g. \"a customer with a\nlarge multi-main setup\", not the company name) and use generic placeholder\nnames (e.g. `Acme Corp`) in tests and examples.\n\n## Github Guidelines\n- When creating a PR, use the conventions in\n  `.github/pull_request_template.md` and\n  `.github/pull_request_title_conventions.md`.\n- Use `gh pr create --draft` to create draft PRs.\n- If there is a corresponding Linear ticket, reference it in the PR\n  description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not\n  create a Linear ticket on your own — ask first.\n- always link to the github issue if mentioned in the linear ticket.\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/n8n-io/n8n/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}