From ec0c0cd9ce35503bf3e8a5878ad3f3f258748cd6 Mon Sep 17 00:00:00 2001
From: Jean Silva <jeancsil@gmail.com>
Date: Sun, 22 Feb 2026 01:09:26 +0100
Subject: [PATCH 1/3] docs: revamp README to clarify purpose and CLI usage

Clarify project scope and replace "educational" wording with a concise
description of the framework's role in building agentic systems.
Reorganize README sections for a faster onboarding flow: "What is this?",
"Quick Start", "Available Agents", "CLI Reference", and "Developer Agent".

Highlight key features (decorator-based agent registration, LangGraph
pattern, MCP permissions, multi-language code tools, safe file editing),
and add a concise agents table summarizing purposes, MCP access and tools.
Streamline Quick Start commands (install, test, list, info, run, timeout,
verbose) and replace project-specific uv invocations with --directory so
examples run from outside the repo. Remove outdated Docker instructions and
old verbose featured-agent lists.

These changes make the README more actionable for new users and surface
important capabilities and CLI usage up front.
---
 AGENTS.md | 569 +++++++++++++++++++++++++++---------------------------
 README.md | 296 +++++++++++++++++-----------
 2 files changed, 460 insertions(+), 405 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ec93a00..d962a72 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,390 +1,385 @@
-# Agents Guide
+# AGENTS.md
 
-This guide is for both external LLMs working within this codebase and developers building new agents and tools.
+**FOR LLM AGENTS DEVELOPING THIS FRAMEWORK.** This document defines strict rules for modifying the agentic-framework codebase.
 
-## Environment
+---
 
-We use uv for package management and running commands.
-cd is aliased to z (zoxide), use full path instead.
-ls is aliased to eza, use full path instead.
+## PURPOSE
 
-## Project Overview
+You are an LLM agent tasked with improving, fixing, or extending the **agentic-framework** codebase. This document defines how you MUST approach this work.
 
-This is a **LangChain + MCP framework** for building agentic systems in Python 3.12+.
+---
 
-### Key Technologies
+## STRICT BEHAVIORAL RULES
 
-- **LangChain**: LLM orchestration framework
-- **LangGraph**: Stateful agent workflows with checkpoints
-- **MCP (Model Context Protocol)**: External tool integration
-- **Typer**: CLI interface
-- **Rich**: Terminal formatting
+### ALWAYS Rules
 
-## Architecture
+1. **ALWAYS** run `make check` after making any code changes.
+2. **ALWAYS** run `make test` after making any code changes.
+3. **ALWAYS** fix all linting errors before indicating completion.
+4. **ALWAYS** fix all test failures before indicating completion.
+5. **ALWAYS** maintain or improve test coverage (current: 80%).
+6. **ALWAYS** follow existing code patterns in the codebase.
+7. **ALWAYS** add tests for new functionality.
+8. **ALWAYS** update docstrings if you change function behavior.
+9. **ALWAYS** use `uv` for package management (not pip, not poetry).
+10. **ALWAYS** run commands from the correct directory (see Working Directory).
 
-### Directory Structure
+### NEVER Rules
 
-```
-src/agentic_framework/
-├── core/               # Agent implementations
-│   ├── __init__.py     # Exports only base classes (no concrete agents)
-│   ├── langgraph_agent.py    # Reusable LangGraphMCPAgent base
-│   ├── simple_agent.py       # Basic LLM agent (no tools)
-│   ├── chef_agent.py         # Recipe finder with web search
-│   ├── travel_agent.py       # Flight search via Kiwi MCP
-│   ├── news_agent.py         # AI news via web-fetch MCP
-│   ├── travel_coordinator_agent.py  # Multi-agent orchestration
-│   └── developer_agent.py    # Codebase exploration agent
-├── interfaces/          # Abstract base classes
-│   └── base.py          # Agent and Tool ABCs
-├── mcp/                 # Model Context Protocol
-│   ├── config.py        # MCP server configurations
-│   └── provider.py      # MCP client and session management
-├── tools/               # Tool implementations
-│   ├── codebase_explorer.py  # Code navigation tools
-│   ├── code_searcher.py      # ripgrep wrapper
-│   ├── web_search.py         # Tavily search
-│   └── example.py            # Demo tools
-├── constants.py         # Project-wide constants
-├── registry.py          # Agent discovery and registration
-└── cli.py               # CLI interface
-```
+1. **NEVER** skip running `make check` and `make test`.
+2. **NEVER** commit changes unless explicitly requested by the user.
+3. **NEVER** push changes without user confirmation.
+4. **NEVER** introduce new dependencies without discussion.
+5. **NEVER** delete existing tests without replacement.
+6. **NEVER** change the public API without updating all affected code.
+7. **NEVER** use synchronous code where async is expected.
+8. **NEVER** raise exceptions from tools - return error strings instead.
+9. **NEVER** edit generated files (uv.lock, etc.) directly.
+10. **NEVER** ignore deprecation warnings - fix them.
 
-## Core Concepts
+### BEFORE Rules
 
-### Agent
+1. **BEFORE** making changes: Read and understand the existing code.
+2. **BEFORE** claiming done: Run `make check && make test`.
+3. **BEFORE** adding features: Check if similar functionality exists.
+4. **BEFORE** refactoring: Ensure tests cover the affected code.
 
-Base class defined in `interfaces/base.py`:
+### AFTER Rules
 
-```python
-class Agent(ABC):
-    @abstractmethod
-    async def run(
-        self,
-        input_data: Union[str, List[BaseMessage]],
-        config: Optional[Dict[str, Any]] = None,
-    ) -> Union[str, BaseMessage]:
-        """Run the agent with the given input."""
-
-    @abstractmethod
-    def get_tools(self) -> List[Any]:
-        """Return available tools for this agent."""
-```
+1. **AFTER** editing code: Run `make check` immediately.
+2. **AFTER** check passes: Run `make test`.
+3. **AFTER** tests pass: Summarize what was changed and why.
 
-### Tool
+---
 
-Base class defined in `interfaces/base.py`:
-
-```python
-class Tool(ABC):
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """The name of the tool."""
-
-    @property
-    @abstractmethod
-    def description(self) -> str:
-        """A description of what the tool does."""
-
-    @abstractmethod
-    def invoke(self, input_str: str) -> Any:
-        """Execute the tool logic."""
-```
+## WORKING DIRECTORY
 
-### Agent Registry
+You are in `/Users/jeancsil/code/agents/agentic-framework/`. The project root is one level up.
 
