swarmctl: add CLI reference docs, same pattern as hivectl

Adds swarmctl markdown-docs (a hidden Verb, same clap-markdown +
hide=true shape as hivectl markdown-docs) and generates
docs/tools/swarmctl-cli.md from it. Wires a swarmctl-docs freshness
check into nix/checks.nix, same shape as hivectl-docs, diffing against
packages.swarmctl.

One real gotcha: PathArgs::resolve() reads required
SWARMCTL_AUTHELIA_* deployment env vars and errors if unset -
swarmctl markdown-docs must not go through that path (it needs none of
those vars, and the docs build runs it outside any real deployment).
Restructured main() so resolve() only runs for the User arm, not
unconditionally before the match.

Also links the new doc from docs/tools/README.md (new 'for the swarm
operator' section), CLAUDE.md's swarmctl bullet, and
docs/conventions.md's flake-check list.

Verified: cargo check/clippy -D warnings/test/fmt -p swarmctl all
clean; swarmctl markdown-docs diffs clean against the committed doc
(checked against both a plain cargo build and the actual nix build.
#swarmctl output); scripts/check-issue-refs.sh clean.

CLAUDE.md

@@ -155,7 +155,10 @@ hand-maintained per-file tree drifts out of sync with the code.
   rejected. Does not link `swarm-controller`, mirroring `hivectl` ÷
   `hive-c0re`. ⚠️ Its user store is **two files, one authoritative**:
   `users.json` is canonical, authelia's `users.yml` is a *rendered
-  artifact* that is written and never read back.
+  artifact* that is written and never read back. Full, always-current
+  verb reference (CI-enforced against the clap tree, same pattern as
+  `hivectl`'s — see `docs/conventions.md`):
+  [`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
 
 ### External dependencies with no directory here
 

Cargo.lock

@@ -4438,6 +4438,7 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "clap",
+ "clap-markdown",
  "serde",
  "serde_json",
 ]

docs/conventions.md

@@ -506,6 +506,11 @@ check derivations they don't:
   flake check catches the drift, and `ci-log` often can't show you
   why (it 500s on a fast failure), so you're left guessing "builder
   flake" when it's a stale doc.
+- **`swarmctl-docs`** is the same check for `swarmctl` /
+  `docs/tools/swarmctl-cli.md`:
+  ```sh
+  nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/tools/swarmctl-cli.md
+  ```
 - there's also a flake `cargo-test` check and NixOS module
   evaluation in the set.
 

docs/tools/README.md

@@ -15,6 +15,15 @@ debug agent behavior.
 - **[hivectl-cli](hivectl-cli.md)** — the exhaustive, auto-generated
   flag-by-flag reference, kept in lockstep with the binary by CI.
 
+## For the swarm operator
+
+- **[swarmctl-cli](swarmctl-cli.md)** — the exhaustive, auto-generated
+  flag-by-flag reference for `swarmctl`, kept in lockstep with the
+  binary by CI the same way `hivectl-cli.md` is. `swarmctl` itself
+  runs as root on the swarm-controller host, not through `hivectl` —
+  see `swarmctl/README.md` for why. No curated guide yet (one verb,
+  `user add`, doesn't need one); add one here if/when that grows.
+
 ## What your agents can do
 
 - **[bash](bash.md)** — background shell execution (`mcp__bash__*`),

docs/tools/swarmctl-cli.md

@@ -0,0 +1,66 @@
+# Command-Line Help for `swarmctl`
+
+This document contains the help content for the `swarmctl` command-line program.
+
+**Command Overview:**
+
+* [`swarmctl`↴](#swarmctl)
+* [`swarmctl user`↴](#swarmctl-user)
+* [`swarmctl user add`↴](#swarmctl-user-add)
+
+## `swarmctl`
+
+swarm-level operator CLI
+
+**Usage:** `swarmctl [OPTIONS] <COMMAND>`
+
+###### **Subcommands:**
+
+* `user` — Manage subjects in the swarm's SSO provider
+
+###### **Options:**
+
+* `--authelia-bin <PATH>` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH`
+* `--users-file <PATH>` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root
+* `--machine <NAME>` — Machine name of the authelia container, for `systemctl -M`
+* `--unit <UNIT>` — authelia's systemd unit inside that container
+* `--store <PATH>` — Canonical user store
+
+
+
+## `swarmctl user`
+
+Manage subjects in the swarm's SSO provider
+
+**Usage:** `swarmctl user <COMMAND>`
+
+###### **Subcommands:**
+
+* `add` — Add a user, generating a password for them
+
+
+
+## `swarmctl user add`
+
+Add a user, generating a password for them
+
+**Usage:** `swarmctl user add [OPTIONS] <USERNAME>`
+
+###### **Arguments:**
+
+* `<USERNAME>` — Login name. Conservative ASCII only — it is a YAML map key and reaches access-control rules and logs
+
+###### **Options:**
+
+* `--display-name <TEXT>` — Name shown in the SSO UI. Defaults to the username
+* `--email <ADDRESS>`
+* `--group <GROUP>` — Repeatable
+
+
+
+<hr/>
+
+<small><i>
+    This document was generated automatically by
+    <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
+</i></small>

nix/checks.nix

@@ -138,4 +138,20 @@ in
     fi
     touch "$out"
   '';
+
+  # `swarmctl` CLI reference freshness check — same shape as
+  # `hivectl-docs` above, `swarmctl markdown-docs` (clap-markdown over
+  # its own command tree) instead. Reuses `packages.<system>.swarmctl`
+  # (already built as its own package, out of `daemonBins` — see
+  # nix/packages/default.nix's comment on it).
+  swarmctl-docs = pkgs.runCommand "swarmctl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
+    ${self.packages.${system}.swarmctl}/bin/swarmctl markdown-docs > generated.md
+    if ! diff -u ${../docs/tools/swarmctl-cli.md} generated.md; then
+      echo "" >&2
+      echo "ERROR: docs/tools/swarmctl-cli.md is out of date — regenerate it:" >&2
+      echo "  nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/tools/swarmctl-cli.md" >&2
+      exit 1
+    fi
+    touch "$out"
+  '';
 }

swarmctl/Cargo.toml

@@ -11,6 +11,7 @@ path = "src/main.rs"
 [dependencies]
 anyhow.workspace = true
 clap.workspace = true
+clap-markdown = "0.1"
 serde.workspace = true
 serde_json.workspace = true
 

swarmctl/src/main.rs

@@ -132,6 +132,17 @@ enum Verb {
         #[command(subcommand)]
         command: UserVerb,
     },
+    /// Emit the full CLI reference as `CommonMark` to stdout.
+    ///
+    /// Hidden tooling command used by the docs build to keep the published
+    /// `swarmctl` reference in lockstep with the code — same pattern as
+    /// `hivectl markdown-docs` (`hivectl/src/main.rs`). Deliberately
+    /// dispatched *before* `PathArgs::resolve()` in `main` below: this
+    /// verb needs none of the `SWARMCTL_AUTHELIA_*` deployment env vars,
+    /// and requiring them here would make `swarmctl markdown-docs` fail
+    /// outside a real deployment — exactly where the docs build runs it.
+    #[command(hide = true)]
+    MarkdownDocs,
 }
 
 #[derive(Subcommand)]
@@ -157,11 +168,17 @@ struct AddArgs {
 
 fn main() -> Result<()> {
     let Cli { paths, command } = Cli::parse();
-    let paths = paths.resolve()?;
     match command {
+        // Resolved lazily, inside the one arm that actually touches the
+        // deployment env vars — see the `MarkdownDocs` doc comment above
+        // for why an unconditional resolve up front would be wrong.
         Verb::User {
             command: UserVerb::Add(args),
-        } => user_add(&paths, args),
+        } => user_add(&paths.resolve()?, args),
+        Verb::MarkdownDocs => {
+            print!("{}", clap_markdown::help_markdown::<Cli>());
+            Ok(())
+        }
     }
 }