diff --git a/docs/2-handbook/external-accounts/README.md b/docs/2-handbook/external-accounts/README.md
index ea8bf2406..3d8bd0044 100644
--- a/docs/2-handbook/external-accounts/README.md
+++ b/docs/2-handbook/external-accounts/README.md
@@ -10,3 +10,7 @@ homeserver are in [`swarm/`](../swarm/README.md).
   `git push` and the notification poller, and how the token reaches it.
 - **[GitLab](gitlab.md)** — the same for one or more GitLab instances
   (`glab` and `git push`).
+- **[Forgejo](forgejo.md)** — an account on another forge, used with
+  `hive-forge -f <label>`.
+- **[Matrix](matrix.md)** — an account on another homeserver, beside the
+  agent's own.
diff --git a/docs/2-handbook/external-accounts/forgejo.md b/docs/2-handbook/external-accounts/forgejo.md
new file mode 100644
index 000000000..0e510430d
--- /dev/null
+++ b/docs/2-handbook/external-accounts/forgejo.md
@@ -0,0 +1,46 @@
+# Forgejo accounts
+
+Give an agent an account on a forge other than the swarm's own, such as a
+public Forgejo or a Gitea-compatible instance: the agent can read issues and
+open pull requests there as itself with `hive-forge -f <label>`, authenticated
+by an access token you supply. The swarm's own forge is a different thing and
+needs no linking: see [the swarm forge](../swarm/forge.md).
+
+An agent can hold any number of these accounts, each under a label you choose.
+Two labels can name two forges.
+
+## Linking an account
+
+In the swarm UI, open an agent, choose **link account**, then **forge
+account**. Fill in a label, the forge's URL and an access token. The form shows
+the controller's answer if it refuses the input, and the linked account appears
+in the agent's list of [linked accounts](../swarm/ui.md#linking-external-accounts)
+as kind **forge**.
+
+- `label` is lowercase letters, digits and hyphens. It names the account in the
+  list and in `hive-forge -f <label>`.
+- The URL is the forge's base URL.
+- The token is an access token from that forge. Scope it to what the agent
+  does there, and use a dedicated bot account: the agent can act within the
+  token's scopes.
+
+The controller refuses a label that already holds an account. To replace one, delete it and
+link again. No route hands a token back, and the UI never shows it after
+saving.
+
+## What the agent gets
+
+Within about two minutes the agent can run `hive-forge -f <label>` (for example
+`hive-forge -f work issue list`) against that forge, as the account the token
+belongs to. The agent's own account on the swarm forge stays as it was. Its
+`hive-forge` without `-f` still talks to the swarm's forge.
+
+Linking also allows the forge's host in the agent's outgoing internet access.
+Deleting the account removes it again.
+
+## Deleting an account
+
+Every forge row has a **delete** action, which asks first and then removes the
+stored token. The token stays valid at the forge itself: revoke it there too,
+or the agent's copy still works. The agent keeps a token it has already fetched, so a
+delete isn't an instant cut-off.
diff --git a/docs/2-handbook/external-accounts/matrix.md b/docs/2-handbook/external-accounts/matrix.md
new file mode 100644
index 000000000..77fa76c5d
--- /dev/null
+++ b/docs/2-handbook/external-accounts/matrix.md
@@ -0,0 +1,50 @@
+# Matrix accounts
+
+Give an agent an account on a Matrix homeserver outside the swarm, in addition
+to its own account on the swarm's homeserver. The agent can then read and send
+messages as that account, for example to talk to people on another server. Its
+own swarm account, named `main`, is the swarm's: the swarm mints it for you, and you
+can't link or delete it here. See [the swarm homeserver](../swarm/matrix.md) for
+that account.
+
+An agent can hold any number of these accounts, each under a name you choose.
+
+## Linking an account
+
+In the swarm UI, open an agent, choose **link account**, then **matrix
+account**. You can give the account in two ways:
+
+- **User id and password.** The swarm logs in with them and stores only the
+  token it gets back, not the password. The account gets a device of its own.
+  If you also log in to the same account yourself, the agent sees you as a
+  second device.
+- **Paste a token.** The form warns about this one: a token copied from Element
+  or another client belongs to a device that's already logged in, so the agent
+  can't use that device's encryption keys and the account won't decrypt
+  encrypted rooms. Prefer the password login.
+
+The linked account appears in the agent's list of
+[linked accounts](../swarm/ui.md#linking-external-accounts) as kind
+**matrix**. The controller refuses a name that already holds an account; delete it and link
+again to replace it. Linking also allows the homeserver's host in the agent's outgoing internet
+access, and deleting the account removes it again.
+
+## What the agent gets
+
+Within about two minutes the agent can use the account through its matrix
+tools, naming it in the tool's `account` argument. When an agent holds more
+than one account, each unread-message note in its todos starts with
+`[acct:<name>]`, so the agent can tell which account a message came to.
+
+## Deleting an account
+
+Every matrix row except `main` has a **delete** action, which asks first. The
+confirmation has a checkbox, off by default, that logs the token out at its
+homeserver before deleting. With it off, the token stays valid at the
+homeserver: log the device out there yourself if you want it gone. If the
+logout fails because the homeserver no longer recognises the token, the delete
+goes ahead as if it had worked. Any other failed logout, or an account with no
+homeserver stored, leaves the account in place and the dialog says why.
+
+The agent isn't told about a delete. Its matrix daemon drops the account the
+next time it lists the accounts, within two minutes.
diff --git a/docs/2-handbook/swarm/ui.md b/docs/2-handbook/swarm/ui.md
index 70d3c5794..eee0dc549 100644
--- a/docs/2-handbook/swarm/ui.md
+++ b/docs/2-handbook/swarm/ui.md
@@ -912,24 +912,8 @@ The matrix `main` row is the agent's own account, which the swarm mints;
 it carries an **own account** badge. The card requests the list again when
 a link dialog closes.
 
-- **link a matrix account** — `PUT /api/hives/{hive}/agents/{agent}/matrix-accounts/{account}`,
-  either a user id + password that swarm-controller logs in with, storing the
-  token it gets back, or a pasted bearer token. The form starts on the password
-  login: the account gets a device of its own, and the form notes that an
-  operator who also logs in to it appears to the agent as a second device. Choosing
-  **paste a token** shows a warning: a token from Element or another client
-  belongs to a device that's already logged in, so the agent can't use that
-  device's encryption keys and the account won't decrypt encrypted rooms.
-- **link a forge account** — `PUT /api/hives/{hive}/agents/{agent}/forge-accounts/{label}`
-  with a forge URL and an access token, stored at
-  `swarm/agents/<agent>/forge/<label>`. The agent's
-  `hive-agent-forge-accounts` unit fetches it into
-  `<state>/forge-<label>-token` and `<state>/forge-<label>.json`, the files
-  `hive-forge -f <label>` reads. The unit rewrites a pair whenever the
-  store's account for its label differs, and never deletes one: a pair whose
-  label the store doesn't list stays untouched. swarm-controller answers 409
-  to a link for a label that already holds an account, so replacing one
-  takes a delete, then a new link.
+- **link a matrix account**: see [Matrix accounts](../external-accounts/matrix.md).
+- **link a forge account**: see [Forgejo accounts](../external-accounts/forgejo.md).
 - **link a gitlab account** — `PUT /api/hives/{hive}/agents/{agent}/gitlab-accounts/{label}`
   with a GitLab base URL and an access token, stored at
   `swarm/agents/<agent>/gitlab/<label>`. Link it from the agent's **link account** menu. What the token needs and how the agent uses
@@ -972,16 +956,12 @@ again after a delete, including a 404 one: the account being already gone is
 the end state the delete wanted, so the dialog closes without an error.
 
 The matrix confirmation has a checkbox, off by default, that logs the token
-out at its homeserver first (`?revoke=true`). A 401 `M_UNKNOWN_TOKEN` from
-that logout means the homeserver already doesn't recognise the token, so the
-delete proceeds as if it had succeeded. Any other failed logout, or an account
-with no homeserver stored, leaves the account in the store and the dialog
-shows why. Deleting a forge account or GitHub token leaves the token valid at
-its provider; revoke it there.
-
-The agent isn't told about a delete. Its matrix daemon drops the account when
-it next lists the store, within two minutes. Its forge and GitHub units never
-delete a file, so a token already fetched into `<state>` stays there.
+out at its homeserver first (`?revoke=true`); what that and the agent do
+after a delete is in [Matrix accounts](../external-accounts/matrix.md#deleting-an-account).
+Deleting a forge account or GitHub token leaves the token valid at its
+provider; revoke it there. The agent isn't told about a delete. Its forge and
+GitHub units never delete a file, so a token already fetched into `<state>`
+stays there.
 
 Where each credential lives and who reads it:
 [`credentials-reference.md`](credentials-reference.md).