diff --git a/README.md b/README.md
index 1d53d3a..4ddb88f 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@ The app updates itself, and the server along with it on the Mac byre runs on. To
 
 ## Docs
 
+- [docs/architecture.md](docs/architecture.md): a layered diagram of byre, from the Macs and tailnet down to the server's and app's components.
 - [docs/operations.md](docs/operations.md): external setup, vendor and platform quirks, and the intent behind byre's rules.
 - [docs/macos.md](docs/macos.md): the macOS app.
 - [docs/clean-install-vm.md](docs/clean-install-vm.md): testing a first-time install on a fresh Mac in a VM.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..3ba21a2
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,122 @@
+# Architecture
+
+byre from the system down to its software layers. Open a box with the magnifier mark (Server Mac, byre serve, the Manager, Byre.app on Mac) to see the layer inside it. The diagram syntax is the `diagrams` knowledge-base article.
+
+```diagram
+row
+  user "You" "on your Macs and iPhone"
+row
+  mac "Byre.app on Mac" "SwiftUI · two panes" blue
+  phone "Byre on iPhone" "same app, tab bar" blue
+  icloud "iCloud" "CloudKit sync of app prefs" green
+  dl "dl.byre.run" "Sparkle appcast + dmg" green
+row
+  tailnet "Tailscale tailnet" "each app and server is its own node · identity = auth"
+row
+  servermac "Server Mac" "launchd service run.fc.byre" amber
+  vendors "Agent vendors" "Anthropic · OpenAI · Google" green
+  origin "git remote" "origin: fetch · push" green
+user -> mac
+user -> phone
+mac -> tailnet "REST · SSE · WebSockets"
+phone -> tailnet
+mac ..> icloud
+mac ..> dl "updates"
+tailnet -> servermac "HTTPS on byre's ts.net name"
+servermac -> vendors "agent CLIs"
+servermac -> origin "merge · push"
+
+inside servermac
+row
+  service "byre serve" "Contents/Helpers/byre" amber
+row
+  clis "Agent CLIs" "one process group per session"
+    claude_cli "claude"
+    codex_cli "codex"
+    agy_cli "agy"
+  hands_srv "byre-hands" "screen · AX · Orion · Chrome, one copy per session"
+row
+  repos "Project checkouts" "default branch + task worktrees" green
+  data "Data dir" "byre.db · loopback-token · codex home" green
+service -> clis "spawn · stream-json / app-server"
+clis -> service "MCP tools · hooks over loopback"
+clis -> hands_srv "MCP stdio"
+clis -> repos "edit · commit"
+service -> repos "snapshots · merge"
+service -> data
+
+inside service
+row
+  listen "Listeners" "cmd/byre serve"
+    tsnet "tsnet node" "Tailscale whois → user"
+    loop "loopback 127.0.0.1" "bearer token, scripts"
+row
+  http "internal/server" "REST (api/openapi.yaml) · SSE hub · client & terminal WebSockets · preview ports" blue
+  aside store "internal/store" "SQLite WAL, migrations" green
+row
+  mgr "internal/agents · Manager" "tasks · lead · reviews · workflows · merges" amber
+row
+  vendor "Vendor adapters" "one session per agent"
+    claude "internal/claude" "stream-json"
+    codex "internal/codex" "app-server JSON-RPC"
+    agy "internal/antigravity" "stream-json · MCP proxy"
+  tools "Agent-facing"
+    mcp "internal/mcp" "byre tools over HTTP"
+    hook "internal/hookcmd" "hooks via curl"
+row
+  infra "Infrastructure"
+    git "internal/git" "worktrees · snapshots · notes"
+    term "internal/terminal" "PTYs · OSC 133"
+    clients "internal/clients" "client Mac requests"
+    wf "internal/workflow · schedule · todo"
+tsnet -> http
+loop -> http
+http -> mgr "start · message · merge"
+mgr -> vendor
+mgr -> tools
+mgr -> infra
+mgr -> store "writes"
+store ..> http "events → SSE"
+store ..> mgr "poke coordinator"
+
+inside mgr
+row
+  coord "coordinator" "level-triggered, one goroutine" amber
+  live "live sessions" "turns · inbox · turn-end commit"
+row
+  lead "lead agent" "per user · notes"
+  tasks "tasks" "fork · subtasks · teams"
+  review "reviews · audits" "workflow runs"
+row
+  workers "workers" "merge · push · snapshot · discard"
+coord -> workers "start (in-progress column)"
+live -> workers "turn end"
+coord -> review
+coord -> lead "deliveries"
+
+inside mac
+row
+  ui "Views" "Panes · Chat · Composer · Sheet · Switcher" blue
+row
+  appstore "Store" "in-memory state of every task" amber
+  pages "Pages" "WKWebView tabs · drive_page"
+row
+  stream "EventStream · EventCache" "SSE + per-server disk cache"
+  remote "Remote" "client WebSocket: shell · files · hands · signing"
+  fwd "Forwards" "*.localhost previews"
+row
+  net "API · TailnetProxy" "ByreAPI client over libtailscale SOCKS5"
+  aside persist "Persistence · Updater" "SwiftData + CloudKit · Sparkle" green
+ui -> appstore
+ui -> pages
+stream -> appstore "events"
+appstore -> net "requests"
+stream -> net
+remote -> net
+fwd -> net
+pages ..> fwd
+
+highlight "Event stream" store http tailnet stream appstore ui
+highlight "Agent turn" mgr vendor clis tools hands_srv repos
+highlight "Client Mac control" mgr clients http remote
+```