-Central registration system in `registry.py`:
+```bash
+# Run make commands from parent directory
+make -C .. check
+make -C .. test
+make -C .. format
 
-```python
-@AgentRegistry.register("agent-name", mcp_servers=["server1", "server2"])
-class MyAgent(Agent):
-    # Implementation
+# Or use full path
+make -C /Users/jeancsil/code/agents check
 ```
 
-**Registry Methods:**
-- `AgentRegistry.list_agents()` - List all registered agents
-- `AgentRegistry.get(name)` - Get agent class by name
-- `AgentRegistry.get_mcp_servers(name)` - Get allowed MCP servers for an agent
-- `AgentRegistry.discover_agents()` - Auto-discover agents in `core/` package
-- `AgentRegistry.set_strict_registration(strict=True)` - Enable strict mode (raises error on duplicate registrations)
-- `AgentRegistry.register(name, mcp_servers, override=False)` - Register an agent with optional override flag
+---
 
-### MCP (Model Context Protocol)
+## DEVELOPMENT WORKFLOW
 
-External tool integration managed by `MCPProvider`.
+### Step 1: UNDERSTAND
+Before making changes:
+1. Read the relevant source files
+2. Read related test files
+3. Understand the existing patterns
+4. Check CLAUDE.md for architectural context
 
-**Available MCP Servers** (see `mcp/config.py`):
-- `kiwi-com-flight-search` - Flight search
-- `tinyfish` - AI assistant
-- `web-fetch` - Web content fetching
-- `tavily` - Web search
+### Step 2: IMPLEMENT
+Make your changes:
+1. Follow existing code style
+2. Add type hints (this project uses strict mypy)
+3. Add/update docstrings for public functions
+4. Keep functions focused and small
 
-## Example of Available Agents
+### Step 3: VERIFY
+After changes:
+```bash
+make -C .. check    # Linting (mypy + ruff)
+make -C .. test     # Run all tests
+```
 
-### simple
-Basic LLM assistant with no tools. Minimal example.
+### Step 4: FIX
+If checks or tests fail:
+1. Read the error message carefully
+2. Fix the issue
+3. Re-run the failing command
+4. Repeat until all pass
 
-### chef
-Recipe finder using local web search tool + Tavily MCP.
+---
 
-### travel
-Flight search assistant using Kiwi MCP.
+## CODE STANDARDS
 
-### news
-AI news aggregator using web-fetch MCP.
+### Type Hints
 
-### travel-coordinator
-Orchestrates 3 specialist agents (flight, city intel, reviewer) with MCP tools.
+This project uses strict mypy. All functions MUST have type hints:
 
-### developer
-Codebase exploration agent with specialized local tools and webfetch MCP:
-- `find_files` - Fast file search via fd
-- `discover_structure` - Directory tree exploration
-- `get_file_outline` - Extract class/function signatures (multi-language)
-- `read_file_fragment` - Read specific line ranges
-- `code_search` - Fast pattern search via ripgrep
-- `webfetch` (MCP) - Web content fetching
+```python
+# GOOD
+async def run(self, input_data: str, config: dict[str, Any] | None = None) -> str:
+    ...
 
-**Supported Languages for `get_file_outline`**:
-Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, PHP
+# BAD
+async def run(self, input_data, config=None):
+    ...
+```
 
-## Using Existing Agents
+### Docstrings
 
-### CLI Usage
-Use always with uv `uv --directory agentic-framework run agentic-run info developer`, 
-from the root of the git repository.
+Use Google-style docstrings:
 
-```bash
-# List all available agents
-uv --directory agentic-framework run agentic-run list
+```python
+def process_data(data: list[str]) -> dict[str, int]:
+    """Process a list of strings and return counts.
 
-# View detailed information about an agent
-uv --directory agentic-framework run agentic-run info developer
+    Args:
+        data: A list of strings to process.
 
-# Run an agent
-uv --directory agentic-framework run agentic-run developer --input "Find all files with 'agent' in the name"
+    Returns:
+        A dictionary mapping each unique string to its count.
 
-# With timeout override
-uv --directory agentic-framework run agentic-run travel --input "BCN to LIS next week" --timeout 120
+    Raises:
+        ValueError: If data is empty.
+    """
 ```
 
-### Programmatic Usage
-
-```python
-from agentic_framework.registry import AgentRegistry
-from agentic_framework.mcp import MCPProvider
+### Error Handling in Tools
 
-# Get agent class
-agent_cls = AgentRegistry.get("developer")
+Tools MUST return error messages as strings, never raise exceptions:
 
-# Without MCP
-agent = agent_cls()
-result = await agent.run("Explain the project structure")
+```python
+# GOOD
+def invoke(self, input_str: str) -> str:
+    try:
+        result = do_something(input_str)
+        return result
+    except FileNotFoundError:
+        return f"Error: File '{input_str}' not found."
 
-# With MCP (if agent supports it)
-provider = MCPProvider(server_names=["webfetch"])
-async with provider.tool_session() as mcp_tools:
-    agent = agent_cls(initial_mcp_tools=mcp_tools)
-    result = await agent.run("Search for...")
+# BAD
+def invoke(self, input_str: str) -> str:
+    if not os.path.exists(input_str):
+        raise FileNotFoundError(f"File '{input_str}' not found")
 ```
 
-## Building New Agents
+### Async Patterns
 
-### Simple Agent (No Tools)
+Agent `run()` methods are async. Use `async def` and `await`:
 
 ```python
-from agentic_framework.interfaces.base import Agent
-from agentic_framework.registry import AgentRegistry
-
-@AgentRegistry.register("my-simple-agent", mcp_servers=None)
-class MySimpleAgent(Agent):
-    async def run(self, input_data, config=None):
-        return f"Response to: {input_data}"
-
-    def get_tools(self):
-        return []
+# GOOD
+async def run(self, input_data: str) -> str:
+    result = await some_async_operation()
+    return result
+
+# BAD
+async def run(self, input_data: str) -> str:
+    result = some_sync_operation()  # Blocks event loop
+    return result
 ```
 
-### LangGraph Agent with Local Tools
+### Agent Registration
+
+Always use the decorator pattern:
 
 ```python
-from langchain_core.tools import StructuredTool
-from agentic_framework.core.langgraph_agent import LangGraphMCPAgent
-from agentic_framework.registry import AgentRegistry
-
-@AgentRegistry.register("my-agent", mcp_servers=None)
+@AgentRegistry.register("agent-name", mcp_servers=["server1"])
 class MyAgent(LangGraphMCPAgent):
