diff --git a/AGENTS.md b/AGENTS.md
index da708130..143e6c74 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,41 +1,355 @@
-# Repository Guidelines
+# Evolution API - AI Agent Guidelines
+
+This document provides comprehensive guidelines for AI agents (Claude, GPT, Cursor, etc.) working with the Evolution API codebase.
+
+## Project Overview
+
+**Evolution API** is a production-ready, multi-tenant WhatsApp API platform built with Node.js, TypeScript, and Express.js. It supports multiple WhatsApp providers and extensive integrations with chatbots, CRM systems, and messaging platforms.
 
 ## Project Structure & Module Organization
-- `src/` – TypeScript source. Key areas: `api/controllers`, `api/routes`, `api/services`, `api/integrations/{channel,chatbot,event,storage}`, `config`, `utils`, `exceptions`.
-- `prisma/` – Prisma schema and migrations. Provider folders: `postgresql-migrations/`, `mysql-migrations/`. Use `DATABASE_PROVIDER` to target the provider.
-- `dist/` – Build output; do not edit.
-- `public/` – Static assets.
-- `Docker*`, `docker-compose*.yaml` – Local stack and deployment helpers.
+
+### Core Directories
+- **`src/`** – TypeScript source code with modular architecture
+  - `api/controllers/` – HTTP route handlers (thin layer)
+  - `api/services/` – Business logic (core functionality)
+  - `api/routes/` – Express route definitions (RouterBroker pattern)
+  - `api/integrations/` – External service integrations
+    - `channel/` – WhatsApp providers (Baileys, Business API, Evolution)
+    - `chatbot/` – AI/Bot integrations (OpenAI, Dify, Typebot, Chatwoot)
+    - `event/` – Event systems (WebSocket, RabbitMQ, SQS, NATS, Pusher)
+    - `storage/` – File storage (S3, MinIO)
+  - `dto/` – Data Transfer Objects (simple classes, no decorators)
+  - `guards/` – Authentication/authorization middleware
+  - `types/` – TypeScript type definitions
+  - `repository/` – Data access layer (Prisma)
+- **`prisma/`** – Database schemas and migrations
+  - `postgresql-schema.prisma` / `mysql-schema.prisma` – Provider-specific schemas
+  - `postgresql-migrations/` / `mysql-migrations/` – Provider-specific migrations
+- **`config/`** – Environment and application configuration
+- **`utils/`** – Shared utilities and helper functions
+- **`validate/`** – JSONSchema7 validation schemas
+- **`exceptions/`** – Custom HTTP exception classes
+- **`cache/`** – Redis and local cache implementations
+
+### Build & Deployment
+- **`dist/`** – Build output (do not edit directly)
+- **`public/`** – Static assets and media files
+- **`Docker*`**, **`docker-compose*.yaml`** – Containerization and local development stack
 
 ## Build, Test, and Development Commands
-- `npm run build` – Type-check (tsc) and bundle with `tsup` to `dist/`.
-- `npm run start` – Run dev server via `tsx src/main.ts`.
-- `npm run dev:server` – Watch mode for local development.
-- `npm run start:prod` – Run compiled app from `dist/`.
-- `npm run lint` / `npm run lint:check` – Auto-fix and check linting.
-- Database (choose provider): `export DATABASE_PROVIDER=postgresql` (or `mysql`), then:
-  - `npm run db:generate` – Generate Prisma client.
-  - `npm run db:migrate:dev` – Apply dev migrations and sync provider folder.
-  - `npm run db:deploy` – Apply migrations in non-dev environments.
-  - `npm run db:studio` – Open Prisma Studio.
-- Docker: `docker-compose up -d` to start local services.
 
