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.

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(())
+        }
     }
 }