-    @property
-    def system_prompt(self) -> str:
-        return "You are a helpful assistant specialized in X."
-
-    def local_tools(self) -> Sequence[Any]:
-        # Add your tools here
-        return [
-            StructuredTool.from_function(
-                func=my_function,
-                name="my_tool",
-                description="Description of what the tool does",
-            )
-        ]
+    ...
 ```
 
-### LangGraph Agent with MCP Tools
+---
 
-```python
-@AgentRegistry.register("my-agent", mcp_servers=["web-fetch", "tavily"])
-class MyAgent(LangGraphMCPAgent):
-    @property
-    def system_prompt(self) -> str:
-        return "You have access to web tools."
+## TESTING REQUIREMENTS
 
-    def local_tools(self) -> Sequence[Any]:
-        return []  # No local tools, just MCP
-```
+### Test Location
 
-## Building New Tools
+Tests are in `/Users/jeancsil/code/agents/agentic-framework/tests/`
 
-### Simple Tool
+### Test Naming
+
+- Test files: `test_<module>.py`
+- Test functions: `test_<function>_<scenario>()`
 
 ```python
-from agentic_framework.interfaces.base import Tool
+# GOOD
+def test_run_with_valid_input_returns_response():
+    ...
 
-class MyTool(Tool):
-    @property
-    def name(self) -> str:
-        return "my_tool"
+def test_invoke_with_missing_file_returns_error():
+    ...
 
-    @property
-    def description(self) -> str:
-        return "Description of what the tool does."
+# BAD
+def test_run():
+    ...
 
-    def invoke(self, input_str: str) -> Any:
-        # Tool logic here
-        return f"Result: {input_str}"
+def testErrorHandling():
+    ...
 ```
 
-### Codebase Explorer Tool
+### Test Patterns
+
+Use `monkeypatch` for external dependencies:
 
 ```python
-from agentic_framework.tools.codebase_explorer import CodebaseExplorer, Tool
+def test_web_search_returns_results(monkeypatch):
+    def mock_search(query: str) -> str:
+        return "Mocked results"
+
+    monkeypatch.setattr("module.web_search", mock_search)
+    tool = WebSearchTool()
+    result = tool.invoke("test query")
+    assert "Mocked results" in result
+```
 
-class MyExplorerTool(CodebaseExplorer, Tool):
-    @property
-    def name(self) -> str:
-        return "my_explorer"
+### Coverage Requirement
 
-    @property
-    def description(self) -> str:
-        return "Description of the explorer tool."
+Minimum coverage: 60% (fail under configured in pyproject.toml)
+Current coverage: 80%
 
-    def invoke(self, input_str: str) -> Any:
-        # Use self.root_dir for project root
-        # Tool logic here
-        return result
+New code should include tests. Aim to maintain or improve coverage.
+
+---
+
+## PROJECT STRUCTURE
+
+```
+agentic-framework/
+├── src/agentic_framework/
+│   ├── core/               # Agent implementations
+│   │   ├── langgraph_agent.py   # Base class - modify carefully
+│   │   ├── simple_agent.py
+│   │   ├── chef_agent.py
+│   │   ├── travel_agent.py
+│   │   ├── news_agent.py
+│   │   ├── developer_agent.py
+│   │   └── travel_coordinator_agent.py
+│   ├── interfaces/         # Abstract base classes
+│   │   └── base.py              # Agent and Tool ABCs
+│   ├── mcp/                # MCP integration
+│   │   ├── config.py            # Server configurations
+│   │   └── provider.py          # Connection management
+│   ├── tools/              # Tool implementations
+│   │   ├── codebase_explorer.py # Code navigation tools
+│   │   ├── code_searcher.py     # ripgrep wrapper
+│   │   ├── syntax_validator.py  # Tree-sitter validation
+│   │   ├── web_search.py
+│   │   └── example.py
+│   ├── constants.py        # BASE_DIR, LOGS_DIR, timeouts
+│   ├── registry.py         # Agent discovery and registration
+│   └── cli.py              # Typer CLI interface
+├── tests/                  # Test suite
+├── pyproject.toml          # Project config, dependencies
+└── uv.lock                 # Lockfile (DO NOT EDIT DIRECTLY)
 ```
 
-### Export from tools/__init__.py
+---
 
-Add your tool to `tools/__init__.py`:
+## GIT HOOKS
 
-```python
-from .my_tool import MyTool
+This project has a pre-push hook that runs `make check`.
+
+If the hook fails:
+1. Run `make -C .. check` to see errors
+2. Fix all errors
+3. Try pushing again
 
-__all__ = [
-    # existing...
-    "MyTool",
-]
+To bypass the hook (NOT RECOMMENDED):
+```bash
+git push --no-verify
 ```
 
-## Patterns and Conventions
+---
 
-### Agent Registration
+## COMMANDS REFERENCE
 
-- Always use `@AgentRegistry.register(name, mcp_servers)` decorator
-- `mcp_servers=None` means no MCP access
-- `mcp_servers=[]` or `mcp_servers=["server1"]` for MCP access
+```bash
+# From agentic-framework directory:
+make -C .. check      # Run mypy + ruff (linting)
+make -C .. test       # Run pytest with coverage
+make -C .. format     # Auto-format with ruff
+make -C .. install    # Install dependencies
+make -C .. clean      # Remove caches and artifacts
+
+# Run the CLI:
+uv run agentic-run list
+uv run agentic-run info developer
+uv run agentic-run developer -i "input"
+```
 
-### System Prompts
+---
 
-- Define as a property named `system_prompt`
-- Keep prompts concise and focused
-- Include instructions on when/how to use tools
+## COMMON TASKS
 
-### Tool Initialization
+### Adding a New Agent
 
-- Tools in `local_tools()` should be initialized once (not per-call)
-- Use `StructuredTool.from_function()` to wrap functions for LangChain
-- Tool names should be snake_case
+1. Create file in `src/agentic_framework/core/my_agent.py`
+2. Subclass `LangGraphMCPAgent`
+3. Add `@AgentRegistry.register()` decorator
+4. Define `system_prompt` property
+5. Override `local_tools()` if needed
+6. Add tests in `tests/test_my_agent.py`
+7. Run `make -C .. check && make -C .. test`
 
-### Codebase Tools Usage
+### Adding a New Tool
 