-## Coding Style & Naming Conventions
-- TypeScript, 2-space indent, single quotes, trailing commas, 120-char max (Prettier).
-- Enforced by ESLint + Prettier; import order via `simple-import-sort`.
-- File names follow `feature.kind.ts` (e.g., `chat.router.ts`, `whatsapp.baileys.service.ts`).
-- Classes: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE_CASE.
+### Development Workflow
+```bash
+# Development server with hot reload
+npm run dev:server
+
+# Direct execution for testing
+npm start
+
+# Production build and run
+npm run build
+npm run start:prod
+```
+
+### Code Quality
+```bash
+# Linting and formatting
+npm run lint        # ESLint with auto-fix
+npm run lint:check  # ESLint check only
+
+# Commit with conventional commits
+npm run commit      # Interactive commit with Commitizen
+```
+
+### Database Management
+```bash
+# Set database provider first (CRITICAL)
+export DATABASE_PROVIDER=postgresql  # or mysql
+
+# Generate Prisma client
+npm run db:generate
+
+# Development migrations (with provider sync)
+npm run db:migrate:dev      # Unix/Mac
+npm run db:migrate:dev:win  # Windows
+
+# Production deployment
+npm run db:deploy      # Unix/Mac
+npm run db:deploy:win  # Windows
+
+# Database tools
+npm run db:studio      # Open Prisma Studio
+```
+
+### Docker Development
+```bash
+# Start local services (Redis, PostgreSQL, etc.)
+docker-compose up -d
+
+# Full development stack
+docker-compose -f docker-compose.dev.yaml up -d
+```
+
+## Coding Standards & Architecture Patterns
+
+### Code Style (Enforced by ESLint + Prettier)
+- **TypeScript strict mode** with full type coverage
+- **2-space indentation**, single quotes, trailing commas
+- **120-character line limit**
+- **Import order** via `simple-import-sort`
+- **File naming**: `feature.kind.ts` (e.g., `whatsapp.baileys.service.ts`)
+- **Naming conventions**:
+  - Classes: `PascalCase`
+  - Functions/variables: `camelCase`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Files: `kebab-case.type.ts`
+
+### Architecture Patterns
+
+#### Service Layer Pattern
+```typescript
+export class ExampleService {
+  constructor(private readonly waMonitor: WAMonitoringService) {}
+  
+  private readonly logger = new Logger('ExampleService');
+  
+  public async create(instance: InstanceDto, data: ExampleDto) {
+    // Business logic here
+    return { example: { ...instance, data } };
+  }
+  
+  public async find(instance: InstanceDto): Promise<ExampleDto | null> {
+    try {
+      const result = await this.waMonitor.waInstances[instance.instanceName].findData();
+      return result || null; // Return null on not found (Evolution pattern)
+    } catch (error) {
+      this.logger.error('Error finding data:', error);
+      return null; // Return null on error (Evolution pattern)
+    }
+  }
+}
+```
+
+#### Controller Pattern (Thin Layer)
+```typescript
+export class ExampleController {
+  constructor(private readonly exampleService: ExampleService) {}
+  
+  public async createExample(instance: InstanceDto, data: ExampleDto) {
+    return this.exampleService.create(instance, data);
+  }
+}
+```
+
+#### RouterBroker Pattern
+```typescript
+export class ExampleRouter extends RouterBroker {
+  constructor(...guards: any[]) {
+    super();
+    this.router.post(this.routerPath('create'), ...guards, async (req, res) => {
+      const response = await this.dataValidate<ExampleDto>({
+        request: req,
+        schema: exampleSchema, // JSONSchema7
+        ClassRef: ExampleDto,
+        execute: (instance, data) => controller.createExample(instance, data),
+      });
+      res.status(201).json(response);
+    });
+  }
+}
+```
+
+#### DTO Pattern (Simple Classes)
+```typescript
+// CORRECT - Evolution API pattern (no decorators)
+export class ExampleDto {
+  name: string;
+  description?: string;
+  enabled: boolean;
+}
+
+// INCORRECT - Don't use class-validator decorators
+export class BadExampleDto {
+  @IsString() // ❌ Evolution API doesn't use decorators
+  name: string;
+}
+```
+
+#### Validation Pattern (JSONSchema7)
+```typescript
+import { JSONSchema7 } from 'json-schema';
+import { v4 } from 'uuid';
+
+export const exampleSchema: JSONSchema7 = {
+  $id: v4(),
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    description: { type: 'string' },
+    enabled: { type: 'boolean' },
+  },
+  required: ['name', 'enabled'],
+};
+```
+
+## Multi-Tenant Architecture
+
+### Instance Isolation
+- **CRITICAL**: All operations must be scoped by `instanceName` or `instanceId`
+- **Database queries**: Always include `where: { instanceId: ... }`
+- **Authentication**: Validate instance ownership before operations
+- **Data isolation**: Complete separation between tenant instances
+
+### WhatsApp Instance Management
+```typescript
+// Access instance via WAMonitoringService
+const waInstance = this.waMonitor.waInstances[instance.instanceName];
+if (!waInstance) {
+  throw new NotFoundException(`Instance ${instance.instanceName} not found`);
+}
+```
+
+## Database Patterns
+
+### Multi-Provider Support
+- **PostgreSQL**: Uses `@db.Integer`, `@db.JsonB`, `@default(now())`
+- **MySQL**: Uses `@db.Int`, `@db.Json`, `@default(now())`
+- **Environment**: Set `DATABASE_PROVIDER=postgresql` or `mysql`
+- **Migrations**: Provider-specific folders auto-selected
+
+### Prisma Repository Pattern
+```typescript
+// Always use PrismaRepository for database operations
+const result = await this.prismaRepository.instance.findUnique({
+  where: { name: instanceName },
+});
+```
+
+## Integration Patterns
+
+### Channel Integration (WhatsApp Providers)
+- **Baileys**: WhatsApp Web with QR code authentication
+- **Business API**: Official Meta WhatsApp Business API  
+- **Evolution API**: Custom WhatsApp integration
+- **Pattern**: Extend base channel service classes
+
+### Chatbot Integration
+- **Base classes**: Extend `BaseChatbotService` and `BaseChatbotController`
+- **Trigger system**: Support keyword, regex, and advanced triggers
+- **Session management**: Handle conversation state per user
+- **Available integrations**: EvolutionBot, OpenAI, Dify, Typebot, Chatwoot, Flowise, N8N, EvoAI
+
+### Event Integration
+- **Internal events**: EventEmitter2 for application events
+- **External events**: WebSocket, RabbitMQ, SQS, NATS, Pusher
+- **Webhook delivery**: Reliable delivery with retry logic
 
 ## Testing Guidelines
