From b8b55ba23eabd35ab14315ecb8819335763cadce Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Sat, 7 Nov 2026 08:29:59 +0100
Subject: [PATCH] credentials-reference: a hand-edited public-key on the
 in-swarm cache is overwritten

---
 .../2-handbook/swarm/credentials-reference.md | 86 +++++++++----------
 1 file changed, 43 insertions(+), 43 deletions(-)

diff --git a/docs/2-handbook/swarm/credentials-reference.md b/docs/2-handbook/swarm/credentials-reference.md
index c427ea3b..c30fc4c0 100644
--- a/docs/2-handbook/swarm/credentials-reference.md
+++ b/docs/2-handbook/swarm/credentials-reference.md
@@ -16,49 +16,49 @@ the rest of the cell says how.
 
 <!-- vale write-good.Passive = NO -->
 
-| store path                                                                                                             | minter                                                                                                                                                                                                                                                                                            | reader                                                                                                                             | automatic re-mint                                                                                                                                            | automatic re-pull                                                                                                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `swarm/agents/<agent>/matrix/main`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the daemon restarts within 5 minutes of a rejection                                                                                                                                                                                                       |
-| `swarm/agents/<agent>/matrix/<account>`                                                                                | `swarm-controller`, from a credential you hand it                                                                                                                                                                                                                                                 | the agent                                                                                                                          | must be stated                                                                                                                                               | ✅ retried within 2 to 16 minutes after a rejection                                                                                                                                                                                                          |
-| `swarm/agents/<agent>/matrix-recovery/<account>`                                                                       | `swarm-controller`, a random passphrase per account                                                                                                                                                                                                                                               | the agent                                                                                                                          | ❌ never replaced: the account's key backup opens only with this passphrase                                                                                  | ❌ read when the account comes up                                                                                                                                                                                                                            |
-| `swarm/controller/swarm-controller/matrix/appservice-token`                                                            | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token`                                                                                                                                                                                                           | `swarm-controller`                                                                                                                 | ❌ follows the registration below                                                                                                                            | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
-| `swarm/controller/swarm-controller/matrix/appservice-registration`                                                     | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged                                                                                                                  | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it                                                             | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver                                                      | ✅ `sync` re-reads it every 10 minutes                                                                                                                                                                                                                       |
-| `swarm/controller/swarm-controller/oidc/client`                                                                        | authelia, first boot                                                                                                                                                                                                                                                                              | `swarm-controller`                                                                                                                 | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/forge/token`                                                                        | the forge, once                                                                                                                                                                                                                                                                                   | `swarm-controller`                                                                                                                 | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/grafana/token`                                                                      | `swarm-bao-grafana-controller-token` on Grafana's host                                                                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ✅ every 10 minutes, when Grafana refuses it or none is stored                                                                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/forge/webhook-secret`                                                               | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered                                                                | ❌ read once; a store down at start is re-read in the background until it answers                                                                                                                                                                            |
-| `swarm/agents/<agent>/bao-mtls`                                                                                        | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing                                                                                                                                     | `hive-c0re`, then the agent                                                                                                        | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed`      | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid                                                                                                                                                                       |
-| `swarm/agents/<agent>/queue`                                                                                           | `swarm-controller`, at agent creation                                                                                                                                                                                                                                                             | the agent; the queue, log and metrics auth services                                                                                | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted                                                                               | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
-| `swarm/agents/<agent>/observability`                                                                                   | `swarm-controller`, when an operator sets, clears or creates an agent's permissions with `logs` or `metrics` in the old or new list, and when it destroys the agent; the leaf stays absent for an agent that never held either                                                                    | the agent (read-only, its own prefix); `swarm-logs-auth` and `swarm-metrics-agent-auth`, which deny when it's absent or unreadable | ✅ the controller rewrites it with the permission, and every five minutes makes it equal the record's                                                        | ✅ the stores honour a changed grant for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default)                                                                                                       |
-| `swarm/agents/<agent>/forge-token`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or no longer matching the forge                                                                                                              | ✅ every 10 minutes                                                                                                                                                                                                                                          |
-| `swarm/agents/<agent>/forge/<label>`                                                                                   | `swarm-controller`, when you link an external forge account in the swarm UI                                                                                                                                                                                                                       | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes                                                                                                                                                                                                                                           |
-| `swarm/agents/<agent>/gitlab/<label>`                                                                                  | `swarm-controller`, when you link a GitLab account through the API                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run                                                                                                                                                                |
-| `swarm/agents/<agent>/github-token`                                                                                    | `swarm-controller`, when you link a GitHub account in the swarm UI                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link again                                                                                                                      | ✅ every 2 minutes                                                                                                                                                                                                                                           |
-| `swarm/agents/<agent>/backend-env`                                                                                     | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI                                                       | the agent                                                                                                                          | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start                                                                                                                                         |
-| `swarm/agents/<agent>/claude-credentials`                                                                              | `swarm-claude-login`, when you log the agent in from its card; one version per login                                                                                                                                                                                                              | the agent, while it waits for a login                                                                                              | ❌ log in again                                                                                                                                              | ✅ every 30 seconds while waiting                                                                                                                                                                                                                            |
-| `swarm/hives/<hive>/matrix/sender-token`                                                                               | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the hive re-reads on every sweep                                                                                                                                                                                                                          |
-| `swarm/hives/<hive>/forge/token`                                                                                       | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every forge call                                                                                                                                                                                                                                  |
-| `swarm/agents/<agent>/proxy-credential`                                                                                | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity                                                                                                                                                                                     | the hive (`hive-c0re`) and the agent, which fetches it                                                                             | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` re-reads it every 30 seconds                                                                                                                                                                                                                  |
-| `swarm/hives/<hive>/squid-selfcheck`                                                                                   | `swarm-controller`, in the same pass as the agents' credentials                                                                                                                                                                                                                                   | the hive: `hive-c0re` and `squid-selfcheck-credential` (root)                                                                      | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes                                                                                                                                                                                              |
-| `swarm/hives/<hive>/oidc/client`                                                                                       | authelia, first boot, straight into the store                                                                                                                                                                                                                                                     | the hive                                                                                                                           | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
-| `swarm/services/<clientId>/oidc/client`                                                                                | authelia                                                                                                                                                                                                                                                                                          | that service                                                                                                                       | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
-| `swarm/services/ci-runner/registration-token`                                                                          | `swarm-controller`, from the forge, at start and every 5 minutes                                                                                                                                                                                                                                  | `swarm-bao-ci-runner` on the runner's host                                                                                         | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes                                               | ✅ every 10 minutes; restarts the runner on a change                                                                                                                                                                                                         |
-| `swarm/services/<grafana client id>/metrics/bearer`                                                                    | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored                                                                                                                                                                                                                         | `swarm-metrics-auth` and `swarm-logs-grafana-auth`                                                                                 | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer`                                                                                                  | ✅ the auth services re-read within a minute, and while they can't reach the store they keep accepting the value they last read, for an hour at most; ❌ Grafana restarts when its copy changes                                                              |
-| `swarm/services/<grafana client id>/secret-key`                                                                        | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none                                                                                                                                                                    | Grafana                                                                                                                            | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets                                                                  | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes                                                                                                                                                                                |
-| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none                                                                                                               | authelia                                                                                                                           | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token           | ❌ read when the unit runs; the unit restarts authelia when the file changes                                                                                                                                                                                 |
-| `swarm/services/review-classifier/anthropic-api-key`                                                                   | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
-| `swarm/services/review-classifier/acp-provider`                                                                        | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
-| `swarm/services/review-classifier/forge/token`                                                                         | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-controller`                                                                                                                 | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every review                                                                                                                                                                                                                                      |
-| `swarm/services/builder/forge/token`                                                                                   | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-builder`, `swarm-controller`                                                                                                | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every build                                                                                                                                                                                                                                       |
-| `swarm/services/attic/push-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin                                                                                                          | `swarm-builder`                                                                                                                    | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false                                                | ✅ read on every push; with both `swarm.attic` options null, nothing reads it                                                                                                                                                                                |
-| `swarm/services/attic/pull-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, to copy it and to check narinfos                                                                               | ❌ write a new token                                                                                                                                         | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/url`                                                                                             | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash)                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value                                                                                    | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/cache`                                                                                           | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ as the URL                                                                                                                                                | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/public-key`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored and again whenever the cache reports another key (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`) | `swarm-controller`, which copies it to each hive                                                                                   | ✅ on the cache's host, a re-created cache's key replaces it at the unit's next run; with an external cache, replace it yourself                             | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}`                                                           | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays                                                                                                                              | the hive (`hive-c0re`)                                                                                                             | ✅ a changed source is written over the copy in the next pass                                                                                                | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
-| `swarm/services/attic/jwt-secret`                                                                                      | `swarm-bao-attic-secret` on the cache's host, when none is stored                                                                                                                                                                                                                                 | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens`                                                                                 | ❌ a new key invalidates both tokens                                                                                                                         | ❌ atticd restarts when the file changes                                                                                                                                                                                                                     |
-| `swarm/services/ci-metrics/forge/token`                                                                                | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-ci-metrics`, `swarm-controller`                                                                                             | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every pass                                                                                                                                                                                                                                        |
-| _(not in the store)_ a hive's mTLS leaf                                                                                | the store's PKI, or you by hand                                                                                                                                                                                                                                                                   | the hive itself, from disk                                                                                                         | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
+| store path                                                                                                             | minter                                                                                                                                                                                                                                                                                            | reader                                                                                                                             | automatic re-mint                                                                                                                                             | automatic re-pull                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `swarm/agents/<agent>/matrix/main`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or rejected by the homeserver                                                                                                                 | ✅ the daemon restarts within 5 minutes of a rejection                                                                                                                                                                                                       |
+| `swarm/agents/<agent>/matrix/<account>`                                                                                | `swarm-controller`, from a credential you hand it                                                                                                                                                                                                                                                 | the agent                                                                                                                          | must be stated                                                                                                                                                | ✅ retried within 2 to 16 minutes after a rejection                                                                                                                                                                                                          |
+| `swarm/agents/<agent>/matrix-recovery/<account>`                                                                       | `swarm-controller`, a random passphrase per account                                                                                                                                                                                                                                               | the agent                                                                                                                          | ❌ never replaced: the account's key backup opens only with this passphrase                                                                                   | ❌ read when the account comes up                                                                                                                                                                                                                            |
+| `swarm/controller/swarm-controller/matrix/appservice-token`                                                            | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token`                                                                                                                                                                                                           | `swarm-controller`                                                                                                                 | ❌ follows the registration below                                                                                                                             | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
+| `swarm/controller/swarm-controller/matrix/appservice-registration`                                                     | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged                                                                                                                  | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it                                                             | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver                                                       | ✅ `sync` re-reads it every 10 minutes                                                                                                                                                                                                                       |
+| `swarm/controller/swarm-controller/oidc/client`                                                                        | authelia, first boot                                                                                                                                                                                                                                                                              | `swarm-controller`                                                                                                                 | ❌ minted once, straight into the store; minted again only when the store holds none                                                                          | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/forge/token`                                                                        | the forge, once                                                                                                                                                                                                                                                                                   | `swarm-controller`                                                                                                                 | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one                                                | ✅ re-read on a 401                                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/grafana/token`                                                                      | `swarm-bao-grafana-controller-token` on Grafana's host                                                                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ✅ every 10 minutes, when Grafana refuses it or none is stored                                                                                                | ✅ re-read on a 401                                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/forge/webhook-secret`                                                               | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered                                                                 | ❌ read once; a store down at start is re-read in the background until it answers                                                                                                                                                                            |
+| `swarm/agents/<agent>/bao-mtls`                                                                                        | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing                                                                                                                                     | `hive-c0re`, then the agent                                                                                                        | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed`       | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid                                                                                                                                                                       |
+| `swarm/agents/<agent>/queue`                                                                                           | `swarm-controller`, at agent creation                                                                                                                                                                                                                                                             | the agent; the queue, log and metrics auth services                                                                                | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted                                                                                | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
+| `swarm/agents/<agent>/observability`                                                                                   | `swarm-controller`, when an operator sets, clears or creates an agent's permissions with `logs` or `metrics` in the old or new list, and when it destroys the agent; the leaf stays absent for an agent that never held either                                                                    | the agent (read-only, its own prefix); `swarm-logs-auth` and `swarm-metrics-agent-auth`, which deny when it's absent or unreadable | ✅ the controller rewrites it with the permission, and every five minutes makes it equal the record's                                                         | ✅ the stores honour a changed grant for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default)                                                                                                       |
+| `swarm/agents/<agent>/forge-token`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or no longer matching the forge                                                                                                               | ✅ every 10 minutes                                                                                                                                                                                                                                          |
+| `swarm/agents/<agent>/forge/<label>`                                                                                   | `swarm-controller`, when you link an external forge account in the swarm UI                                                                                                                                                                                                                       | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                             | ✅ every 2 minutes                                                                                                                                                                                                                                           |
+| `swarm/agents/<agent>/gitlab/<label>`                                                                                  | `swarm-controller`, when you link a GitLab account through the API                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                             | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run                                                                                                                                                                |
+| `swarm/agents/<agent>/github-token`                                                                                    | `swarm-controller`, when you link a GitHub account in the swarm UI                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link again                                                                                                                       | ✅ every 2 minutes                                                                                                                                                                                                                                           |
+| `swarm/agents/<agent>/backend-env`                                                                                     | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI                                                       | the agent                                                                                                                          | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was  | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start                                                                                                                                         |
+| `swarm/agents/<agent>/claude-credentials`                                                                              | `swarm-claude-login`, when you log the agent in from its card; one version per login                                                                                                                                                                                                              | the agent, while it waits for a login                                                                                              | ❌ log in again                                                                                                                                               | ✅ every 30 seconds while waiting                                                                                                                                                                                                                            |
+| `swarm/hives/<hive>/matrix/sender-token`                                                                               | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or rejected by the homeserver                                                                                                                 | ✅ the hive re-reads on every sweep                                                                                                                                                                                                                          |
+| `swarm/hives/<hive>/forge/token`                                                                                       | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or no longer matching the forge                                                                                                               | ✅ read on every forge call                                                                                                                                                                                                                                  |
+| `swarm/agents/<agent>/proxy-credential`                                                                                | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity                                                                                                                                                                                     | the hive (`hive-c0re`) and the agent, which fetches it                                                                             | ❌ never replaced: written only while the path holds nothing                                                                                                  | ✅ `hive-c0re` re-reads it every 30 seconds                                                                                                                                                                                                                  |
+| `swarm/hives/<hive>/squid-selfcheck`                                                                                   | `swarm-controller`, in the same pass as the agents' credentials                                                                                                                                                                                                                                   | the hive: `hive-c0re` and `squid-selfcheck-credential` (root)                                                                      | ❌ never replaced: written only while the path holds nothing                                                                                                  | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes                                                                                                                                                                                              |
+| `swarm/hives/<hive>/oidc/client`                                                                                       | authelia, first boot, straight into the store                                                                                                                                                                                                                                                     | the hive                                                                                                                           | ❌ minted once, straight into the store; minted again only when the store holds none                                                                          | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
+| `swarm/services/<clientId>/oidc/client`                                                                                | authelia                                                                                                                                                                                                                                                                                          | that service                                                                                                                       | must be stated                                                                                                                                                | must be stated                                                                                                                                                                                                                                               |
+| `swarm/services/ci-runner/registration-token`                                                                          | `swarm-controller`, from the forge, at start and every 5 minutes                                                                                                                                                                                                                                  | `swarm-bao-ci-runner` on the runner's host                                                                                         | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes                                                | ✅ every 10 minutes; restarts the runner on a change                                                                                                                                                                                                         |
+| `swarm/services/<grafana client id>/metrics/bearer`                                                                    | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored                                                                                                                                                                                                                         | `swarm-metrics-auth` and `swarm-logs-grafana-auth`                                                                                 | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer`                                                                                                   | ✅ the auth services re-read within a minute, and while they can't reach the store they keep accepting the value they last read, for an hour at most; ❌ Grafana restarts when its copy changes                                                              |
+| `swarm/services/<grafana client id>/secret-key`                                                                        | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none                                                                                                                                                                    | Grafana                                                                                                                            | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets                                                                   | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes                                                                                                                                                                                |
+| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none                                                                                                               | authelia                                                                                                                           | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token            | ❌ read when the unit runs; the unit restarts authelia when the file changes                                                                                                                                                                                 |
+| `swarm/services/review-classifier/anthropic-api-key`                                                                   | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                            | ✅ read on every run                                                                                                                                                                                                                                         |
+| `swarm/services/review-classifier/acp-provider`                                                                        | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                            | ✅ read on every run                                                                                                                                                                                                                                         |
+| `swarm/services/review-classifier/forge/token`                                                                         | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-controller`                                                                                                                 | ✅ when missing or no longer matching the forge                                                                                                               | ✅ read on every review                                                                                                                                                                                                                                      |
+| `swarm/services/builder/forge/token`                                                                                   | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-builder`, `swarm-controller`                                                                                                | ✅ when missing or no longer matching the forge                                                                                                               | ✅ read on every build                                                                                                                                                                                                                                       |
+| `swarm/services/attic/push-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin                                                                                                          | `swarm-builder`                                                                                                                    | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false                                                 | ✅ read on every push; with both `swarm.attic` options null, nothing reads it                                                                                                                                                                                |
+| `swarm/services/attic/pull-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, to copy it and to check narinfos                                                                               | ❌ write a new token                                                                                                                                          | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/url`                                                                                             | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash)                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value                                                                                     | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/cache`                                                                                           | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ as the URL                                                                                                                                                 | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/public-key`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored and again whenever the cache reports another key (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`) | `swarm-controller`, which copies it to each hive                                                                                   | ✅ on the cache's host, the unit's next run replaces any other value, a hand edit included, with the cache's key; with an external cache, replace it yourself | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}`                                                           | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays                                                                                                                              | the hive (`hive-c0re`)                                                                                                             | ✅ a changed source is written over the copy in the next pass                                                                                                 | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
+| `swarm/services/attic/jwt-secret`                                                                                      | `swarm-bao-attic-secret` on the cache's host, when none is stored                                                                                                                                                                                                                                 | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens`                                                                                 | ❌ a new key invalidates both tokens                                                                                                                          | ❌ atticd restarts when the file changes                                                                                                                                                                                                                     |
+| `swarm/services/ci-metrics/forge/token`                                                                                | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-ci-metrics`, `swarm-controller`                                                                                             | ✅ when missing or no longer matching the forge                                                                                                               | ✅ read on every pass                                                                                                                                                                                                                                        |
+| _(not in the store)_ a hive's mTLS leaf                                                                                | the store's PKI, or you by hand                                                                                                                                                                                                                                                                   | the hive itself, from disk                                                                                                         | must be stated                                                                                                                                                | must be stated                                                                                                                                                                                                                                               |
 
 <!-- vale write-good.Passive = YES -->