diff --git a/.cursorrules b/.cursorrules
deleted file mode 100644
index 42ef136ae..000000000
--- a/.cursorrules
+++ /dev/null
@@ -1,1429 +0,0 @@
-# CrewAI Development Rules
-# Comprehensive best practices for developing with the CrewAI library, covering code organization, performance, security, testing, and common patterns. Based on actual CrewAI codebase analysis for accuracy.
-
-## General Best Practices:
-- Leverage structured responses from LLM calls using Pydantic BaseModel for output validation.
-- Use the @CrewBase decorator pattern with @agent, @task, and @crew decorators for proper organization.
-- Regularly validate outputs from agents and tasks using built-in guardrails or custom validation.
-- Use UV for dependency management (CrewAI's standard) with pyproject.toml configuration.
-- Python version requirements: 3.10 to 3.14 (as per CrewAI's pyproject.toml).
-- Prefer declarative YAML configuration for agents and tasks over hardcoded definitions.
-
-## Code Organization and Structure:
-- **Standard CrewAI Project Structure** (from CLI templates):
-  - `project_name/` (Root directory)
-    - `.env` (Environment variables - never commit API keys)
-    - `pyproject.toml` (UV-based dependency management)
-    - `knowledge/` (Knowledge base files)
-    - `src/project_name/`
-      - `__init__.py`
-      - `main.py` (Entry point)
-      - `crew.py` (Crew orchestration with @CrewBase decorator)
-      - `config/`
-        - `agents.yaml` (Agent definitions)
-        - `tasks.yaml` (Task definitions)
-      - `tools/`
-        - `custom_tool.py` (Custom agent tools)
-        - `__init__.py`
-- **File Naming Conventions**:
-  - Use descriptive, lowercase names with underscores (e.g., `research_agent.py`).
-  - Pydantic models: singular names (e.g., `article_summary.py` with class `ArticleSummary`).
-  - Tests: mirror source file name with `_test` suffix (e.g., `crew_test.py`).
-- **CrewAI Class Architecture**:
-  - Use @CrewBase decorator for main crew class.
-  - Define agents with @agent decorator returning Agent instances.
-  - Define tasks with @task decorator returning Task instances.
-  - Define crew orchestration with @crew decorator returning Crew instance.
-  - Access configuration via `self.agents_config` and `self.tasks_config`.
-
-## Memory System Patterns:
-- **Memory Types** (all supported by CrewAI):
-  - Short-term memory: ChromaDB with RAG for current context
-  - Long-term memory: SQLite for task results across sessions
-  - Entity memory: RAG to track entities (people, places, concepts)
-  - External memory: Mem0 integration for advanced memory features
-- **Memory Configuration**:
-  - Enable basic memory: `Crew(..., memory=True)`
-  - Custom storage location: Set `CREWAI_STORAGE_DIR` environment variable
-  - Memory is stored in platform-specific directories via `appdirs` by default
-- **Memory Usage**:
-  - Memory is automatically managed by agents during task execution
-  - Access via agent's memory attribute for custom implementations
-  - Use metadata for categorizing and filtering memory entries
-
-## Pydantic Integration Patterns:
-- **Structured Outputs**:
-  - Use `output_pydantic` in Task definitions for structured results
-  - Use `output_json` for JSON dictionary outputs
-  - Cannot use both output_pydantic and output_json simultaneously
-- **Task Output Handling**:
-  - TaskOutput contains raw, pydantic, and json_dict attributes
-  - CrewOutput aggregates all task outputs with token usage metrics
-  - Use model_validate_json for Pydantic model validation
-- **Custom Models**:
-  - Inherit from BaseModel for all data structures
-  - Use Field descriptions for LLM understanding
-  - Implement model_validator for custom validation logic
-
-## YAML Configuration Best Practices:
-- **agents.yaml Structure**:
-  ```yaml
-  agent_name:
-    role: "Clear, specific role description"
-    goal: "Specific goal statement"
-    backstory: "Detailed background for context"
-    # Optional: tools, llm, memory, etc.
-  ```
-- **tasks.yaml Structure**:
-  ```yaml
-  task_name:
-    description: "Detailed task description with context"
-    expected_output: "Clear output format specification"
-    agent: agent_name  # Reference to agent in agents.yaml
-    # Optional: context, tools, output_file, etc.
-  ```
-- **Configuration Access**:
-  - Use `self.agents_config['agent_name']` in @agent methods
-  - Use `self.tasks_config['task_name']` in @task methods
-  - Support for dynamic configuration via placeholders like {topic}
-
-## Tools and Integration Patterns:
-- **Custom Tools**:
-  - Inherit from BaseTool for custom tool implementation
-  - Use @tool decorator for simple tool definitions
-  - Implement proper error handling and input validation
-- **Tool Integration**:
-  - Add tools to agents via tools parameter in Agent constructor
-  - Tools are automatically inherited by tasks from their assigned agents
-  - Use structured tool outputs for better LLM understanding
-
-## Performance Considerations:
-- **LLM Optimization**:
-  - Use task context to pass information between sequential tasks
-  - Implement output caching to avoid redundant LLM calls
-  - Configure appropriate LLM models per agent for cost/performance balance
-- **Memory Management**:
-  - Be mindful of memory storage growth in long-running applications
-  - Use score_threshold in memory search to filter relevant results
-  - Implement periodic memory cleanup if needed
-- **Async Operations**:
-  - Use execute_sync for synchronous task execution
-  - Consider async patterns for I/O-bound operations in custom tools
-
-## Security Best Practices:
-- **API Key Management**:
-  - Always use .env files for API keys and sensitive configuration
-  - Never commit API keys to version control
-  - Use environment variables in production deployments
-- **Input Validation**:
-  - Validate all inputs using Pydantic models where possible
-  - Implement guardrails for task output validation
-  - Use field_validator for custom validation logic
-- **Tool Security**:
-  - Implement proper access controls in custom tools
-  - Validate tool inputs and outputs
-  - Follow principle of least privilege for tool permissions
-
-## Testing Approaches:
-- **Unit Testing**:
-  - Test individual agents, tasks, and tools in isolation
-  - Use mocking for external dependencies (LLMs, APIs)
-  - Test configuration loading and validation
-- **Integration Testing**:
-  - Test crew execution end-to-end with realistic scenarios
-  - Verify memory persistence across crew runs
-  - Test tool integration and data flow between tasks
-- **Test Organization**:
-  - Follow CrewAI's test structure: separate test files for each component
-  - Use pytest fixtures for common test setup
-  - Mock LLM responses for consistent, fast tests
-
-## Common CrewAI Patterns and Anti-patterns:
-- **Recommended Patterns**:
-  - Use sequential Process for dependent tasks, hierarchical for manager delegation
-  - Implement task context for data flow between tasks
-  - Use output_file for persistent task results
-  - Leverage crew callbacks with @before_kickoff and @after_kickoff decorators
-- **Anti-patterns to Avoid**:
-  - Don't hardcode agent configurations in Python code (use YAML)
-  - Don't create circular task dependencies
-  - Don't ignore task execution failures without proper error handling
-  - Don't overload single agents with too many diverse tools
-- **Error Handling**:
-  - Implement task-level guardrails for output validation
-  - Use try-catch blocks in custom tools
-  - Set appropriate max_retries for tasks prone to failures
-  - Log errors with sufficient context for debugging
-
-## Development Workflow:
-- **UV Commands**:
-  - `crewai create crew <name>` - Create new crew project
-  - `crewai install` - Install dependencies via UV
-  - `crewai run` - Execute the crew
-  - `uv sync` - Sync dependencies
-  - `uv add <package>` - Add new dependencies
-- **Project Setup**:
-  - Use CrewAI CLI for project scaffolding
-  - Follow the standard directory structure
-  - Configure agents and tasks in YAML before implementing crew logic
-- **Development Tools**:
-  - Use UV for dependency management (CrewAI standard)
-  - Configure pre-commit hooks for code quality
-  - Use pytest for testing with CrewAI's testing patterns
-
-## Deployment and Production:
-- **Environment Configuration**:
-  - Set CREWAI_STORAGE_DIR for controlled memory storage location
-  - Use proper logging configuration for production monitoring
-  - Configure appropriate LLM providers and rate limits
-- **Containerization**:
-  - Include knowledge and config directories in Docker images
-  - Mount memory storage as persistent volumes if needed
-  - Set proper environment variables for API keys and configuration
-- **Monitoring**:
-  - Monitor token usage via CrewOutput.token_usage
-  - Track task execution times and success rates
-  - Implement health checks for long-running crew services
-
-## CrewAI Flow Patterns and Best Practices
-
-### Flow Architecture and Structure
-- **Use Flow class** for complex multi-step workflows that go beyond simple crew orchestration
-- **Combine Flows with Crews** to create sophisticated AI automation pipelines
-- **Leverage state management** to share data between flow methods
-- **Event-driven design** allows for dynamic and responsive workflow execution
-
-### Flow Decorators and Control Flow
-- **@start()**: Mark entry points for flow execution (can have multiple start methods)
-- **@listen()**: Create method dependencies and execution chains
-- **@router()**: Implement conditional branching based on method outputs
-- **or_()** and **and_()**: Combine multiple trigger conditions for complex workflows
-
-### Flow State Management Patterns
-```python
-# Structured state with Pydantic (recommended for complex workflows)
-class WorkflowState(BaseModel):
-    task_results: List[str] = []
-    current_step: str = "initialize"
-    user_preferences: dict = {}
-    completion_status: bool = False
-
-class MyFlow(Flow[WorkflowState]):
-    @start()
-    def initialize(self):
-        self.state.current_step = "processing"
-        # State automatically gets unique UUID in self.state.id
-
-# Unstructured state (good for simple workflows)
-class SimpleFlow(Flow):
-    @start()
-    def begin(self):
-        self.state["counter"] = 0
-        self.state["results"] = []
-        # Auto-generated ID available in self.state["id"]
-```
-
-### Flow Method Patterns
-```python
-# Basic sequential flow
-@start()
-def step_one(self):
-    return "data from step one"
-
-@listen(step_one)
-def step_two(self, data_from_step_one):
-    return f"processed: {data_from_step_one}"
-
-# Parallel execution with convergence
-@start()
-def task_a(self):
-    return "result_a"
-
-@start()
-def task_b(self):
-    return "result_b"
-
-@listen(and_(task_a, task_b))
-def combine_results(self):
-    # Waits for both task_a AND task_b to complete
-    return f"combined: {self.state}"
-
-# Conditional routing
-@router(step_one)
-def decision_point(self):
-    if some_condition:
-        return "success_path"
-    return "failure_path"
-
-@listen("success_path")
-def handle_success(self):
-    # Handle success case
-    pass
-
-@listen("failure_path")
-def handle_failure(self):
-    # Handle failure case
-    pass
-
-# OR condition listening
-@listen(or_(task_a, task_b))
-def process_any_result(self, result):
-    # Triggers when EITHER task_a OR task_b completes
-    return f"got result: {result}"
-```
-
-### Flow Persistence Patterns
-```python
-# Class-level persistence (all methods persisted)
-@persist(verbose=True)
-class PersistentFlow(Flow[MyState]):
-    @start()
-    def initialize(self):
-        self.state.counter += 1
-
-# Method-level persistence (selective)
-class SelectiveFlow(Flow):
-    @persist
-    @start()
-    def critical_step(self):
-        # Only this method's state is persisted
-        self.state["important_data"] = "value"
-
-    @start()
-    def temporary_step(self):
-        # This method's state is not persisted
-        pass
-```
-
-### Flow Execution Patterns
-```python
-# Synchronous execution
-flow = MyFlow()
-result = flow.kickoff()
-final_state = flow.state
-
-# Asynchronous execution
-async def run_async_flow():
-    flow = MyFlow()
-    result = await flow.kickoff_async()
-    return result
-
-# Flow with input parameters
-flow = MyFlow()
-result = flow.kickoff(inputs={"user_id": "123", "task": "research"})
-
-# Flow plotting and visualization
-flow.plot("workflow_diagram")  # Generates HTML visualization
-```
-
-### Advanced Flow Patterns
-```python
-# Cyclic/Loop patterns
-class CyclicFlow(Flow):
-    max_iterations = 5
-    current_iteration = 0
-
-    @start("loop")
-    def process_iteration(self):
-        if self.current_iteration >= self.max_iterations:
-            return
-        # Process current iteration
-        self.current_iteration += 1
-
-    @router(process_iteration)
-    def check_continue(self):
-        if self.current_iteration < self.max_iterations:
-            return "loop"  # Continue cycling
-        return "complete"
-
-    @listen("complete")
-    def finalize(self):
-        # Final processing
-        pass
-
-# Complex multi-router pattern
-@router(analyze_data)
-def primary_router(self):
-    # Returns multiple possible paths based on analysis
-    if self.state.confidence > 0.8:
-        return "high_confidence"
-    elif self.state.errors_found:
-        return "error_handling"
-    return "manual_review"
-
-@router("high_confidence")
-def secondary_router(self):
-    # Further routing based on high confidence results
-    return "automated_processing"
-
-# Exception handling in flows
-@start()
-def risky_operation(self):
-    try:
-        # Some operation that might fail
-        result = dangerous_function()
-        self.state["success"] = True
-        return result
-    except Exception as e:
-        self.state["error"] = str(e)
-        self.state["success"] = False
-        return None
-
-@listen(risky_operation)
-def handle_result(self, result):
-    if self.state.get("success", False):
-        # Handle success case
-        pass
-    else:
-        # Handle error case
-        error = self.state.get("error")
-        # Implement error recovery logic
-```
-
-### Flow Integration with Crews
-```python
-# Combining Flows with Crews for complex workflows
-class CrewOrchestrationFlow(Flow[WorkflowState]):
-    @start()
-    def research_phase(self):
-        research_crew = ResearchCrew()
-        result = research_crew.crew().kickoff(inputs={"topic": self.state.research_topic})
-        self.state.research_results = result.raw
-        return result
-
-    @listen(research_phase)
-    def analysis_phase(self, research_results):
-        analysis_crew = AnalysisCrew()
-        result = analysis_crew.crew().kickoff(inputs={
-            "data": self.state.research_results,
-            "focus": self.state.analysis_focus
-        })
-        self.state.analysis_results = result.raw
-        return result
-
-    @router(analysis_phase)
-    def decide_next_action(self):
-        if self.state.analysis_results.confidence > 0.7:
-            return "generate_report"
-        return "additional_research"
-
-    @listen("generate_report")
-    def final_report(self):
-        reporting_crew = ReportingCrew()
-        return reporting_crew.crew().kickoff(inputs={
-            "research": self.state.research_results,
-            "analysis": self.state.analysis_results
-        })
-```
-
-### Flow Best Practices
-- **State Management**: Use structured state (Pydantic) for complex workflows, unstructured for simple ones
-- **Method Design**: Keep flow methods focused and single-purpose
-- **Error Handling**: Implement proper exception handling and error recovery paths
-- **State Persistence**: Use @persist for critical workflows that need recovery capability
-- **Flow Visualization**: Use flow.plot() to understand and debug complex workflow structures
-- **Async Support**: Leverage async methods for I/O-bound operations within flows
-- **Resource Management**: Be mindful of state size and memory usage in long-running flows
-- **Testing Flows**: Test individual methods and overall flow execution patterns
-- **Event Monitoring**: Use CrewAI event system to monitor flow execution and performance
-
-### Flow Anti-patterns to Avoid
-- **Don't create overly complex flows** with too many branches and conditions
-- **Don't store large objects** in state that could cause memory issues
-- **Don't ignore error handling** in flow methods
-- **Don't create circular dependencies** between flow methods
-- **Don't mix synchronous and asynchronous** patterns inconsistently
-- **Don't overuse routers** when simple linear flow would suffice
-- **Don't forget to handle edge cases** in router logic
-
-## CrewAI Version Compatibility:
-- Stay updated with CrewAI releases for new features and bug fixes
-- Test crew functionality when upgrading CrewAI versions
-- Use version constraints in pyproject.toml (e.g., "crewai[tools]>=0.140.0,<1.0.0")
-- Monitor deprecation warnings for future compatibility
-
-## Code Examples and Implementation Patterns
-
-### Complete Crew Implementation Example:
-```python
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff
-from crewai_tools import SerperDevTool, FileReadTool
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
-from pydantic import BaseModel, Field
-
-class ResearchOutput(BaseModel):
-    title: str = Field(description="Research topic title")
-    summary: str = Field(description="Executive summary")
-    key_findings: List[str] = Field(description="Key research findings")
-    recommendations: List[str] = Field(description="Actionable recommendations")
-    sources: List[str] = Field(description="Source URLs and references")
-    confidence_score: float = Field(description="Confidence in findings (0-1)")
-
-@CrewBase
-class ResearchCrew():
-    """Advanced research crew with structured outputs and validation"""
-
-    agents: List[BaseAgent]
-    tasks: List[Task]
-
-    @before_kickoff
-    def setup_environment(self):
-        """Initialize environment before crew execution"""
-        print("🚀 Setting up research environment...")
-        # Validate API keys, create directories, etc.
-
-    @after_kickoff
-    def cleanup_and_report(self, output):
-        """Handle post-execution tasks"""
-        print(f"✅ Research completed. Generated {len(output.tasks_output)} task outputs")
-        print(f"📊 Token usage: {output.token_usage}")
-
-    @agent
-    def researcher(self) -> Agent:
-        return Agent(
-            config=self.agents_config['researcher'],
-            tools=[SerperDevTool()],
-            verbose=True,
-            memory=True,
-            max_iter=15,
-            max_execution_time=1800
-        )
-
-    @agent
-    def analyst(self) -> Agent:
-        return Agent(
-            config=self.agents_config['analyst'],
-            tools=[FileReadTool()],
-            verbose=True,
-            memory=True
-        )
-
-    @task
-    def research_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['research_task'],
-            agent=self.researcher(),
-            output_pydantic=ResearchOutput
-        )
-
-    @task
-    def validation_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['validation_task'],
-            agent=self.analyst(),
-            context=[self.research_task()],
-            guardrail=self.validate_research_quality,
-            max_retries=3
-        )
-
-    def validate_research_quality(self, output) -> tuple[bool, str]:
-        """Custom guardrail to ensure research quality"""
-        content = output.raw
-        if len(content) < 500:
-            return False, "Research output too brief. Need more detailed analysis."
-        if not any(keyword in content.lower() for keyword in ['conclusion', 'finding', 'result']):
-            return False, "Missing key analytical elements."
-        return True, content
-
-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            memory=True,
-            verbose=True,
-            max_rpm=100
-        )
-```
-
-### Custom Tool Implementation with Error Handling:
-```python
-from crewai.tools import BaseTool
-from typing import Type, Optional, Any
-from pydantic import BaseModel, Field
-import requests
-import time
-from tenacity import retry, stop_after_attempt, wait_exponential
-
-class SearchInput(BaseModel):
-    query: str = Field(description="Search query")
-    max_results: int = Field(default=10, description="Maximum results to return")
-    timeout: int = Field(default=30, description="Request timeout in seconds")
-
-class RobustSearchTool(BaseTool):
-    name: str = "robust_search"
-    description: str = "Perform web search with retry logic and error handling"
-    args_schema: Type[BaseModel] = SearchInput
-
-    def __init__(self, api_key: Optional[str] = None, **kwargs):
-        super().__init__(**kwargs)
-        self.api_key = api_key or os.getenv("SEARCH_API_KEY")
-        self.rate_limit_delay = 1.0
-        self.last_request_time = 0
-
-    @retry(
-        stop=stop_after_attempt(3),
-        wait=wait_exponential(multiplier=1, min=4, max=10)
-    )
-    def _run(self, query: str, max_results: int = 10, timeout: int = 30) -> str:
-        """Execute search with retry logic"""
-        try:
-            # Rate limiting
-            time_since_last = time.time() - self.last_request_time
-            if time_since_last < self.rate_limit_delay:
-                time.sleep(self.rate_limit_delay - time_since_last)
-
-            # Input validation
-            if not query or len(query.strip()) == 0:
-                return "Error: Empty search query provided"
-
-            if len(query) > 500:
-                return "Error: Search query too long (max 500 characters)"
-
-            # Perform search
-            results = self._perform_search(query, max_results, timeout)
-            self.last_request_time = time.time()
-
-            return self._format_results(results)
-
-        except requests.exceptions.Timeout:
-            return f"Search timed out after {timeout} seconds"
-        except requests.exceptions.RequestException as e:
-            return f"Search failed due to network error: {str(e)}"
-        except Exception as e:
-            return f"Unexpected error during search: {str(e)}"
-
-    def _perform_search(self, query: str, max_results: int, timeout: int) -> List[dict]:
-        """Implement actual search logic here"""
-        # Your search API implementation
-        pass
-
-    def _format_results(self, results: List[dict]) -> str:
-        """Format search results for LLM consumption"""
-        if not results:
-            return "No results found for the given query."
-
-        formatted = "Search Results:\n\n"
-        for i, result in enumerate(results[:10], 1):
-            formatted += f"{i}. {result.get('title', 'No title')}\n"
-            formatted += f"   URL: {result.get('url', 'No URL')}\n"
-            formatted += f"   Summary: {result.get('snippet', 'No summary')}\n\n"
-
-        return formatted
-```
-
-### Advanced Memory Management:
-```python
-import os
-from crewai.memory import ExternalMemory, ShortTermMemory, LongTermMemory
-from crewai.memory.storage.mem0_storage import Mem0Storage
-
-class AdvancedMemoryManager:
-    """Enhanced memory management for CrewAI applications"""
-
-    def __init__(self, crew, config: dict = None):
-        self.crew = crew
-        self.config = config or {}
-        self.setup_memory_systems()
-
-    def setup_memory_systems(self):
-        """Configure multiple memory systems"""
-        # Short-term memory for current session
-        self.short_term = ShortTermMemory()
-
-        # Long-term memory for cross-session persistence
-        self.long_term = LongTermMemory()
-
-        # External memory with Mem0 (if configured)
-        if self.config.get('use_external_memory'):
-            self.external = ExternalMemory.create_storage(
-                crew=self.crew,
-                embedder_config={
-                    "provider": "mem0",
-                    "config": {
-                        "api_key": os.getenv("MEM0_API_KEY"),
-                        "user_id": self.config.get('user_id', 'default')
-                    }
-                }
-            )
-
-    def save_with_context(self, content: str, memory_type: str = "short_term",
-                         metadata: dict = None, agent: str = None):
-        """Save content with enhanced metadata"""
-        enhanced_metadata = {
-            "timestamp": time.time(),
-            "session_id": self.config.get('session_id'),
-            "crew_type": self.crew.__class__.__name__,
-            **(metadata or {})
-        }
-
-        if memory_type == "short_term":
-            self.short_term.save(content, enhanced_metadata, agent)
-        elif memory_type == "long_term":
-            self.long_term.save(content, enhanced_metadata, agent)
-        elif memory_type == "external" and hasattr(self, 'external'):
-            self.external.save(content, enhanced_metadata, agent)
-
-    def search_across_memories(self, query: str, limit: int = 5) -> dict:
-        """Search across all memory systems"""
-        results = {
-            "short_term": [],
-            "long_term": [],
-            "external": []
-        }
-
-        # Search short-term memory
-        results["short_term"] = self.short_term.search(query, limit=limit)
-
-        # Search long-term memory
-        results["long_term"] = self.long_term.search(query, limit=limit)
-
-        # Search external memory (if available)
-        if hasattr(self, 'external'):
-            results["external"] = self.external.search(query, limit=limit)
-
-        return results
-
-    def cleanup_old_memories(self, days_threshold: int = 30):
-        """Clean up old memories based on age"""
-        cutoff_time = time.time() - (days_threshold * 24 * 60 * 60)
-
-        # Implement cleanup logic based on timestamps in metadata
-        # This would vary based on your specific storage implementation
-        pass
-```
-
-### Production Monitoring and Metrics:
-```python
-import time
-import logging
-import json
-from datetime import datetime
-from typing import Dict, Any, List
-from dataclasses import dataclass, asdict
-
-@dataclass
-class TaskMetrics:
-    task_name: str
-    agent_name: str
-    start_time: float
-    end_time: float
-    duration: float
-    tokens_used: int
-    success: bool
-    error_message: Optional[str] = None
-    memory_usage_mb: Optional[float] = None
-
-class CrewMonitor:
-    """Comprehensive monitoring for CrewAI applications"""
-
-    def __init__(self, crew_name: str, log_level: str = "INFO"):
-        self.crew_name = crew_name
-        self.metrics: List[TaskMetrics] = []
-        self.session_start = time.time()
-
-        # Setup logging
-        logging.basicConfig(
-            level=getattr(logging, log_level),
-            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-            handlers=[
-                logging.FileHandler(f'crew_{crew_name}_{datetime.now().strftime("%Y%m%d")}.log'),
-                logging.StreamHandler()
-            ]
-        )
-        self.logger = logging.getLogger(f"CrewAI.{crew_name}")
-
-    def start_task_monitoring(self, task_name: str, agent_name: str) -> dict:
-        """Start monitoring a task execution"""
-        context = {
-            "task_name": task_name,
-            "agent_name": agent_name,
-            "start_time": time.time()
-        }
-
-        self.logger.info(f"Task started: {task_name} by {agent_name}")
-        return context
-
-    def end_task_monitoring(self, context: dict, success: bool = True,
-                           tokens_used: int = 0, error: str = None):
-        """End monitoring and record metrics"""
-        end_time = time.time()
-        duration = end_time - context["start_time"]
-
-        # Get memory usage (if psutil is available)
-        memory_usage = None
-        try:
-            import psutil
-            process = psutil.Process()
-            memory_usage = process.memory_info().rss / 1024 / 1024  # MB
-        except ImportError:
-            pass
-
-        metrics = TaskMetrics(
-            task_name=context["task_name"],
-            agent_name=context["agent_name"],
-            start_time=context["start_time"],
-            end_time=end_time,
-            duration=duration,
-            tokens_used=tokens_used,
-            success=success,
-            error_message=error,
-            memory_usage_mb=memory_usage
-        )
-
-        self.metrics.append(metrics)
-
-        # Log the completion
-        status = "SUCCESS" if success else "FAILED"
-        self.logger.info(f"Task {status}: {context['task_name']} "
-                        f"(Duration: {duration:.2f}s, Tokens: {tokens_used})")
-
-        if error:
-            self.logger.error(f"Task error: {error}")
-
-    def get_performance_summary(self) -> Dict[str, Any]:
-        """Generate comprehensive performance summary"""
-        if not self.metrics:
-            return {"message": "No metrics recorded yet"}
-
-        successful_tasks = [m for m in self.metrics if m.success]
-        failed_tasks = [m for m in self.metrics if not m.success]
-
-        total_duration = sum(m.duration for m in self.metrics)
-        total_tokens = sum(m.tokens_used for m in self.metrics)
-        avg_duration = total_duration / len(self.metrics)
-
-        return {
-            "crew_name": self.crew_name,
-            "session_duration": time.time() - self.session_start,
-            "total_tasks": len(self.metrics),
-            "successful_tasks": len(successful_tasks),
-            "failed_tasks": len(failed_tasks),
-            "success_rate": len(successful_tasks) / len(self.metrics),
-            "total_duration": total_duration,
-            "average_task_duration": avg_duration,
-            "total_tokens_used": total_tokens,
-            "average_tokens_per_task": total_tokens / len(self.metrics) if self.metrics else 0,
-            "slowest_task": max(self.metrics, key=lambda x: x.duration).task_name if self.metrics else None,
-            "most_token_intensive": max(self.metrics, key=lambda x: x.tokens_used).task_name if self.metrics else None,
-            "common_errors": self._get_common_errors()
-        }
-
-    def _get_common_errors(self) -> Dict[str, int]:
-        """Get frequency of common errors"""
-        error_counts = {}
-        for metric in self.metrics:
-            if metric.error_message:
-                error_counts[metric.error_message] = error_counts.get(metric.error_message, 0) + 1
-        return dict(sorted(error_counts.items(), key=lambda x: x[1], reverse=True))
-
-    def export_metrics(self, filename: str = None) -> str:
-        """Export metrics to JSON file"""
-        if not filename:
-            filename = f"crew_metrics_{self.crew_name}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
-
-        export_data = {
-            "summary": self.get_performance_summary(),
-            "detailed_metrics": [asdict(m) for m in self.metrics]
-        }
-
-        with open(filename, 'w') as f:
-            json.dump(export_data, f, indent=2, default=str)
-
-        self.logger.info(f"Metrics exported to {filename}")
-        return filename
-
-# Usage in crew implementation
-monitor = CrewMonitor("research_crew")
-
-@task
-def monitored_research_task(self) -> Task:
-    def task_callback(task_output):
-        # This would be called after task completion
-        context = getattr(task_output, '_monitor_context', {})
-        if context:
-            tokens = getattr(task_output, 'token_usage', {}).get('total', 0)
-            monitor.end_task_monitoring(context, success=True, tokens_used=tokens)
-
-    # Start monitoring would be called before task execution
-    # This is a simplified example - in practice you'd integrate this into the task execution flow
-
-    return Task(
-        config=self.tasks_config['research_task'],
-        agent=self.researcher(),
-        callback=task_callback
-    )
-```
-
-### Error Handling and Recovery Patterns:
-```python
-from enum import Enum
-from typing import Optional, Callable, Any
-import traceback
-
-class ErrorSeverity(Enum):
-    LOW = "low"
-    MEDIUM = "medium"
-    HIGH = "high"
-    CRITICAL = "critical"
-
-class CrewError(Exception):
-    """Base exception for CrewAI applications"""
-    def __init__(self, message: str, severity: ErrorSeverity = ErrorSeverity.MEDIUM,
-                 context: dict = None):
-        super().__init__(message)
-        self.severity = severity
-        self.context = context or {}
-        self.timestamp = time.time()
-
-class TaskExecutionError(CrewError):
-    """Raised when task execution fails"""
-    pass
-
-class ValidationError(CrewError):
-    """Raised when validation fails"""
-    pass
-
-class ConfigurationError(CrewError):
-    """Raised when configuration is invalid"""
-    pass
-
-class ErrorHandler:
-    """Centralized error handling for CrewAI applications"""
-
-    def __init__(self, crew_name: str):
-        self.crew_name = crew_name
-        self.error_log: List[CrewError] = []
-        self.recovery_strategies: Dict[type, Callable] = {}
-
-    def register_recovery_strategy(self, error_type: type, strategy: Callable):
-        """Register a recovery strategy for specific error types"""
-        self.recovery_strategies[error_type] = strategy
-
-    def handle_error(self, error: Exception, context: dict = None) -> Any:
-        """Handle errors with appropriate recovery strategies"""
-
-        # Convert to CrewError if needed
-        if not isinstance(error, CrewError):
-            crew_error = CrewError(
-                message=str(error),
-                severity=ErrorSeverity.MEDIUM,
-                context=context or {}
-            )
-        else:
-            crew_error = error
-
-        # Log the error
-        self.error_log.append(crew_error)
-        self._log_error(crew_error)
-
-        # Apply recovery strategy if available
-        error_type = type(error)
-        if error_type in self.recovery_strategies:
-            try:
-                return self.recovery_strategies[error_type](error, context)
-            except Exception as recovery_error:
-                self._log_error(CrewError(
-                    f"Recovery strategy failed: {str(recovery_error)}",
-                    ErrorSeverity.HIGH,
-                    {"original_error": str(error), "recovery_error": str(recovery_error)}
-                ))
-
-        # If critical, re-raise
-        if crew_error.severity == ErrorSeverity.CRITICAL:
-            raise crew_error
-
-        return None
-
-    def _log_error(self, error: CrewError):
-        """Log error with appropriate level based on severity"""
-        logger = logging.getLogger(f"CrewAI.{self.crew_name}.ErrorHandler")
-
-        error_msg = f"[{error.severity.value.upper()}] {error}"
-        if error.context:
-            error_msg += f" | Context: {error.context}"
-
-        if error.severity in [ErrorSeverity.HIGH, ErrorSeverity.CRITICAL]:
-            logger.error(error_msg)
-            logger.error(f"Stack trace: {traceback.format_exc()}")
-        elif error.severity == ErrorSeverity.MEDIUM:
-            logger.warning(error_msg)
-        else:
-            logger.info(error_msg)
-
-    def get_error_summary(self) -> Dict[str, Any]:
-        """Get summary of errors encountered"""
-        if not self.error_log:
-            return {"total_errors": 0}
-
-        severity_counts = {}
-        for error in self.error_log:
-            severity_counts[error.severity.value] = severity_counts.get(error.severity.value, 0) + 1
-
-        return {
-            "total_errors": len(self.error_log),
-            "severity_breakdown": severity_counts,
-            "recent_errors": [str(e) for e in self.error_log[-5:]],  # Last 5 errors
-            "most_recent_error": str(self.error_log[-1]) if self.error_log else None
-        }
-
-# Example usage in crew
-error_handler = ErrorHandler("research_crew")
-
-# Register recovery strategies
-def retry_with_simpler_model(error, context):
-    """Recovery strategy: retry with a simpler model"""
-    if "rate limit" in str(error).lower():
-        time.sleep(60)  # Wait and retry
-        return "RETRY"
-    elif "model overloaded" in str(error).lower():
-        # Switch to simpler model and retry
-        return "RETRY_WITH_SIMPLE_MODEL"
-    return None
-
-error_handler.register_recovery_strategy(TaskExecutionError, retry_with_simpler_model)
-
-@task
-def robust_task(self) -> Task:
-    def execute_with_error_handling(task_func):
-        def wrapper(*args, **kwargs):
-            try:
-                return task_func(*args, **kwargs)
-            except Exception as e:
-                result = error_handler.handle_error(e, {"task": "research_task"})
-                if result == "RETRY":
-                    # Implement retry logic
-                    pass
-                elif result == "RETRY_WITH_SIMPLE_MODEL":
-                    # Switch model and retry
-                    pass
-                else:
-                    # Use fallback response
-                    return "Task failed, using fallback response"
-        return wrapper
-
-    return Task(
-        config=self.tasks_config['research_task'],
-        agent=self.researcher()
-    )
-```
-
-### Environment and Configuration Management:
-```python
-import os
-from enum import Enum
-from typing import Optional, Dict, Any
-from pydantic import BaseSettings, Field, validator
-
-class Environment(str, Enum):
-    DEVELOPMENT = "development"
-    TESTING = "testing"
-    STAGING = "staging"
-    PRODUCTION = "production"
-
-class CrewAISettings(BaseSettings):
-    """Comprehensive settings management for CrewAI applications"""
-
-    # Environment
-    environment: Environment = Field(default=Environment.DEVELOPMENT)
-    debug: bool = Field(default=True)
-
-    # API Keys (loaded from environment)
-    openai_api_key: Optional[str] = Field(default=None, env="OPENAI_API_KEY")
-    anthropic_api_key: Optional[str] = Field(default=None, env="ANTHROPIC_API_KEY")
-    serper_api_key: Optional[str] = Field(default=None, env="SERPER_API_KEY")
-    mem0_api_key: Optional[str] = Field(default=None, env="MEM0_API_KEY")
-
-    # CrewAI Configuration
-    crew_max_rpm: int = Field(default=100)
-    crew_max_execution_time: int = Field(default=3600)  # 1 hour
-    default_llm_model: str = Field(default="gpt-4")
-    fallback_llm_model: str = Field(default="gpt-3.5-turbo")
-
-    # Memory and Storage
-    crewai_storage_dir: str = Field(default="./storage", env="CREWAI_STORAGE_DIR")
-    memory_enabled: bool = Field(default=True)
-    memory_cleanup_interval: int = Field(default=86400)  # 24 hours in seconds
-
-    # Performance
-    enable_caching: bool = Field(default=True)
-    max_retries: int = Field(default=3)
-    retry_delay: float = Field(default=1.0)
-
-    # Monitoring
-    enable_monitoring: bool = Field(default=True)
-    log_level: str = Field(default="INFO")
-    metrics_export_interval: int = Field(default=3600)  # 1 hour
-
-    # Security
-    input_sanitization: bool = Field(default=True)
-    max_input_length: int = Field(default=10000)
-    allowed_file_types: list = Field(default=["txt", "md", "pdf", "docx"])
-
-    @validator('environment', pre=True)
-    def set_debug_based_on_env(cls, v):
-        return v
-
-    @validator('debug')
-    def set_debug_from_env(cls, v, values):
-        env = values.get('environment')
-        if env == Environment.PRODUCTION:
-            return False
-        return v
-
-    @validator('openai_api_key')
-    def validate_openai_key(cls, v):
-        if not v:
-            raise ValueError("OPENAI_API_KEY is required")
-        if not v.startswith('sk-'):
-            raise ValueError("Invalid OpenAI API key format")
-        return v
-
-    @property
-    def is_production(self) -> bool:
-        return self.environment == Environment.PRODUCTION
-
-    @property
-    def is_development(self) -> bool:
-        return self.environment == Environment.DEVELOPMENT
-
-    def get_llm_config(self) -> Dict[str, Any]:
-        """Get LLM configuration based on environment"""
-        config = {
-            "model": self.default_llm_model,
-            "temperature": 0.1 if self.is_production else 0.3,
-            "max_tokens": 4000 if self.is_production else 2000,
-            "timeout": 60
-        }
-
-        if self.is_development:
-            config["model"] = self.fallback_llm_model
-
-        return config
-
-    def get_memory_config(self) -> Dict[str, Any]:
-        """Get memory configuration"""
-        return {
-            "enabled": self.memory_enabled,
-            "storage_dir": self.crewai_storage_dir,
-            "cleanup_interval": self.memory_cleanup_interval,
-            "provider": "mem0" if self.mem0_api_key and self.is_production else "local"
-        }
-
-    class Config:
-        env_file = ".env"
-        env_file_encoding = 'utf-8'
-        case_sensitive = False
-
-# Global settings instance
-settings = CrewAISettings()
-
-# Usage in crew
-@CrewBase
-class ConfigurableCrew():
-    """Crew that uses centralized configuration"""
-
-    def __init__(self):
-        self.settings = settings
-        self.validate_configuration()
-
-    def validate_configuration(self):
-        """Validate configuration before crew execution"""
-        required_keys = [self.settings.openai_api_key]
-        if not all(required_keys):
-            raise ConfigurationError("Missing required API keys")
-
-        if not os.path.exists(self.settings.crewai_storage_dir):
-            os.makedirs(self.settings.crewai_storage_dir, exist_ok=True)
-
-    @agent
-    def adaptive_agent(self) -> Agent:
-        """Agent that adapts to configuration"""
-        llm_config = self.settings.get_llm_config()
-
-        return Agent(
-            config=self.agents_config['researcher'],
-            llm=llm_config["model"],
-            max_iter=15 if self.settings.is_production else 10,
-            max_execution_time=self.settings.crew_max_execution_time,
-            verbose=self.settings.debug
-        )
-```
-
-### Comprehensive Testing Framework:
-```python
-import pytest
-import asyncio
-from unittest.mock import Mock, patch, MagicMock
-from crewai import Agent, Task, Crew
-from crewai.tasks.task_output import TaskOutput
-
-class CrewAITestFramework:
-    """Comprehensive testing framework for CrewAI applications"""
-
-    @staticmethod
-    def create_mock_agent(role: str = "test_agent", tools: list = None) -> Mock:
-        """Create a mock agent for testing"""
-        mock_agent = Mock(spec=Agent)
-        mock_agent.role = role
-        mock_agent.goal = f"Test goal for {role}"
-        mock_agent.backstory = f"Test backstory for {role}"
-        mock_agent.tools = tools or []
-        mock_agent.llm = "gpt-3.5-turbo"
-        mock_agent.verbose = False
-        return mock_agent
-
-    @staticmethod
-    def create_mock_task_output(content: str, success: bool = True,
-                               tokens: int = 100) -> TaskOutput:
-        """Create a mock task output for testing"""
-        return TaskOutput(
-            description="Test task",
-            raw=content,
-            agent="test_agent",
-            pydantic=None,
-            json_dict=None
-        )
-
-    @staticmethod
-    def create_test_crew(agents: list = None, tasks: list = None) -> Crew:
-        """Create a test crew with mock components"""
-        test_agents = agents or [CrewAITestFramework.create_mock_agent()]
-        test_tasks = tasks or []
-
-        return Crew(
-            agents=test_agents,
-            tasks=test_tasks,
-            verbose=False
-        )
-
-# Example test cases
-class TestResearchCrew:
-    """Test cases for research crew functionality"""
-
-    def setup_method(self):
-        """Setup test environment"""
-        self.framework = CrewAITestFramework()
-        self.mock_serper = Mock()
-
-    @patch('crewai_tools.SerperDevTool')
-    def test_agent_creation(self, mock_serper_tool):
-        """Test agent creation with proper configuration"""
-        mock_serper_tool.return_value = self.mock_serper
-
-        crew = ResearchCrew()
-        researcher = crew.researcher()
-
-        assert researcher.role == "Senior Research Analyst"
-        assert len(researcher.tools) > 0
-        assert researcher.verbose is True
-
-    def test_task_validation(self):
-        """Test task validation logic"""
-        crew = ResearchCrew()
-
-        # Test valid output
-        valid_output = self.framework.create_mock_task_output(
-            "This is a comprehensive research summary with conclusions and findings."
-        )
-        is_valid, message = crew.validate_research_quality(valid_output)
-        assert is_valid is True
-
-        # Test invalid output (too short)
-        invalid_output = self.framework.create_mock_task_output("Too short")
-        is_valid, message = crew.validate_research_quality(invalid_output)
-        assert is_valid is False
-        assert "brief" in message.lower()
-
-    @patch('requests.get')
-    def test_tool_error_handling(self, mock_requests):
-        """Test tool error handling and recovery"""
-        # Simulate network error
-        mock_requests.side_effect = requests.exceptions.RequestException("Network error")
-
-        tool = RobustSearchTool()
-        result = tool._run("test query")
-
-        assert "network error" in result.lower()
-        assert "failed" in result.lower()
-
-    @pytest.mark.asyncio
-    async def test_crew_execution_flow(self):
-        """Test complete crew execution with mocked dependencies"""
-        with patch.object(Agent, 'execute_task') as mock_execute:
-            mock_execute.return_value = self.framework.create_mock_task_output(
-                "Research completed successfully with findings and recommendations."
-            )
-
-            crew = ResearchCrew()
-            result = crew.crew().kickoff(inputs={"topic": "AI testing"})
-
-            assert result is not None
-            assert "successfully" in result.raw.lower()
-
-    def test_memory_integration(self):
-        """Test memory system integration"""
-        crew = ResearchCrew()
-        memory_manager = AdvancedMemoryManager(crew)
-
-        # Test saving to memory
-        test_content = "Important research finding about AI"
-        memory_manager.save_with_context(
-            content=test_content,
-            memory_type="short_term",
-            metadata={"importance": "high"},
-            agent="researcher"
-        )
-
-        # Test searching memory
-        results = memory_manager.search_across_memories("AI research")
-        assert "short_term" in results
-
-    def test_error_handling_workflow(self):
-        """Test error handling and recovery mechanisms"""
-        error_handler = ErrorHandler("test_crew")
-
-        # Test error registration and handling
-        test_error = TaskExecutionError("Test task failed", ErrorSeverity.MEDIUM)
-        result = error_handler.handle_error(test_error)
-
-        assert len(error_handler.error_log) == 1
-        assert error_handler.error_log[0].severity == ErrorSeverity.MEDIUM
-
-    def test_configuration_validation(self):
-        """Test configuration validation"""
-        # Test with missing API key
-        with patch.dict(os.environ, {}, clear=True):
-            with pytest.raises(ValueError):
-                settings = CrewAISettings()
-
-        # Test with valid configuration
-        with patch.dict(os.environ, {"OPENAI_API_KEY": "sk-test-key"}):
-            settings = CrewAISettings()
-            assert settings.openai_api_key == "sk-test-key"
-
-    @pytest.mark.integration
-    def test_end_to_end_workflow(self):
-        """Integration test for complete workflow"""
-        # This would test the entire crew workflow with real components
-        # Use sparingly and with proper API key management
-        pass
-
-# Performance testing
-class TestCrewPerformance:
-    """Performance tests for CrewAI applications"""
-
-    def test_memory_usage(self):
-        """Test memory usage during crew execution"""
-        import psutil
-        import gc
-
-        process = psutil.Process()
-        initial_memory = process.memory_info().rss
-
-        # Create and run crew multiple times
-        for i in range(10):
-            crew = ResearchCrew()
-            # Simulate crew execution
-            del crew
-            gc.collect()
-
-        final_memory = process.memory_info().rss
-        memory_increase = final_memory - initial_memory
-
-        # Assert memory increase is reasonable (less than 100MB)
-        assert memory_increase < 100 * 1024 * 1024
-
-    def test_concurrent_execution(self):
-        """Test concurrent crew execution"""
-        import concurrent.futures
-
-        def run_crew(crew_id):
-            crew = ResearchCrew()
-            # Simulate execution
-            return f"crew_{crew_id}_completed"
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
-            futures = [executor.submit(run_crew, i) for i in range(5)]
-            results = [future.result() for future in futures]
-
-        assert len(results) == 5
-        assert all("completed" in result for result in results)
-
-# Run tests with coverage
-# pytest --cov=src --cov-report=html --cov-report=term tests/
-```
-
-## Troubleshooting Common Issues
-
-### Memory and Performance Issues:
-- **Large memory usage**: Implement memory cleanup, use score thresholds, monitor ChromaDB size
-- **Slow LLM responses**: Optimize prompts, use appropriate model sizes, implement caching
-- **High token costs**: Implement output caching, use context efficiently, set token limits
-- **Memory leaks**: Properly dispose of crew instances, monitor memory usage, use garbage collection
-
-### Configuration and Setup Issues:
-- **YAML parsing errors**: Validate YAML syntax, check indentation, use YAML linters
-- **Missing environment variables**: Use .env.example, validate at startup, provide clear error messages
-- **Tool import failures**: Ensure proper tool installation, check import paths, verify dependencies
-- **API key issues**: Validate key format, check permissions, implement key rotation
-
-### Storage and Persistence Issues:
-- **Permission errors**: Check CREWAI_STORAGE_DIR permissions, ensure write access
-- **Database locks**: Ensure single crew instance access, implement proper connection handling
-- **Storage growth**: Implement cleanup strategies, monitor disk usage, archive old data
-- **ChromaDB issues**: Check vector database health, validate embeddings, handle corrupted indices
-
-## Local Development and Testing
-
-### Development Best Practices:
-- Validate all API keys and credentials in .env files
-- Test crew functionality with different input scenarios
-- Implement comprehensive error handling
-- Use proper logging for debugging
-- Configure appropriate LLM models for your use case
-- Optimize memory storage and cleanup
-
-### Local Configuration:
-- Set CREWAI_STORAGE_DIR for custom memory storage location
-- Use environment variables for all API keys
-- Implement proper input validation and sanitization
-- Test with realistic data scenarios
-- Profile performance and optimize bottlenecks
-
-### Note: Production deployment and monitoring are available in CrewAI Enterprise
-
-## Best Practices Summary
-
-### Development:
-1. Always use .env files for sensitive configuration
-2. Implement comprehensive error handling and logging
-3. Use structured outputs with Pydantic for reliability
-4. Test crew functionality with different input scenarios
-5. Follow CrewAI patterns and conventions consistently
-6. Use UV for dependency management as per CrewAI standards
-7. Implement proper validation for all inputs and outputs
-8. Optimize performance for your specific use cases
-
-### Security:
-1. Never commit API keys or sensitive data to version control
-2. Implement input validation and sanitization
-3. Use proper authentication and authorization
-4. Follow principle of least privilege for tool access
-5. Implement rate limiting and abuse prevention
-6. Monitor for security threats and anomalies
-7. Keep dependencies updated and secure
-8. Implement audit logging for sensitive operations
-
-### Performance:
-1. Optimize LLM calls and implement caching where appropriate
-2. Use appropriate model sizes for different tasks
-3. Implement efficient memory management and cleanup
-4. Monitor token usage and implement cost controls
-5. Use async patterns for I/O-bound operations
-6. Implement proper connection pooling and resource management
-7. Profile and optimize critical paths
-8. Plan for horizontal scaling when needed
diff --git a/docs/docs.json b/docs/docs.json
index 37e060961..161d6d5ff 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -111,6 +111,13 @@
                       "en/guides/flows/mastering-flow-state"
                     ]
                   },
