docs: document MODE=swarm support and its opt-in label / manager-node requirements

CLAUDE.md

@@ -26,7 +26,9 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
 - `internal/api`      — HTTP handlers, bearer-token auth, request-id + access-log middleware
 - `internal/config`   — env-var loading; fails fast if `UPDATER_API_KEY` missing
 - `internal/discovery`— given an image, return Compose `Job`s to run (label parsing, path check, dedup)
+- `internal/discovery/swarm.go`  — SwarmDiscovery: same FindJobs signature, lists `docker service ls`, gates on service-level opt-in label instead of STACKS_ROOT path-check
 - `internal/updater`  — FIFO queue + single worker + `docker compose` subprocess executor
+- `internal/updater/swarm_executor.go` — SwarmExecutor: `docker service update --image` via the Docker API instead of a `docker compose` subprocess
 - `internal/selfupdate` — flush-then-exec wrapper for updating ourselves (NOT wired in live, see gotcha)
 - `internal/metrics`  — Prometheus collectors
 - `internal/logging`  — slog JSON, request-id context propagation
@@ -45,6 +47,10 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
   Tests rely on this — don't drop the nil-check.
 - **Stateless**: no DB, no config file, no on-disk audit log. Docker daemon is
   the source of truth.
+- **Compose mode and Swarm mode are selected once per deployment via `MODE`**, never
+  mixed at request time. Swarm mode's security gate is opt-in label only — there is
+  no STACKS_ROOT-equivalent path check, since Swarm services have no local compose
+  file. Don't add one; don't weaken Compose mode's three-factor gate to match.
 
 ## Gotchas
 
@@ -63,6 +69,10 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
   without the other has caused a fix commit already.
 - **`<summary>` C# convention from global CLAUDE.md does not apply here** — this
   is Go. Use idiomatic GoDoc (`// FuncName does X.`).
+- **Swarm mode requires manager-node API access.** `docker service update` fails
+  with a permission error against a worker-only node. This is an operator/deployment
+  concern (point `DOCKER_HOST` at a manager, or schedule the updater on a manager),
+  not something the code can detect or work around.
 
 ## References