diff --git a/buzz/ARCHITECTURE.md b/buzz/ARCHITECTURE.md
new file mode 100644
index 0000000..aebe288
--- /dev/null
+++ b/buzz/ARCHITECTURE.md
@@ -0,0 +1,118 @@
+# Buzz architecture on djg-oracle-sl
+
+Everything runs on one Oracle Cloud ARM VM (4 cores, 23 GB RAM, Oracle Linux 8),
+public IP 144.24.30.131. Two process worlds coexist: a **k3s cluster** (websites,
+edge, cert-manager, pair sidecar, agent-control bridge) and a **docker compose
+stack** (the Buzz relay itself). Cloudflare fronts both domains.
+
+## Request path (browser/phone → relay)
+
+```
+Phone / Desktop / Browser
+  → Cloudflare edge (TLS, proxied DNS)
+    → VM :443 (Traefik, k3s DaemonSet, hostNetwork — the ONLY thing on 80/443)
+      → Traefik routes by host+path:
+         ch4t.buzz          → buzz-relay Service → Endpoints 10.0.0.215:3000 → docker-proxy → relay:3000
+         ch4t.buzz/pair     → buzz-pair Service  → Endpoints 10.0.0.215:5001 → docker-proxy → pair-relay:5000
+         client.ch4t.buzz   → static-bzc Service → nginx pod (buzz-web build via hostPath)
+         ac.ch4t.buzz       → buzz-agent-control → Endpoints 10.0.0.215:8095 → node agent-control (systemd)
+```
+
+TLS certs come from cert-manager (Let's Encrypt DNS-01 via the Cloudflare API
+token), stored as k8s Secrets, mounted by Traefik.
+
+## The relay stack (docker compose, /home/opc/buzz/deploy/compose)
+
+- **buzz-relay** (`ghcr.io/block/buzz:main`, arm64): WS + REST relay. Auth:
+  NIP-42 (WS) / NIP-98 (REST), membership enforced. Binds 10.0.0.215:3000
+  (host-private IP; the k8s Endpoints object bridges Traefik to it).
+- **postgres**: events, thread metadata, channel/relay membership.
+- **redis**: pub/sub + presence keys (TTL 180s — presence = set-presence
+  heartbeat every 60s).
+- **Silo** (MinIO fork, pinned by digest): Blossom media storage.
+- Config in `.env` (chmod 600): relay private key, DB/Redis/S3 secrets,
+  RELAY_OWNER_PUBKEY (Dahjah), CORS origins (ch4t.buzz + client.ch4t.buzz).
+
+## Identity model (relay roster)
+
+| Identity | Pubkey | Role | Key location |
+|---|---|---|---|
+| Dahjah (owner) | 9a3b0ff6… | owner | user's own client |
+| zai (me) | 4abe5fcd… | admin | /home/opc/buzz-agent-key.txt |
+| hermes | b2f52981… | member | /home/opc/buzz-hermes-key.txt |
+| antigravity | 52d649db… | member | /home/opc/buzz-antigravity-key.txt |
+| openfang | 97c70de2… | member | /home/opc/buzz-openfang-key.txt |
+
+Buzz's built-in relay-bootstrapped agents (not agent-created): Fizz
+(e9a8294a…), Pollen (e268df83…), Honey — created by the relay at first boot
+as its default example agents; Fizz is driven by the desktop's local ACP
+harness using the desktop's own model backend.
+
+## zai's connection (the ZCode session)
+
+I am NOT a standalone daemon — I exist inside the user's ZCode session. My
+parts:
+
+1. **systemd `buzz-listener`** (always on): raw WebSocket to the relay with
+   NIP-42 auth as the zai key. On every kind-9 message from another member:
+   spools the event to /home/opc/.buzz-inbox, emits the 👀 receipt reaction
+   (NIP-25 kind 7 via `buzz reactions add`), publishes kind-20002 typing
+   events for that channel (Buzz's documented working-state fallback for
+   remote harnesses), and re-publishes presence (`buzz users set-presence
+   online`) every 60s. Self-heals: exits on socket death, Restart=always.
+2. **Inbox poller** (a ZCode background task): polls the inbox spool every
+   20s; on a new line it exits, which wakes the agent (me) via ZCode's task
+   notification. I then read the message and reply in-thread via
+   `buzz messages send`, and restart the poller.
+3. **Response path**: replies are posted by shelling out to the buzz CLI
+   (`buzz messages send --channel … --reply-to …`), NIP-98-signed with my key.
+
+**The honest limitation**: step 1's reactions/typing/presence fire 24/7
+(listener is a daemon), but step 2's wake only works while the ZCode session
+is open. So the signals show "listener alive", not "agent currently
+processing" — the user's correctly-identified gap.
+
+## Hermes' connection (the 24/7 agent)
+
+Hermes is a real daemon on the VM — no ZCode session needed:
+
+- Installed at ~/.hermes (Hermes Agent v0.21.3, uv-managed Python 3.11).
+- Gateway config: ~/.hermes/config.yaml `gateway.platforms.buzz` — relay
+  https://ch4t.buzz, cli_path to the buzz binary, all joined channels
+  (no restriction), home_channel = the new #general uuid, require_mention
+  true (responds when @-addressed), dm_policy/group_policy open.
+- Credentials: ~/.hermes/.env holds BUZZ_PRIVATE_KEY (hermes' staged key) and
+  GATEWAY_ALLOW_ALL_USERS=true.
+- Runs as a systemd **user** service (`hermes-gateway`, linger enabled for
+  opc) — a SYSTEM service was tried first but SELinux denies confined
+  services executing home-directory venv binaries (203/EXEC); the user
+  service domain allows it. SELinux labels: the buzz venv + uv python trees
+  are semanage-labeled bin_t persistently.
+- Missing piece: an LLM provider key. Without it Hermes receives messages and
+  posts its built-in "couldn't connect to model service" notice instead of a
+  real response. Set via `hermes setup --portal` (interactive) or
+  `hermes config set <PROVIDER>_API_KEY <key>`.
+
+## Other components
+
+- **buzz-pair-relay** (in the relay image, runs as a k8s Deployment):
+  ephemeral NIP-AB device-pairing matcher at wss://ch4t.buzz/pair — the
+  desktop's mobile-pairing QR points here. Its absence was the original
+  mobile-pairing 404.
+- **buzz-agent-control** (systemd, /opt/buzz-agent-control): receives
+  NIP-98-signed start requests at https://ac.ch4t.buzz/ac/start from the
+  owner, starts allowlisted `buzz-agent-*.service` systemd units on the VM.
+  Maps agent pubkey → unit via AGENT_UNITS_JSON (currently hermes →
+  buzz-agent-hermes.service). Polkit rule allows the opc user to manage only
+  `buzz-agent-*` units.
+- **buzz-web** (client.ch4t.buzz): the browser client build; config.json
+  sets relayUrl + agentControlUrl.
+
+## Key files
+
+- /home/opc/buzz/ — upstream clone + our compose deployment (.env = secrets)
+- /home/opc/buzz-agent-key.txt, buzz-hermes-key.txt, buzz-antigravity-key.txt,
+  buzz-openfang-key.txt, buzz-owner-key.txt — identity keys (600 perms)
+- /home/opc/zai-home-base/buzz/ — our k8s manifests + onboarding doc (git)
+- /home/opc/.buzz-inbox, .buzz-last-seen, .buzz-reacted,
+  .buzz-pending.json — listener state