docs: document master/agent phase 1 and add master stack example

README.md

@@ -46,6 +46,21 @@ Two things to get right when running in Swarm mode:
   mounted. This is a deployment concern the service cannot detect or work
   around.
 
+## Master/agent (in progress)
+
+A master with one agent per machine is replacing the single-instance webhook
+model; see the [design spec](docs/superpowers/specs/2026-10-12-master-agent-design.md).
+Phase 1 delivers a live inventory: every Compose stack, Swarm service and
+container on every machine, behind Authentik login. Updates still go through
+the existing `/update` webhook until phase 3.
+
+- Master: `updater-master` in the same image, example stack in `deploy/master.stack.yml`.
+  At startup it does OIDC discovery against `OIDC_ISSUER` and exits if the issuer
+  is unreachable; Swarm then restarts it.
+- Agents: add one per machine on the master's **Agents** page; it shows a
+  ready-to-run compose file with the agent's token and the master's key
+  fingerprint.
+
 ## Quick start
 
 1. Build and push the image (e.g. via your own CI).