YASSERRMD · YASSERRMD · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026
diff --git a/README.md b/README.md
@@ -1,20 +1,33 @@
-# 🦞 ClawForge — Enterprise & Government AI Agent Control Plane
+<p align="center">
+  <img src="docs/assets/banner.png" alt="ClawForge — Enterprise & Government AI Agent Control Plane" width="100%">
+</p>
+
+<h1 align="center">ClawForge</h1>
 
 <p align="center">
   <strong>The control plane for governing, securing, observing, auditing, and operating AI agents and MCP servers.</strong>
 </p>
 
 <p align="center">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/Rust-1.80+-orange.svg?style=for-the-badge" alt="Rust Version">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-1E3A5F.svg?style=for-the-badge" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/Rust-1.80%2B-D4AF37.svg?style=for-the-badge" alt="Rust 1.80+">
+  <img src="https://img.shields.io/badge/Tests-82%20passing-2E7D32.svg?style=for-the-badge" alt="82 tests passing">
+  <img src="https://img.shields.io/badge/Status-Foundation%20complete-0A1A2F.svg?style=for-the-badge" alt="Status">
+</p>
+
+<p align="center">
+  <em>Kubernetes&nbsp;·&nbsp;ServiceNow&nbsp;·&nbsp;Splunk&nbsp;—&nbsp;for AI Agents.</em>
 </p>
 
-> **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
+
+<p align="center">
+  <img src="docs/assets/architecture.png" alt="ClawForge control-plane architecture" width="100%">
+</p>
 
-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
diff --git a/docs/assets/banner.png b/docs/assets/banner.png