chore(sync): merge upstream/master into origin/master (2026-03-31)

.agents/design-system-style-rules.md

@@ -0,0 +1,62 @@
+# Design System Style Review Rules
+
+Use these rules when reviewing CSS/SCSS/Vue style changes, especially in
+`packages/frontend/` and `packages/frontend/@n8n/design-system/`.
+
+## 1) Token source priority
+
+Prefer this order when choosing visual values:
+
+1. Semantic tokens from
+   `packages/frontend/@n8n/design-system/src/css/_tokens.scss`
+2. Primitives from
+   `packages/frontend/@n8n/design-system/src/css/_primitives.scss`
+3. Hard-coded values only when no suitable token exists
+
+If no token exists, request a short rationale in the PR.
+
+## 2) Hard-coded visual values
+
+Flag hard-coded visual values and suggest token alternatives. This includes:
+
+- Colors (`#fff`, `rgb()`, `hsl()`, `oklch()`)
+- Spacing and sizing (`px`, `rem`, numeric layout constants in styles)
+- Radius, border widths/styles, and shadows
+- Typography values (font size, weight, line-height)
+- Motion values (durations and easing like `cubic-bezier(...)`)
+
+Severity: strong warning (expected migration to tokens/primitives when possible).
+
+## 3) Legacy token usage
+
+In `_tokens.scss`, the compatibility section labeled
+"Legacy tokens (kept for compatibility)" is considered legacy usage.
+
+When new or modified code uses these legacy token families, flag it as a
+migration opportunity and recommend semantic token usage where available.
+
+Severity: strong warning (discourage new usage, allow compatibility paths).
+
+## 4) Deprecated style and component surfaces
+
+Flag new usage of deprecated/legacy style surfaces in design-system components,
+for example:
+
+- `Button.legacy.scss` and legacy button override classes
+- Legacy button variants/types (for example `highlight`, `highlight-fill`)
+- Legacy component variants that exist for compatibility (for example legacy
+  tabs variant)
+
+Severity: strong warning (prefer modern semantic variants/components).
+
+## 5) Token substitution changes
+
+If a PR changes one token reference to another (for example
+`--text-color` -> `--text-color--subtle`), flag it as a soft warning.
+
+Ask for intent in the PR description/comment:
+
+- Intentional design adjustment, or
+- Potential accidental visual regression
+
+Do not treat token substitution as a hard failure by default.

.claude/commands/n8n-plan.md

@@ -1,10 +1,10 @@
 ---
 description: Plan n8n Linear ticket implementation
 argument-hint: [PAY-XXXX | DEV-XXXX | ENG-XXXX]
-allowed-tools: Task
+allowed-tools: Task, Agent, Read, Glob, Grep, Write, Bash
 ---
 
-Launch a Plan agent (built-in) to create an implementation plan for Linear issue $ARGUMENTS.
+Launch a Plan agent (built-in) to research and design an implementation plan for Linear issue $ARGUMENTS.
 
 The agent should:
 1. Fetch and analyze the Linear ticket using Linear MCP
@@ -15,4 +15,11 @@ The agent should:
 
 Apply n8n architectural patterns (monorepo structure, TypeScript standards, Vue 3 Composition API, Controller-Service-Repository, etc.).
 
-Return a detailed, actionable plan ready for implementation.
+The agent should return the full plan as text (it cannot write files). After receiving the result, save it to `.claude/plans/<TICKET-ID>.md` (e.g. `.claude/plans/PAY-1234.md`). Create the directory if needed. This directory is gitignored.
+
+The plan file should contain:
+- The ticket title and link
+- A summary of the ticket
+- The full implementation plan
+- Testing strategy
+- Risks and open questions

.claude/plugins/n8n/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "n8n",
+  "owner": {
+    "name": "n8n"
+  },
+  "plugins": [
+    {
+      "name": "n8n",
+      "source": "./"
+    }
+  ]
+}

.claude/plugins/n8n/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "n8n",
+  "description": "n8n Claude Code plugin — shared skills, commands, and agents for n8n development"
+}

.claude/plugins/n8n/README.md

