swarmctl setup status shows where the setup ceremony stands

docs/1-getting-started/setup.md

@@ -8,6 +8,10 @@ required options, is [`nixos.md`](nixos.md).
 
 Every command runs as **root on the host**.
 
+Run `swarmctl setup status` at any point to see how far you have got. It lists
+the hand steps below, numbered 1 to 10 in the order the sections run them, marks
+each done, not done or unknown, and names the next one. It changes nothing.
+
 > **Not all-local?** Each step says which host it runs on. A split swarm
 > also has credentials you can't generate where they're read — each
 > host's mTLS identity at the secret store. Read [`2-handbook/swarm/credentials.md`](../2-handbook/swarm/credentials.md) first; it

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

@@ -35,6 +35,8 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl user list`↴](#swarmctl-user-list)
 * [`swarmctl forge`↴](#swarmctl-forge)
 * [`swarmctl forge make-admin`↴](#swarmctl-forge-make-admin)
+* [`swarmctl setup`↴](#swarmctl-setup)
+* [`swarmctl setup status`↴](#swarmctl-setup-status)
 * [`swarmctl login`↴](#swarmctl-login)
 * [`swarmctl completions`↴](#swarmctl-completions)
 
@@ -50,6 +52,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
 * `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
 
@@ -59,7 +62,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 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 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
 * `--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`
 
 
@@ -638,6 +641,36 @@ 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
+
+**Usage:** `swarmctl 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
+
+
+
+## `swarmctl setup status`
+
+Print each step of the first-run setup, in order, as `done`, `not done` or `unknown`, and what to do next.
+
+Read-only, and needs no token. The secret store's steps come from `bao status` and systemd, so they show only on the host running swarm-bao; the SSO account comes from authelia's users file, on its host; ruth and the other agents come from the swarm-controller. When a check can't run, its steps print `unknown` with the reason, and the rest still print. Steps 7 and 8, the browser login and the forge site admin, always print `unknown (not observable)`.
+
+Exits 0 when every step it can see has finished, and 1 otherwise, including when a check failed to run. Step 10, another agent, is optional and never changes the exit code. The steps are those of `docs/1-getting-started/setup.md`.
+
+**Usage:** `swarmctl setup status [OPTIONS]`
+
+###### **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 login`
 
 Log in to the swarm named by `--swarm` as your own SSO account.