docs(validator): compute-requirements table + turnkey install with auto-update

docs/validator/README.md

@@ -1,17 +1,119 @@
-# Validator Submitter Guide (Docker Swarm)
+# Validator Guide (Docker Swarm)
 
-This guide is only for normal validators. It installs the submit-only on-chain
-weight submitter as a systemd service. The submitter fetches the master weight
-vector from the public BASE endpoint and submits it on-chain. It runs
-no challenge orchestration: all challenge services run on the BASE
-master (manager) node.
+This guide covers running a BASE validator on Docker Swarm. There is no
+Kubernetes anywhere in BASE: the only backend is Docker Swarm.
+
+A validator runs in one of a few profiles, from a submit-only on-chain weight
+submitter through a full challenge-evaluating validator node. The
+[Compute Requirements](#compute-requirements) below size each profile, and the
+[Automatic Install (One Command)](#automatic-install-one-command) section brings
+up a self-updating validator node with the turnkey installer.
+
+The simplest profile is the submit-only on-chain weight submitter, installed as a
+systemd service. The submitter fetches the master weight vector from the public
+BASE endpoint and submits it on-chain. It runs no challenge orchestration: all
+challenge services run on the BASE master (manager) node.
 
 The default weights endpoint is:
 
 ```text
 https://chain.joinbase.ai/v1/weights/latest
 ```
 
+## Compute Requirements
+
+How much compute a validator needs depends on which evaluation work it performs.
+The numbers in this table are authoritative.
+
+| Validator profile | Compute |
+|-------------------|---------|
+| Submit-only / simple validator (no challenge execution) | 2 vCPU, 4 GB RAM |
+| Validator running the base (agent-challenge) evaluation | 8 vCPU, 32 GB RAM |
+| PRISM challenge | No additional compute required |
+
+PRISM adds no compute to the validator: its heavy GPU evaluation is **delegated
+to miner-funded worker agents** (the worker plane), and the validator only
+performs light verification plus probabilistic replay audits. A validator
+therefore never needs a local GPU for PRISM.
+
+## Automatic Install (One Command)
+
+`deploy/swarm/install-swarm.sh` is the automatic, one-command install path. On a
+blank host it installs everything it needs: Docker Engine (its `ensure_docker`
+step), the `uv` runtime (its `ensure_uv` step, when the supervisor is installed),
+and the Docker Swarm (`swarm init`).
+
+### Dry-run by default
+
+The installer is **dry-run by default**: with no flags it prints every planned
+command via its `plan` gate and changes nothing. Pass `--apply` to execute.
+Every destructive step stays behind its own explicit flag, so nothing mutates
+until you opt in.
+
+```bash
+bash deploy/swarm/install-swarm.sh --help        # list flags + required env
+bash deploy/swarm/install-swarm.sh               # dry-run: prints the plan, changes nothing
+```
+
+### Auto-update (base-supervisor image-updater)
+
+`--validator-node` brings up `base validator agent` as an **auto-updatable**
+Docker Swarm service (`base-validator-agent`) plus a node-local base-supervisor
+whose image-updater digest-pins that service on every new
+`base-validator-runtime:latest` digest. That image-updater **is** the
+auto-update: the validator's `base` code rolls forward automatically, with no
+manual `docker service update`.
+
+`--install-supervisor` enables the `base-supervisor.service` systemd unit, the
+control-plane auto-update unit. Its image-updater runs on a 60s interval, and
+optional base self-update is wired only when `SUPERVISOR_SELF_UPDATE_MANIFEST_URL`
+is set (otherwise self-update is explicitly disabled, never left inert).
+
+### Quick start: validator node (dry-run first, then `--apply`)
+
+Set the required environment, run a dry-run to review the plan, then re-run with
+`--apply` (adding `--install-supervisor` to enable the node-local auto-update
+unit).
+
+Required environment for `--validator-node`:
+
+- `VALIDATOR_MASTER_URL`: the MASTER coordination/gateway root (for example
+  `http://<master-host>:19080`). There is no default: a validator must never
+  point at its own advertise address, so an unset value fails fast.
+- `VALIDATOR_BROKER_TOKEN`: the validator's own broker token (mounted at
+  `/run/secrets/base_broker_token`).
+- the validator hotkey wallet, staged under `VALIDATOR_WALLET_PATH` (default
+  `/var/lib/base/wallets`), wallet name `VALIDATOR_WALLET_NAME`.
+
+`VALIDATOR_CAPABILITIES` selects the evaluation work this node performs:
+
+- `["cpu"]` (default): the base agent-challenge (Terminal-Bench) CPU
+  evaluation.
+- PRISM GPU evaluation is **delegated** to the miner-funded worker plane, so a
+  validator needs no GPU capability for PRISM; it only performs light
+  verification plus probabilistic replay audits. (`["gpu","cpu"]` remains
+  available for the legacy path where a validator itself runs PRISM GPU
+  re-execution at concurrency 1.)
+
+```bash
+export VALIDATOR_MASTER_URL="http://<master-host>:19080"
+export VALIDATOR_BROKER_TOKEN="<validator-broker-token>"
+export VALIDATOR_CAPABILITIES='["cpu"]'   # base agent-challenge; PRISM is delegated
+# stage the validator hotkey wallet under /var/lib/base/wallets first
+
+# 1) DRY-RUN (default): prints the planned docker swarm commands, changes nothing
+bash deploy/swarm/install-swarm.sh --validator-node
+
+# 2) APPLY: execute, and enable the node-local auto-update supervisor unit
+bash deploy/swarm/install-swarm.sh --validator-node --apply --install-supervisor
+```
+
+The dry-run renders the node-local supervisor config
+(`validator_agent_target_enabled: true`, watching
+`base-validator-runtime:latest`) and the per-validator `validator.yaml`, and
+prints the `docker service create base-validator-agent ...` it would run. Review
+that plan before you pass `--apply`.
+
 ## Secret Rule
 
 The submitter needs exactly one secret: the validator hotkey. Never place coldkey
@@ -93,9 +195,12 @@ dependency.
 
 ### What are the minimum requirements?
 
-A submit-only node needs very little: a Python runtime, network access to the
-master endpoint and the chain, and the validator hotkey file. A node that also
-acts as the Swarm manager should have at least 2 vCPUs and 8 GB RAM.
+See [Compute Requirements](#compute-requirements) above for the authoritative
+sizing per validator profile. In short: a submit-only node needs very little (a
+Python runtime, network access to the master endpoint and the chain, and the
+validator hotkey file) and fits in 2 vCPU / 4 GB RAM. A validator that runs the
+base agent-challenge evaluation needs 8 vCPU and 32 GB RAM; PRISM adds no compute
+because its GPU evaluation is delegated to the miner-funded worker plane.
 
 ### What if the requirements are too high?