diff --git a/README.md b/README.md
index 34c4abb..42f09ed 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,33 @@
-# ๐ฆ ClawForge โ Enterprise & Government AI Agent Control Plane
+
+ 
+
+
+ClawForge
The control plane for governing, securing, observing, auditing, and operating AI agents and MCP servers.
- 
- 
+ 
+ 
+ 
+ 
+
+
+
+ Kubernetes ยท ServiceNow ยท Splunk โ for AI Agents.
-> **ClawForge = Kubernetes + ServiceNow + Splunk for AI Agents.**
+---
-**ClawForge is not another agent framework.** It is the **control plane** for managing,
-governing, securing, observing, auditing, and operating AI agents, MCP servers,
-workflows, tools, models, and enterprise integrations โ built for government entities,
-municipalities, and enterprise IT, security, and AI platform teams.
+## Overview
+
+**ClawForge is not another agent framework.** It is the **control plane** for
+managing, governing, securing, observing, auditing, and operating AI agents, MCP
+servers, workflows, tools, models, and enterprise integrations โ built for
+government entities, municipalities, and enterprise IT, security, and AI platform
+teams.
| Product | Role |
|---------|------|
@@ -23,18 +36,30 @@ municipalities, and enterprise IT, security, and AI platform teams.
| **Paperclip** | AI company OS |
| **ClawForge** | **Enterprise / Government Agent Control Plane** |
-Underneath the control plane sits a high-performance, local-first **agent runtime**
-written entirely in Rust (a Rust implementation of the [OpenClaw](https://openclaw.ai)
-topology). The runtime orchestrates autonomous agents over a central WebSocket Gateway,
-across channels (WhatsApp, Telegram, Discord, Slack), with tools, sandboxing, and memory.
-The control plane (`clawforge-controlplane`) wraps that runtime with the registry,
-governance, security, observability, and compliance layers an organisation needs to run
-agents safely at scale.
+Beneath the control plane sits a high-performance, local-first **agent runtime**
+written entirely in Rust โ a Rust implementation of the
+[OpenClaw](https://openclaw.ai) topology that orchestrates autonomous agents over
+a central WebSocket gateway, across channels (WhatsApp, Telegram, Discord, Slack),
+with tools, sandboxing, and memory. The `clawforge-controlplane` crate wraps that
+runtime with the registry, governance, security, observability, and compliance
+layers an organisation needs to run agents safely at scale.
+
+> ClawForge is an enterprise-grade AI agent control plane for governing, securing,
+> monitoring, auditing, and operating AI agents and MCP servers across government
+> and enterprise environments.
+
+## Architecture
+
+
+ 
+
-See [docs/product-positioning.md](docs/product-positioning.md) and
-[docs/architecture.md](docs/architecture.md) for the full picture.
+Operators and governance teams drive the **control plane**; the control plane
+authorises and governs the **agent runtime**; the runtime streams execution
+events back for observability and audit. See
+[docs/architecture.md](docs/architecture.md) and [docs/diagrams.md](docs/diagrams.md).
-## The Control Plane
+## Capabilities
The `clawforge-controlplane` crate adds the layers an organisation needs to run
agents safely at scale. Each is a self-contained, SQLite-backed, fully tested
@@ -44,117 +69,83 @@ domain module:
|------------|--------------|------|
| **Agent Registry** | Single source of truth for every agent (owner, tools, MCP, data access, risk, lifecycle) | [registry.md](docs/registry.md) |
| **Governance Engine** | Human approval workflow with department ownership, change history, and audit | [governance.md](docs/governance.md) |
-| **Observability** | Execution events โ task/cost/latency/failure/risk metrics, per-agent and fleet-wide | [observability.md](docs/observability.md) |
-| **Security Gateway** | Pre-execution checks on every action (tool/MCP/model/data/budget/approval) + risk score | [security-gateway.md](docs/security-gateway.md) |
+| **Observability** | Execution events โ task / cost / latency / failure / risk metrics, per-agent and fleet-wide | [observability.md](docs/observability.md) |
+| **Security Gateway** | Pre-execution checks on every action (tool / MCP / model / data / budget / approval) + risk score | [security-gateway.md](docs/security-gateway.md) |
| **MCP Governance** | Registry, approval, health, and usage tracking for MCP servers | [mcp-governance.md](docs/mcp-governance.md) |
| **Agent Marketplace** | Verified, reusable internal agent templates with compliance badges | [marketplace.md](docs/marketplace.md) |
| **Enterprise Integrations** | Governed connectors (DBs, SSO, GIS, ITSM) โ credentials referenced, never stored | [enterprise-integrations.md](docs/enterprise-integrations.md) |
| **Government Compliance** | PII classification, retention, approval chains, audit evidence, reporting (UAE PDPL-aware) | [government-compliance.md](docs/government-compliance.md) |
-See [docs/architecture.md](docs/architecture.md) for how these fit together, and
-[docs/use-cases.md](docs/use-cases.md) for end-to-end government and enterprise
-walkthroughs.
+## Quick start
-> **ClawForge is an enterprise-grade AI agent control plane for governing,
-> securing, monitoring, auditing, and operating AI agents and MCP servers across
-> government and enterprise environments.**
-
-## Install & Quick Start
-
-Requires **Rust โฅ 1.80** and **Node โฅ 20** (for frontend UI).
+Requires **Rust โฅ 1.80** (and **Node โฅ 20** only for the web dashboard).
```bash
-# Clone and build the workspace
git clone https://github.com/YASSERRMD/clawforge.git
cd clawforge
-# Export required configs
-export OPENROUTER_API_KEY="sk-or-v1-..."
+# Build & test the control plane
+cargo build -p clawforge-controlplane
+cargo test -p clawforge-controlplane # 82 tests
-# Run the local-first Gateway Daemon
-cargo run -p clawforge-cli -- serve --port 3000
+# Run the end-to-end control-plane demo
+cargo run -p clawforge-controlplane --example demo
```
-Start the frontend dashboard in a separate terminal:
-```bash
-cd frontend
-npm install
-npm run dev
-```
+The demo walks a single agent through the whole control plane โ marketplace
+install โ MCP approval โ governance โ security gateway โ observability โ
+compliance report โ in memory. See [docs/demo.md](docs/demo.md).
+
+### Running the full runtime (optional)
-Alternatively, run everything via Docker Compose:
```bash
-docker-compose up --build
-```
+export OPENROUTER_API_KEY="sk-or-v1-..."
+cargo run -p clawforge-cli -- serve --port 3000 # local-first gateway
-## Highlights
+cd frontend && npm install && npm run dev # dashboard (separate terminal)
+# or: docker-compose up --build
+```
-- **Local-first Rust Gateway** โ A robust Tokio-based WebSocket control plane for sessions, tools, and events.
-- **Multi-channel integration** โ Full deep adapters for Telegram, Discord, Slack, LINE, iMessage, and WhatsApp via the `clawforge-channels` crate.
-- **Advanced Tooling & Plugins** โ Out of the box CDP browser automation, sandboxed WASM Plugin System, and strict Docker sandboxing for untrusted bash/python executions.
-- **Media Pipeline** โ Dedicated crate for STT transcription hooks (Deepgram/Whisper), OCR visual text extraction, and document mining.
-- **Tailscale Serve** โ Natively bind the runtime to Tailscale for secure remote access.
-- **Declarative Environments** โ Fully reproducible developer environment via `flake.nix`.
+Configuration is environment-driven; see [.env.example](.env.example) and
+[docs/installation.md](docs/installation.md).
-## Everything We Built So Far
+## Documentation
-### Core Platform
-- **`clawforge-core`**: The central vocabulary schemas (`AgentSpec`, `Message`, `Event`).
-- **`clawforge-scheduler`**: Cron and Webhook evaluations that wake up agents.
-- **`clawforge-planner`**: LLM provider integrations (OpenRouter, Ollama) with tool-call parsing and Reflection.
-- **`clawforge-executor`**: Sandboxes and evaluates actions.
-- **`clawforge-supervisor`**: SQLite persistence, policy checks, run state tracking (Active, Paused, AwaitingInput).
-- **`clawforge-memory`**: Vector store implementations for RAG.
+- **Start here:** [Product positioning](docs/product-positioning.md) ยท [Architecture](docs/architecture.md) ยท [Diagrams](docs/diagrams.md) ยท [Installation](docs/installation.md) ยท [Demo](docs/demo.md)
+- **Use cases:** [Overview](docs/use-cases.md) ยท [Government municipality](docs/government-municipality.md) ยท [Enterprise IT](docs/enterprise.md)
+- **Operations:** [UAE PDPL note](docs/uae-pdpl.md) ยท [Security disclaimer](docs/security-disclaimer.md) ยท [Roadmap](docs/roadmap.md) ยท [Limitations](docs/limitations.md)
+- **Contributing:** [Developer guide](docs/developer-guide.md) ยท [CONTRIBUTING.md](CONTRIBUTING.md)
-### Apps + Nodes (Stubs)
-- Built stubs for macOS native app and mobile companion nodes.
-- Engineered a `Canvas` React component in the Frontend for Agent-to-UI visual workspace control.
+Full index: [docs/README.md](docs/README.md).
-### Deep Adapters & Integrations
-- **`clawforge-channels`**: Complete webhook and websocket adapters for Telegram, Discord, Slack, LINE, iMessage, and WhatsApp.
-- **`clawforge-plugins`**: Sandboxed WASM plugin loader with granular permission scopes and internal event bus.
-- **`clawforge-browser`**: Native CDP client for Playwright-style DOM observation, A11y queries, and synthetic interactions.
-- **`clawforge-understanding`**: Media cracking pipelines for OCR, STT, PDF extraction, and ffmpeg native video thumbnails.
-- **`clawforge-infra` & `clawforge-acp`**: Secure mDNS peer pairing, device identity management, Canvas hosting routines, and hierarchical Agent Control Protocol routing.
+## The runtime underneath
-## Planned Missing OpenClaw Features (WIP Phases)
+ClawForge's control plane governs a complete, local-first agent runtime (Rust workspace):
-Compared to the upstream `openclaw` repository, ClawForge is expanding next into:
+- **`clawforge-core`** โ central schemas (`AgentSpec`, `Message`, `Event`).
+- **`clawforge-gateway` / `clawforge-daemon`** โ Tokio WebSocket control plane for sessions, tools, and events.
+- **`clawforge-planner` / `clawforge-executor`** โ LLM provider integrations (OpenRouter, Ollama) and sandboxed action execution.
+- **`clawforge-channels`** โ deep adapters for Telegram, Discord, Slack, LINE, iMessage, and WhatsApp.
+- **`clawforge-plugins` / `clawforge-browser` / `clawforge-understanding`** โ WASM plugins, CDP browser automation, and OCR/STT/PDF media pipelines.
+- **`clawforge-memory` / `clawforge-supervisor`** โ vector memory for RAG and SQLite run-state persistence.
-- **Skills Registry (Phase 13)**: Connecting to ClawHub for dynamic integrations (Notion, GitHub, 1Password).
-- **Long-tail Channels (Phase 25)**: Matrix, Signal, and MS Teams adapters.
-- **Full Control UI & Bots (Phase 15)**: Replacing stubs with full WebChat, Moltbot, and Clawdbot profiles.
-- **Complete Native Apps (Phase 16)**: Bringing the full macOS menu bar app and iOS/Android capabilities (Voice Wake, Screen Recording).
+## Security
-## Security Model (Important)
+ClawForge connects to real messaging surfaces โ treat inbound messages, tool
+output, and MCP responses as **untrusted input**. The Security Gateway gates
+*capabilities* (which tool / MCP / model / data an action may use); keep
+untrusted execution sandboxed (the runtime supports Docker isolation). Secrets
+are never stored โ integrations hold credential *references* only. Read the full
+[security disclaimer](docs/security-disclaimer.md) and [limitations](docs/limitations.md)
+before relying on ClawForge.
-OpenClaw connects to real messaging surfaces. Treat inbound DMs as **untrusted input**.
-In ClawForge, any `ShellTool` executions are strictly evaluated. For group/channel safety, you can enforce execution to route through isolated Docker containers instead of the host machine, matching the OpenClaw sandboxing specs.
+## Contributing
-## Configuration
+Contributions are welcome. Please read the [developer guide](docs/developer-guide.md)
+and [CONTRIBUTING.md](CONTRIBUTING.md) โ work in atomic, well-described commits,
+run `cargo test -p clawforge-controlplane` before opening a pull request, and keep
+documentation in step with code.
-ClawForge uses TOML bridging and environment variables. Tailscale access can be enabled quickly:
-```bash
-export CLAWFORGE_ENABLE_TAILSCALE=1
-cargo run -p clawforge-cli -- serve
-```
+## License
-## Structure
-```
-WhatsApp / Telegram / Slack / Discord / WebChat
- โ
- โผ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ ClawForge Gateway โ
-โ (Rust control plane) โ
-โ ws://127.0.0.1:3000 โ
-โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโ
- โ
- โโ Planner (LLM RPC)
- โโ Supervisor (SQLite)
- โโ Tools (CDP/Docker)
- โโ Frontend Web Dashboard
-```
-
-## Community
-AI/vibe-coded PRs welcome! We are consistently tracking the `openclaw` reference repository and mapping its TypeScript concepts to idiomatic Rust abstractions.
+[MIT](LICENSE).
diff --git a/docs/assets/architecture.png b/docs/assets/architecture.png
new file mode 100644
index 0000000..4928ab2
Binary files /dev/null and b/docs/assets/architecture.png differ
diff --git a/docs/assets/banner.png b/docs/assets/banner.png
new file mode 100644
index 0000000..73c4bf2
Binary files /dev/null and b/docs/assets/banner.png differ