-- Use `find_files` when you need to locate files by name/pattern
-- Use `discover_structure` for project layout overview
-- Use `get_file_outline` to skim file contents before reading
-  - Supports: Python (`.py`), JavaScript (`.js`), TypeScript (`.ts`), Rust (`.rs`), Go (`.go`), Java (`.java`), C (`.c`, `.h`), C++ (`.cpp`, `.hpp`), PHP (`.php`)
-  - Returns: `[{"line": 15, "signature": "class MyAgent:"}, ...]`
-- Use `read_file_fragment` to read specific lines (format: `path:start:end`)
-- Use `code_search` for fast global pattern matching
+1. Create file in `src/agentic_framework/tools/my_tool.py`
+2. Subclass `Tool` from `interfaces.base`
+3. Implement `name`, `description`, `invoke()`
+4. Export from `tools/__init__.py`
+5. Add tests in `tests/test_my_tool.py`
+6. Run `make -C .. check && make -C .. test`
 
-### Async/Await
+### Adding a New MCP Server
 
-- All agent `run()` methods are async
-- Use `await` when calling agent methods
-- MCP operations use async context managers
+1. Add configuration in `mcp/config.py`
+2. Update `DEFAULT_MCP_SERVERS` dict
+3. Document API key requirements if any
+4. Test connection manually
+5. Update relevant agent registrations
 
-### Thread IDs
+### Fixing a Bug
 
-- LangGraph uses thread IDs for checkpointing
-- Provide unique thread_ids for concurrent agent runs
-- Format: `"1"`, `"agent:1"`, etc.
+1. Write a failing test that reproduces the bug
+2. Run `make -C .. test` to confirm failure
+3. Fix the code
+4. Run `make -C .. check && make -C .. test`
+5. Confirm test now passes
 
-### Error Handling
+---
 
-- Tools should return error messages as strings, not raise exceptions
-- CLI provides error reporting with `--verbose` flag
-- MCP connection errors are handled via `MCPConnectionError`
+## DEPENDENCIES
 
-## Testing
+### Adding Dependencies
 
-```python
-# Test agent discovery
-def test_my_agent_registered():
-    AgentRegistry.discover_agents()
-    assert "my-agent" in AgentRegistry.list_agents()
-
-# Test agent behavior (use monkeypatch for external dependencies)
-def test_my_agent_run(monkeypatch):
-    # Mock external dependencies
-    monkeypatch.setattr("module.Class", mock_class)
-    agent = MyAgent()
-    result = await agent.run("test")
-    assert "expected" in result
+```bash
+uv add package-name
+```
+
+### Adding Dev Dependencies
+
+```bash
+uv add --dev package-name
 ```
-## Before committing
 
-Before commiting, run `make check`, `make test` and if needed, `make format`. Fix them before committing.
+### Updating Dependencies
+
+```bash
+uv lock --upgrade-package package-name
+```
 
-make check runs:
-  - mypy - type checking
-  - ruff check - linting (no fixes)
-  - ruff format --check - formatting check (no fixes)
+---
 
+## FINAL CHECKLIST
 
-## Constants
+Before saying a task is complete:
 
-- `BASE_DIR` - Project root directory
-- `LOGS_DIR` - Logs directory (logs/)
-- Default timeout: 600 seconds
-- Connection timeout: 15 seconds
+- [ ] Code follows project style
+- [ ] Type hints are complete
+- [ ] Docstrings are updated
+- [ ] `make check` passes with no errors
+- [ ] `make test` passes with no failures
+- [ ] Coverage maintained or improved
+- [ ] No new warnings introduced
 
-## Notes for External LLMs
+---
 
-When working with this codebase:
+## WHEN IN DOUBT
 
-1. **Agent Discovery**: All agents are auto-registered in `AgentRegistry`
-2. **MCP Access**: Check `AgentRegistry.get_mcp_servers(name)` before using MCP
-3. **Tool Conventions**: Tools return strings for errors, not exceptions
-4. **Codebase Navigation**: The developer agent has specialized tools for code exploration
-5. **Model Selection**: The default model name may be a placeholder - check environment variables
-6. **File Patterns**: Ignore patterns include `.git`, `__pycache__`, `node_modules`, `.venv`, etc.
+1. Read existing code for patterns
+2. Run `make -C .. check` early and often
+3. Ask the user for clarification
+4. Don't guess - verify
diff --git a/README.md b/README.md
index c011229..e57941d 100644
--- a/README.md
+++ b/README.md
@@ -1,194 +1,254 @@
 # Agentic Framework
 
-An educational LangChain + MCP framework for learning and building agentic systems in Python 3.12+.
+A LangChain + MCP framework for building agentic systems in Python 3.12+.
 
 ![Build Status](https://github.com/jeancsil/agentic-framework/actions/workflows/ci.yml/badge.svg)
 ![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)
 ![GitHub License](https://img.shields.io/github/license/jeancsil/agentic-framework)
 
-## Goal of This Repository
+## What is this?
 
-This project is intentionally small so you can learn the core building blocks of agentic coding:
+This framework helps you build AI agents that can:
+- Use **local tools** (file operations, code search, etc.)
+- Connect to **MCP servers** (web search, flight booking, etc.)
+- Combine both in a single runtime
 
-- agent registry and dynamic CLI commands
-- reusable LangGraph agent pattern
-- optional MCP server access with explicit per-agent permissions
-- local tools + MCP tools combined in one runtime
-- testable architecture (no network required in unit tests)
+**Key features:**
+- Decorator-based agent registration with automatic CLI generation
+- Reusable LangGraph agent pattern with checkpointing
+- Per-agent MCP server permissions
+- Multi-language code navigation tools
+- Safe file editing with automatic syntax validation
 
-## Prerequisites
-
-- Python >= 3.12, < 3.14
-- [uv](https://docs.astral.sh/uv/) (recommended)
-
-## Quickstart
+## Quick Start
 
 ```bash
+# Install dependencies
 make install
+
+# Run tests
 make test
-```
 
-Run a specialized agent for codebase exploration:
+# List available agents
+uv --directory agentic-framework run agentic-run list
 
-```bash
-uv --project agentic-framework run agentic-run developer -i "List the project structure and explain what the main components do."
+# Run the developer agent
+uv --directory agentic-framework run agentic-run developer -i "Explain the project structure"
 ```
 
-List all available agents:
+## Available Agents
 
-```bash
-uv --project agentic-framework run agentic-run list
-```
-
-## Docker Support 🐳
+| Agent | Purpose | MCP Access | Tools |
+|-------|---------|------------|-------|
+| `developer` | Codebase exploration & editing | webfetch | find_files, discover_structure, get_file_outline, read_file_fragment, code_search, edit_file |
+| `travel-coordinator` | Multi-agent trip planning | kiwi-com-flight-search, web-fetch | Orchestrates 3 specialist agents |
+| `chef` | Recipe suggestions | tavily | web_search |
+| `news` | AI news aggregation | web-fetch | - |
+| `travel` | Flight search | kiwi-com-flight-search | - |
+| `simple` | Basic conversation | none | - |
 
-Run the framework in Docker with mounted volumes for live code updates:
+## CLI Reference
 
 ```bash
