fleetd #103: document systemd worker secrets

deploy/fleetd.service

@@ -31,11 +31,19 @@ Environment=HERDR_SOCKET_PATH=%h/.config/herdr/herdr.sock
 # spawns, so this line decides whether the fleet can run a build at all. systemd does not source a
 # login shell, so without it the daemon — and every worker — gets a bare default with no JDK/Maven.
 Environment=PATH=/usr/lib/jvm/temurin-25-jdk/bin:/usr/share/maven/bin:/usr/local/bin:/usr/bin:/bin
-# Secrets are NOT set here — this file is committed. Put the API/worker tokens in a private
-# drop-in that systemd reads with restrictive permissions:
-#   systemctl --user edit fleetd     →  [Service] / Environment=FLEETD_API_TOKEN=...
-# or point EnvironmentFile at a 0600 file:
+# Secrets are NOT set here — this file is committed. Put ALL three tokens in a private drop-in
+# that systemd reads with restrictive permissions. In `systemctl --user edit fleetd`, add:
+#   [Service]
+#   Environment=FLEETD_API_TOKEN=...
+#   Environment=WORKER_GITEA_TOKEN=...
+#   Environment=AI_GATEWAY_TOKEN=...
+# FLEETD_API_TOKEN protects fleetd's API. WORKER_GITEA_TOKEN lets members open pull requests; if
+# it is missing, fleetd still starts, but a member fails when it later tries to open a pull request.
+# AI_GATEWAY_TOKEN authenticates gateway profiles; if it is missing, fleetd still starts, but a
+# gateway profile later returns HTTP 401. Or, put the same three variables in a 0600 file and add:
 # EnvironmentFile=%h/.config/fleetd/env
+# After starting, check `journalctl --user -u fleetd` for Fleetd.reportRequiredSecrets. It lists
+# the required secret names that resolved, without printing their values.
 
 Restart=on-failure
 RestartSec=10s