diff --git a/README.md b/README.md
index 9097327f4..cba1f3a03 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,80 @@ It also includes open source models such as [NVIDIA Nemotron](https://build.nvid
 
 ---
 
+## Architecture
+
+**OpenShell** is a general-purpose agent runtime. It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement — but no opinions about what runs inside.
+
+**NemoClaw** is an opinionated reference stack built on OpenShell. It adds:
+
+| Layer | What it provides |
+|-------|------------------|
+| **Onboarding** | Guided setup that validates credentials, selects providers, and creates a working sandbox in one command. |
+| **Blueprint** | A hardened Dockerfile with security policies, capability drops, and least-privilege network rules. |
+| **State management** | Safe migration of agent state across machines with credential stripping and integrity verification. |
+| **Messaging bridges** | Host-side processes that connect Telegram, Discord, and Slack to the sandboxed agent. |
+
+OpenShell handles *how* to sandbox an agent securely. NemoClaw handles *what* goes in the sandbox and makes the setup accessible.
+
+```mermaid
+graph LR
+    classDef nemoclaw fill:#76b900,stroke:#5a8f00,color:#fff,stroke-width:2px,font-weight:bold
+    classDef openshell fill:#1a1a1a,stroke:#1a1a1a,color:#fff,stroke-width:2px,font-weight:bold
+    classDef sandbox fill:#444,stroke:#76b900,color:#fff,stroke-width:2px,font-weight:bold
+    classDef agent fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px
+    classDef external fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px
+    classDef user fill:#fff,stroke:#76b900,color:#1a1a1a,stroke-width:2px,font-weight:bold
+
+    USER(["👤 User"]):::user
+
+    subgraph EXTERNAL["External Services"]
+        INFERENCE["Inference Provider<br/><small>NVIDIA Endpoints · OpenAI<br/>Anthropic · Ollama · vLLM</small>"]:::external
+        MSGAPI["Messaging Platforms<br/><small>Telegram · Discord · Slack</small>"]:::external
+        INTERNET["Internet<br/><small>PyPI · npm · GitHub · APIs</small>"]:::external
+    end
+
+    subgraph HOST["Host Machine"]
+
+        subgraph NEMOCLAW["NemoClaw"]
+            direction TB
+            NCLI["CLI + Onboarding<br/><small>Guided setup · provider selection<br/>credential validation · deploy</small>"]:::nemoclaw
+            BRIDGE["Messaging Bridges<br/><small>Connect chat platforms<br/>to sandboxed agent</small>"]:::nemoclaw
+            BP["Blueprint<br/><small>Hardened Dockerfile<br/>Network policies · Presets<br/>Security configuration</small>"]:::nemoclaw
+            MIGRATE["State Management<br/><small>Migration snapshots<br/>Credential stripping<br/>Integrity verification</small>"]:::nemoclaw
+        end
+
+        subgraph OPENSHELL["OpenShell"]
+            direction TB
+            GW["Gateway<br/><small>Credential store<br/>Inference proxy<br/>Policy engine<br/>Device auth</small>"]:::openshell
+            OSCLI["openshell CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell
+
+            subgraph SANDBOX["Sandbox Container 🔒"]
+                direction TB
+                AGENT["Agent<br/><small>OpenClaw or any<br/>compatible agent</small>"]:::agent
+                PLUG["NemoClaw Plugin<br/><small>Extends agent with<br/>managed configuration</small>"]:::sandbox
+            end
+        end
+    end
+
+    USER -->|"nemoclaw onboard<br/>nemoclaw connect"| NCLI
+    USER -->|"Chat messages"| MSGAPI
+
+    NCLI -->|"Orchestrates"| OSCLI
+    BP -->|"Defines sandbox<br/>shape + policies"| SANDBOX
+    MIGRATE -->|"Safe state<br/>transfer"| SANDBOX
+
+    AGENT -->|"Inference requests<br/><small>no credentials</small>"| GW
+    GW -->|"Proxied with<br/>credential injected"| INFERENCE
+
+    MSGAPI -->|"Bot messages"| BRIDGE
+    BRIDGE -->|"Relayed as data<br/>via SSH"| AGENT
+
+    AGENT -.->|"Policy-gated"| INTERNET
+    GW -.->|"Enforced by<br/>gateway"| INTERNET
+```
+
+---
+
 ## Quick Start
 
 Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent.