docs: rewrite CLAUDE.md and add AGENTS.md contributor guide (#928)

* docs: rewrite CLAUDE.md to match current codebase

Architecture section replaced with a directory-level map covering all
current subsystems (telemetry, community, triggers, n8n wrapper, tool-docs,
skills). Commands verified against package.json: removed broken
test:templates and stale migrate:fts5, added build:all, test:e2e,
fetch:community, generate:docs:incremental with pointers to the
MEMORY_N8N_UPDATE.md and MEMORY_TEMPLATE_UPDATE.md runbooks. Replaced
retired get_node_essentials/get_node_info guidance with get_node detail
levels. Removed the duplicated instruction block and version annotations,
fixed the attribution spelling. 208 lines down to 100.

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: add repository contributor guide

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

* docs: address Copilot review feedback

Mark the src/ map as non-exhaustive and add the scripts/ subsystem,
scope the attribution rule to exclude file contents unambiguously, and
mention src/scripts/ in the AGENTS.md project structure.

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: czlonkowski

AGENTS.md

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

CLAUDE.md

@@ -6,204 +6,96 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-n8n-mcp is a comprehensive documentation and knowledge server that provides AI assistants with complete access to n8n node information through the Model Context Protocol (MCP). It serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively.
-
-### Current Architecture:
-```
-src/
-├── loaders/
-│   └── node-loader.ts         # NPM package loader for both packages
-├── parsers/
-│   ├── node-parser.ts         # Enhanced parser with version support
-│   └── property-extractor.ts  # Dedicated property/operation extraction
-├── mappers/
-│   └── docs-mapper.ts         # Documentation mapping with fixes
-├── database/
-│   ├── schema.sql             # SQLite schema
-│   ├── node-repository.ts     # Data access layer
-│   └── database-adapter.ts    # Universal database adapter (NEW in v2.3)
-├── services/
-│   ├── property-filter.ts     # Filters properties to essentials (NEW in v2.4)
-│   ├── example-generator.ts   # Generates working examples (NEW in v2.4)
-│   ├── task-templates.ts      # Pre-configured node settings (NEW in v2.4)
-│   ├── config-validator.ts    # Configuration validation (NEW in v2.4)
-│   ├── enhanced-config-validator.ts # Operation-aware validation (NEW in v2.4.2)
-│   ├── node-specific-validators.ts  # Node-specific validation logic (NEW in v2.4.2)
-│   ├── property-dependencies.ts # Dependency analysis (NEW in v2.4)
-│   ├── type-structure-service.ts # Type structure validation (NEW in v2.22.21)
-│   ├── expression-validator.ts # n8n expression syntax validation (NEW in v2.5.0)
-│   └── workflow-validator.ts  # Complete workflow validation (NEW in v2.5.0)
-├── types/
-│   ├── type-structures.ts      # Type structure definitions (NEW in v2.22.21)
-│   ├── instance-context.ts     # Multi-tenant instance configuration
-│   └── session-state.ts        # Session persistence types (NEW in v2.24.1)
-├── constants/
-│   └── type-structures.ts      # 22 complete type structures (NEW in v2.22.21)
-├── templates/
-│   ├── template-fetcher.ts    # Fetches templates from n8n.io API (NEW in v2.4.1)
-│   ├── template-repository.ts # Template database operations (NEW in v2.4.1)
-│   └── template-service.ts    # Template business logic (NEW in v2.4.1)
-├── scripts/
-│   ├── rebuild.ts             # Database rebuild with validation
-│   ├── validate.ts            # Node validation (includes critical-node checks)
-│   ├── test-essentials.ts     # Test new essentials tools (NEW in v2.4)
-│   ├── test-enhanced-validation.ts # Test enhanced validation (NEW in v2.4.2)
-│   ├── test-structure-validation.ts # Test type structure validation (NEW in v2.22.21)
-│   ├── test-workflow-validation.ts # Test workflow validation (NEW in v2.5.0)
-│   ├── test-ai-workflow-validation.ts # Test AI workflow validation (NEW in v2.5.1)
-│   ├── test-mcp-tools.ts      # Test MCP tool enhancements (NEW in v2.5.1)
-│   ├── test-n8n-validate-workflow.ts # Test n8n_validate_workflow tool (NEW in v2.6.3)
-│   ├── test-typeversion-validation.ts # Test typeVersion validation (NEW in v2.6.1)
-│   ├── test-workflow-diff.ts  # Test workflow diff engine (NEW in v2.7.0)
-│   ├── test-tools-documentation.ts # Test tools documentation (NEW in v2.7.3)
-│   ├── fetch-templates.ts     # Fetch workflow templates from n8n.io (NEW in v2.4.1)
-│   └── test-templates.ts      # Test template functionality (NEW in v2.4.1)
-├── mcp/
-│   ├── server.ts              # MCP server with enhanced tools
-│   ├── tools.ts               # Tool definitions including new essentials
-│   ├── tools-documentation.ts # Tool documentation system (NEW in v2.7.3)
-│   └── index.ts               # Main entry point with mode selection
-├── utils/
-│   ├── console-manager.ts     # Console output isolation (NEW in v2.3.1)
-│   └── logger.ts              # Logging utility with HTTP awareness
-├── http-server-single-session.ts  # Single-session HTTP server (NEW in v2.3.1)
-│                                   # Session persistence API (NEW in v2.24.1)
-├── mcp-engine.ts              # Clean API for service integration (NEW in v2.3.1)
-│                                # Session persistence wrappers (NEW in v2.24.1)
-└── index.ts                   # Library exports
-```
+n8n-mcp is an MCP (Model Context Protocol) server that gives AI assistants access to n8n node documentation, workflow validation, and workflow management. Documentation and validation tools work offline against a bundled SQLite database of node information; management tools (`n8n_*`) operate on a live n8n instance when API credentials are configured.
 
 ## Common Development Commands
 
 ```bash
-# Build and Setup
-npm run build          # Build TypeScript (always run after changes)
+# Build
+npm run build          # Compile TypeScript (always run after changes)
+npm run build:all      # Sync skills pack + build UI apps + compile
 npm run rebuild        # Rebuild node database from n8n packages
-npm run validate       # Validate all node data in database
+npm run validate       # Validate node data in database
+npm run dev            # build + rebuild + validate
 
 # Testing
-npm test               # Run all tests
-npm run test:unit      # Run unit tests only
-npm run test:integration # Run integration tests
-npm run test:coverage  # Run tests with coverage report
-npm run test:watch     # Run tests in watch mode
-npm run test:structure-validation # Test type structure validation (Phase 3)
-
-# Run a single test file
-npm test -- tests/unit/services/property-filter.test.ts
-
-# Linting and Type Checking
-npm run lint           # Check TypeScript types (alias for typecheck)
-npm run typecheck      # Check TypeScript types
-
-# Running the Server
-npm start              # Start MCP server in stdio mode
-npm run start:http     # Start MCP server in HTTP mode
-npm run dev            # Build, rebuild database, and validate
-npm run dev:http       # Run HTTP server with auto-reload
-
-# Update n8n Dependencies
-npm run update:n8n:check  # Check for n8n updates (dry run)
-npm run update:n8n        # Update n8n packages to latest
-
-# Database Management
-npm run db:rebuild     # Rebuild database from scratch
-npm run migrate:fts5   # Migrate to FTS5 search (if needed)
-
-# Template Management
-npm run fetch:templates  # Fetch latest workflow templates from n8n.io
-npm run test:templates   # Test template functionality
+npm test               # Run all tests (vitest)
+npm run test:unit      # Unit tests only
+npm run test:integration # Integration tests
+npm run test:e2e       # End-to-end tests
+npm run test:coverage  # Coverage report
+npm test -- tests/unit/services/property-filter.test.ts  # Single file
+
+# Type checking
+npm run typecheck      # tsc --noEmit (npm run lint is an alias)
+
+# Running the server
+npm start              # MCP server in stdio mode
+npm run start:http     # MCP server in HTTP mode
+npm run dev:http       # HTTP server with auto-reload
+
+# n8n dependency updates — follow MEMORY_N8N_UPDATE.md
+npm run update:n8n:check  # Dry run
+npm run update:n8n        # Update n8n packages
+
+# Templates and community nodes
+npm run fetch:templates   # Fetch workflow templates from n8n.io — see MEMORY_TEMPLATE_UPDATE.md
+npm run fetch:community   # Fetch/refresh community nodes (upserts; preserves existing docs)
+npm run generate:docs:incremental  # Generate AI docs for community nodes missing them
 ```
 
-## High-Level Architecture
+## Architecture
 
-### Core Components
+Key subsystems of `src/` (non-exhaustive — smaller directories are omitted). This file intentionally stays at subsystem level; for file-level detail, explore the directories.
 
-1. **MCP Server** (`mcp/server.ts`)
-   - Implements Model Context Protocol for AI assistants
-   - Provides tools for searching, validating, and managing n8n nodes
-   - Supports both stdio (Claude Desktop) and HTTP modes
+- `mcp/` — MCP server, tool definitions (`tools.ts`, `tools-n8n-manager.ts`), request handlers, per-tool documentation (`tool-docs/`), bundled skills (`skills/`)
+- `database/` — SQLite storage: universal adapter over better-sqlite3/sql.js, `node-repository.ts` data access, FTS5 full-text search, `migrations/`
+- `loaders/`, `parsers/`, `mappers/` — node processing pipeline: load nodes from n8n packages → parse metadata and properties → map external documentation
+- `services/` — business logic: config/workflow/expression validators, validation profiles, workflow diff engine, auto-fixer, node similarity and version services, n8n API client, security/audit scanners
+- `templates/` — fetching and storing workflow templates from n8n.io
+- `community/` — community node fetching and documentation generation
+- `telemetry/` — opt-in anonymous usage telemetry
+- `triggers/` — trigger detection and registry
+- `n8n/` — n8n community node wrapper (N8N_MODE)
+- `scripts/` — maintenance CLI scripts (rebuild, validate, template/community fetching), compiled to `dist/scripts/`
+- `types/`, `constants/`, `utils/` — shared types, type structures, helpers
+- `http-server.ts`, `http-server-single-session.ts` — HTTP mode with session persistence
+- `mcp-engine.ts`, `mcp-tools-engine.ts` — clean API for embedding the server in other services
 
-2. **Database Layer** (`database/`)
-   - SQLite database storing all n8n node information
-   - Universal adapter pattern supporting both better-sqlite3 and sql.js
-   - Full-text search capabilities with FTS5
+### Key design patterns
 
-3. **Node Processing Pipeline**
-   - **Loader** (`loaders/node-loader.ts`): Loads nodes from n8n packages
-   - **Parser** (`parsers/node-parser.ts`): Extracts node metadata and structure
-   - **Property Extractor** (`parsers/property-extractor.ts`): Deep property analysis
-   - **Docs Mapper** (`mappers/docs-mapper.ts`): Maps external documentation
+1. **Repository pattern**: all database operations go through repository classes
+2. **Service layer**: business logic separated from data access
+3. **Validation profiles**: strictness levels `minimal`, `runtime`, `ai-friendly`, `strict`
+4. **Diff-based updates**: `n8n_update_partial_workflow` applies operation diffs, saving 80–90% of tokens vs full updates
 
-4. **Service Layer** (`services/`)
-   - **Property Filter**: Reduces node properties to AI-friendly essentials
-   - **Config Validator**: Multi-profile validation system
-   - **Type Structure Service**: Validates complex type structures (filter, resourceMapper, etc.)
-   - **Expression Validator**: Validates n8n expression syntax
-   - **Workflow Validator**: Complete workflow structure validation
+### MCP tools
 
-5. **Template System** (`templates/`)
-   - Fetches and stores workflow templates from n8n.io
-   - Provides pre-built workflow examples
-   - Supports template search and validation
+Two groups:
 
-### Key Design Patterns
+- **Documentation and validation** (offline, always available): `search_nodes`, `get_node`, `validate_node`, `validate_workflow`, `search_templates`, `get_template`, `tools_documentation`
+- **Management** (`n8n_*`, require n8n API configuration): workflow CRUD and partial updates, executions, workflow testing, versions, autofix, template deployment, credentials, datatables, instance audit
 
-1. **Repository Pattern**: All database operations go through repository classes
-2. **Service Layer**: Business logic separated from data access
-3. **Validation Profiles**: Different validation strictness levels (minimal, runtime, ai-friendly, strict)
-4. **Diff-Based Updates**: Efficient workflow updates using operation diffs
+`get_node` supports detail levels (`minimal`/`standard`/`full`) — request the smallest level that answers the question.
 
-### MCP Tools Architecture
+## Development Workflow
 
-The MCP server exposes tools in several categories:
+- After changing MCP server code: build, then ask the user to reload the MCP server before testing
+- Run `npm run typecheck` after every code change
+- Never commit directly to main — use feature branches and PRs
+- Add to every commit message and PR description: `Conceived by Romuald Członkowski - www.aiadvisors.pl/en`. The attribution belongs in commit messages and PR descriptions only — never in source, test, or documentation file contents
+- When reviewing issues, use the GH CLI (`gh`) to fetch the issue and all its comments
+- Do not use hyperbolic or dramatic language in comments and documentation
 
-1. **Discovery Tools**: Finding and exploring nodes
-2. **Configuration Tools**: Getting node details and examples
-3. **Validation Tools**: Validating configurations before deployment
-4. **Workflow Tools**: Complete workflow validation
-5. **Management Tools**: Creating and updating workflows (requires API config)
+### Sub-agents
 
-## Memories and Notes for Development
+- When a task divides into independent subtasks, spawn sub-agents to handle them in parallel; pick the best agent type per its description
+- Sub-agents must not spawn further sub-agents
+- Sub-agents must not commit or push — do that yourself
 
-### Development Workflow Reminders
-- When you make changes to MCP server, you need to ask the user to reload it before you test
-- When the user asks to review issues, you should use GH CLI to get the issue and all the comments
-- When the task can be divided into separated subtasks, you should spawn separate sub-agents to handle them in parallel
-- Use the best sub-agent for the task as per their descriptions
+### Pitfalls
 
-### Testing Best Practices
-- Always run `npm run build` before testing changes
-- Use `npm run dev` to rebuild database after package updates
-- Check coverage with `npm run test:coverage`
+- Database rebuilds take 2–3 minutes due to n8n package size
 - Integration tests require a clean database state
-
-### Common Pitfalls
-- The MCP server needs to be reloaded in Claude Desktop after changes
-- HTTP mode requires proper CORS and auth token configuration
-- Database rebuilds can take 2-3 minutes due to n8n package size
-- Always validate workflows before deployment to n8n
-
-### Performance Considerations
-- Use `get_node_essentials()` instead of `get_node_info()` for faster responses
-- Batch validation operations when possible
-- The diff-based update system saves 80-90% tokens on workflow updates
-
-### Agent Interaction Guidelines
-- Sub-agents are not allowed to spawn further sub-agents
-- When you use sub-agents, do not allow them to commit and push. That should be done by you
-
-### Development Best Practices
-- Run typecheck and lint after every code change
-
-# important-instruction-reminders
-Do what has been asked; nothing more, nothing less.
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-- When you make changes to MCP server, you need to ask the user to reload it before you test
-- When the user asks to review issues, you should use GH CLI to get the issue and all the comments
-- When the task can be divided into separated subtasks, you should spawn separate sub-agents to handle them in paralel
-- Use the best sub-agent for the task as per their descriptions
-- Do not use hyperbolic or dramatic language in comments and documentation
-- Add to every commit and PR: Concieved by Romuald Członkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations
+- HTTP mode requires proper auth token configuration
+- Always validate workflows before deploying them to n8n