@@ -0,0 +1,67 @@
+# n8n Claude Code Plugin
+
+Shared skills, commands, and agents for n8n development.
+
+## Skills
+
+### `n8n:setup-mcps`
+
+Configures commonly used MCP servers for n8n engineers.
+
+**Usage:**
+```
+/n8n:setup-mcps
+```
+
+**What it does:**
+1. Checks which MCPs are already configured (matches by URL, not name)
+2. Presents a multi-select menu of available MCPs (Linear, Notion, Context7, Figma)
+3. For each selected MCP, asks which scope to install in:
+   - **user** (recommended) — available across all projects
+   - **local** — only in this project (`settings.local.json`)
+4. Installs using official recommended commands
+
+**Note:** Project scope is intentionally not offered since `.claude/settings.json` is tracked in git.
+
+## Design Decisions
+
+### Why a plugin instead of standalone skills?
+
+To get the `n8n:` namespace prefix for all n8n-specific skills, avoiding name
+collisions with built-in or personal skills. Claude Code only supports
+colon-namespaced skills (`n8n:setup-mcps`) through the plugin system —
+standalone `.claude/skills/` entries cannot be namespaced. This also provides a
+home for future n8n skills, commands, and agents under the same `n8n:` prefix.
+
+### Why only user and local scope (no project scope)?
+
+Project scope writes MCP config to `.claude/settings.json`, which is tracked in
+git. Since MCP credentials are personal (OAuth tokens, API keys), they should
+not end up in version control. User scope makes MCPs available across all
+projects; local scope (`settings.local.json`) keeps them project-specific but
+gitignored.
+
+### Why ask scope per MCP instead of once for all?
+
+Engineers may want different scopes for different MCPs. For example, Context7
+and Figma are useful across all projects (user scope), while Linear or Notion
+might only be needed for this project (local scope).
+
+## Plugin Structure
+
+```
+.claude/plugins/n8n/
+├── .claude-plugin/
+│   ├── marketplace.json    # Marketplace manifest
+│   └── plugin.json         # Plugin identity
+├── skills/
+│   └── sample-skill/
+│       └── SKILL.md
+└── README.md
+```
+
+## Known Issues
+
+- Plugin skill namespacing requires omitting the `name` field from SKILL.md
+  frontmatter due to a [Claude Code bug](https://github.com/anthropics/claude-code/issues/17271).
+  The directory name is used as the skill identifier instead.

.claude/plugins/n8n/skills/setup-mcps/SKILL.md

@@ -0,0 +1,75 @@
+---
+description: >-
+  Configure MCP servers for n8n development. Use when the user says /setup-mcps
+  or asks to set up MCP servers for n8n.
+---
+
+# MCP Setup for n8n Development
+
+Configure commonly used MCP servers for n8n engineers.
+
+## Instructions
+
+1. First, check which MCPs are already configured by running:
+```bash
+claude mcp list
+```
+Parse the output and match by **URL/command**, not server name (users may have
+used different names). The URLs to check for:
+- Linear: `mcp.linear.app`
+- Notion: `mcp.notion.com`
+- Context7: `ctx7` or `context7-mcp`
+- Figma: `mcp.figma.com`
+
+Skip any MCP whose URL/command is already present (regardless of scope or name).
+
+2. Present the MCP selection menu using `AskUserQuestion` with `multiSelect: true`.
+Only show MCPs that are **not** already configured. If all are already configured,
+inform the user and skip the menu.
+
+| Option | Label | Description |
+|--------|-------|-------------|
+| Linear | `Linear` | Linear ticket management (HTTP, OAuth — opens browser to authenticate) |
+| Notion | `Notion` | Notion workspace integration (HTTP, OAuth — opens browser to authenticate) |
+| Context7 | `Context7` | Library documentation lookup (OAuth setup via CLI) |
+| Figma | `Figma` | Figma design integration (HTTP, OAuth — opens browser to authenticate) |
+
+3. Process each selected MCP **one at a time** in a loop. For each MCP:
+   a. Ask the user via `AskUserQuestion`: "Where should **{MCP name}** be installed?"
+      - **user** (default, recommended) — available in all projects
+      - **local** — only in this project
+   b. Run the install command for that MCP with the chosen scope
+   c. Then move to the next MCP and ask again
+
+Do NOT batch the scope question — ask separately for each MCP.
+Do NOT offer project scope — it modifies `.claude/settings.json` which is tracked in git.
+
+Commands per MCP:
+
+### Linear
+```bash
+claude mcp add -s {scope} linear-server --transport http https://mcp.linear.app/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+### Notion
+```bash
+claude mcp add -s {scope} notion --transport http https://mcp.notion.com/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+### Context7
+Tell the user to run this command themselves (it handles auth via OAuth automatically):
+
+```
+npx ctx7 setup --claude
+```
+
+### Figma
+```bash
+claude mcp add -s {scope} figma --transport http https://mcp.figma.com/mcp
+```
+After adding, tell the user to run `/mcp` in their next session to authenticate.
+
+5. After running the commands, confirm which MCPs were configured and note any
+   manual steps remaining (authentication via `/mcp`, Context7 setup).

.claude/settings.json

@@ -10,7 +10,20 @@
 			"Bash(pnpm test:*)",
 			"Bash(pnpm typecheck:*)",
 			"Bash(popd)",
-			"Bash(pushd:*)"
+			"Bash(pushd:*)",
+			"Bash(mkdir -p .claude/plans)",
+			"Write(.claude/plans/*)"
 		]
+	},
+	"extraKnownMarketplaces": {
+		"n8n": {
+			"source": {
+				"source": "directory",
+				"path": "./.claude/plugins/n8n"
+			}
+		}
+	},
+	"enabledPlugins": {
+		"n8n@n8n": true
 	}
 }