-- No formal suite yet. Place tests under `test/` as `*.test.ts`.
-- Run `npm test` (watches `test/all.test.ts` if present). Prefer fast, isolated unit tests.
+
+### Current State
+- **No formal test suite** currently implemented
+- **Manual testing** is the primary approach
+- **Integration testing** in development environment
+
+### Testing Strategy
+```typescript
+// Place tests in test/ directory as *.test.ts
+// Run: npm test (watches test/all.test.ts)
+
+describe('ExampleService', () => {
+  it('should create example', async () => {
+    // Mock external dependencies
+    // Test business logic
+    // Assert expected behavior
+  });
+});
+```
+
+### Recommended Approach
+- Focus on **critical business logic** in services
+- **Mock external dependencies** (WhatsApp APIs, databases)
+- **Integration tests** for API endpoints
+- **Manual testing** for WhatsApp connection flows
 
 ## Commit & Pull Request Guidelines
-- Conventional Commits enforced by commitlint. Use `npm run commit` (Commitizen).
-  - Examples: `feat(api): add message status`, `fix(route): handle 404 on send`.
-- PRs: include clear description, linked issues, migration impact (provider), local run steps, and screenshots/logs where relevant.
+
+### Conventional Commits (Enforced by commitlint)
+```bash
+# Use interactive commit tool
+npm run commit
+
+# Commit format: type(scope): subject (max 100 chars)
+# Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert, security
+```
+
+### Examples
+- `feat(api): add WhatsApp message status endpoint`
+- `fix(baileys): resolve connection timeout issue`
+- `docs(readme): update installation instructions`
+- `refactor(service): extract common message validation logic`
+
+### Pull Request Requirements
+- **Clear description** of changes and motivation
+- **Linked issues** if applicable
+- **Migration impact** (specify database provider)
+- **Local testing steps** with screenshots/logs
+- **Breaking changes** clearly documented
 
 ## Security & Configuration