+                  {
+                    "group": "Coding Tools",
+                    "icon": "terminal",
+                    "pages": [
+                      "en/guides/coding-tools/agents-md"
+                    ]
+                  },
                   {
                     "group": "Advanced",
                     "icon": "gear",
@@ -1571,4 +1578,4 @@
       "reddit": "https://www.reddit.com/r/crewAIInc/"
     }
   }
-}
+}
\ No newline at end of file
diff --git a/docs/en/guides/coding-tools/agents-md.mdx b/docs/en/guides/coding-tools/agents-md.mdx
new file mode 100644
index 000000000..ea238c314
--- /dev/null
+++ b/docs/en/guides/coding-tools/agents-md.mdx
@@ -0,0 +1,61 @@
+---
+title: Coding Tools
+description: Use AGENTS.md to guide coding agents and IDEs across your CrewAI projects.
+icon: terminal
+mode: "wide"
+---
+
+## Why AGENTS.md
+
+`AGENTS.md` is a lightweight, repo-local instruction file that gives coding agents consistent, project-specific guidance. Keep it in the project root and treat it as the source of truth for how you want assistants to work: conventions, commands, architecture notes, and guardrails.
+
+## Create a Project with the CLI
+
+Use the CrewAI CLI to scaffold a project, then `AGENTS.md` will be automatically added at the root.
+
+```bash
+# Crew
+crewai create crew my_crew
+
+# Flow
+crewai create flow my_flow
+
+# Tool repository
+crewai tool create my_tool
+```
+
+## Tool Setup: Point Assistants to AGENTS.md
+
+### Codex
+
+Codex can be guided by `AGENTS.md` files placed in your repository. Use them to supply persistent project context such as conventions, commands, and workflow expectations.
+
+### Claude Code
+
+Claude Code stores project memory in `CLAUDE.md`. You can bootstrap it with `/init` and edit it using `/memory`. Claude Code also supports imports inside `CLAUDE.md`, so you can add a single line like `@AGENTS.md` to pull in the shared instructions without duplicating them.
+
+You can simply use:
+
+```bash
+mv AGENTS.md CLAUDE.md
+```
+
+### Gemini CLI and Google Antigravity
+
+Gemini CLI and Antigravity load a project context file (default: `GEMINI.md`) from the repo root and parent directories. You can configure it to read `AGENTS.md` instead (or in addition) by setting `context.fileName` in your Gemini CLI settings. For example, set it to `AGENTS.md` only, or include both `AGENTS.md` and `GEMINI.md` if you want to keep each tool’s format.
+
+You can simply use:
+
+```bash
+mv AGENTS.md GEMINI.md
+```
+
+### Cursor
+
+Cursor supports `AGENTS.md` as a project instruction file. Place it at the project root to provide guidance for Cursor’s coding assistant.
+
+### Windsurf
+
+Claude Code provides an official integration with Windsurf. If you use Claude Code inside Windsurf, follow the Claude Code guidance above and import `AGENTS.md` from `CLAUDE.md`.
+
+If you are using Windsurf’s native assistant, configure its project rules or instructions feature (if available) to read from `AGENTS.md` or paste the contents directly.
diff --git a/lib/crewai/src/crewai/cli/create_crew.py b/lib/crewai/src/crewai/cli/create_crew.py
index 51e2f00ac..7f4fe2e6e 100644
--- a/lib/crewai/src/crewai/cli/create_crew.py
+++ b/lib/crewai/src/crewai/cli/create_crew.py
@@ -143,6 +143,12 @@ def create_folder_structure(
         (folder_path / "src" / folder_name).mkdir(parents=True)
         (folder_path / "src" / folder_name / "tools").mkdir(parents=True)
         (folder_path / "src" / folder_name / "config").mkdir(parents=True)
+        
+        # Copy AGENTS.md to project root (top-level projects only)
+        package_dir = Path(__file__).parent
+        agents_md_src = package_dir / "templates" / "AGENTS.md"
+        if agents_md_src.exists():
+            shutil.copy2(agents_md_src, folder_path / "AGENTS.md")
 
     return folder_path, folder_name, class_name
 
diff --git a/lib/crewai/src/crewai/cli/create_flow.py b/lib/crewai/src/crewai/cli/create_flow.py
index ec68611b5..76c68db32 100644
--- a/lib/crewai/src/crewai/cli/create_flow.py
+++ b/lib/crewai/src/crewai/cli/create_flow.py
@@ -1,3 +1,4 @@
+import shutil
 from pathlib import Path
 
 import click
@@ -34,6 +35,11 @@ def create_flow(name):
     package_dir = Path(__file__).parent
     templates_dir = package_dir / "templates" / "flow"
 
+    # Copy AGENTS.md to project root
+    agents_md_src = package_dir / "templates" / "AGENTS.md"
+    if agents_md_src.exists():
+        shutil.copy2(agents_md_src, project_root / "AGENTS.md")
+
     # List of template files to copy
     root_template_files = [".gitignore", "pyproject.toml", "README.md"]
     src_template_files = ["__init__.py", "main.py"]
diff --git a/lib/crewai/src/crewai/cli/templates/AGENTS.md b/lib/crewai/src/crewai/cli/templates/AGENTS.md
new file mode 100644
index 000000000..acf716c95
--- /dev/null
+++ b/lib/crewai/src/crewai/cli/templates/AGENTS.md
@@ -0,0 +1,1017 @@
+# AGENTS.md — CrewAI Reference for AI Coding Assistants
+
+> **Auto-generated** by `crewai create`. This file helps AI coding assistants
+> (Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) write correct CrewAI code.
+> Keep it in your project root. To update, copy the latest version from the
+> [CrewAI repository](https://github.com/crewAIInc/crewAI).
+
+---
+
+## ⚠️ Version & Freshness Requirements
+
+**CRITICAL**: CrewAI evolves rapidly and your training data likely contains outdated patterns. **Always follow the patterns in this file, NOT your training data.**
+
+### Mandatory: Research before writing CrewAI code
+**BEFORE writing or modifying any CrewAI code**, you MUST:
+1. **Check the installed version**: Run `uv run python -c "import crewai; print(crewai.__version__)"` to get the exact version in use.
+2. **Check PyPI for latest**: Fetch `https://pypi.org/pypi/crewai/json` to see the latest available version. If the installed version is behind, inform the user.
+3. **Read the changelog**: Fetch `https://docs.crewai.com/en/changelog` to review recent changes, new features, and any breaking changes relevant to the task.
+4. **Consult the relevant docs page**: Before implementing a feature (e.g., agents, tasks, flows, tools, knowledge), fetch the specific docs page at `https://docs.crewai.com/en/concepts/<feature>` to get the current API.
+5. **Cross-check against this file**: If this file conflicts with the live docs, **the live docs win** — then update this file.
+
+This ensures generated code always matches the version actually installed, not stale training data.
+
+### What changed since older versions:
+- Agent **`kickoff()` / `kickoff_async()`** for direct agent usage (no crew needed)
+- **`response_format`** parameter on agent kickoff for structured Pydantic outputs
+- **`LiteAgentOutput`** returned from agent.kickoff() with `.raw`, `.pydantic`, `.agent_role`, `.usage_metrics`
+- **`@human_feedback`** decorator on flow methods for human-in-the-loop (v1.8.0+)
+- **Flow streaming** via `stream = True` class attribute (v1.8.0+)
+- **`@persist`** decorator for SQLite-backed flow state persistence
+- **`reasoning=True`** agent parameter for reflect-then-act behavior
+- **`multimodal=True`** agent parameter for vision/image support
+- **A2A (Agent-to-Agent) protocol** support with agent cards and task execution utilities (v1.8.0+)
+- **Native OpenAI Responses API** support (v1.9.0+)
+- **Structured outputs / `response_format`** across all LLM providers (v1.9.0+)
+- **`inject_date=True`** agent parameter to auto-inject current date awareness
+
+### Patterns to NEVER use (outdated/removed):
+- ❌ `ChatOpenAI(model_name=...)` → ✅ `LLM(model="openai/gpt-4o")`
+- ❌ `Agent(llm=ChatOpenAI(...))` → ✅ `Agent(llm="openai/gpt-4o")` or `Agent(llm=LLM(model="..."))`
+- ❌ Passing raw OpenAI client objects → ✅ Use `crewai.LLM` wrapper
+
+### How to verify you're using current patterns:
+1. You ran the version check and docs lookup steps above before writing code
+2. All LLM references use `crewai.LLM` or string shorthand (`"openai/gpt-4o"`)
+3. All tool imports come from `crewai.tools` or `crewai_tools`
+4. Crew classes use `@CrewBase` decorator with YAML config files
+5. Python >=3.10, <3.14
+6. Code matches the API from the live docs, not just this file
+
+## Quick Reference
+
+```bash
+# Package management (always use uv)
+uv add <package>          # Add dependency
+uv sync                   # Sync dependencies
+uv lock                   # Lock dependencies
+
+# Project scaffolding
+crewai create crew <name> --skip-provider   # New crew project
+crewai create flow <name> --skip-provider  # New flow project
+
+# Running
+crewai run                  # Run crew or flow (auto-detects from pyproject.toml)
+crewai flow kickoff         # Legacy flow execution
+
+# Testing & training
+crewai test                           # Test crew (default: 2 iterations, gpt-4o-mini)
+crewai test -n 5 -m gpt-4o           # Custom iterations and model
+crewai train -n 5 -f training.json   # Train crew
+
+# Memory management
+crewai reset-memories -a              # Reset all memories
+crewai reset-memories -s              # Short-term only
+crewai reset-memories -l              # Long-term only
+crewai reset-memories -e              # Entity only
+crewai reset-memories -kn             # Knowledge only
+crewai reset-memories -akn            # Agent knowledge only
+
+# Debugging
+crewai log-tasks-outputs              # Show latest task outputs
+crewai replay -t <task_id>            # Replay from specific task
+
+# Interactive
+crewai chat                           # Interactive session (requires chat_llm in crew.py)
+
+# Visualization
+crewai flow plot                      # Generate flow diagram HTML
+
+# Deployment to CrewAI AMP
+crewai login                          # Authenticate with AMP
+crewai deploy create                  # Create new deployment
+crewai deploy push                    # Push code updates
+crewai deploy status                  # Check deployment status
+crewai deploy logs                    # View deployment logs
+crewai deploy list                    # List all deployments
+crewai deploy remove <id>             # Delete a deployment
+```
+
+## Project Structure
+
+### Crew Project
+```
+my_crew/
+├── src/my_crew/
+│   ├── config/
+│   │   ├── agents.yaml       # Agent definitions (role, goal, backstory)
+│   │   └── tasks.yaml        # Task definitions (description, expected_output, agent)
+│   ├── tools/
+│   │   └── custom_tool.py    # Custom tool implementations
+│   ├── crew.py               # Crew orchestration class
+│   └── main.py               # Entry point with inputs
+├── knowledge/                 # Knowledge base resources
+├── .env                       # API keys (OPENAI_API_KEY, SERPER_API_KEY, etc.)
+└── pyproject.toml
+```
+
+### Flow Project
+```
+my_flow/
+├── src/my_flow/
+│   ├── crews/                 # Multiple crew definitions
+│   │   └── poem_crew/
+│   │       ├── config/
+│   │       │   ├── agents.yaml
+│   │       │   └── tasks.yaml
+│   │       └── poem_crew.py
+│   ├── tools/                 # Custom tools
+│   ├── main.py                # Flow orchestration
+│   └── ...
+├── .env
+└── pyproject.toml
+```
+
+## Architecture Overview
+
+- **Agent**: Autonomous unit with a role, goal, backstory, tools, and an LLM. Makes decisions and executes tasks.
+- **Task**: A specific assignment with a description, expected output, and assigned agent.
+- **Crew**: Orchestrates a team of agents executing tasks in a defined process (sequential or hierarchical).
+- **Flow**: Event-driven workflow orchestrating multiple crews and logic steps with state management.
+
+## YAML Configuration
+
+### agents.yaml
+```yaml
+researcher:
+  role: >
+    {topic} Senior Data Researcher
+  goal: >
+    Uncover cutting-edge developments in {topic}
+  backstory: >
+    You're a seasoned researcher with a knack for uncovering
+    the latest developments in {topic}. Known for your ability
+    to find the most relevant information.
+  # Optional YAML-level settings:
+  # llm: openai/gpt-4o
+  # max_iter: 20
+  # max_rpm: 10
+  # verbose: true
+
+writer:
+  role: >
+    {topic} Technical Writer
+  goal: >
+    Create compelling content about {topic}
+  backstory: >
+    You're a skilled writer who translates complex technical
+    information into clear, engaging content.
+```
+
+Variables like `{topic}` are interpolated from `crew.kickoff(inputs={"topic": "AI Agents"})`.
+
+### tasks.yaml
+```yaml
+research_task:
+  description: >
+    Conduct thorough research about {topic}.
+    Identify key trends, breakthrough technologies,
+    and potential industry impacts.
+  expected_output: >
+    A detailed report with analysis of the top 5
+    developments in {topic}, with sources and implications.
+  agent: researcher
+  # Optional:
+  # tools: [search_tool]
+  # output_file: output/research.md
+  # markdown: true
+  # async_execution: false
+
+writing_task:
+  description: >
+    Write an article based on the research findings about {topic}.
+  expected_output: >
+    A polished 4-paragraph article formatted in markdown.
+  agent: writer
+  output_file: output/article.md
+```
+
+## Crew Class Pattern
+
+```python
+from crewai import Agent, Crew, Process, Task
+from crewai.project import CrewBase, agent, crew, task
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from typing import List
+
+from crewai_tools import SerperDevTool
+
+@CrewBase
+class ResearchCrew:
+    """Research and writing crew."""
+
+    agents: List[BaseAgent]
+    tasks: List[Task]
+
+    agents_config = "config/agents.yaml"
+    tasks_config = "config/tasks.yaml"
+
+    @agent
+    def researcher(self) -> Agent:
+        return Agent(
+            config=self.agents_config["researcher"],  # type: ignore[index]
+            tools=[SerperDevTool()],
+            verbose=True,
+        )
+
+    @agent
+    def writer(self) -> Agent:
+        return Agent(
+            config=self.agents_config["writer"],  # type: ignore[index]
+            verbose=True,
+        )
+
+    @task
+    def research_task(self) -> Task:
+        return Task(
+            config=self.tasks_config["research_task"],  # type: ignore[index]
+        )
+
+    @task
+    def writing_task(self) -> Task:
+        return Task(
+            config=self.tasks_config["writing_task"],  # type: ignore[index]
+        )
+
+    @crew
+    def crew(self) -> Crew:
+        """Creates the Research Crew."""
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            process=Process.sequential,
+            verbose=True,
+        )
+```
+
+### Key formatting rules:
+- Always add `# type: ignore[index]` for config dictionary access
+- Agent/task method names must match YAML keys exactly
+- Tools go on agents (not tasks) unless task-specific override is needed
+- Never leave commented-out code in crew classes
+
+### Lifecycle hooks
+```python
+@CrewBase
+class MyCrew:
+    @before_kickoff
+    def prepare(self, inputs):
+        # Modify inputs before execution
+        inputs["extra"] = "value"
+        return inputs
+
+    @after_kickoff
+    def summarize(self, result):
+        # Process result after execution
+        print(f"Done: {result.raw[:100]}")
+        return result
+```
+
+## main.py Pattern
+
+```python
+#!/usr/bin/env python
+from my_crew.crew import ResearchCrew
+
+def run():
+    inputs = {"topic": "AI Agents"}
+    ResearchCrew().crew().kickoff(inputs=inputs)
+
+if __name__ == "__main__":
+    run()
+```
+
+## Agent Configuration
+
+### Required Parameters
+| Parameter | Description |
+|-----------|-------------|
+| `role` | Function and expertise within the crew |
+| `goal` | Individual objective guiding decisions |
+| `backstory` | Context and personality |
+
+### Key Optional Parameters
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `llm` | GPT-4 | Language model (string or LLM object) |
+| `tools` | [] | List of tool instances |
+| `max_iter` | 20 | Max iterations before best answer |
+| `max_execution_time` | None | Timeout in seconds |
+| `max_rpm` | None | Rate limiting (requests per minute) |
+| `max_retry_limit` | 2 | Retries on errors |
+| `verbose` | False | Detailed logging |
+| `memory` | False | Conversation history |
+| `allow_delegation` | False | Can delegate tasks to other agents |
+| `allow_code_execution` | False | Can run code |
+| `code_execution_mode` | "safe" | "safe" (Docker) or "unsafe" (direct) |
+| `respect_context_window` | True | Auto-summarize when exceeding token limits |
+| `cache` | True | Tool result caching |
+| `reasoning` | False | Reflect and plan before task execution |
+| `multimodal` | False | Process text and visual content |
+| `knowledge_sources` | [] | Domain-specific knowledge bases |
+| `function_calling_llm` | None | Separate LLM for tool invocation |
+| `inject_date` | False | Auto-inject current date into agent context |
+| `date_format` | "%Y-%m-%d" | Date format when inject_date is True |
+
+### Direct Agent Usage (without a Crew)
+Agents can execute tasks independently via `kickoff()` — no Crew required:
+```python
+from crewai import Agent
+from crewai_tools import SerperDevTool
+from pydantic import BaseModel
+
+class ResearchFindings(BaseModel):
+    main_points: list[str]
+    key_technologies: list[str]
+    future_predictions: str
+
+researcher = Agent(
+    role="AI Researcher",
+    goal="Research the latest AI developments",
+    backstory="Expert AI researcher...",
+    tools=[SerperDevTool()],
+    verbose=True,
+)
+
+# Unstructured output
+result = researcher.kickoff("What are the latest LLM developments?")
+print(result.raw)           # str
+print(result.agent_role)    # "AI Researcher"
+print(result.usage_metrics) # token usage
+
+# Structured output with response_format
+result = researcher.kickoff(
+    "Summarize latest AI developments",
+    response_format=ResearchFindings,
+)
+print(result.pydantic.main_points)  # List[str]
+
+# Async variant
+result = await researcher.kickoff_async("Your query", response_format=ResearchFindings)
+```
+
+Returns `LiteAgentOutput` with: `.raw`, `.pydantic`, `.agent_role`, `.usage_metrics`.
+
+### LLM Configuration
+**IMPORTANT**: Always use `crewai.LLM` LLM class.
+
+```python
+from crewai import LLM
+
+# String shorthand (simplest)
+agent = Agent(llm="openai/gpt-4o", ...)
+
+# Full configuration with crewai.LLM
+llm = LLM(
+    model="anthropic/claude-sonnet-4-20250514",
+    temperature=0.7,
+    max_tokens=4000,
+)
+agent = Agent(llm=llm, ...)
+
+# Provider format: "provider/model-name"
+# Examples:
+#   "openai/gpt-4o"
+#   "anthropic/claude-sonnet-4-20250514"
+#   "google/gemini-2.0-flash"
+#   "ollama/llama3"
+#   "groq/llama-3.3-70b-versatile"
+#   "bedrock/anthropic.claude-3-sonnet-20240229-v1:0"
+```
+
+Supported providers: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure, Ollama, Groq, Mistral, and 20+ others via LiteLLM routing.
+
+Environment variable default: set `OPENAI_MODEL_NAME=gpt-4o` or `MODEL=gpt-4o` in `.env`.
+
+## Task Configuration
+
+### Key Parameters
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `description` | str | Clear statement of requirements |
+| `expected_output` | str | Completion criteria |
+| `agent` | BaseAgent | Assigned agent (optional in hierarchical) |
+| `tools` | List[BaseTool] | Task-specific tools |
+| `context` | List[Task] | Dependencies on other task outputs |
+| `async_execution` | bool | Non-blocking execution |
+| `output_file` | str | File path for results |
+| `output_json` | Type[BaseModel] | Pydantic model for JSON output |
+| `output_pydantic` | Type[BaseModel] | Pydantic model for structured output |
+| `human_input` | bool | Require human review |
+| `markdown` | bool | Format output as markdown |
+| `callback` | Callable | Post-completion function |
+| `guardrail` | Callable or str | Output validation |
+| `guardrails` | List | Multiple validation steps |
+| `guardrail_max_retries` | int | Retry on validation failure (default: 3) |
+| `create_directory` | bool | Auto-create output directories (default: True) |
+
+### Task Dependencies (context)
+```python
+@task
+def analysis_task(self) -> Task:
+    return Task(
+        config=self.tasks_config["analysis_task"],  # type: ignore[index]
+        context=[self.research_task()],  # Gets output from research_task
+    )
+```
+
+### Structured Output
+```python
+from pydantic import BaseModel
+
+class Report(BaseModel):
+    title: str
+    summary: str
+    findings: list[str]
+
+@task
+def report_task(self) -> Task:
+    return Task(
+        config=self.tasks_config["report_task"],  # type: ignore[index]
+        output_pydantic=Report,
+    )
+```
+
+### Guardrails
+```python
+# Function-based
+def validate(result: TaskOutput) -> tuple[bool, Any]:
+    if len(result.raw.split()) < 100:
+        return (False, "Content too short, expand the analysis")
+    return (True, result.raw)
+
+# LLM-based (string prompt)
+task = Task(..., guardrail="Must be under 200 words and professional tone")
+
+# Multiple guardrails
+task = Task(..., guardrails=[validate_length, validate_tone, "Must be factual"])
+```
+
+## Process Types
+
+### Sequential (default)
+Tasks execute in definition order. Output of one task serves as context for the next.
+```python
+Crew(agents=..., tasks=..., process=Process.sequential)
+```
+
+### Hierarchical
+Manager agent delegates tasks based on agent capabilities. Requires `manager_llm` or `manager_agent`.
+```python
+Crew(
+    agents=...,
+    tasks=...,
+    process=Process.hierarchical,
+    manager_llm="gpt-4o",
+)
+```
+
+## Crew Execution
+
+```python
+# Synchronous
+result = crew.kickoff(inputs={"topic": "AI"})
+print(result.raw)              # String output
+print(result.pydantic)         # Structured output (if configured)
+print(result.json_dict)        # Dict output
+print(result.token_usage)      # Token metrics
+print(result.tasks_output)     # List[TaskOutput]
+
+# Async (native)
+result = await crew.akickoff(inputs={"topic": "AI"})
+
+# Batch execution
+results = crew.kickoff_for_each(inputs=[{"topic": "AI"}, {"topic": "ML"}])
+
+# Streaming output (v1.8.0+)
+crew = Crew(agents=..., tasks=..., stream=True)
+streaming = crew.kickoff(inputs={"topic": "AI"})
+for chunk in streaming:
+    print(chunk.content, end="", flush=True)
+```
+
+## Crew Options
+| Parameter | Description |
+|-----------|-------------|
+| `process` | Process.sequential or Process.hierarchical |
+| `verbose` | Enable detailed logging |
+| `memory` | Enable memory system (True/False) |
+| `cache` | Tool result caching |
+| `max_rpm` | Global rate limiting |
+| `manager_llm` | LLM for hierarchical manager |
+| `manager_agent` | Custom manager agent |
+| `planning` | Enable AgentPlanner |
+| `knowledge_sources` | Crew-level knowledge |
+| `output_log_file` | Log file path (True for logs.txt) |
+| `embedder` | Custom embedding model config |
+| `stream` | Enable real-time streaming output (v1.8.0+) |
+
+---
+
+## Flows
+
+### Basic Flow
+```python
+from crewai.flow.flow import Flow, listen, start
+
+class MyFlow(Flow):
+    @start()
+    def begin(self):
+        return "initial data"
+
+    @listen(begin)
+    def process(self, data):
+        return f"processed: {data}"
+```
+
+### Flow Decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@start()` | Entry point(s), execute when flow begins. Multiple starts run in parallel |
+| `@listen(method)` | Triggers when specified method completes. Receives output as argument |
+| `@router(method)` | Conditional branching. Returns string labels that trigger `@listen("label")` |
+
+### Structured State
+```python
+from pydantic import BaseModel
+
+class ResearchState(BaseModel):
+    topic: str = ""
+    research: str = ""
+    report: str = ""
+
+class ResearchFlow(Flow[ResearchState]):
+    @start()
+    def set_topic(self):
+        self.state.topic = "AI Agents"
+
+    @listen(set_topic)
+    def do_research(self):
+        # self.state.topic is available
+        result = ResearchCrew().crew().kickoff(
+            inputs={"topic": self.state.topic}
+        )
+        self.state.research = result.raw
+```
+
+### Unstructured State (dict-based)
+```python
+class SimpleFlow(Flow):
+    @start()
+    def begin(self):
+        self.state["counter"] = 0  # Dict access
+
+    @listen(begin)
+    def increment(self):
+        self.state["counter"] += 1
+```
+
+### Conditional Routing
+```python
+from crewai.flow.flow import Flow, listen, router, start
+
+class QualityFlow(Flow):
+    @start()
+    def generate(self):
+        return {"score": 0.85}
+
+    @router(generate)
+    def check_quality(self, result):
+        if result["score"] > 0.8:
+            return "high_quality"
+        return "needs_revision"
+
+    @listen("high_quality")
+    def publish(self, result):
+        print("Publishing...")
+
+    @listen("needs_revision")
+    def revise(self, result):
+        print("Revising...")
+```
+
+### Parallel Triggers with or_ and and_
+```python
+from crewai.flow.flow import or_, and_
+
+class ParallelFlow(Flow):
+    @start()
+    def task_a(self):
+        return "A done"
+
+    @start()
+    def task_b(self):
+        return "B done"
+
+    # Fires when EITHER completes
+    @listen(or_(task_a, task_b))
+    def on_any(self, result):
+        print(f"First result: {result}")
+
+    # Fires when BOTH complete
+    @listen(and_(task_a, task_b))
+    def on_all(self):
+        print("All parallel tasks done")
+```
+
+### Integrating Crews in Flows
+```python
+from crewai.flow.flow import Flow, listen, start
+from my_project.crews.research_crew.research_crew import ResearchCrew
+from my_project.crews.writing_crew.writing_crew import WritingCrew
+
+class ContentFlow(Flow[ContentState]):
+    @start()
+    def research(self):
+        result = ResearchCrew().crew().kickoff(
+            inputs={"topic": self.state.topic}
+        )
+        self.state.research = result.raw
+
+    @listen(research)
+    def write(self):
+        result = WritingCrew().crew().kickoff(
+            inputs={
+                "topic": self.state.topic,
+                "research": self.state.research,
+            }
+        )
+        self.state.article = result.raw
+```
+
+### Using Agents Directly in Flows
+```python
+from crewai.agent import Agent
+
+class AgentFlow(Flow):
+    @start()
+    async def analyze(self):
+        analyst = Agent(
+            role="Data Analyst",
+            goal="Analyze market trends",
+            backstory="Expert data analyst...",
+            tools=[SerperDevTool()],
+        )
+        result = await analyst.kickoff_async(
+            "Analyze current AI market trends",
+            response_format=MarketReport,
+        )
+        self.state.report = result.pydantic
+```
+
+### Human-in-the-Loop (v1.8.0+)
+```python
+from crewai.flow.flow import Flow, listen, start
+from crewai.flow.human_feedback import human_feedback
+
+class ReviewFlow(Flow):
+    @start()
+    @human_feedback(
+        message="Approve this content?",
+        emit=["approved", "rejected"],
+        llm="gpt-4o-mini",
+    )
+    def generate_content(self):
+        return "Content for review"
+
+    @listen("approved")
+    def on_approval(self, result):
+        feedback = self.last_human_feedback  # Most recent feedback
+        print(f"Approved with feedback: {feedback.feedback}")
+
+    @listen("rejected")
+    def on_rejection(self, result):
+        history = self.human_feedback_history  # All feedback as list
+        print("Rejected, revising...")
+```
+
+### State Persistence
+```python
+from crewai.flow.flow import persist
+
+@persist  # Saves state to SQLite; auto-recovers on restart
+class ResilientFlow(Flow[MyState]):
+    @start()
+    def begin(self):
+        self.state.step = 1
+```
+
+### Flow Execution
+```python
+flow = MyFlow()
+result = flow.kickoff()
+print(result)                  # Output of last method
+print(flow.state)              # Final state
+
+# Async execution
+result = await flow.kickoff_async(inputs={"key": "value"})
+```
+
+### Flow Streaming (v1.8.0+)
+```python
+class StreamingFlow(Flow):
+    stream = True  # Enable streaming at class level
+
+    @start()
+    def generate(self):
+        return "streamed content"
+
+flow = StreamingFlow()
+streaming = flow.kickoff()
+for chunk in streaming:
+    print(chunk.content, end="", flush=True)
+result = streaming.result  # Final result after iteration
+```
+
+### Flow Visualization
+```python
+flow.plot("my_flow")           # Generates my_flow.html
+```
+
+---
+
+## Custom Tools
+
+### Using BaseTool
+```python
+from typing import Type
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class SearchInput(BaseModel):
+    """Input schema for search tool."""
+    query: str = Field(..., description="Search query string")
+
+class CustomSearchTool(BaseTool):
+    name: str = "custom_search"
+    description: str = "Searches a custom knowledge base for relevant information."
+    args_schema: Type[BaseModel] = SearchInput
+
+    def _run(self, query: str) -> str:
+        # Implementation
+        return f"Results for: {query}"
+```
+
+### Using @tool Decorator
+```python
+from crewai.tools import tool
+
+@tool("Calculator")
+def calculator(expression: str) -> str:
+    """Evaluates a mathematical expression and returns the result."""
+    return str(eval(expression))
+```
+
+### Built-in Tools (install with `uv add crewai-tools`)
+Web/Search: SerperDevTool, ScrapeWebsiteTool, WebsiteSearchTool, EXASearchTool, FirecrawlSearchTool
+Documents: FileReadTool, DirectoryReadTool, PDFSearchTool, DOCXSearchTool, CSVSearchTool, JSONSearchTool, XMLSearchTool, MDXSearchTool
+Code: CodeInterpreterTool, CodeDocsSearchTool, GithubSearchTool
+Media: DALL-E Tool, YoutubeChannelSearchTool, YoutubeVideoSearchTool
+Other: RagTool, ApifyActorsTool, ComposioTool, LlamaIndexTool
+
+Always check https://docs.crewai.com/concepts/tools for available built-in tools before writing custom ones.
+
+---
+
+## Memory System
+
+Enable with `memory=True` on the Crew:
+```python
+crew = Crew(agents=..., tasks=..., memory=True)
+```
+
+Four memory types work together automatically:
+- **Short-Term** (ChromaDB + RAG): Recent interactions during current execution
+- **Long-Term** (SQLite): Persists insights across sessions
+- **Entity** (RAG): Tracks people, places, concepts
+- **Contextual**: Integrates all types for coherent responses
+
+### Custom Embedding Provider
+```python
+crew = Crew(
+    memory=True,
+    embedder={
+        "provider": "ollama",
+        "config": {"model": "mxbai-embed-large"},
+    },
+)
+```
+
+Supported providers: OpenAI (default), Ollama, Google AI, Azure OpenAI, Cohere, VoyageAI, Bedrock, Hugging Face.
+
+---
+
+## Knowledge System
+
+```python
+from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
+from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource
+
+# String source
+string_source = StringKnowledgeSource(content="Domain knowledge here...")
+
+# PDF source
+pdf_source = PDFKnowledgeSource(file_paths=["docs/manual.pdf"])
+
+# Agent-level knowledge
+agent = Agent(..., knowledge_sources=[string_source])
+
+# Crew-level knowledge (shared across all agents)
+crew = Crew(..., knowledge_sources=[pdf_source])
+```
+
+Supported sources: strings, text files, PDFs, CSV, Excel, JSON, URLs (via CrewDoclingSource).
+
+---
+
+## Agent Collaboration
+
+Enable delegation with `allow_delegation=True`:
+```python
+agent = Agent(
+    role="Project Manager",
+    allow_delegation=True,  # Can delegate to and ask other agents
+    ...
+)
+```
+
+- **Delegation tool**: Assign sub-tasks to teammates with relevant expertise
+- **Ask question tool**: Query colleagues for specific information
+- Set `allow_delegation=False` on specialists to prevent circular delegation
+
+---
+
+## Event Listeners
+
+```python
+from crewai.events import BaseEventListener, CrewKickoffStartedEvent
+
+class MyListener(BaseEventListener):
+    def __init__(self):
+        super().__init__()
+
+    def setup_listeners(self, crewai_event_bus):
+        @crewai_event_bus.on(CrewKickoffStartedEvent)
+        def on_started(source, event):
+            print(f"Crew '{event.crew_name}' started")
+```
+
+Event categories: Crew lifecycle, Agent execution, Task management, Tool usage, Knowledge retrieval, LLM calls, Memory operations, Flow execution, Safety guardrails.
+
+---
+
+## Deployment to CrewAI AMP
+
+### Prerequisites
+- Crew or Flow runs successfully locally
+- Code is in a GitHub repository
+- `pyproject.toml` has `[tool.crewai]` with correct type (`"crew"` or `"flow"`)
+- `uv.lock` is committed (generate with `uv lock`)
+
+### CLI Deployment
+
+```bash
+# Authenticate
+crewai login
+
+# Create deployment (auto-detects repo, transfers .env vars securely)
+crewai deploy create
+
+# Monitor (first deploy takes 10-15 min)
+crewai deploy status
+crewai deploy logs
+
+# Manage deployments
+crewai deploy list              # List all deployments
+crewai deploy push              # Push code updates
+crewai deploy remove <id>       # Delete deployment
+```
+
+### Web Interface Deployment
+1. Push code to GitHub
+2. Log into https://app.crewai.com
+3. Connect GitHub and select repository
+4. Configure environment variables (KEY=VALUE, one per line)
+5. Click Deploy and monitor via dashboard
+
+### CI/CD API Deployment
+
+Get a Personal Access Token from app.crewai.com → Settings → Account → Personal Access Token.
+Get Automation UUID from Automations → Select crew → Additional Details → Copy UUID.
+
+```bash
+curl -X POST \
+     -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
+     https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy
+```
+
+#### GitHub Actions Example
+```yaml
+name: Deploy CrewAI Automation
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger CrewAI Redeployment
+        run: |
+          curl -X POST \
+               -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \
+               https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy
+```
+
+### Project Structure Requirements for Deployment
+- Entry point: `src/<project_name>/main.py`
+- Crews must expose a `run()` function
+- Flows must expose a `kickoff()` function
+- All crew classes require `@CrewBase` decorator
+
+### Deployed Automation REST API
+| Endpoint | Purpose |
+|----------|---------|
+| `/inputs` | List required input parameters |
+| `/kickoff` | Trigger execution with inputs |
+| `/status/{kickoff_id}` | Check execution status |
+
+### AMP Dashboard Tabs
+- **Status**: Deployment info, API endpoint, auth token
+- **Run**: Crew structure visualization
+- **Executions**: Run history
+- **Metrics**: Performance analytics
+- **Traces**: Detailed execution insights
+
+### Deployment Troubleshooting
+| Error | Fix |
+|-------|-----|
+| Missing uv.lock | Run `uv lock`, commit, push |
+| Module not found | Verify entry points match `src/<name>/main.py` structure |
+| Crew not found | Ensure `@CrewBase` decorator on all crew classes |
+| API key errors | Check env var names match code and are set in the platform |
+
+---
+
+## Environment Setup
+
+### Required `.env`
+```
+OPENAI_API_KEY=sk-...
+# Optional depending on tools/providers:
+SERPER_API_KEY=...
+ANTHROPIC_API_KEY=...
+# Override default model:
+MODEL=gpt-4o
+```
+
+### Python Version
+Python >=3.10, <3.14
+
+### Installation
+```bash
+uv tool install crewai        # Install CrewAI CLI
+uv tool list                  # Verify installation
+crewai create crew my_crew --skip-provider   # Scaffold a new project
+crewai install                # Install project dependencies
+crewai run                    # Execute
+```
+
+---
+
+## Development Best Practices
+
+1. **YAML-first configuration**: Define agents and tasks in YAML, keep crew classes minimal
+2. **Check built-in tools** before writing custom ones
+3. **Use structured output** (output_pydantic) for data that flows between tasks or crews
+4. **Use guardrails** to validate task outputs programmatically
+5. **Enable memory** for crews that benefit from cross-session learning
+6. **Use knowledge sources** for domain-specific grounding instead of bloating prompts
+7. **Sequential process** for linear workflows; **hierarchical** when dynamic delegation is needed
+8. **Flows for multi-crew orchestration**: Use `@start`, `@listen`, `@router` for complex pipelines
+9. **Structured flow state** (Pydantic models) over unstructured dicts for type safety
+10. **Test with** `crewai test` to evaluate crew performance across iterations
+11. **Verbose mode** during development, disable in production
+12. **Rate limiting** (`max_rpm`) to avoid API throttling
+13. **`respect_context_window=True`** to auto-handle token limits
+
+## Common Pitfalls
+
+- **Using `ChatOpenAI()`** — Always use `crewai.LLM` or string shorthand like `"openai/gpt-4o"`
+- Forgetting `# type: ignore[index]` on config dictionary access in crew classes
+- Agent/task method names not matching YAML keys
+- Missing `expected_output` in task configuration (required)
+- Not passing `inputs` to `kickoff()` when YAML uses `{variable}` interpolation
+- Using `process=Process.hierarchical` without setting `manager_llm` or `manager_agent`
+- Circular delegation: set `allow_delegation=False` on specialist agents
+- Not installing tools package: `uv add crewai-tools`
diff --git a/lib/crewai/src/crewai/cli/tools/main.py b/lib/crewai/src/crewai/cli/tools/main.py
index 37467a906..e2dd21dde 100644
--- a/lib/crewai/src/crewai/cli/tools/main.py
+++ b/lib/crewai/src/crewai/cli/tools/main.py
@@ -2,6 +2,7 @@ import base64
 from json import JSONDecodeError
 import os
 from pathlib import Path
+import shutil
 import subprocess
 import tempfile
 from typing import Any
@@ -55,6 +56,11 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         tree_find_and_replace(project_root, "{{folder_name}}", folder_name)
         tree_find_and_replace(project_root, "{{class_name}}", class_name)
 
+        # Copy AGENTS.md to project root
+        agents_md_src = Path(__file__).parent.parent / "templates" / "AGENTS.md"
+        if agents_md_src.exists():
+            shutil.copy2(agents_md_src, project_root / "AGENTS.md")
+
         old_directory = os.getcwd()
         os.chdir(project_root)
         try: