chore: Add a CLAUDE.md file with instructions for Claude Code (#17868)

CLAUDE.md

@@ -0,0 +1,159 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in the n8n repository.
+
+## Project Overview
+
+n8n is a workflow automation platform written in TypeScript, using a monorepo
+structure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js
+frontend, and extensible node-based workflow engine.
+
+## General Guidelines
+
+- Always use pnpm
+- We use Linear as a ticket tracking system
+- We use Posthog for feature flags
+- When starting to work on a new ticket – create a new branch from fresh
+  master with the name specified in Linear ticket
+- When creating a new branch for a ticket in Linear - use the branch name
+  suggested by linear
+- Use mermaid diagrams in MD files when you need to visualise something
+
+## Essential Commands
+
+### Building
+Use `pnpm build` to build all packages. ALWAYS redirect the output of the
+build command to a file:
+
+```bash
+pnpm build > build.log 2>&1
+```
+
+You can inspect the last few lines of the build log file to check for errors:
+```bash
+tail -n 20 build.log
+```
+
+### Testing
+- `pnpm test` - Run all tests
+- `pnpm test:affected` - Runs tests based on what has changed since the last
+  commit
+- `pnpm dev:e2e` - E2E tests in development mode
+
+Running a particular test file requires going to the directory of that test
+and running: `pnpm test <test-file>`.
+
+When changing directories, use `pushd` to navigate into the directory and
+`popd` to return to the previous directory. When in doubt, use `pwd` to check
+your current directory.
+
+### Code Quality
+- `pnpm lint` - Lint code
+- `pnpm typecheck` - Run type checks
+
+Always run lint and typecheck before committing code to ensure quality.
+Execute these commands from within the specific package directory you're
+working on (e.g., `cd packages/cli && pnpm lint`). Run the full repository
+check only when preparing the final PR. When your changes affect type
+definitions, interfaces in `@n8n/api-types`, or cross-package dependencies,
+build the system before running lint and typecheck.
+
+## Architecture Overview
+
+**Monorepo Structure:** pnpm workspaces with Turbo build orchestration
+
+### Package Structure
+
+The monorepo is organized into these key packages:
+
+- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend
+- **`packages/workflow`**: Core workflow interfaces and types
+- **`packages/core`**: Workflow execution engine
+- **`packages/cli`**: Express server, REST API, and CLI commands
+- **`packages/editor-ui`**: Vue 3 frontend application
+- **`packages/@n8n/i18n`**: Internationalization for UI text
+- **`packages/nodes-base`**: Built-in nodes for integrations
+- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes
+- **`@n8n/design-system`**: Vue component library for UI consistency
+- **`@n8n/config`**: Centralized configuration management
+
+## Technology Stack
+
+- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library
+- **Backend:** Node.js + TypeScript + Express + TypeORM
+- **Testing:** Jest (unit) + Playwright (E2E)
+- **Database:** TypeORM with SQLite/PostgreSQL/MySQL support
+- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks
+
+### Key Architectural Patterns
+
+1. **Dependency Injection**: Uses `@n8n/di` for IoC container
+2. **Controller-Service-Repository**: Backend follows MVC-like pattern
+3. **Event-Driven**: Internal event bus for decoupled communication
+4. **Context-Based Execution**: Different contexts for different node types
+5. **State Management**: Frontend uses Pinia stores
+6. **Design System**: Reusable components and design tokens are centralized in
+   `@n8n/design-system`, where all pure Vue components should be placed to
+   ensure consistency and reusability
+
+## Key Development Patterns
+
+- Each package has isolated build configuration and can be developed independently
+- Hot reload works across the full stack during development
+- Node development uses dedicated `node-dev` CLI tool
+- Workflow tests are JSON-based for integration testing
+- AI features have dedicated development workflow (`pnpm dev:ai`)
+
+### TypeScript Best Practices
+- **NEVER use `any` type** - use proper types or `unknown`
+- **Avoid type casting with `as`** - use type guards or type predicates instead
+- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication
+
+### Error Handling
+- Don't use `ApplicationError` class in CLI and nodes for throwing errors,
+  because it's deprecated. Use `UnexpectedError`, `OperationalError` or
+  `UserError` instead.
+- Import from appropriate error classes in each package
+
+### Frontend Development
+- **All UI text must use i18n** - add translations to `@n8n/i18n` package
+- **Use CSS variables directly** - never hardcode spacing as px values
+- **data-test-id must be a single value** (no spaces or multiple values)
+
+When implementing CSS, refer to @packages/frontend/CLAUDE.md for guidelines on
+CSS variables and styling conventions.
+
+### Testing Guidelines
+- **Always work from within the package directory** when running tests
+- **Mock all external dependencies** in unit tests
+- **Confirm test cases with user** before writing unit tests
+- **Typecheck is critical before committing** - always run `pnpm typecheck`
+- **When modifying pinia stores**, check for unused computed properties
+
+What we use for testing and writing tests:
+- For testing nodes and other backend components, we use Jest for unit tests. Examples can be found in `packages/nodes-base/nodes/**/*test*`.
+- We use `nock` for server mocking
+- For frontend we use `vitest`
+- For e2e tests we use `Playwright` and `pnpm dev:e2e`. The old Cypress tests
+  are being migrated to Playwright, so please use Playwright for new tests.
+
+### Common Development Tasks
+
+When implementing features:
+1. Define API types in `packages/@n8n/api-types`
+2. Implement backend logic in `packages/cli` module, follow
+   `@packages/cli/scripts/backend-module/backend-module.guide.md`
+3. Add API endpoints via controllers
+4. Update frontend in `packages/editor-ui` with i18n support
+5. Write tests with proper mocks
+6. Run `pnpm typecheck` to verify types
+
+## Github Guidelines
+- When creating a PR, use the conventions in
+  `.github/pull_request_template.md` and
+  `.github/pull_request_title_conventions.md`.
+- Use `gh pr create --draft` to create draft PRs.
+- Always reference the Linear ticket in the PR description,
+  use `https://linear.app/n8n/issue/[TICKET-ID]`
+- always link to the github issue if mentioned in the linear ticket.

packages/frontend/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+Extra information, specific to the frontend codebase.
+
+### CSS Variables Reference
+
+Use the following CSS variables to maintain consistency across the
+application. These variables cover colors, spacing, typography, and borders.
+
+#### Colors
+```css
+/* Primary Colors */
+--color-primary-shade-1
+--color-primary
+--color-primary-tint-1
+--color-primary-tint-2
+--color-primary-tint-3
+
+/* Secondary Colors */
+--color-secondary-shade-1
+--color-secondary
+--color-secondary-tint-1
+--color-secondary-tint-3
+
+/* Success Colors */
+--color-success-shade-1
+--color-success
+--color-success-light
+--color-success-light-2
+--color-success-tint-1
+--color-success-tint-2
+
+/* Warning Colors */
+--color-warning-shade-1
+--color-warning
+--color-warning-tint-1
+--color-warning-tint-2
+
+/* Danger Colors */
+--color-danger-shade-1
+--color-danger
+--color-danger-tint-1
+--color-danger-tint-2
+
+/* Text Colors */
+--color-text-dark
+--color-text-base
+--color-text-light
+--color-text-lighter
+--color-text-xlight
+--color-text-danger
+
+/* Foreground Colors */
+--color-foreground-xdark
+--color-foreground-dark
+--color-foreground-base
+--color-foreground-light
+--color-foreground-xlight
+
+/* Background Colors */
+--color-background-dark
+--color-background-medium
+--color-background-base
+--color-background-light
+--color-background-xlight
+```
+
+#### Spacing
+```css
+--spacing-5xs: 2px
+--spacing-4xs: 4px
+--spacing-3xs: 6px
+--spacing-2xs: 8px
+--spacing-xs: 12px
+--spacing-s: 16px
+--spacing-m: 20px
+--spacing-l: 24px
+--spacing-xl: 32px
+--spacing-2xl: 48px
+--spacing-3xl: 64px
+--spacing-4xl: 128px
+--spacing-5xl: 256px
+```
+
+#### Typography
+```css
+--font-size-3xs: 10px
+--font-size-2xs: 12px
+--font-size-xs: 13px
+--font-size-s: 14px
+--font-size-m: 16px
+--font-size-l: 18px
+--font-size-xl: 20px
+--font-size-2xl: 28px
+
+--font-line-height-compact: 1.25
+--font-line-height-regular: 1.3
+--font-line-height-loose: 1.35
+--font-line-height-xloose: 1.5
+
+--font-weight-regular: 400
+--font-weight-bold: 600
+--font-family: InterVariable, sans-serif
+```
+
+#### Borders
+```css
+--border-radius-small: 2px
+--border-radius-base: 4px
+--border-radius-large: 8px
+--border-radius-xlarge: 12px
+
+--border-width-base: 1px
+--border-style-base: solid
+--border-base: var(--border-width-base) var(--border-style-base) var(--color-foreground-base)
+```
+