diff --git a/README.md b/README.md
index 4a62114e..b33acc54 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,34 @@ whitelist to itself, nothing for the operator to set.
 For the full list of host and agent NixOS options see the
 **[options reference](https://hyperhive.darkest.space/options/)**.
 
+## Agent configuration
+
+Per-agent config lives in each agent's `agent.nix` (proposed, operator-approved, deployed as git commits). Key options:
+
+### Multi-account Matrix support
+
+`hyperhive.matrixAccounts` declares *additional* matrix accounts for an agent, beyond the hive-internal one. Each entry is keyed by account name and specifies:
+
+- `tokenFile` — path to the matrix bearer token (provisioned out-of-band)
+- `sessionDir` — path to the per-account matrix-sdk sqlite state (crypto keys + cache)
+- `homeserver` — optional homeserver URL (defaults to `hyperhive.matrix.url`)
+
+**Example:**
+
+```nix
+hyperhive.matrixAccounts = {
+  external-public = {
+    tokenFile = "/agents/myagent/state/matrix-token-external";
+    sessionDir = "/agents/myagent/state/matrix-sdk-state-external";
+    homeserver = "https://matrix.org";
+  };
+};
+```
+
+The hive-internal account is always named `main` (synthesized from `hyperhive.matrix.url` + agent state). This option only declares *extras*; the `main` name is reserved and cannot be used here. Requires `hyperhive.matrix.enable = true`.
+
+For more details see [`docs/matrix.md`](docs/matrix.md).
+
 ## Operator CLI
 
 `hivectl` is the operator-facing host CLI for ad-hoc administration that