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

README.md

@@ -27,6 +27,25 @@ A container is eligible for update only if it has **both**:
 
 Defense in depth: a valid bearer token AND the opt-in label must both be present before any container is touched.
 
+## Swarm mode
+
+Set `MODE=swarm` to update Docker Swarm services instead of Compose stacks. The
+service runs `docker service update --image` via the Docker API instead of
+shelling out to `docker compose`.
+
+Two things to get right when running in Swarm mode:
+
+- **The opt-in label goes on the service, not the container/task.** Swarm mode
+  reads `Service.Spec.Labels`, so add it with
+  `docker service update --label-add se.shcizo.auto-update=true <service>` or
+  set it under `deploy.labels` in the stack file — a plain `labels:` entry on
+  the service (container-level) is not visible to Swarm mode's discovery.
+- **The updater must talk to a Swarm manager.** `docker service update`
+  requires manager API access, so either point `DOCKER_HOST` at a manager node
+  or schedule the updater container itself on a manager with the socket
+  mounted. This is a deployment concern the service cannot detect or work
+  around.
+
 ## Quick start
 
 1. Build and push the image (e.g. via your own CI).
@@ -49,6 +68,7 @@ All via environment variables.
 | `LOG_LEVEL` | no | `info` | `debug` / `info` / `warn` / `error`. |
 | `UPDATE_TIMEOUT` | no | `5m` | Per-job timeout (Go duration). |
 | `OPT_IN_LABEL` | no | `se.shcizo.auto-update` | Label name to check; value must equal `"true"`. |
+| `MODE` | no | `compose` | `compose` or `swarm`. Selects the update mechanism for the whole deployment; not mixed per-request. |
 
 ## Endpoints
 
@@ -80,5 +100,7 @@ These are tracked in the spec's section 2 and section 15 as deliberate out-of-sc
 
 - **Self-update wiring**: `internal/selfupdate.Wrapped` exists and is unit-tested but is not wired into the live queue. The HTTP response flush ordering for self-replacement is a future enhancement; for now, expect to manually rerun `docker compose up -d` on the host if pushing a new image of `package-updater` itself causes a mid-response interruption.
 - **No rollback**: Compose's "keep old container if new fails to start" is the only safety net.
-- **Single host only**.
+- **Single host only in Compose mode**. Swarm mode (`MODE=swarm`) is the
+  multi-node path, but only from a manager node's point of view — the updater
+  itself still needs manager API access (see "Swarm mode" above).
 - **No per-repo API keys**: a single shared bearer token is used.