-# Build the Docker image
-make docker-build
+# List all agents
+uv --directory agentic-framework run agentic-run list
 
-# Run agents using the shell wrapper
-bin/agent.sh developer -i "Search for all Tool definitions in the project"
-bin/agent.sh chef -i "I have bread, tuna, lettuce and mayo"
-bin/agent.sh list
+# Get agent info
+uv --directory agentic-framework run agentic-run info <agent>
 
-# Access logs (same location as local)
-tail -f agentic-framework/logs/agent.log
+# Run an agent
+uv --directory agentic-framework run agentic-run <agent> -i "your input"
+
+# With timeout (seconds)
+uv --directory agentic-framework run agentic-run <agent> -i "input" -t 120
+
+# Verbose logging
+uv --directory agentic-framework run agentic-run <agent> -i "input" -v
 ```
 
-**Key Features:**
-- ✅ No rebuild needed when changing Python code (mounted volumes)
-- ✅ Environment variables safely loaded from `.env`
-- ✅ Logs accessible from host machine
-- ✅ Uses `uv` just like local development
-- ✅ Simple shell wrapper mimics local CLI experience
+## Developer Agent
 
+The `developer` agent is a Principal Software Engineer assistant for codebase work.
 
-## Featured Agents
+**Available tools:**
 
-| Agent | What it does | MCP Access |
-|---|---|---|
-| `developer` | 🚀 **Principal Engineer** assistant for codebase exploration and search | `web-fetch` |
-| `travel-coordinator` | ✈️ **Multi-agent Orchestrator** (Flights + City Intel + Reviewer) | `kiwi-com-flight-search`, `web-fetch` |
-| `chef` | 🍳 Recipe suggestions from ingredients | `tavily` |
-| `news` | 📰 AI news assistant (TechCrunch specialist) | `web-fetch` |
-| `travel` | 🎫 Flight planning assistant | `kiwi-com-flight-search` |
-| `simple` | 💬 Basic conversational chain | none |
+| Tool | Description | Input Format |
+|------|-------------|--------------|
+| `find_files` | Search files by name | `pattern` |
+| `discover_structure` | Directory tree | `[max_depth]` |
+| `get_file_outline` | Extract signatures | `file_path` |
+| `read_file_fragment` | Read line range | `path:start:end` |
+| `code_search` | Pattern search | `pattern` |
+| `edit_file` | Edit files | See below |
 
-## Showcase: Developer Agent
+**Supported languages for `get_file_outline`:** Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, PHP
 
-The `developer` agent is designed to assist with codebase maintenance and understanding. It comes equipped with local tools for:
-- **File Discovery**: Finding files by name across the project.
-- **Structure Exploration**: Visualizing the project directory tree.
-- **Code Outlining**: Extracting functions, classes, and signatures from code files.
-  - Supports: Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, PHP
-  - Returns line numbers for precise navigation.
-- **Pattern Search**: Global search using `ripgrep` for fast pattern matching.
+**File editing workflow:**
+```bash
+# Search/replace (recommended - no line numbers needed)
+{"op": "search_replace", "path": "file.py", "old": "exact text", "new": "new text"}
 
-Implementation: `src/agentic_framework/core/developer_agent.py`
+# Line-based operations
+replace:path:start:end:content
+insert:path:after_line:content
+delete:path:start:end
+```
 
-## Showcase: Travel Coordinator (Multi-Agent System)
+## Multi-Agent Systems
 
-Run:
+The `travel-coordinator` demonstrates multi-agent orchestration:
 
 ```bash
-uv --project agentic-framework run agentic-run travel-coordinator -i "Plan a 5-day trip from Lisbon to Berlin in May."
+uv --directory agentic-framework run agentic-run travel-coordinator -i "Plan a 5-day trip from Lisbon to Berlin in May"
 ```
 
-This example demonstrates complex orchestration using two remote MCP servers: `kiwi-com-flight-search` and `web-fetch`.
+**Workflow:**
+1. `FlightSpecialistAgent` → gathers flight options
+2. `CityIntelAgent` → adds destination intelligence
+3. `TravelReviewerAgent` → final itinerary
 
-**How it works:**
+## Docker Support
 
-1. **FlightSpecialistAgent** uses MCP tools to gather flight options.
-2. **CityIntelAgent** receives the flight report and adds destination intelligence.
-3. **TravelReviewerAgent** receives both reports and returns the final itinerary brief.
-
-The coordinator implementation lives in: `src/agentic_framework/core/travel_coordinator_agent.py`
-
-## Architecture (Beginner-Friendly)
+```bash
+# Build image
+make docker-build
 
-Core flow:
+# Run agents
+bin/agent.sh developer -i "Search for all Tool definitions"
+bin/agent.sh chef -i "I have bread, tuna, lettuce and mayo"
 
-1. Register an agent in `src/agentic_framework/registry.py`.
-2. CLI discovers registered agents and creates commands automatically.
-3. If an agent has MCP permissions, CLI opens those MCP tool sessions.
-4. Agent runs with local tools + MCP tools and returns final response.
+# View logs
+tail -f agentic-framework/logs/agent.log
+```
 
-Key files:
+## Environment Variables
 
-- `agentic-framework/src/agentic_framework/core/langgraph_agent.py`: reusable base class for most agents
-- `agentic-framework/src/agentic_framework/mcp/config.py`: all available MCP servers
-- `agentic-framework/src/agentic_framework/registry.py`: agent registration + allowed MCP servers
-- `agentic-framework/src/agentic_framework/cli.py`: command runner and error handling
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_MODEL_NAME` | No | LLM model (default: gpt-4) |
+| `OPENAI_API_KEY` | Yes | OpenAI API key |
+| `TAVILY_API_KEY` | For chef agent | Tavily search API |
+| `TINYFISH_API_KEY` | Optional | TinyFish MCP access |
 
-## Create a New Agent
+## Building New Agents
 
-Minimal pattern:
+### Minimal Agent
 
 ```python
 from agentic_framework.core.langgraph_agent import LangGraphMCPAgent
 from agentic_framework.registry import AgentRegistry
 
-
-@AgentRegistry.register("my-agent", mcp_servers=["tavily", "web-fetch"])
+@AgentRegistry.register("my-agent", mcp_servers=["tavily"])
 class MyAgent(LangGraphMCPAgent):
     @property
     def system_prompt(self) -> str:
         return "You are my custom agent."
 ```
 