-- Copy `.env.example` to `.env`; never commit secrets.
-- Set `DATABASE_PROVIDER` before DB commands; see `SECURITY.md` for reporting vulnerabilities.
+
+### Environment Setup
+```bash
+# Copy example environment file
+cp .env.example .env
+
+# NEVER commit secrets to version control
+# Set DATABASE_PROVIDER before database commands
+export DATABASE_PROVIDER=postgresql  # or mysql
+```
+
+### Security Best Practices
+- **API key authentication** via `apikey` header
+- **Input validation** with JSONSchema7
+- **Rate limiting** on all endpoints
+- **Webhook signature validation**
+- **Instance-based access control**
+- **Secure defaults** for all configurations
+
+### Vulnerability Reporting
+- See `SECURITY.md` for security vulnerability reporting process
+- Contact: `contato@evolution-api.com`
+
+## Communication Standards
+
+### Language Requirements
+- **User communication**: Always respond in Portuguese (PT-BR)
+- **Code/comments**: English for technical documentation
+- **API responses**: English for consistency
+- **Error messages**: Portuguese for user-facing errors
+
+### Documentation Standards
+- **Inline comments**: Document complex business logic
+- **API documentation**: Document all public endpoints
+- **Integration guides**: Document new integration patterns
+- **Migration guides**: Document database schema changes
+
+## Performance & Scalability
+
+### Caching Strategy
+- **Redis primary**: Distributed caching for production
+- **Node-cache fallback**: Local caching when Redis unavailable
+- **TTL strategy**: Appropriate cache expiration per data type
+- **Cache invalidation**: Proper invalidation on data changes
+
+### Connection Management
+- **Database**: Prisma connection pooling
+- **WhatsApp**: One connection per instance with lifecycle management
+- **Redis**: Connection pooling and retry logic
+- **External APIs**: Rate limiting and retry with exponential backoff
+
+### Monitoring & Observability
+- **Structured logging**: Pino logger with correlation IDs
+- **Error tracking**: Comprehensive error scenarios
+- **Health checks**: Instance status and connection monitoring
+- **Telemetry**: Usage analytics (non-sensitive data only)
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 949045d8..7c0e87a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,10 +1,15 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides comprehensive guidance to Claude AI when working with the Evolution API codebase.
 
 ## Project Overview
 
-Evolution API is a REST API for WhatsApp communication that supports both Baileys (WhatsApp Web) and official WhatsApp Business API. It's built with TypeScript/Node.js and provides extensive integrations with various platforms.
+**Evolution API** is a powerful, production-ready REST API for WhatsApp communication that supports multiple WhatsApp providers:
+- **Baileys** (WhatsApp Web) - Open-source WhatsApp Web client
+- **Meta Business API** - Official WhatsApp Business API
+- **Evolution API** - Custom WhatsApp integration
+
+Built with **Node.js 20+**, **TypeScript 5+**, and **Express.js**, it provides extensive integrations with chatbots, CRM systems, and messaging platforms in a **multi-tenant architecture**.
 
 ## Common Development Commands
 
