+
+[](https://www.paracles.com)
+
+### Multi-Agent Framework for AI-Native Applications
+
+**Write Once, Deploy Everywhere**
+
+
+
+[Quick Start](#quick-start) |
+[Documentation](#documentation) |
+[Architecture](#architecture) |
+[Innovative Features](#more-features)
+
+
-**User-driven multi-agent framework for AI-native applications**
+---
-[](LICENSE)
-[](https://www.python.org/downloads/)
-[](https://github.com/IbIFACE-Tech/paracle-lite/actions)
+## Overview
----
+Paracle is an enterprise-grade framework for building production-ready multi-agent AI applications. Designed for scalability, security, and interoperability, Paracle enables organizations to develop sophisticated AI systems with confidence.
+
+### Core Capabilities
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ | + +#### Agent Inheritance + +Implement sophisticated agent hierarchies using object-oriented principles. Inherit configurations, behaviors, and capabilities across agent families for maintainable, scalable systems. + +#### Multi-Provider Architecture + +Support for 14+ LLM providers ensures vendor flexibility: + +- **Commercial**: OpenAI, Anthropic, Google AI, xAI, DeepSeek, Groq, Mistral AI, Cohere, Together AI, Perplexity, OpenRouter, Fireworks AI +- **Self-Hosted**: Ollama, LM Studio, vLLM, llama.cpp, LocalAI, Jan + +#### Framework Agnostic + +Seamless integration with leading AI frameworks: Microsoft Semantic Kernel (MSAF), LangChain, LlamaIndex. Choose the right tool for your use case. + +#### Portable Skills System + +Define agent capabilities once, deploy across platforms: GitHub Copilot, Cursor, Claude Code, OpenAI Codex, and custom IDEs. + + | ++ +#### API-First Architecture + +Production-grade RESTful API built with FastAPI. Comprehensive OpenAPI documentation, authentication, and rate limiting included. + +#### Model Context Protocol (MCP) + +Native support for the emerging MCP standard, enabling standardized tool discovery and interoperability across AI platforms. -## 🎯 What is Paracle? +#### Agent-to-Agent Protocol (A2A) -Paracle is a powerful framework for building **multi-agent AI applications** with unique features: +Federated agent communication protocol supporting distributed multi-agent systems and cross-organization collaboration. -- **🧬 Agent Inheritance**: Reuse and specialize agents like classes -- **🔌 Multi-Provider**: 14+ providers - Commercial (OpenAI, Anthropic, Google, xAI, DeepSeek, Groq, Mistral, Cohere, Together, Perplexity, OpenRouter, Fireworks) + Self-hosted (Ollama, LM Studio, vLLM, llama.cpp, LocalAI, Jan) -- **🎨 Multi-Framework**: MSAF, LangChain, LlamaIndex support -- **🎯 Write Once Skills**: Define skills once, export to Copilot, Cursor, Claude, Codex -- **🌐 API-First**: RESTful API with FastAPI -- **📡 MCP Native**: Model Context Protocol support -- **🤝 A2A Protocol**: Agent-to-Agent interoperability with external agents -- **🎭 BYO Philosophy**: Bring Your Own models, frameworks, tools +#### Enterprise Flexibility -## 🚀 Quick Start +Bring Your Own (BYO) architecture: models, frameworks, tools, infrastructure. No vendor lock-in. + +#### Security & Compliance + +- 95/100 security score (Bandit, Safety, Semgrep) +- ISO 27001:2022 & ISO 42001:2023 aligned +- SOC2 Type II compliant controls +- OWASP Top 10 & GDPR compliant + + | +
| + +**Using uv (Recommended)** + ```bash -# Using uv (recommended) uv pip install paracle +``` + + | ++ +**Using pip** -# Using pip +```bash pip install paracle ``` -### Configure API Keys + | +
| + +**API Keys Setup** ```bash # Copy example and add your keys cp .env.example .env -# Edit .env with your API keys (OPENAI_API_KEY, etc.) +# Edit .env with your API keys ``` -📖 **See [API Keys Guide](content/docs/api-keys.md) for detailed setup** +📖 [API Keys Guide](content/docs/api-keys.md) + + | +
+
+
+### 🎯 Step 4: Initialize & Run Your First Agent
```bash
# Initialize workspace
@@ -80,7 +187,7 @@ paracle agents list
paracle agents run coder --task "Create a hello world script"
```
-### Or Use the Python API
+### 💻 Or Use the Python API
```python
from paracle_domain.models import AgentSpec, Agent
@@ -96,9 +203,15 @@ agent_spec = AgentSpec(
)
agent = Agent(spec=agent_spec)
-print(f"Agent created: {agent.id}")
+print(f"✅ Agent created: {agent.id}")
```
+Interactive Tutorial (30 minutes hands-on training)
```bash paracle tutorial start ``` -The tutorial guides you through: -1. Creating your first agent -2. Adding tools (filesystem, http, shell) -3. Adding skills for specialized capabilities -4. Creating project templates -5. Testing your agent locally -6. Building your first workflow +**Training Modules:** + +1. Agent creation and configuration +2. Tool integration (filesystem, HTTP, shell) +3. Skills definition and deployment +4. Project template development +5. Local testing and validation +6. Workflow orchestration -Resume anytime with `paracle tutorial resume` +Resume anytime: `paracle tutorial resume` -### Initialize & Run Your First Agent +
+
+**🎉 That's it! You're ready to build AI applications with Paracle!**
+
+
+
## 📦 Project Structure
```
@@ -135,9 +248,12 @@ Paracle follows a **modular monolith** architecture with clear boundaries:
See [Architecture Documentation](content/docs/architecture.md) for details.
-## 🌟 Key Features
+## More Features
+
+### Agent Inheritance System
-### Agent Inheritance
+
+
+
+Hierarchical Agent Architecture
```python # Base agent @@ -148,29 +264,37 @@ base_agent = AgentSpec( temperature=0.7 ) -# Specialized agent (inherits from base) +# Specialized agent (inherits from base) 🎯 python_expert = AgentSpec( name="python-expert", - parent="base-coder", # Inheritance! + parent="base-coder", # ← Inheritance magic! system_prompt="Expert in Python best practices", tools=["pytest", "pylint"] ) ``` -### Multi-Provider Support +
+
+
+🔌 Multi-Provider Support - Switch providers instantly
```python -# OpenAI +# OpenAI 🤖 agent1 = AgentSpec(provider="openai", model="gpt-4") -# Anthropic +# Anthropic 🧠 agent2 = AgentSpec(provider="anthropic", model="claude-sonnet-4.5") -# Local +# Local (free!) 💻 agent3 = AgentSpec(provider="ollama", model="llama3") ``` -### Workflows +**14+ providers supported** - Commercial + Self-hosted + +
+
+
## 📖 Documentation
-### Getting Started
+Workflow Orchestration
```python from paracle_domain.models import Workflow, WorkflowStep @@ -187,42 +311,64 @@ workflow = Workflow( id="suggest", agent_id="advisor", prompt="Suggest improvements", - dependencies=["analyze"] + dependencies=["analyze"] # ← Sequential execution ) ] ) ``` +| + +### 🎓 Getting Started + +- [⚡ Getting Started Guide](content/docs/getting-started.md) +- [🔑 API Keys Configuration](content/docs/api-keys.md) +- [🔌 Providers Guide](content/docs/providers.md) -- [Getting Started Guide](content/docs/getting-started.md) - Quick start in 5 minutes -- [API Keys Configuration](content/docs/api-keys.md) - Set up LLM provider API keys -- [Providers Guide](content/docs/providers.md) - All 14+ supported providers + | +-### Architecture & Design +### 🏗️ Architecture & Design -- [Architecture Overview](content/docs/architecture.md) - System design and patterns -- [Synchronization Guide](content/docs/synchronization-guide.md) - Sync/async patterns -- [API-First CLI](content/docs/api-first-cli.md) - CLI architecture with API fallback +- [🎯 Architecture Overview](content/docs/architecture.md) +- [🔄 Synchronization Guide](content/docs/synchronization-guide.md) +- [🌐 API-First CLI](content/docs/api-first-cli.md) -### Features + | +-- [Skills System](content/docs/skills.md) - Write once, export to all AI platforms -- [Built-in Tools](content/docs/builtin-tools.md) - 9 native tools (filesystem, HTTP, shell) -- [MCP Integration](content/docs/mcp-integration.md) - Model Context Protocol support -- [Security Audit Report](content/docs/security-audit-report.md) - Security assessment -- [Examples](examples/) - 11 code examples and tutorials +### ✨ Features -### Reference +- [🎯 Skills System](content/docs/skills.md) +- [🔧 Built-in Tools](content/docs/builtin-tools.md) +- [📡 MCP Integration](content/docs/mcp-integration.md) +- [🔒 Security Audit](content/docs/security-audit-report.md) -- [Roadmap](.parac/roadmap/roadmap.yaml) - Development roadmap -- [Architecture Decisions](.parac/roadmap/decisions.md) - ADRs + | +
| + +### 📚 Reference + +[🗺️ Roadmap](.parac/roadmap/roadmap.yaml) • +[📝 Architecture Decisions](.parac/roadmap/decisions.md) • +[💡 Examples](examples/) + + | +||
+
+
+🔧 Setup Development Environment
```bash # Clone repository @@ -232,66 +378,142 @@ cd paracle-lite # Install with dev dependencies make install-dev -# Or with uv +# Or with uv (recommended) uv sync --all-extras ``` -### Running Tests +
+
+
+🧪 Running Tests
```bash -# Run tests +# Run all tests make test -# With coverage +# With coverage report make test-cov -# Watch mode +# Watch mode (auto-reload) make test-watch ``` -### Linting +**700+ tests** - Unit, integration, and end-to-end + +
+
+
+### 🗺️ Roadmap
+
+✨ Code Quality
```bash # Run all linters make lint -# Format code +# Auto-format code make format ``` -## 🗺️ Roadmap +**Tools**: ruff, mypy, black, isort + +
-Paracle is under active development. See [roadmap](.parac/roadmap/roadmap.yaml) for details.
+**Paracle v1.0.1** is production-ready! 🎉
-## 🤝 Contributing
+Current Phase: **Phase 10 - Governance & v1.0 Release** (95% complete)
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+[📋 View Full Roadmap](.parac/roadmap/roadmap.yaml) • [🎯 Current Phase Details](.parac/memory/context/current_state.yaml)
-### Development Workflow
+
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run tests and linters
-5. Submit a pull request
+### Contributing
-## 📄 License
+
-Paracle is licensed under the [Apache License 2.0](LICENSE).
+We welcome contributions from the community.
-## 🔗 Links
+
+
-- **Repository**: [github.com/IbIFACE-Tech/paracle-lite](https://github.com/IbIFACE-Tech/paracle-lite)
-- **Documentation**: Coming soon
-- **Issues**: [github.com/IbIFACE-Tech/paracle-lite/issues](https://github.com/IbIFACE-Tech/paracle-lite/issues)
+[Contributing Guidelines](CONTRIBUTING.md) | [Code of Conduct](CODE_OF_CONDUCT.md)
-## 💬 Support
+
-- GitHub Issues: For bugs and feature requests
-- Discussions: For questions and community support
+### 📄 License
+
+|
+1. Fork +Fork Repository + |
+
+2. Branch +Create Feature Branch + |
+
+3. Develop +Implement Changes + |
+
+4. Test +Validate Quality + |
+
+5. Submit +Pull Request + |
+
+
+Licensed under [Apache License 2.0](LICENSE)
+
+**Free and open source** for personal and commercial use
+
+
---
-**Built with ❤️ by IbIFACE-Tech**
+### 🔗 Connect with Us
+
+
+
+
+
+
+### 💬 Get Support
+
+**🐛 Bug Reports** • **✨ Feature Requests** • **❓ Questions** • **💡 Ideas**
+
+All welcome on [GitHub Issues](https://github.com/IbIFACE-Tech/paracle-lite/issues) and [Discussions](https://github.com/IbIFACE-Tech/paracle-lite/discussions)
+
+
+
+
+
+
+
+ |
+
+
+
+
+ |
+
+
+---
+
+### Paracle Framework
+
+**Version 1.0.1**
+700+ Tests | 95/100 Security Score | ISO/SOC2 Compliant
+
+Built with ❤️ by [IbIFACE Team](https://www.ibiface.com)
+
+[Back to top](#)
-_Paracle v0.0.1 - 700+ tests passing_
+
diff --git a/assets/paracle_icon.png b/assets/paracle_icon.png
new file mode 100644
index 0000000..211191c
Binary files /dev/null and b/assets/paracle_icon.png differ
diff --git a/assets/paracle_icon_64.png b/assets/paracle_icon_64.png
new file mode 100644
index 0000000..30b3063
Binary files /dev/null and b/assets/paracle_icon_64.png differ
diff --git a/assets/paracle_vis.png b/assets/paracle_vis.png
new file mode 100644
index 0000000..35d17b6
Binary files /dev/null and b/assets/paracle_vis.png differ
diff --git a/content/docs/api-first-cli.md b/content/docs/api-first-cli.md
new file mode 100644
index 0000000..dd41edd
--- /dev/null
+++ b/content/docs/api-first-cli.md
@@ -0,0 +1,492 @@
+# API-First CLI Architecture
+
+Paracle CLI follows an API-first design pattern with graceful fallback to direct core access.
+
+## Overview
+
+The CLI acts as a thin client that communicates with the Paracle API server. When the API is unavailable, it falls back to direct core access for offline functionality.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ User │
+└────────────────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Paracle CLI │
+│ ┌─────────────────────────────────────────────────────────────┐│
+│ │ Command Layer ││
+│ │ paracle agents list | paracle workflow run | paracle sync ││
+│ └──────────────────────────┬──────────────────────────────────┘│
+│ │ │
+│ ┌──────────────────────────▼──────────────────────────────────┐│
+│ │ API Client Layer ││
+│ │ use_api_or_fallback() function ││
+│ └──────────────────────────┬──────────────────────────────────┘│
+└─────────────────────────────┼───────────────────────────────────┘
+ │
+ ┌─────────────────┴─────────────────┐
+ │ │
+ ▼ ▼
+┌───────────────────────┐ ┌───────────────────────┐
+│ API Available │ │ API Unavailable │
+│ │ │ │
+│ ┌─────────────────┐ │ │ ┌─────────────────┐ │
+│ │ HTTP Request │ │ │ │ Direct Core │ │
+│ │ to API Server │ │ │ │ Function Call │ │
+│ └────────┬────────┘ │ │ └────────┬────────┘ │
+│ │ │ │ │ │
+│ ▼ │ │ ▼ │
+│ ┌─────────────────┐ │ │ ┌─────────────────┐ │
+│ │ Paracle API │ │ │ │ paracle_core │ │
+│ │ (FastAPI) │ │ │ │ paracle_domain │ │
+│ └─────────────────┘ │ │ │ paracle_store │ │
+└───────────────────────┘ │ └─────────────────┘ │
+ └───────────────────────┘
+```
+
+## Design Principles
+
+### 1. API-First
+
+All functionality is exposed through REST APIs first:
+
+```python
+# CLI command calls API endpoint
+def agents_list():
+ client = get_client()
+ response = client.agents_list() # HTTP GET /agents
+ display_agents(response)
+```
+
+### 2. Graceful Fallback
+
+When API is unavailable, fall back to direct access:
+
+```python
+from paracle_cli.api_client import use_api_or_fallback
+
+def list_agents():
+ return use_api_or_fallback(
+ api_func=lambda client: client.agents_list(),
+ fallback_func=direct_list_agents,
+ )
+```
+
+### 3. Consistent Interface
+
+Users get the same experience regardless of API availability:
+
+```bash
+# Works the same whether API is running or not
+paracle agents list
+paracle status
+paracle sync
+```
+
+## API Client
+
+The `APIClient` class provides typed methods for all API endpoints:
+
+```python
+from paracle_cli.api_client import APIClient, get_client
+
+# Get client instance
+client = get_client() # Defaults to http://localhost:8000
+
+# Custom URL
+client = APIClient(base_url="http://api.example.com:8080")
+
+# Check availability
+if client.is_available():
+ response = client.agents_list()
+```
+
+### Available Endpoints
+
+```python
+class APIClient:
+ # Health
+ def health(self) -> dict[str, Any]
+ def is_available(self) -> bool
+
+ # Parac/Governance
+ def parac_status(self) -> dict[str, Any]
+ def parac_sync(self, update_git, update_metrics) -> dict[str, Any]
+ def parac_validate(self) -> dict[str, Any]
+ def parac_session_start(self) -> dict[str, Any]
+ def parac_session_end(self, progress, completed, in_progress) -> dict[str, Any]
+
+ # Agents
+ def agents_list(self) -> dict[str, Any]
+ def agents_get(self, agent_id: str) -> dict[str, Any]
+ def agents_get_spec(self, agent_id: str) -> dict[str, Any]
+
+ # Workflows
+ def workflow_list(self, limit, offset, status) -> dict[str, Any]
+ def workflow_get(self, workflow_id: str) -> dict[str, Any]
+ def workflow_execute(self, workflow_id, inputs, async_execution) -> dict[str, Any]
+ def workflow_execution_status(self, execution_id: str) -> dict[str, Any]
+
+ # IDE Integration
+ def ide_list(self) -> dict[str, Any]
+ def ide_init(self, ides, force, copy) -> dict[str, Any]
+ def ide_sync(self, copy: bool) -> dict[str, Any]
+
+ # Approvals (Human-in-the-Loop)
+ def approvals_list_pending(self) -> dict[str, Any]
+ def approvals_approve(self, approval_id, approver, reason) -> dict[str, Any]
+ def approvals_reject(self, approval_id, approver, reason) -> dict[str, Any]
+
+ # Kanban Board
+ def boards_list(self, include_archived) -> dict[str, Any]
+ def boards_create(self, name, description, columns) -> dict[str, Any]
+ def tasks_list(self, board_id, status, assigned_to) -> dict[str, Any]
+ def tasks_move(self, task_id, status, reason) -> dict[str, Any]
+
+ # Observability
+ def metrics_list(self) -> dict[str, Any]
+ def metrics_export(self, format) -> dict[str, Any]
+ def traces_list(self, limit) -> dict[str, Any]
+ def alerts_list(self, severity, active_only) -> dict[str, Any]
+```
+
+## Fallback Pattern
+
+### use_api_or_fallback()
+
+The main utility for implementing API-first with fallback:
+
+```python
+from paracle_cli.api_client import use_api_or_fallback
+
+def get_project_status():
+ """Get status via API or direct access."""
+ return use_api_or_fallback(
+ api_func=lambda client: client.parac_status(),
+ fallback_func=get_status_direct,
+ )
+
+def get_status_direct():
+ """Direct access fallback."""
+ from paracle_core.parac import read_current_state
+ return read_current_state()
+```
+
+### Fallback Behavior
+
+1. **Check API availability** - Quick health check
+2. **Try API call** - If available, use API
+3. **Handle errors** - Catch connection errors, timeouts
+4. **Fall back** - Use direct core access
+5. **User notification** - Optionally inform user of fallback
+
+```python
+def use_api_or_fallback(api_func, fallback_func, *args, **kwargs):
+ client = get_client()
+
+ if client.is_available():
+ try:
+ return api_func(client, *args, **kwargs)
+ except APIError as e:
+ if e.status_code == 404:
+ pass # Let fallback handle
+ else:
+ console.print(f"[yellow]API error:[/yellow] {e.detail}")
+ console.print("[dim]Falling back to direct access...[/dim]")
+ except Exception as e:
+ console.print(f"[yellow]API unavailable:[/yellow] {e}")
+ console.print("[dim]Falling back to direct access...[/dim]")
+
+ return fallback_func(*args, **kwargs)
+```
+
+## Command Implementation
+
+### Example: Status Command
+
+```python
+import click
+from rich.console import Console
+from paracle_cli.api_client import use_api_or_fallback, get_client
+
+console = Console()
+
+@click.command()
+def status():
+ """Show project status."""
+ result = use_api_or_fallback(
+ api_func=lambda client: client.parac_status(),
+ fallback_func=get_status_fallback,
+ )
+ display_status(result)
+
+def get_status_fallback():
+ """Direct access when API unavailable."""
+ from paracle_core.parac.sync import read_current_state
+ from pathlib import Path
+
+ parac_dir = Path.cwd() / ".parac"
+ if not parac_dir.exists():
+ return {"error": "No .parac/ folder found"}
+
+ return read_current_state(parac_dir)
+
+def display_status(result):
+ """Format and display status."""
+ if "error" in result:
+ console.print(f"[red]{result['error']}[/red]")
+ return
+
+ console.print(f"[bold]Phase:[/bold] {result.get('phase', 'Unknown')}")
+ console.print(f"[bold]Progress:[/bold] {result.get('progress', 0)}%")
+```
+
+### Example: Agents List Command
+
+```python
+@click.command()
+@click.option("--format", type=click.Choice(["table", "json"]), default="table")
+def list_agents(format):
+ """List all available agents."""
+ result = use_api_or_fallback(
+ api_func=lambda client: client.agents_list(),
+ fallback_func=list_agents_fallback,
+ )
+
+ if format == "json":
+ console.print_json(data=result)
+ else:
+ display_agents_table(result)
+
+def list_agents_fallback():
+ """Scan .parac/agents/specs/ directly."""
+ from paracle_core.agents import AgentRegistry
+
+ registry = AgentRegistry()
+ return {"agents": registry.list_all()}
+```
+
+## Authentication
+
+The API client supports token-based authentication:
+
+```python
+client = get_client()
+client.set_token("your-api-token")
+
+# All subsequent requests include the token
+response = client.agents_list()
+```
+
+Headers are automatically set:
+
+```python
+def _get_headers(self) -> dict[str, str]:
+ headers = {"Content-Type": "application/json"}
+ if self._token:
+ headers["Authorization"] = f"Bearer {self._token}"
+ return headers
+```
+
+## Error Handling
+
+### APIError
+
+Custom exception for API errors:
+
+```python
+class APIError(Exception):
+ def __init__(self, status_code: int, detail: str):
+ self.status_code = status_code
+ self.detail = detail
+```
+
+### Error Response Handling
+
+```python
+def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+ if response.status_code >= 400:
+ try:
+ detail = response.json().get("detail", response.text)
+ except (ValueError, KeyError):
+ detail = response.text
+ raise APIError(response.status_code, detail)
+
+ return response.json()
+```
+
+### CLI Error Display
+
+```python
+try:
+ result = client.workflow_execute(workflow_id, inputs)
+except APIError as e:
+ if e.status_code == 404:
+ console.print(f"[red]Workflow not found: {workflow_id}[/red]")
+ elif e.status_code == 400:
+ console.print(f"[red]Invalid request: {e.detail}[/red]")
+ else:
+ console.print(f"[red]API error: {e.detail}[/red]")
+```
+
+## Starting the API Server
+
+The CLI includes a `serve` command to start the API:
+
+```bash
+# Start with defaults (localhost:8000)
+paracle serve
+
+# Custom host and port
+paracle serve --host 0.0.0.0 --port 9000
+
+# With auto-reload for development
+paracle serve --reload
+
+# Production mode
+paracle serve --workers 4
+```
+
+### Server Configuration
+
+```python
+@click.command()
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", default=8000)
+@click.option("--reload", is_flag=True)
+@click.option("--workers", default=1)
+def serve(host, port, reload, workers):
+ """Start the Paracle API server."""
+ import uvicorn
+ uvicorn.run(
+ "paracle_api.main:app",
+ host=host,
+ port=port,
+ reload=reload,
+ workers=workers,
+ )
+```
+
+## Benefits of API-First
+
+### 1. Separation of Concerns
+
+- CLI handles user interaction and formatting
+- API handles business logic and data access
+- Core provides domain models and utilities
+
+### 2. Multiple Interfaces
+
+Same API serves:
+- CLI commands
+- IDE integrations
+- MCP protocol
+- Web dashboard
+- CI/CD pipelines
+
+### 3. Remote Access
+
+Run CLI commands against remote Paracle instances:
+
+```bash
+export PARACLE_API_URL=https://paracle.company.com
+paracle agents list
+```
+
+### 4. Testing
+
+API-first makes testing easier:
+
+```python
+# Test API directly
+def test_agents_list(client):
+ response = client.get("/agents")
+ assert response.status_code == 200
+
+# Test CLI with mocked API
+def test_cli_agents_list(mocker):
+ mocker.patch("paracle_cli.api_client.get_client")
+ result = runner.invoke(cli, ["agents", "list"])
+ assert result.exit_code == 0
+```
+
+### 5. Offline Support
+
+Fallback ensures CLI works without API:
+
+```bash
+# Works even if API server is down
+paracle status
+paracle agents list
+paracle sync
+```
+
+## Best Practices
+
+### 1. Always Use use_api_or_fallback()
+
+```python
+# Good - graceful degradation
+result = use_api_or_fallback(api_func, fallback_func)
+
+# Avoid - no fallback
+result = client.api_call() # Fails if API down
+```
+
+### 2. Keep Fallbacks Simple
+
+```python
+# Good - minimal fallback logic
+def fallback():
+ return read_file_directly()
+
+# Avoid - complex fallback
+def fallback():
+ # Don't replicate full API logic here
+ pass
+```
+
+### 3. Handle Errors Gracefully
+
+```python
+# Good - specific error handling
+try:
+ result = client.workflow_execute(id)
+except APIError as e:
+ if e.status_code == 404:
+ console.print("[red]Workflow not found[/red]")
+ raise
+
+# Avoid - generic error handling
+try:
+ result = client.workflow_execute(id)
+except Exception:
+ console.print("[red]Error[/red]")
+```
+
+### 4. Use Rich for Output
+
+```python
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+# Good - rich formatting
+table = Table(title="Agents")
+table.add_column("Name")
+table.add_column("Status")
+console.print(table)
+
+# Avoid - plain print
+print("Agents:")
+for agent in agents:
+ print(f" {agent['name']}")
+```
+
+## Related Documentation
+
+- [Architecture Overview](architecture.md) - System design
+- [Synchronization Guide](synchronization-guide.md) - Async patterns
+- [CLI Reference](technical/cli-reference.md) - Command reference
diff --git a/content/docs/architecture.md b/content/docs/architecture.md
new file mode 100644
index 0000000..0111a64
--- /dev/null
+++ b/content/docs/architecture.md
@@ -0,0 +1,316 @@
+# Paracle Architecture Overview
+
+System design and architectural patterns for the Paracle multi-agent framework.
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ User Interface │
+│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────────┐ │
+│ │ CLI │ │ API │ │ MCP │ │ IDE Integrations │ │
+│ └────┬────┘ └────┬────┘ └────┬────┘ └──────────┬──────────┘ │
+└───────┼────────────┼────────────┼──────────────────┼────────────┘
+ │ │ │ │
+ ▼ ▼ ▼ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Application Layer │
+│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
+│ │ Orchestration │ │ Workflows │ │ Agent Execution │ │
+│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+ │ │ │ │
+ ▼ ▼ ▼ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Domain Layer │
+│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────────────────┐ │
+│ │ Agents │ │ Workflows │ │ Tools │ │ Skills │ │
+│ └─────────┘ └──────────┘ └─────────┘ └───────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+ │ │ │ │
+ ▼ ▼ ▼ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Infrastructure Layer │
+│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
+│ │Providers │ │ Store │ │ Events │ │ Resilience │ │
+│ └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Design Principles
+
+### 1. Hexagonal Architecture (Ports & Adapters)
+
+Paracle follows hexagonal architecture to ensure:
+- **Testability**: Core logic is isolated from external dependencies
+- **Flexibility**: Swap implementations without changing business logic
+- **Maintainability**: Clear boundaries between layers
+
+```
+ ┌─────────────────┐
+ │ Domain │
+ │ (Business │
+ │ Logic) │
+ └────────┬────────┘
+ │
+ ┌───────────────────┼───────────────────┐
+ │ │ │
+ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
+ │ Port │ │ Port │ │ Port │
+ │(Provider)│ │ (Store) │ │ (Event) │
+ └────┬────┘ └────┬────┘ └────┬────┘
+ │ │ │
+ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
+ │ Adapter │ │ Adapter │ │ Adapter │
+ │(Anthropic)│ │(SQLite) │ │(Redis) │
+ └─────────┘ └─────────┘ └─────────┘
+```
+
+### 2. API-First Design
+
+All functionality is exposed through REST APIs first:
+- CLI commands call API endpoints
+- IDE integrations use the same APIs
+- Consistent behavior across interfaces
+
+### 3. Event-Driven Communication
+
+Components communicate through domain events:
+- Loose coupling between modules
+- Audit trail built-in
+- Easy extension points
+
+## Package Structure
+
+```
+packages/
+├── paracle_core/ # Core utilities, logging, governance
+├── paracle_domain/ # Domain models (Pydantic)
+├── paracle_store/ # Persistence (SQLAlchemy)
+├── paracle_events/ # Event bus, webhooks
+├── paracle_providers/ # LLM providers (Anthropic, OpenAI, etc.)
+├── paracle_orchestration/ # Agent execution engine
+├── paracle_tools/ # Built-in tools
+├── paracle_skills/ # Skills system
+├── paracle_api/ # REST API (FastAPI)
+├── paracle_cli/ # CLI (Typer)
+├── paracle_mcp/ # MCP server
+├── paracle_meta/ # AI generation engine
+├── paracle_kanban/ # Kanban board management
+├── paracle_resilience/ # Circuit breakers, retry
+├── paracle_vector/ # Vector search (pgvector)
+├── paracle_observability/ # Metrics, tracing
+└── paracle_transport/ # Remote execution
+```
+
+## Domain Model
+
+### Agent
+
+The fundamental unit of work:
+
+```python
+class AgentSpec(BaseModel):
+ name: str # Unique identifier
+ description: str # What the agent does
+ model: str = "claude-sonnet-4-20250514"
+ temperature: float = 0.7
+ system_prompt: str | None
+ parent: str | None # Inheritance
+ capabilities: list[str]
+ tools: list[str]
+ skills: list[str]
+```
+
+### Workflow
+
+Orchestrates multiple agents:
+
+```python
+class Workflow(BaseModel):
+ name: str
+ description: str
+ steps: list[WorkflowStep]
+ inputs: list[WorkflowInput]
+ outputs: list[WorkflowOutput]
+```
+
+### Tool
+
+Executable capability:
+
+```python
+class Tool(BaseModel):
+ name: str
+ description: str
+ category: str
+ parameters: dict[str, ToolParameter]
+ handler: Callable
+```
+
+## Execution Model
+
+### Agent Execution Flow
+
+```
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│ Request │────▶│ Resolve │────▶│ Execute │
+│ (Task) │ │ (Inheritance)│ │ (LLM) │
+└──────────────┘ └──────────────┘ └──────┬───────┘
+ │
+┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐
+│ Response │◀────│ Log │◀────│ Tool Calls │
+│ │ │ (Audit) │ │ │
+└──────────────┘ └──────────────┘ └──────────────┘
+```
+
+### Workflow Execution
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Workflow Engine │
+│ ┌─────────┐ │
+│ │ Start │ │
+│ └────┬────┘ │
+│ │ │
+│ ┌────▼────┐ ┌─────────┐ ┌─────────┐ │
+│ │ Step 1 │───▶│ Step 2 │───▶│ Step 3 │──▶ ... │
+│ │(Agent A)│ │(Agent B)│ │(Agent C)│ │
+│ └─────────┘ └─────────┘ └─────────┘ │
+│ │ │ │ │
+│ ▼ ▼ ▼ │
+│ ┌─────────────────────────────────────────────────┐ │
+│ │ Event Bus │ │
+│ └─────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Request Processing
+
+1. **Input**: User request via CLI/API/MCP
+2. **Validation**: Pydantic model validation
+3. **Resolution**: Agent inheritance, tool binding
+4. **Execution**: LLM call with tools
+5. **Logging**: Audit trail, metrics
+6. **Response**: Formatted output
+
+### State Management
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ .parac/ Workspace │
+│ │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
+│ │ Agents │ │ Workflows │ │ Tools │ │
+│ │ (specs/) │ │ (*.yaml) │ │ (registry) │ │
+│ └──────────────┘ └──────────────┘ └──────────────┘ │
+│ │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
+│ │ Memory │ │ Roadmap │ │ Policies │ │
+│ │ (context/) │ │ (phases) │ │ (rules) │ │
+│ └──────────────┘ └──────────────┘ └──────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Security Architecture
+
+### Authentication & Authorization
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Security Layer │
+│ │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
+│ │ API Keys │ │ RBAC │ │ Policies │ │
+│ │ (providers) │ │ (agents) │ │ (tools) │ │
+│ └──────────────┘ └──────────────┘ └──────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────┐ │
+│ │ Audit Trail (ISO 42001) │ │
+│ └──────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Tool Permissions
+
+```yaml
+tools:
+ read_file:
+ requires_approval: false
+ write_file:
+ requires_approval: true
+ sandbox: optional
+ run_command:
+ requires_approval: true
+ sandbox: required
+```
+
+## Scalability
+
+### Horizontal Scaling
+
+```
+┌─────────────┐ ┌─────────────────────────────────────┐
+│ Load │────▶│ API Instances │
+│ Balancer │ │ ┌─────┐ ┌─────┐ ┌─────┐ │
+└─────────────┘ │ │ API │ │ API │ │ API │ │
+ │ └──┬──┘ └──┬──┘ └──┬──┘ │
+ └─────┼───────┼───────┼──────────────┘
+ │ │ │
+ ┌─────▼───────▼───────▼──────────────┐
+ │ PostgreSQL │
+ │ (with pgvector) │
+ └─────────────────────────────────────┘
+```
+
+### Connection Pooling
+
+```python
+engine = create_async_engine(
+ DATABASE_URL,
+ pool_size=20,
+ max_overflow=10,
+ pool_pre_ping=True,
+ pool_recycle=3600,
+)
+```
+
+## Extension Points
+
+### Custom Providers
+
+```python
+class MyProvider(LLMProvider):
+ async def complete(self, messages, model, temperature):
+ # Custom implementation
+ pass
+```
+
+### Custom Tools
+
+```python
+@tool(name="my_tool", category="custom")
+def my_tool(param: str) -> str:
+ """My custom tool."""
+ return result
+```
+
+### Custom Skills
+
+```yaml
+# .parac/agents/skills/my-skill/skill.yaml
+name: my-skill
+description: "Custom skill"
+prompts:
+ main: |
+ Custom prompt template
+```
+
+## Related Documentation
+
+- [Synchronization Guide](synchronization-guide.md) - Async patterns
+- [API-First CLI](api-first-cli.md) - CLI architecture
+- [MCP Integration](mcp-integration.md) - MCP protocol
+- [Security Audit](security-audit-report.md) - Security assessment
diff --git a/content/docs/builtin-tools.md b/content/docs/builtin-tools.md
new file mode 100644
index 0000000..d73de0c
--- /dev/null
+++ b/content/docs/builtin-tools.md
@@ -0,0 +1,653 @@
+# Built-in Tools
+
+Paracle provides 9 secure built-in tools for filesystem, HTTP, and shell operations.
+
+## Overview
+
+Built-in tools are native capabilities that agents can use for common operations. All tools are designed with security-first principles:
+
+- **Mandatory sandboxing** - No unrestricted filesystem access
+- **Explicit allowlists** - Shell commands require whitelisting
+- **Path traversal protection** - Prevents directory escape attacks
+- **Symlink attack prevention** - Detects malicious symlinks
+- **Audit logging** - All operations are logged
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Built-in Tools │
+├─────────────────────────────────────────────────────────────────┤
+│ │
+│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
+│ │ Filesystem │ │ HTTP │ │ Shell │ │
+│ │ │ │ │ │ │ │
+│ │ read_file │ │ http_get │ │ run_command │ │
+│ │ write_file │ │ http_post │ │ │ │
+│ │ list_directory │ │ http_put │ │ │ │
+│ │ delete_file │ │ http_delete │ │ │ │
+│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Tool Registry
+
+Tools are managed through the `BuiltinToolRegistry`:
+
+```python
+from paracle_tools.builtin.registry import BuiltinToolRegistry
+
+# Initialize with security configuration (REQUIRED)
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app/data", "/app/config"],
+ allowed_commands=["git", "ls", "cat", "grep"],
+ http_timeout=30.0,
+ command_timeout=30.0,
+)
+
+# Execute a tool
+result = await registry.execute_tool(
+ "read_file",
+ path="/app/data/config.json",
+)
+
+# List available tools
+tools = registry.list_tools()
+```
+
+### Security Requirements
+
+The registry **requires** explicit configuration:
+
+```python
+# This will FAIL - no unrestricted access allowed
+registry = BuiltinToolRegistry() # ValueError!
+
+# This is correct - explicit paths and commands
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app/data"],
+ allowed_commands=["git"],
+)
+```
+
+## Filesystem Tools
+
+### read_file
+
+Read contents of a file within allowed paths.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | Yes | Path to file to read |
+| `encoding` | string | No | File encoding (default: utf-8) |
+
+**Permissions:** `filesystem:read`
+
+**Security:**
+- Path must be within `allowed_paths`
+- Maximum file size: 10 MB
+- Symlink attacks are prevented
+- Path traversal blocked
+
+```python
+result = await registry.execute_tool(
+ "read_file",
+ path="/app/data/config.json",
+)
+
+# Result
+{
+ "content": "{ ... }",
+ "path": "/app/data/config.json",
+ "size": 1024,
+ "encoding": "utf-8"
+}
+```
+
+**Errors:**
+
+```python
+# Path not allowed
+PermissionError: "Access denied: path is not in allowed directories"
+
+# File too large
+ToolError: "File exceeds maximum size of 10485760 bytes"
+
+# File not found
+ToolError: "File not found: /path/to/file"
+```
+
+### write_file
+
+Write content to a file within allowed paths.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | Yes | Path to file to write |
+| `content` | string | Yes | Content to write |
+| `encoding` | string | No | File encoding (default: utf-8) |
+| `create_dirs` | boolean | No | Create parent directories (default: false) |
+
+**Permissions:** `filesystem:write`
+
+**Security:**
+- Path must be within `allowed_paths`
+- Parent directories validated
+- Atomic writes where possible
+
+```python
+result = await registry.execute_tool(
+ "write_file",
+ path="/app/data/output.json",
+ content='{"status": "success"}',
+ create_dirs=True,
+)
+
+# Result
+{
+ "path": "/app/data/output.json",
+ "size": 21,
+ "created": true
+}
+```
+
+### list_directory
+
+List contents of a directory.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | Yes | Directory path |
+| `pattern` | string | No | Glob pattern filter |
+| `recursive` | boolean | No | List recursively (default: false) |
+
+**Permissions:** `filesystem:read`
+
+**Security:**
+- Maximum 10,000 entries returned
+- Path must be within `allowed_paths`
+
+```python
+result = await registry.execute_tool(
+ "list_directory",
+ path="/app/data",
+ pattern="*.json",
+ recursive=True,
+)
+
+# Result
+{
+ "path": "/app/data",
+ "entries": [
+ {"name": "config.json", "type": "file", "size": 1024},
+ {"name": "data.json", "type": "file", "size": 2048},
+ ],
+ "total": 2
+}
+```
+
+### delete_file
+
+Delete a file within allowed paths.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | Yes | Path to file to delete |
+
+**Permissions:** `filesystem:delete`
+
+**Security:**
+- Path must be within `allowed_paths`
+- Cannot delete directories (use `list_directory` + loop)
+- Operation is logged
+
+```python
+result = await registry.execute_tool(
+ "delete_file",
+ path="/app/data/temp.json",
+)
+
+# Result
+{
+ "path": "/app/data/temp.json",
+ "deleted": true
+}
+```
+
+## HTTP Tools
+
+### http_get
+
+Make an HTTP GET request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | string | Yes | URL to request |
+| `headers` | object | No | HTTP headers |
+| `params` | object | No | Query parameters |
+
+**Permissions:** `http:request`
+
+```python
+result = await registry.execute_tool(
+ "http_get",
+ url="https://api.example.com/data",
+ headers={"Authorization": "Bearer token"},
+ params={"page": "1"},
+)
+
+# Result
+{
+ "status_code": 200,
+ "headers": {"content-type": "application/json"},
+ "body": '{"data": [...]}',
+ "json": {"data": [...]},
+ "url": "https://api.example.com/data?page=1"
+}
+```
+
+**Errors:**
+
+```python
+# Timeout
+ToolError: "Request timed out after 30.0s"
+
+# Connection error
+ToolError: "Connection failed: ..."
+```
+
+### http_post
+
+Make an HTTP POST request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | string | Yes | URL to request |
+| `headers` | object | No | HTTP headers |
+| `data` | string | No | Request body (raw) |
+| `json` | object | No | JSON request body |
+
+**Permissions:** `http:request`
+
+```python
+result = await registry.execute_tool(
+ "http_post",
+ url="https://api.example.com/items",
+ json={"name": "New Item", "value": 42},
+)
+
+# Result
+{
+ "status_code": 201,
+ "headers": {...},
+ "body": '{"id": 123, "name": "New Item"}',
+ "json": {"id": 123, "name": "New Item"}
+}
+```
+
+### http_put
+
+Make an HTTP PUT request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | string | Yes | URL to request |
+| `headers` | object | No | HTTP headers |
+| `data` | string | No | Request body (raw) |
+| `json` | object | No | JSON request body |
+
+**Permissions:** `http:request`
+
+```python
+result = await registry.execute_tool(
+ "http_put",
+ url="https://api.example.com/items/123",
+ json={"name": "Updated Item"},
+)
+```
+
+### http_delete
+
+Make an HTTP DELETE request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | string | Yes | URL to request |
+| `headers` | object | No | HTTP headers |
+
+**Permissions:** `http:request`
+
+```python
+result = await registry.execute_tool(
+ "http_delete",
+ url="https://api.example.com/items/123",
+)
+
+# Result
+{
+ "status_code": 204,
+ "headers": {...},
+ "body": ""
+}
+```
+
+## Shell Tool
+
+### run_command
+
+Execute a shell command from the allowed list.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | string | Yes | Command to execute |
+
+**Permissions:** `shell:execute`
+
+**Security Features:**
+- **Strict allowlist** - Only whitelisted commands can run
+- **No shell=True** - Prevents command injection attacks
+- **Timeout enforcement** - Maximum 5 minutes
+- **Argument validation** - Commands parsed with shlex
+- **Audit logging** - All executions logged
+
+```python
+# Initialize with allowed commands
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app"],
+ allowed_commands=["git", "ls", "cat", "grep", "python"],
+)
+
+# Execute allowed command
+result = await registry.execute_tool(
+ "run_command",
+ command="git status",
+)
+
+# Result
+{
+ "exit_code": 0,
+ "stdout": "On branch main\nnothing to commit...",
+ "stderr": "",
+ "command": "git status",
+ "timed_out": false
+}
+```
+
+**What's Blocked:**
+
+```python
+# Command not in allowlist
+result = await registry.execute_tool("run_command", command="rm -rf /")
+# PermissionError: "Command 'rm' is not in allowed commands list"
+
+# Command chaining (;) - blocked by design
+result = await registry.execute_tool("run_command", command="ls; rm -rf /")
+# Only "ls" is executed, "rm -rf /" is treated as argument
+
+# Pipe injection (|) - blocked by design
+result = await registry.execute_tool("run_command", command="cat file | rm -rf")
+# Only "cat" is executed, rest is treated as arguments
+```
+
+**Why shell=True is Removed:**
+
+The `shell=True` option allowed:
+- Command chaining: `git status; rm -rf /`
+- Command substitution: `git $(rm -rf /)`
+- Pipe injection: `git status | malicious_script`
+- Blocklist bypass: `/bin/rm`, `busybox rm`
+
+All of these are now **impossible** because:
+1. Commands are parsed with `shlex.split()`
+2. Executed directly via `asyncio.create_subprocess_exec()`
+3. No shell interpretation occurs
+
+## Tool Permissions
+
+Each tool requires specific permissions:
+
+| Tool | Permissions |
+|------|-------------|
+| `read_file` | `filesystem:read` |
+| `write_file` | `filesystem:write` |
+| `list_directory` | `filesystem:read` |
+| `delete_file` | `filesystem:delete` |
+| `http_get` | `http:request` |
+| `http_post` | `http:request` |
+| `http_put` | `http:request` |
+| `http_delete` | `http:request` |
+| `run_command` | `shell:execute` |
+
+### Checking Permissions
+
+```python
+# Get required permissions for a tool
+perms = registry.get_tool_permissions("write_file")
+# ["filesystem:write"]
+
+# Get tools by category
+categories = registry.get_tools_by_category()
+# {
+# "filesystem": ["read_file", "write_file", "list_directory", "delete_file"],
+# "http": ["http_get", "http_post", "http_put", "http_delete"],
+# "shell": ["run_command"]
+# }
+```
+
+## Configuration
+
+### Filesystem Paths
+
+Configure allowed paths for filesystem operations:
+
+```python
+# Initial configuration
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app/data", "/app/config"],
+ allowed_commands=["git"],
+)
+
+# Reconfigure at runtime
+registry.configure_filesystem_paths([
+ "/app/data",
+ "/app/config",
+ "/app/uploads", # Add new path
+])
+```
+
+### Allowed Commands
+
+Configure allowed shell commands:
+
+```python
+# Initial configuration
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app"],
+ allowed_commands=["git", "ls", "cat"],
+)
+
+# Reconfigure at runtime
+registry.configure_allowed_commands([
+ "git",
+ "ls",
+ "cat",
+ "python", # Add new command
+ "pytest",
+])
+```
+
+### Timeouts
+
+Configure operation timeouts:
+
+```python
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app"],
+ allowed_commands=["git"],
+ http_timeout=60.0, # HTTP request timeout
+ command_timeout=120.0, # Shell command timeout (max 300s)
+)
+```
+
+## Tool Results
+
+All tools return a `ToolResult` object:
+
+```python
+@dataclass
+class ToolResult:
+ success: bool # Whether operation succeeded
+ data: dict[str, Any] # Result data
+ error: str | None # Error message if failed
+ metadata: dict # Additional metadata
+
+# Success result
+ToolResult(
+ success=True,
+ data={"content": "file contents..."},
+ error=None,
+ metadata={"duration_ms": 12}
+)
+
+# Error result
+ToolResult(
+ success=False,
+ data={},
+ error="File not found: /path/to/file",
+ metadata={"error_code": "FILE_NOT_FOUND"}
+)
+```
+
+## Error Handling
+
+### ToolError
+
+General tool execution error:
+
+```python
+from paracle_tools.builtin.base import ToolError
+
+try:
+ result = await registry.execute_tool("read_file", path="/missing")
+except ToolError as e:
+ print(f"Tool error: {e.message}")
+ print(f"Context: {e.context}")
+```
+
+### PermissionError
+
+Security-related access denial:
+
+```python
+from paracle_tools.builtin.base import PermissionError
+
+try:
+ result = await registry.execute_tool("read_file", path="/etc/passwd")
+except PermissionError as e:
+ print(f"Access denied: {e.message}")
+ print(f"Tool: {e.tool_name}")
+```
+
+## Agent-Specific Tools
+
+Beyond built-in tools, Paracle provides specialized tools for each agent type:
+
+| Module | Purpose |
+|--------|---------|
+| `paracle_tools.coder_tools` | Code generation, refactoring |
+| `paracle_tools.reviewer_tools` | Code review, analysis |
+| `paracle_tools.tester_tools` | Test generation, coverage |
+| `paracle_tools.documenter_tools` | Documentation generation |
+| `paracle_tools.architect_tools` | Architecture design |
+| `paracle_tools.pm_tools` | Project management |
+| `paracle_tools.git_tools` | Git operations |
+| `paracle_tools.release_tools` | Release management |
+| `paracle_tools.terminal_tools` | Terminal operations |
+
+## Best Practices
+
+### 1. Principle of Least Privilege
+
+Only allow what's necessary:
+
+```python
+# Good - minimal permissions
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/app/data"], # Only data directory
+ allowed_commands=["git", "ls"], # Only git and ls
+)
+
+# Avoid - overly permissive
+registry = BuiltinToolRegistry(
+ filesystem_paths=["/"], # Entire filesystem
+ allowed_commands=["bash", "sh"], # Full shell access
+)
+```
+
+### 2. Use Absolute Paths
+
+Always use absolute paths for clarity:
+
+```python
+# Good
+result = await registry.execute_tool(
+ "read_file",
+ path="/app/data/config.json",
+)
+
+# Avoid - relative paths
+result = await registry.execute_tool(
+ "read_file",
+ path="../../../etc/passwd", # Path traversal attempt
+)
+```
+
+### 3. Handle Errors Gracefully
+
+```python
+result = await registry.execute_tool("read_file", path=file_path)
+
+if not result.success:
+ logger.error(f"Failed to read file: {result.error}")
+ return handle_error(result.error)
+
+content = result.data["content"]
+```
+
+### 4. Log Operations
+
+All tool operations are logged automatically, but you can add context:
+
+```python
+from paracle_core.logging import get_logger
+
+logger = get_logger(__name__)
+
+logger.info(f"Reading config file: {file_path}")
+result = await registry.execute_tool("read_file", path=file_path)
+logger.info(f"Config loaded: {result.success}")
+```
+
+## Related Documentation
+
+- [Skills System](skills.md) - Skills with tools
+- [MCP Integration](mcp-integration.md) - MCP tool protocol
+- [Security Audit Report](security-audit-report.md) - Security assessment
+- [Architecture Overview](architecture.md) - System design
diff --git a/content/docs/mcp-integration.md b/content/docs/mcp-integration.md
new file mode 100644
index 0000000..83ffb64
--- /dev/null
+++ b/content/docs/mcp-integration.md
@@ -0,0 +1,649 @@
+# MCP Integration
+
+Paracle provides full support for the Model Context Protocol (MCP), enabling tool sharing between AI applications.
+
+## Overview
+
+The Model Context Protocol (MCP) is a standard protocol for sharing tools and context between AI applications. Paracle supports MCP in two ways:
+
+1. **MCP Server** - Expose Paracle tools to IDEs and AI assistants
+2. **MCP Client** - Discover and use tools from external MCP servers
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ MCP Integration │
+├─────────────────────────────────────────────────────────────────┤
+│ │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ Paracle MCP Server │ │
+│ │ │ │
+│ │ Exposes: │ │
+│ │ - Built-in tools (filesystem, HTTP, shell) │ │
+│ │ - Agent tools (coder, reviewer, tester, etc.) │ │
+│ │ - Custom tools (.parac/tools/custom/) │ │
+│ │ - Context tools (state, roadmap, policies) │ │
+│ │ │ │
+│ │ Transports: stdio, HTTP, WebSocket │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│ ↕ │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ MCP Client │ │
+│ │ │ │
+│ │ Discovers tools from: │ │
+│ │ - External MCP servers │ │
+│ │ - Claude Desktop │ │
+│ │ - VS Code MCP extensions │ │
+│ │ - Custom MCP providers │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## MCP Server
+
+### Starting the Server
+
+```bash
+# Start MCP server (stdio transport - for IDE integration)
+paracle mcp serve
+
+# Start with HTTP transport
+paracle mcp serve --transport http --port 3000
+
+# Start with WebSocket transport
+paracle mcp serve --transport websocket --port 3000
+
+# With verbose logging
+paracle mcp serve --verbose
+```
+
+### Exposed Tools
+
+The MCP server exposes several categories of tools:
+
+#### Context Tools
+
+| Tool | Description |
+|------|-------------|
+| `context.current_state` | Get current project state from `.parac/memory/context/current_state.yaml` |
+| `context.roadmap` | Get project roadmap from `.parac/roadmap/roadmap.yaml` |
+| `context.policies` | Get project policies from `.parac/policies/` |
+| `context.decisions` | Get architecture decisions from `.parac/roadmap/decisions.md` |
+
+#### Workflow Tools
+
+| Tool | Description |
+|------|-------------|
+| `workflow.list` | List available workflows |
+| `workflow.run` | Execute a workflow |
+| `workflow.status` | Get workflow execution status |
+
+#### Memory Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory.log_action` | Log an action to `.parac/memory/logs/agent_actions.log` |
+| `memory.log_decision` | Log a decision to `.parac/memory/logs/decisions.log` |
+
+#### Agent Tools
+
+All agent-specific tools are exposed with the agent prefix:
+
+| Tool Pattern | Example |
+|--------------|---------|
+| `coder.*` | `coder.generate_code`, `coder.refactor` |
+| `reviewer.*` | `reviewer.analyze`, `reviewer.suggest` |
+| `tester.*` | `tester.generate_tests`, `tester.coverage` |
+| `documenter.*` | `documenter.generate_docs` |
+
+### Server Configuration
+
+Configure the MCP server in `.parac/tools/mcp/`:
+
+```yaml
+# .parac/tools/mcp/mcp.yaml
+server:
+ name: paracle
+ version: 1.0.0
+ description: Paracle multi-agent framework tools
+
+ # Transport configuration
+ transports:
+ stdio:
+ enabled: true
+ http:
+ enabled: true
+ port: 3000
+ host: localhost
+ websocket:
+ enabled: false
+
+ # Tool filtering
+ expose_tools:
+ - context.*
+ - workflow.*
+ - memory.*
+ - coder.*
+ - reviewer.*
+
+ # Security
+ security:
+ require_auth: false
+ allowed_origins:
+ - "*"
+```
+
+### IDE Integration
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "paracle": {
+ "command": "paracle",
+ "args": ["mcp", "serve"],
+ "cwd": "/path/to/your/project"
+ }
+ }
+}
+```
+
+#### VS Code
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+ "servers": {
+ "paracle": {
+ "command": "paracle",
+ "args": ["mcp", "serve"],
+ "transport": "stdio"
+ }
+ }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "paracle": {
+ "command": "paracle",
+ "args": ["mcp", "serve"],
+ "env": {
+ "PARACLE_PROJECT": "${workspaceFolder}"
+ }
+ }
+ }
+}
+```
+
+## MCP Client
+
+### Connecting to External Servers
+
+```python
+from paracle_mcp.client import MCPClient
+from paracle_mcp.registry import MCPToolRegistry
+
+# Create client
+client = MCPClient(server_url="http://localhost:3000")
+
+# Connect to server
+async with client:
+ # List available tools
+ tools = await client.list_tools()
+ for tool in tools:
+ print(f"{tool['name']}: {tool['description']}")
+
+ # Call a tool
+ result = await client.call_tool(
+ "search",
+ query="paracle documentation",
+ )
+```
+
+### Tool Registry
+
+The `MCPToolRegistry` maintains a catalog of discovered tools:
+
+```python
+from paracle_mcp.client import MCPClient
+from paracle_mcp.registry import MCPToolRegistry
+
+# Create registry
+registry = MCPToolRegistry()
+
+# Discover tools from multiple servers
+async with MCPClient("http://server1:3000") as client1:
+ count1 = await registry.discover_from_server("server1", client1)
+ print(f"Discovered {count1} tools from server1")
+
+async with MCPClient("http://server2:3000") as client2:
+ count2 = await registry.discover_from_server("server2", client2)
+ print(f"Discovered {count2} tools from server2")
+
+# List all discovered tools
+all_tools = registry.list_tools()
+print(f"Total tools: {len(all_tools)}")
+
+# Get specific tool
+tool = registry.get_tool("server1.search")
+print(tool['description'])
+
+# Call tool through registry
+result = await registry.call_tool(
+ "server1.search",
+ query="example",
+)
+```
+
+### Configuring External Servers
+
+Define external MCP servers in `.parac/tools/mcp/`:
+
+```yaml
+# .parac/tools/mcp/external.yaml
+external_servers:
+ - id: github
+ name: GitHub Tools
+ description: GitHub API tools via MCP
+ command: npx
+ args: ["@modelcontextprotocol/server-github"]
+ env:
+ GITHUB_TOKEN: "${GITHUB_TOKEN}"
+ tools_prefix: github
+ enabled: true
+
+ - id: filesystem
+ name: Filesystem Tools
+ description: Extended filesystem tools
+ command: npx
+ args: ["@modelcontextprotocol/server-filesystem", "/app/data"]
+ tools_prefix: fs
+ enabled: true
+
+ - id: memory
+ name: Memory Tools
+ description: Persistent memory via MCP
+ command: npx
+ args: ["@modelcontextprotocol/server-memory"]
+ enabled: true
+```
+
+## Custom Tools
+
+### Creating Custom MCP Tools
+
+Create Python tools in `.parac/tools/custom/`:
+
+```python
+# .parac/tools/custom/my_tool.py
+
+"""My custom MCP tool."""
+
+# Tool metadata (required)
+TOOL_NAME = "my_custom_tool"
+TOOL_DESCRIPTION = "Performs custom operation"
+TOOL_PARAMETERS = {
+ "type": "object",
+ "properties": {
+ "input": {
+ "type": "string",
+ "description": "Input data",
+ },
+ "options": {
+ "type": "object",
+ "description": "Optional settings",
+ },
+ },
+ "required": ["input"],
+}
+
+
+async def execute(input: str, options: dict = None) -> dict:
+ """Execute the custom tool.
+
+ Args:
+ input: Input data
+ options: Optional settings
+
+ Returns:
+ Result dictionary
+ """
+ # Your tool logic here
+ result = process_input(input, options or {})
+
+ return {
+ "success": True,
+ "result": result,
+ }
+```
+
+### Registering Custom Tools
+
+Register in `.parac/tools/registry.yaml`:
+
+```yaml
+# .parac/tools/registry.yaml
+custom:
+ - name: my_custom_tool
+ description: Performs custom operation
+ file: custom/my_tool.py
+ parameters:
+ type: object
+ properties:
+ input:
+ type: string
+ options:
+ type: object
+ required:
+ - input
+
+ - name: another_tool
+ description: Another custom tool
+ file: custom/another.py
+```
+
+## Protocol Implementation
+
+### Request/Response Format
+
+MCP uses JSON-RPC 2.0:
+
+```json
+// Request
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "search",
+ "arguments": {
+ "query": "example"
+ }
+ }
+}
+
+// Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "content": [
+ {
+ "type": "text",
+ "text": "Search results..."
+ }
+ ]
+ }
+}
+```
+
+### Tool Annotations
+
+Tools can include annotations for client hints:
+
+```python
+TOOL_ANNOTATIONS = {
+ "readOnlyHint": True, # Tool only reads data
+ "destructiveHint": False, # Tool doesn't modify data
+ "idempotentHint": True, # Repeated calls are safe
+ "openWorldHint": False, # Tool operates in closed system
+}
+```
+
+### Error Handling
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "error": {
+ "code": -32602,
+ "message": "Invalid params",
+ "data": {
+ "details": "Missing required parameter 'query'"
+ }
+ }
+}
+```
+
+## Transports
+
+### stdio Transport
+
+Default transport for IDE integration:
+
+```python
+from paracle_mcp.transports.stdio import StdioTransport
+
+transport = StdioTransport()
+await transport.start()
+```
+
+Configuration:
+- Input: stdin
+- Output: stdout
+- Errors: stderr (for debugging)
+
+### HTTP Transport
+
+REST-based transport:
+
+```python
+from paracle_mcp.transports.http import HTTPTransport
+
+transport = HTTPTransport(host="0.0.0.0", port=3000)
+await transport.start()
+```
+
+Endpoints:
+- `POST /mcp/initialize` - Initialize session
+- `POST /mcp/tools/list` - List tools
+- `POST /mcp/tools/call` - Call tool
+- `POST /mcp/shutdown` - End session
+
+### WebSocket Transport
+
+Bidirectional communication:
+
+```python
+from paracle_mcp.transports.websocket import WebSocketTransport
+
+transport = WebSocketTransport(host="0.0.0.0", port=3000)
+await transport.start()
+```
+
+Connection: `ws://localhost:3000/mcp`
+
+## CLI Commands
+
+### Server Commands
+
+```bash
+# Start MCP server
+paracle mcp serve [OPTIONS]
+
+Options:
+ --transport [stdio|http|websocket] Transport type (default: stdio)
+ --host TEXT Host for HTTP/WS (default: localhost)
+ --port INTEGER Port for HTTP/WS (default: 3000)
+ --verbose Enable verbose logging
+```
+
+### Client Commands
+
+```bash
+# List tools from MCP server
+paracle mcp list-tools --server http://localhost:3000
+
+# Call a tool
+paracle mcp call