-Optional local tools:
+### Agent with Local Tools
 
 ```python
-def local_tools(self):
-    return [my_langchain_tool]
+from langchain_core.tools import StructuredTool
+from agentic_framework.core.langgraph_agent import LangGraphMCPAgent
+from agentic_framework.registry import AgentRegistry
+
+@AgentRegistry.register("my-agent", mcp_servers=None)
+class MyAgent(LangGraphMCPAgent):
+    @property
+    def system_prompt(self) -> str:
+        return "You are a helpful assistant."
+
+    def local_tools(self) -> list:
+        return [
+            StructuredTool.from_function(
+                func=my_function,
+                name="my_tool",
+                description="What this tool does",
+            )
+        ]
 ```
 
-## Build Complex Coordinators (No Base Changes)
+### Multi-Agent Coordinator
 
-Use this repeatable pattern for multi-agent systems:
+```python
+from agentic_framework.interfaces.base import Agent
+from agentic_framework.registry import AgentRegistry
 
-1. Create small specialist classes that subclass `LangGraphMCPAgent`.
-2. Create one coordinator class that implements `Agent` directly.
-3. Register only the coordinator in `AgentRegistry` with allowed MCP servers.
-4. In coordinator `run()`, call specialists in stages and pass each stage output to the next.
-5. Keep coordinator logic explicit in Python (handoff format, retries, branch rules).
-6. Add unit tests that assert call order and stage-to-stage context propagation.
+@AgentRegistry.register("coordinator", mcp_servers=["server1", "server2"])
+class CoordinatorAgent(Agent):
+    async def run(self, input_data, config=None):
+        # Stage 1: First specialist
+        specialist1 = Specialist1Agent()
+        result1 = await specialist1.run(input_data)
 
-This is the same pattern used by `travel-coordinator` and scales to routers, supervisors, and team-of-agents designs.
+        # Stage 2: Second specialist
+        specialist2 = Specialist2Agent()
+        result2 = await specialist2.run(result1)
 
-After adding the file under `src/agentic_framework/core/`, the CLI command appears automatically:
+        return result2
 
-```bash
-uv --project agentic-framework run agentic-run my-agent -i "hello"
+    def get_tools(self):
+        return []
 ```
 
+After creating your agent in `src/agentic_framework/core/`, it automatically becomes available:
 
-## Scaling to Coordinators and Multi-Agent Systems
+```bash
+uv --directory agentic-framework run agentic-run my-agent -i "hello"
+```
 
-Recommended approach:
+## Architecture
 
-1. Build each specialist as a small `LangGraphMCPAgent` subclass.
-2. Keep MCP permissions strict per specialist in the registry.
-3. Add a coordinator agent that routes user intent to specialists.
-4. Keep shared policies/prompts in one place; keep specialist prompts focused.
-5. Add contract tests for routing and handoff behavior.
+```
+User Input
+    │
+    ▼
+┌─────────────────┐
+│   CLI (Typer)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ AgentRegistry   │────▶│ Agent Discovery │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│  MCPProvider    │────▶│  MCP Servers    │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│ LangGraph Agent │
+│  (base class)   │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+┌───────┐ ┌───────┐
+│ Local │ │  MCP  │
+│ Tools │ │ Tools │
+└───────┘ └───────┘
+```
+
+**Key files:**
+- `src/agentic_framework/core/langgraph_agent.py` - Reusable agent base
+- `src/agentic_framework/registry.py` - Agent registration
+- `src/agentic_framework/mcp/provider.py` - MCP connection management
+- `src/agentic_framework/tools/` - Tool implementations
 
-This keeps the code easy for medium-level engineers to extend while remaining production-friendly.
+## Development
 
-## Development Commands
+```bash
+make install    # Install dependencies
+make test       # Run tests (coverage threshold: 60%)
+make lint       # Run mypy + ruff
+make format     # Auto-format code
+make check      # Run all checks (lint + format check)
+```
 
-### Local Development
-- `make install`: install dependencies
-- `make test`: run tests (coverage threshold configured to fail under 60%)
-- `make lint`: run mypy + ruff
-- `make run`: run a sample agent
-- `make clean`: remove caches and temporary artifacts
+**Before committing:** Run `make check && make test`
 
-### Docker
-- `make docker-build`: build Docker image
-- `make docker-clean`: remove containers and images
-- `bin/agent.sh <agent> [args]`: run agents in Docker (see [DOCKER.md](DOCKER.md))
+## License
 
-See `make help` for all available commands.
+MIT License - see [LICENSE](LICENSE) for details.

From 59ee9707c843bf633015154896aff283006c382f Mon Sep 17 00:00:00 2001
From: Jean Silva <jeancsil@gmail.com>
Date: Mon, 23 Feb 2026 11:35:48 +0100
Subject: [PATCH 2/3] docs: clarify uv usage and prefer Docker for local runs

Update AGENTS.md to enforce `uv` as the sole package manager, expand
instructions for using `uv`, and add a clear "UV IS MANDATORY" section
with commands and forbidden examples. Prefer Docker for running and
testing the framework: add a "DOCKER (PREFERRED)" section describing
benefits and common commands, and emphasize avoiding local dependency
installs. Rework Working Directory guidance to explain the project
layout (agentic-framework/ is a subdirectory) and show running make from
the parent directory or using `cd .. && make check`.

Other tidy-ups:
- Replace absolute paths with relative project paths for tests and
  working-directory examples.
- Add NEVER rules forbidding pip, pipenv, poetry, and local installs
  when Docker is available.
- Remove bypass-push hook instructions to encourage fixing issues.

These changes improve onboarding clarity, enforce consistent dependency
management, and reduce local environment drift by promoting Docker.
---
 AGENTS.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 89 insertions(+), 12 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d962a72..e47dc02 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,8 +22,9 @@ You are an LLM agent tasked with improving, fixing, or extending the **agentic-f
 6. **ALWAYS** follow existing code patterns in the codebase.
 7. **ALWAYS** add tests for new functionality.
 8. **ALWAYS** update docstrings if you change function behavior.
-9. **ALWAYS** use `uv` for package management (not pip, not poetry).
-10. **ALWAYS** run commands from the correct directory (see Working Directory).
+9. **ALWAYS** use `uv` for package management - **NO EXCEPTIONS** (not pip, not poetry, not pipenv).
+10. **ALWAYS** prefer Docker for running the framework locally (see Docker section).
+11. **ALWAYS** run commands from the correct directory (see Working Directory).
 
 ### NEVER Rules
 
@@ -37,6 +38,8 @@ You are an LLM agent tasked with improving, fixing, or extending the **agentic-f
 8. **NEVER** raise exceptions from tools - return error strings instead.
 9. **NEVER** edit generated files (uv.lock, etc.) directly.
 10. **NEVER** ignore deprecation warnings - fix them.
+11. **NEVER** use pip, pipenv, poetry, or any package manager other than `uv`.
+12. **NEVER** install dependencies locally when Docker can be used instead.
 
 ### BEFORE Rules
 
@@ -55,16 +58,16 @@ You are an LLM agent tasked with improving, fixing, or extending the **agentic-f
 
 ## WORKING DIRECTORY
 
-You are in `/Users/jeancsil/code/agents/agentic-framework/`. The project root is one level up.
+The framework code lives in `agentic-framework/` subdirectory. The project root (with Makefile) is one level up.
 
 ```bash
