From c6af5a2abff1bf2ab1f58a8becb46ea5fd11f892 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Mon, 3 Aug 2026 12:48:37 +0200
Subject: [PATCH] docs: trim impl detail out of the top-level README

Per mara on hyperhive#1898: the top-level README should not go into
details about impl details or specific subsystems. Trims the
Multi-account Matrix support and GitHub account sections down to a
one-line pointer each.

The matrixAccounts option detail that was only ever documented in the
README (checked: docs/matrix.md is entirely about the host hive-matrix
container, not this per-agent option) moves to docs/tools/matrix.md
instead, next to the account parameter every matrix tool already
takes - the natural home, not a link to a page that never covered it.
---
 README.md            | 45 +++++++++-----------------------------------
 docs/tools/matrix.md | 17 +++++++++++++++++
 2 files changed, 26 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index f069ea8c..4e0a87c0 100644
--- a/README.md
+++ b/README.md
@@ -105,43 +105,16 @@ For the full list of host and agent NixOS options see the
 
 ## Agent configuration
 
-Per-agent config lives in each agent's `agent.nix` (proposed, operator-approved, deployed as git commits). Key options:
+Per-agent config lives in each agent's `agent.nix` (proposed, operator-approved, deployed as git commits). Two accounts an agent can hold, both provisioned mostly outside of nix:
 
-### 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).
-
-### GitHub account
-
-Every agent gets a managed GitHub identity — a `gh` CLI wrapper and `git push` over HTTPS — on by default (`hyperhive.github.enable`), inert until a PAT is provisioned. There is nothing per-agent to declare: paste an operator-supplied personal access token into the agent's dashboard **credentials** tab (or `hivectl github set-token <agent> --token-stdin`) and it works. The `gh` wrapper + git credential helper read the token live (git auths as `x-access-token` + the PAT; github.com only), so a rotated PAT takes effect with no rebuild.
-
-Turn the integration off for the whole hive with the host option:
-
-```nix
-services.hyperhive.github.enable = false;
-```
-
-The PAT value is never in nix — only the enable flag. For more details see [`docs/github.md`](docs/github.md).
+- **A second Matrix identity**, beyond the hive-internal one (e.g. an
+  external-facing account alongside the internal one) — see
+  [`docs/tools/matrix.md`](docs/tools/matrix.md) for the
+  `hyperhive.matrixAccounts` option and setup.
+- **A managed GitHub identity** (`gh` CLI + `git push` over HTTPS) — on
+  by default, provisioned by pasting a PAT into the agent's dashboard
+  credentials tab, nothing to declare in nix. See
+  [`docs/github.md`](docs/github.md) for setup and the disable flag.
 
 ## Operator CLI
 
diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md
index 014274c7..896e742b 100644
--- a/docs/tools/matrix.md
+++ b/docs/tools/matrix.md
@@ -67,6 +67,23 @@ room you haven't read yet.
 
 - `mark_read(room, event_id)` — advance the read receipt
 
+## Multiple accounts
+
+`hyperhive.matrixAccounts` (declared in `agent.nix`) gives an agent
+*additional* matrix identities beyond the hive-internal one — e.g. an
+external-facing account alongside the internal one. Each entry is
+keyed by account name and specifies `tokenFile` (bearer token,
+provisioned out-of-band; basename must start with `matrix-token`),
+`sessionDir` (per-account matrix-sdk sqlite state — crypto keys +
+cache), and an optional `homeserver` (defaults to
+`hyperhive.matrix.url`). The hive-internal account is always named
+`main`, synthesized from `hyperhive.matrix.url` + agent state — this
+option only declares extras, and `main` is a reserved key here.
+Requires `hyperhive.matrix.enable = true`.
+
+Every matrix tool above takes an optional `account` parameter (a name
+from this map) to act as that identity instead of the primary one.
+
 ## Architecture
 
 `hive-matrix-daemon` is a single long-running process (one per agent