From 645fd0d56c075c36dc6b4d36ea6df1f54d99253c Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Mon, 17 Aug 2026 23:16:47 +0200
Subject: [PATCH] docs(#3255): record the controller's first persisted file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The crate's module doc claimed no persistence and no writes, which this
change makes false, and docs/persistence.md had no swarm-controller entry
at all — the webhook secret is the daemon's first persisted state.
---
 docs/persistence.md          | 17 +++++++++++++++++
 swarm-controller/src/main.rs | 13 ++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index 679b2dd3..4480495a 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -468,6 +468,23 @@ sends to the swarm's snapshot store — see
 [`docs/snapshot-store.md`](snapshot-store.md) for what a pushed
 snapshot contains and how the store authenticates a sender.
 
+## `/var/lib/swarm-controller/` (swarm-controller host only)
+
+Only present on the one host running
+`services.hyperhive.swarm.controller.enable`. systemd `StateDirectory=`,
+so it survives restarts and redeploys.
+
+- `webhook-secret` — the HMAC key the swarm's forge webhooks are signed
+  with. **Keep it.** It is handed to Forgejo when a hook is registered,
+  so replacing the file means every subsequent delivery fails
+  verification until the hook is re-registered with the new value. It is
+  generated automatically on first start; there is nothing to configure.
+
+If the file is unreadable at startup the daemon still starts and logs
+`webhook secret unavailable`; the webhook endpoint then answers 503
+rather than accepting deliveries it cannot verify. Everything else the
+controller serves is unaffected.
+
 ## Run-time dirs
 
 `/run/hyperhive/` is tmpfs-backed (systemd `RuntimeDirectory=`) but
diff --git a/swarm-controller/src/main.rs b/swarm-controller/src/main.rs
index 08ae0e25..1e172019 100644
--- a/swarm-controller/src/main.rs
+++ b/swarm-controller/src/main.rs
@@ -3,11 +3,14 @@
 //! `services.hyperhive.swarm.controller.enable` on, and serves HTTP over a
 //! unix socket that the hive-gateway's nginx proxies to.
 //!
-//! Holds one piece of read-only state: the swarm's hive directory, loaded
-//! once at startup from an env var the NixOS module sets
-//! (`services.hyperhive.swarm.controller`) — see `load_hives`. Still no
-//! persistence and no writes; a config change means a redeploy, same as
-//! every other option this process reads.
+//! Configuration is read-only and loaded once at startup from env vars the
+//! NixOS module sets (`services.hyperhive.swarm.controller`) — see
+//! `load_hives`. A config change means a redeploy, same as every other
+//! option this process reads.
+//!
+//! The one thing it does persist is `webhook-secret` under its
+//! `StateDirectory` (see `webhook`), because that key is handed to Forgejo
+//! at registration and so cannot be regenerated per boot.
 //!
 //! Distinct from `hive-c0re`, which is per-hive: c0re owns the agents on
 //! one host, this owns what is true across hives.