-# Run make commands from parent directory
+# If you're in agentic-framework/ directory, run make commands from parent:
 make -C .. check
 make -C .. test
 make -C .. format
 
-# Or use full path
-make -C /Users/jeancsil/code/agents check
+# Or navigate to project root first:
+cd .. && make check
 ```
 
 ---
@@ -101,6 +104,85 @@ If checks or tests fail:
 
 ---
 
+## UV IS MANDATORY
+
+**This project uses `uv` exclusively.** No other package manager is allowed.
+
+### Why uv?
+- Fast dependency resolution
+- Consistent lockfile (uv.lock)
+- Built-in virtual environment management
+- Replaces pip, pip-tools, poetry, pipenv
+
+### Required Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Add a dependency
+uv add package-name
+
+# Add a dev dependency
+uv add --dev package-name
+
+# Run a command in the virtual environment
+uv run <command>
+
+# Update lockfile
+uv lock --upgrade-package package-name
+```
+
+### Forbidden Commands
+
+```bash
+# NEVER use these:
+pip install package-name      # WRONG
+pipenv install package-name   # WRONG
+poetry add package-name       # WRONG
+pip install -r requirements.txt  # WRONG
+```
+
+If you need a dependency, use `uv add`. No exceptions.
+
+---
+
+## DOCKER (PREFERRED)
+
+**Docker is the preferred way to run and test the framework.** Avoid installing dependencies locally.
+
+### Why Docker?
+- Consistent environment across all machines
+- No pollution of local Python environment
+- Easy cleanup and isolation
+- Matches production deployment
+
+### Docker Commands
+
+```bash
+# Build the Docker image
+make docker-build
+
+# Run agents in Docker
+bin/agent.sh developer -i "Explain the project structure"
+bin/agent.sh chef -i "I have eggs and cheese"
+bin/agent.sh list
+
+# Run tests in Docker
+docker compose run --rm app make test
+
+# View logs (same location as local)
+tail -f agentic-framework/logs/agent.log
+```
+
+### Docker Benefits
+- No rebuild needed when changing Python code (mounted volumes)
+- Environment variables loaded from `.env`
+- Logs accessible from host machine
+- Uses `uv` just like local development
+
+---
+
 ## CODE STANDARDS
 
 ### Type Hints
@@ -187,7 +269,7 @@ class MyAgent(LangGraphMCPAgent):
 
 ### Test Location
 
-Tests are in `/Users/jeancsil/code/agents/agentic-framework/tests/`
+Tests are in `agentic-framework/tests/`
 
 ### Test Naming
 
@@ -277,11 +359,6 @@ If the hook fails:
 2. Fix all errors
 3. Try pushing again
 
-To bypass the hook (NOT RECOMMENDED):
-```bash
-git push --no-verify
-```
-
 ---
 
 ## COMMANDS REFERENCE

From 8e5314fa5cacc12954fce40e5fd11f8976461ebd Mon Sep 17 00:00:00 2001
From: Jean Silva <jeancsil@gmail.com>
Date: Mon, 23 Feb 2026 12:30:22 +0100
Subject: [PATCH 3/3] docs: update README and agent docs; enforce README sync

- Add requirement in AGENTS.md to update README.md when public API,
  agents, tools, MCP servers, or agent capabilities change. Clarify
  do/don't checklist to prevent stale docs.
- Expand README.md with Docker quick start and rationale, example
  commands for building, running, and viewing logs, and note Docker as
  recommended workflow.
- Improve local installation instructions and clearly separate Python
  vs system dependencies.
- Revise agent usage examples for both Docker and local setups and
  simplify developer-agent invocation.
- Add Available Tools and Available MCP Servers tables with tool/
  server descriptions and input formats; detail recommended file-edit
  operations (search_replace and line-based formats).
- Reorganize sections (quick start, tools, MCP servers, CLI reference,
  developer agent) for clearer navigation and synchronized guidance.

Reason: ensure documentation is complete, consistent, and aligned with
framework changes so contributors and users can run and extend agents
reliably and avoid outdated README contents.
---
 AGENTS.md |  17 +++++++
 README.md | 147 ++++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 122 insertions(+), 42 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e47dc02..358a2fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -451,6 +451,23 @@ Before saying a task is complete:
 - [ ] `make test` passes with no failures
 - [ ] Coverage maintained or improved
 - [ ] No new warnings introduced
+- [ ] README.md is updated if public API or agents/tools changed
+
+## KEEPING README.md IN SYNC
+
+**README.md must stay in sync with framework changes.**
+
+Update README.md when you:
+- Add a new agent (add to Available Agents table)
+- Add a new tool (add to Available Tools table)
+- Add a new MCP server (add to Available MCP Servers table)
+- Change public API (update Architecture section if needed)
+- Modify agent capabilities (update agent descriptions)
+
+**Do NOT:**
+- Leave outdated information in README.md
+- Document features that no longer exist
+- Skip updating relevant sections
 
 ---
 
diff --git a/README.md b/README.md
index e57941d..2a7618d 100644
--- a/README.md
+++ b/README.md
@@ -20,22 +20,98 @@ This framework helps you build AI agents that can:
 - Multi-language code navigation tools
 - Safe file editing with automatic syntax validation
 
