swarmctl: interactive setup walks the first-run ceremony

swarmctl setup with no subcommand checks the setup status first, then takes the open steps one at a time: prompts for input, shows a running action as one live line, prints the store keys, root token and new password under a warning until the operator confirms, and names the deploy option for a step this host cannot do. It calls the code of bao init, bao grant-bootstrap, user add, forge make-admin, agent create, agent permissions set and agent set-state. Refuses without root or a terminal.

docs/2-handbook/swarm/swarmctl-cli.md

@@ -55,7 +55,7 @@ swarm-level operator CLI
 * `schedule` — Manage scheduled prompts
 * `user` — Manage subjects in the swarm's SSO provider
 * `forge` — Manage human accounts on the swarm's forge
-* `setup` — Show where the first-run setup ceremony stands
+* `setup` — Walk through the first-run setup, interactively
 * `bao` — Initialise the swarm's secret store and bootstrap its granter
 * `login` — Log in to the swarm named by `--swarm` as your own SSO account
 * `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
@@ -66,7 +66,7 @@ swarm-level operator CLI
 * `--users-file <PATH>` — Host-side path of authelia's users database — that is, the path inside the container, prefixed with the container's root.
 
    This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
-* `--swarm <URL>` — The swarm's domain, as `https://<domain>` or the bare domain. Given, the `agent`, `schedule` and `forge` verbs, and the agent checks of `setup status`, go through its gateway as the account `swarmctl login` logged in, instead of over the controller's socket. Falls back to `SWARMCTL_SWARM`; `login` then falls back to `SWARMCTL_LOGIN_DEFAULT_SWARM`, which the swarm-controller nix module sets to its host's own swarm
+* `--swarm <URL>` — The swarm's domain, as `https://<domain>` or the bare domain. Given, the `agent`, `schedule` and `forge` verbs, and the agent checks and steps of `setup`, go through its gateway as the account `swarmctl login` logged in, instead of over the controller's socket. Falls back to `SWARMCTL_SWARM`; `login` then falls back to `SWARMCTL_LOGIN_DEFAULT_SWARM`, which the swarm-controller nix module sets to its host's own swarm
 * `--ca-file <PATH>` — A PEM CA certificate to trust beside the system roots, for a swarm whose gateway serves a certificate from the swarm's own CA. Falls back to `SWARMCTL_CA_FILE`
 
 
@@ -647,14 +647,25 @@ The forge creates a human's account on their first SSO login, and this fails unt
 
 ## `swarmctl setup`
 
-Show where the first-run setup ceremony stands
+Walk through the first-run setup, interactively.
 
-**Usage:** `swarmctl setup <COMMAND>`
+Run it as root, in a terminal. It checks `docs/1-getting-started/setup.md` first, so a rerun continues at the first open step, then takes the open steps one at a time. It prompts for what a step needs, shows a running action as one live line, and prints anything to record in colour under a ⚠️ warning, such as the secret store's keys and root token. It prints those once and stores none of them. A step that needs a service this host doesn't run names the deploy option to enable and the host to run `swarmctl setup` on. A step without a verb yet prints its command and waits until you confirm you ran it.
+
+For scripts, use `setup status` and the individual verbs.
+
+**Usage:** `swarmctl setup [OPTIONS]
+       setup <COMMAND>`
 
 ###### **Subcommands:**
 
 * `status` — Print each step of the first-run setup, in order, as `done`, `not done` or `unknown`, and what to do next
 
+###### **Options:**
+
+* `--controller-socket <PATH>` — swarm-controller's unix socket.
+
+   Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
+
 
 
 ## `swarmctl setup status`