From 7df6672c87af8c96fe23175f85f6ae9eb0315e51 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Tue, 10 Nov 2026 20:49:47 +0100
Subject: [PATCH] docs: external forge and matrix accounts get pages in
 external-accounts

The directory covered GitHub and GitLab only; the forge and matrix account
kinds an operator can link were described under the swarm UI page. Two new
pages (forgejo.md, matrix.md) cover linking, what the agent gets and
deleting in operator terms, the directory README lists them, and the UI page
keeps a pointer for each kind.
---
 docs/2-handbook/external-accounts/README.md  |  4 ++
 docs/2-handbook/external-accounts/forgejo.md | 46 ++++++++++++++++++
 docs/2-handbook/external-accounts/matrix.md  | 50 ++++++++++++++++++++
 docs/2-handbook/swarm/ui.md                  | 36 ++++----------
 4 files changed, 108 insertions(+), 28 deletions(-)
 create mode 100644 docs/2-handbook/external-accounts/forgejo.md
 create mode 100644 docs/2-handbook/external-accounts/matrix.md

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).