diff --git a/agent-diagram.gif b/.github/media/agent-diagram.gif
similarity index 100%
rename from agent-diagram.gif
rename to .github/media/agent-diagram.gif
diff --git a/og.png b/.github/media/og.png
similarity index 100%
rename from og.png
rename to .github/media/og.png
diff --git a/.gitignore b/.gitignore
index 592ba87..50db972 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,7 @@ yarn.lock
 
 # Cache
 .cache/
+.astro/
 *.tsbuildinfo
 .turbo/
 
diff --git a/README.md b/README.md
index adc9e0a..af06217 100644
--- a/README.md
+++ b/README.md
@@ -44,11 +44,14 @@ Want support for another agent? [Open an issue](https://github.com/anthropics/sa
 
 ## Architecture
 
-- Run the `sandbox-agent` daemon locally or inside a sandbox.
-- The daemon spawns agents, normalizes their event streams into a universal schema, and exposes a single HTTP/SSE API.
-- Clients (SDK, CLI, Inspector UI) all use the same `/v1` API for sessions and events.
+![Agent Architecture Diagram](./.github/media/agent-diagram.gif)
 
-See https://rivet.dev/docs/architecture for a deeper walkthrough.
+The Sandbox Agent acts as a universal adapter between your client application and various coding agents (Claude Code, Codex, OpenCode, Amp). Each agent has its own adapter (e.g., `claude_adapter.rs`) that handles the translation between the universal API and the agent-specific interface.
+
+- **Embedded Mode**: Runs agents locally as subprocesses
+- **Server Mode**: Runs as HTTP server from any sandbox provider
+
+[Documentation](https://rivet.dev/docs/architecture)
 
 ## Components