-## Quick Start
+---
+
+## Quick Start (Docker - Recommended)
+
+**Docker is the recommended way to run this framework.** It comes pre-configured with all required tools and dependencies.
+
+```bash
+# Build the Docker image
+make docker-build
+
+# Run agents (no rebuild needed for code changes)
+bin/agent.sh developer -i "Explain project structure"
+bin/agent.sh chef -i "I have eggs and cheese"
+bin/agent.sh list
+
+# View logs (same location as local)
+tail -f agentic-framework/logs/agent.log
+```
+
+**Why Docker?**
+- All dependencies pre-installed: `ripgrep`, `fd`, `fzf`, `tree-sitter`
+- No environment setup needed - just build and run
+- Code changes reflected immediately (mounted volumes)
+- Consistent environment across all machines
+
+---
+
+## Local Installation
+
+If you need to run locally, you must install these dependencies:
+
+**System packages:**
+- `ripgrep` - Ultra-fast text searching
+- `fd` - User-friendly alternative to `find`
+- `fzf` - General-purpose command-line fuzzy finder
+
+**Python packages (managed by `uv`):**
+- `tree-sitter` - Parser generator
+- `tree-sitter-languages` - Grammar packages
 
 ```bash
-# Install dependencies
+# Install Python dependencies
 make install
 
 # Run tests
 make test
 
-# List available agents
-uv --directory agentic-framework run agentic-run list
+# Run agents
+uv --directory agentic-framework run agentic-run developer -i "Explain project structure"
+```
+
+---
+
+## Available Tools
+
+| Tool | Purpose | Input Format |
+|-------|---------|--------------|
+| `find_files` | Fast file search via `fd` | `pattern` |
+| `discover_structure` | Directory tree exploration | `[max_depth]` (default: 3) |
+| `get_file_outline` | Extract class/function signatures | `file_path` |
+| `read_file_fragment` | Read specific line ranges | `path:start:end` (1-indexed) |
+| `code_search` | Pattern search via `ripgrep` | `regex_pattern` |
+| `edit_file` | Safe file editing with syntax validation | See below |
+| `web_search` | Web search via Tavily | `query` |
+
+### File Editing
 
-# Run the developer agent
-uv --directory agentic-framework run agentic-run developer -i "Explain the project structure"
+**RECOMMENDED: search_replace (no line numbers needed)**
+```json
+{"op": "search_replace", "path": "file.py", "old": "exact text", "new": "replacement text"}
 ```
 
+**Line-based operations:**
+```
+replace:path:start:end:content
+insert:path:after_line:content
+delete:path:start:end
+```
+
+---
+
+## Available MCP Servers
+
+| Server | Purpose | API Key Required |
+|--------|---------|------------------|
+| `kiwi-com-flight-search` | Flight search | No |
+| `webfetch` | Web content fetching | No |
+| `tavily` | Web search | Yes (`TAVILY_API_KEY`) |
+| `tinyfish` | AI assistant | Yes (`TINYFISH_API_KEY`) |
+
+---
+
 ## Available Agents
 
 | Agent | Purpose | MCP Access | Tools |
@@ -47,6 +123,8 @@ uv --directory agentic-framework run agentic-run developer -i "Explain the proje
 | `travel` | Flight search | kiwi-com-flight-search | - |
 | `simple` | Basic conversation | none | - |
 
+---
+
 ## CLI Reference
 
 ```bash
@@ -66,40 +144,28 @@ uv --directory agentic-framework run agentic-run <agent> -i "input" -t 120
 uv --directory agentic-framework run agentic-run <agent> -i "input" -v
 ```
 
-## Developer Agent
+**In Docker:**
+```bash
+bin/agent.sh <agent> -i "input"
+bin/agent.sh list
+```
 
-The `developer` agent is a Principal Software Engineer assistant for codebase work.
+---
 
-**Available tools:**
+## Developer Agent
 
-| Tool | Description | Input Format |
-|------|-------------|--------------|
-| `find_files` | Search files by name | `pattern` |
-| `discover_structure` | Directory tree | `[max_depth]` |
-| `get_file_outline` | Extract signatures | `file_path` |
-| `read_file_fragment` | Read line range | `path:start:end` |
-| `code_search` | Pattern search | `pattern` |
-| `edit_file` | Edit files | See below |
+The `developer` agent is a Principal Software Engineer assistant for codebase work.
 
 **Supported languages for `get_file_outline`:** Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, PHP
 
-**File editing workflow:**
-```bash
-# Search/replace (recommended - no line numbers needed)
-{"op": "search_replace", "path": "file.py", "old": "exact text", "new": "new text"}
-
-# Line-based operations
-replace:path:start:end:content
-insert:path:after_line:content
-delete:path:start:end
-```
+---
 
 ## Multi-Agent Systems
 
 The `travel-coordinator` demonstrates multi-agent orchestration:
 
 ```bash
-uv --directory agentic-framework run agentic-run travel-coordinator -i "Plan a 5-day trip from Lisbon to Berlin in May"
+bin/agent.sh travel-coordinator -i "Plan a 5-day trip from Lisbon to Berlin in May"
 ```
 
 **Workflow:**
@@ -107,19 +173,7 @@ uv --directory agentic-framework run agentic-run travel-coordinator -i "Plan a 5
 2. `CityIntelAgent` → adds destination intelligence
 3. `TravelReviewerAgent` → final itinerary
 
-## Docker Support
-
-```bash
-# Build image
-make docker-build
-
-# Run agents
-bin/agent.sh developer -i "Search for all Tool definitions"
-bin/agent.sh chef -i "I have bread, tuna, lettuce and mayo"
-
-# View logs
-tail -f agentic-framework/logs/agent.log
-```
+---
 
 ## Environment Variables
 
@@ -130,6 +184,8 @@ tail -f agentic-framework/logs/agent.log
 | `TAVILY_API_KEY` | For chef agent | Tavily search API |
 | `TINYFISH_API_KEY` | Optional | TinyFish MCP access |
 
+---
+
 ## Building New Agents
 
 ### Minimal Agent
@@ -197,6 +253,8 @@ After creating your agent in `src/agentic_framework/core/`, it automatically bec
 uv --directory agentic-framework run agentic-run my-agent -i "hello"
 ```
 
+---
+
 ## Architecture
 
 ```
@@ -237,18 +295,23 @@ User Input
 - `src/agentic_framework/mcp/provider.py` - MCP connection management
 - `src/agentic_framework/tools/` - Tool implementations
 
+---
+
 ## Development
 
+For contributing to the framework itself, see [AGENTS.md](AGENTS.md).
+
 ```bash
 make install    # Install dependencies
 make test       # Run tests (coverage threshold: 60%)
-make lint       # Run mypy + ruff
 make format     # Auto-format code
 make check      # Run all checks (lint + format check)
 ```
 
 **Before committing:** Run `make check && make test`
 
+---
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.