@@ -30,13 +35,20 @@ npm run commit      # Interactive commit with commitizen
 
 ### Database Management
 ```bash
+# Set database provider first
+export DATABASE_PROVIDER=postgresql  # or mysql
+
 # Generate Prisma client (automatically uses DATABASE_PROVIDER env)
 npm run db:generate
 
-# Deploy migrations
+# Deploy migrations (production)
 npm run db:deploy      # Unix/Mac
 npm run db:deploy:win  # Windows
 
+# Development migrations (with sync to provider folder)
+npm run db:migrate:dev      # Unix/Mac
+npm run db:migrate:dev:win  # Windows
+
 # Open Prisma Studio
 npm run db:studio
 
@@ -53,42 +65,64 @@ npm test    # Run tests with watch mode
 ## Architecture Overview
 
 ### Core Structure
-- **Multi-provider database support**: PostgreSQL and MySQL via Prisma ORM with provider-specific schemas
-- **Connection management**: Each WhatsApp instance maintains its own connection state and session
-- **Event-driven architecture**: Uses EventEmitter2 for internal events and supports multiple external event systems
+- **Multi-tenant SaaS**: Complete instance isolation with per-tenant authentication
+- **Multi-provider database**: PostgreSQL and MySQL via Prisma ORM with provider-specific schemas and migrations
+- **WhatsApp integrations**: Baileys, Meta Business API, and Evolution API with unified interface
+- **Event-driven architecture**: EventEmitter2 for internal events + WebSocket, RabbitMQ, SQS, NATS, Pusher for external events
+- **Microservices pattern**: Modular integrations for chatbots, storage, and external services
 
 ### Directory Layout
 ```
 src/
 ├── api/
-│   ├── controllers/     # HTTP route handlers
-│   ├── services/        # Business logic
+│   ├── controllers/     # HTTP route handlers (thin layer)
+│   ├── services/        # Business logic (core functionality)
 │   ├── repository/      # Data access layer (Prisma)
-│   ├── dto/            # Data validation schemas
-│   ├── guards/         # Authentication/authorization
+│   ├── dto/            # Data Transfer Objects (simple classes)
+│   ├── guards/         # Authentication/authorization middleware
 │   ├── integrations/   # External service integrations
-│   └── routes/         # Express route definitions
+│   │   ├── channel/    # WhatsApp providers (Baileys, Business API, Evolution)
+│   │   ├── chatbot/    # AI/Bot integrations (OpenAI, Dify, Typebot, Chatwoot)
+│   │   ├── event/      # Event systems (WebSocket, RabbitMQ, SQS, NATS, Pusher)
+│   │   └── storage/    # File storage (S3, MinIO)
+│   ├── routes/         # Express route definitions (RouterBroker pattern)
+│   └── types/          # TypeScript type definitions
 ├── config/             # Environment and app configuration
 ├── cache/             # Redis and local cache implementations
-├── exceptions/        # Custom exception classes
-├── utils/            # Shared utilities
-└── validate/         # Validation schemas
+├── exceptions/        # Custom HTTP exception classes
+├── utils/            # Shared utilities and helpers
+└── validate/         # JSONSchema7 validation schemas
 ```
 
-### Key Services Integration Points
+### Key Integration Points
 
-**WhatsApp Service** (`src/api/integrations/channel/whatsapp/`):
-- Manages Baileys connections and Meta Business API
-- Handles message sending, receiving, and status updates
-- Connection lifecycle management per instance
+**Channel Integrations** (`src/api/integrations/channel/`):
+- **Baileys**: WhatsApp Web client with QR code authentication
+- **Business API**: Official Meta WhatsApp Business API
+- **Evolution API**: Custom WhatsApp integration
+- Connection lifecycle management per instance with automatic reconnection
 
-**Integration Services** (`src/api/integrations/`):
-- Chatwoot: Customer service platform integration
-- Typebot: Conversational bot builder
-- OpenAI: AI capabilities including audio transcription
-- Dify: AI agent platform
-- RabbitMQ/SQS: Message queue integrations
-- S3/Minio: Media storage
+**Chatbot Integrations** (`src/api/integrations/chatbot/`):
+- **EvolutionBot**: Native chatbot with trigger system
+- **Chatwoot**: Customer service platform integration
+- **Typebot**: Visual chatbot flow builder
+- **OpenAI**: AI capabilities including GPT and Whisper (audio transcription)
+- **Dify**: AI agent workflow platform
+- **Flowise**: LangChain visual builder
+- **N8N**: Workflow automation platform
+- **EvoAI**: Custom AI integration
+
+**Event Integrations** (`src/api/integrations/event/`):
+- **WebSocket**: Real-time Socket.io connections
+- **RabbitMQ**: Message queue for async processing
+- **Amazon SQS**: Cloud-based message queuing
+- **NATS**: High-performance messaging system
+- **Pusher**: Real-time push notifications
+
+**Storage Integrations** (`src/api/integrations/storage/`):
+- **AWS S3**: Cloud object storage
+- **MinIO**: Self-hosted S3-compatible storage
+- Media file management and URL generation
 
 ### Database Schema Management
 - Separate schema files: `postgresql-schema.prisma` and `mysql-schema.prisma`
@@ -96,10 +130,12 @@ src/
 - Migration folders are provider-specific and auto-selected during deployment
 
 ### Authentication & Security
-- API key-based authentication via `apikey` header
-- Instance-specific authentication for WhatsApp connections
-- Guards system for route protection
-- Input validation using `class-validator`
+- **API key-based authentication** via `apikey` header (global or per-instance)
+- **Instance-specific tokens** for WhatsApp connection authentication
+- **Guards system** for route protection and authorization
+- **Input validation** using JSONSchema7 with RouterBroker `dataValidate`
+- **Rate limiting** and security middleware
+- **Webhook signature validation** for external integrations
 
 ## Important Implementation Details
 
@@ -136,24 +172,47 @@ Critical configurations:
 - `REDIS_ENABLED`: Enable Redis cache
 - `RABBITMQ_ENABLED`/`SQS_ENABLED`: Message queue options
 
-## Development Guidelines from Cursor Instructions
+## Development Guidelines
 
-The project includes specific development instructions in `.cursor/instructions`:
-- Always respond in Portuguese Brazilian
-- Follow established architecture patterns
-- Robust error handling with retry logic
-- Multi-database compatibility requirements
-- Security validations and rate limiting
-- Performance optimizations with caching
-- Minimum 70% test coverage target
+The project follows comprehensive development standards defined in `.cursor/rules/`:
+
+### Core Principles
+- **Always respond in Portuguese (PT-BR)** for user communication
+- **Follow established architecture patterns** (Service Layer, RouterBroker, etc.)
+- **Robust error handling** with retry logic and graceful degradation
+- **Multi-database compatibility** (PostgreSQL and MySQL)
+- **Security-first approach** with input validation and rate limiting
+- **Performance optimizations** with Redis caching and connection pooling
+
+### Code Standards
+- **TypeScript strict mode** with full type coverage
+- **JSONSchema7** for input validation (not class-validator)
+- **Conventional Commits** enforced by commitlint
+- **ESLint + Prettier** for code formatting
+- **Service Object pattern** for business logic
+- **RouterBroker pattern** for route handling with `dataValidate`
+
+### Architecture Patterns
+- **Multi-tenant isolation** at database and instance level
+- **Event-driven communication** with EventEmitter2
+- **Microservices integration** pattern for external services
+- **Connection pooling** and lifecycle management
+- **Caching strategy** with Redis primary and Node-cache fallback
 
 ## Testing Approach
 
-Tests are located alongside source files or in dedicated test directories. The project uses:
-- Unit tests for services
-- Integration tests for critical APIs
-- Mock external dependencies
-- Test command runs with watch mode for development
+Currently, the project has minimal formal testing infrastructure:
+- **Manual testing** is the primary approach
+- **Integration testing** in development environment
+- **No unit test suite** currently implemented
+- Test files can be placed in `test/` directory as `*.test.ts`
+- Run `npm test` for watch mode development testing
+
+### Recommended Testing Strategy
+- Focus on **critical business logic** in services
+- **Mock external dependencies** (WhatsApp APIs, databases)
+- **Integration tests** for API endpoints
+- **Manual testing** for WhatsApp connection flows
 
 ## Deployment Considerations