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

CLAUDE.md

@@ -11,6 +11,8 @@ See `README.md` for user-facing docs. This file is for working ON the code.
 go test ./...                          # all tests, fast (no docker required)
 go test -run TestFoo ./internal/api    # single test
 go build ./cmd/server                  # produces ./server
+go build ./cmd/master ./cmd/agent      # new master/agent binaries (phase 1: inventory)
+DATABASE_URL=postgres://... go test -tags integration ./internal/master/store/   # Postgres tests
 docker build -t package-updater:dev .  # multi-stage, builds golang:1.26-alpine
 
 # Local smoke test (builds from Dockerfile, runs against /var/run/docker.sock):
@@ -32,6 +34,13 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
 - `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
+- `cmd/master`, `cmd/agent` — master/agent architecture (spec `2026-10-12-master-agent-design.md`), phase 1 = inventory only. `cmd/server` keeps doing updates until phase 3.
+- `internal/protocol`  — agent↔master WebSocket messages
+- `internal/pin`       — master key pair, self-signed cert, fingerprint-pinned TLS client
+- `internal/agenttoken`— per-agent tokens (`pua_` prefix, only the SHA-256 hash is stored)
+- `internal/imageref`  — split `repo:tag@digest`
+- `internal/agent/...` — inventory collection, Docker event debounce, connection loop
+- `internal/master/...`— Postgres store, agent hub, change broker, OIDC auth, htmx UI
 
 ## Design intent (do not break without discussion)
 
@@ -73,12 +82,19 @@ curl -sH "Authorization: Bearer $UPDATER_API_KEY" \
   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.
+- **WebSocket read limit is raised to 1 MiB on both sides.** coder/websocket defaults to 32 KiB, which a full snapshot from a busy machine exceeds — symptom is an agent stuck in a reconnect loop.
+- **The master's key lives in Postgres (`master_identity`).** Wiping the database means every agent needs a new `MASTER_KEY`.
+- **SSE responses must flush through every wrapper.** `web.events` uses `http.ResponseController`; a middleware that wraps `ResponseWriter` without `Unwrap()` silently breaks live updates. Nginx needs `X-Accel-Buffering: no` (set by the handler).
+- **The "stateless" and "label gate" design intents above describe `cmd/server` only.** The master is stateful by design and gates updates per service in the UI (spec 2026-10-12).
+- **The master does OIDC discovery once at startup and exits if the issuer is unreachable.** It does not retry; Swarm restarts the container, so a short Authentik outage during deploy resolves itself.
 
 ## References
 
 - Design spec: `docs/superpowers/specs/2026-05-22-package-updater-design.md` (489 lines, authoritative)
 - Implementation plan: `docs/superpowers/plans/2026-05-22-package-updater-implementation.md`
 - Consumer-side CI integration: `gitea-action/`
+- Master/agent spec: `docs/superpowers/specs/2026-10-12-master-agent-design.md`
+- Phase 1 plan: `docs/superpowers/plans/2026-10-12-master-agent-phase-1-inventory.md`
 
 ## Conventions