treefmt: a generated CLI doc is the generator's, not prettier's

docs/tools/swarmctl-cli.md is rendered by `swarmctl markdown-docs`, and
nix/checks.nix's swarmctl-docs-fresh check diffs the committed copy
against fresh binary output. Enabling prettier on markdown rewrote its
list bullets and footer indentation, which no regeneration can settle:
formatting it fails the freshness check, not formatting it fails
treefmt. .prettierignore already carried hivectl-cli.md for exactly
this reason; swarmctl's doc was added later and the entry was not.

Restore the file to its generated bytes, list it alongside hivectl's,
and state the invariant where the next CLI doc gets added.

.prettierignore

@@ -1,7 +1,11 @@
-# Auto-generated by `hivectl markdown-docs` — do not format.
+# Generated by `<tool> markdown-docs` — do not format. The matching
-# The hivectl-docs CI check diffs this against fresh binary output,
+# *-docs-fresh check in nix/checks.nix diffs each against fresh binary
-# so reformatting it would break that check.
+# output, so any reformatting fails that check permanently: the
+# generator, not the formatter, owns these files' layout. Every CLI
+# reference doc belongs here — adding one and forgetting this line is
+# what made swarmctl's fail.
 docs/tools/hivectl-cli.md
+docs/tools/swarmctl-cli.md
 
 # Files with multi-line list-item continuations that prettier strips to col 0.
 # prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item

docs/tools/swarmctl-cli.md

@@ -4,12 +4,12 @@ This document contains the help content for the `swarmctl` command-line program.
 
 **Command Overview:**
 
-- [`swarmctl`↴](#swarmctl)
+* [`swarmctl`↴](#swarmctl)
-- [`swarmctl user`↴](#swarmctl-user)
+* [`swarmctl user`↴](#swarmctl-user)
-- [`swarmctl user add`↴](#swarmctl-user-add)
+* [`swarmctl user add`↴](#swarmctl-user-add)
-- [`swarmctl user update`↴](#swarmctl-user-update)
+* [`swarmctl user update`↴](#swarmctl-user-update)
-- [`swarmctl user list`↴](#swarmctl-user-list)
+* [`swarmctl user list`↴](#swarmctl-user-list)
-- [`swarmctl completions`↴](#swarmctl-completions)
+* [`swarmctl completions`↴](#swarmctl-completions)
 
 ## `swarmctl`
 
@@ -19,15 +19,17 @@ swarm-level operator CLI
 
 ###### **Subcommands:**
 
-- `user` — Manage subjects in the swarm's SSO provider
+* `user` — Manage subjects in the swarm's SSO provider
-- `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
+* `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
 
 ###### **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`
+* `--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.
+* `--users-file <PATH>` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root.
+
+   This is the only user store: it is read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
+
 
-  This is the only user store: it is read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
 
 ## `swarmctl user`
 
@@ -37,9 +39,11 @@ Manage subjects in the swarm's SSO provider
 
 ###### **Subcommands:**
 
-- `add` — Add a user, generating a password for them
+* `add` — Add a user, generating a password for them
-- `update` — Change an existing user's attributes
+* `update` — Change an existing user's attributes
-- `list` — List every user in authelia's users database
+* `list` — List every user in authelia's users database
+
+
 
 ## `swarmctl user add`
 
@@ -49,13 +53,15 @@ Add a user, generating a password for them
 
 ###### **Arguments:**
 
-- `<USERNAME>` — Login name. Conservative ASCII only — it is a YAML map key and reaches access-control rules and logs
+* `<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
+* `--display-name <TEXT>` — Name shown in the SSO UI. Defaults to the username
-- `--email <ADDRESS>`
+* `--email <ADDRESS>`
-- `--group <GROUP>` — Repeatable
+* `--group <GROUP>` — Repeatable
+
+
 
 ## `swarmctl user update`
 
@@ -67,14 +73,16 @@ Every flag is optional and they compose, so one call can set several things at o
 
 ###### **Arguments:**
 
-- `<USERNAME>` — Login name of an existing user
+* `<USERNAME>` — Login name of an existing user
 
 ###### **Options:**
 
-- `--display-name <TEXT>` — Name shown in the SSO UI
+* `--display-name <TEXT>` — Name shown in the SSO UI
-- `--email <ADDRESS>`
+* `--email <ADDRESS>`
-- `--add-group <GROUP>` — Repeatable. Adding a group the user is already in is not an error
+* `--add-group <GROUP>` — Repeatable. Adding a group the user is already in is not an error
-- `--remove-group <GROUP>` — Repeatable. Fails if the user is not in the group — a revocation that reports success without revoking is the failure nobody re-checks
+* `--remove-group <GROUP>` — Repeatable. Fails if the user is not in the group — a revocation that reports success without revoking is the failure nobody re-checks
+
+
 
 ## `swarmctl user list`
 
@@ -84,6 +92,8 @@ Read-only: it never writes the file. Shows every subject in it, including agent
 
 **Usage:** `swarmctl user list`
 
+
+
 ## `swarmctl completions`
 
 Generate a shell completion script for `swarmctl` and print it to stdout.
@@ -96,13 +106,16 @@ Dispatched before `PathArgs::resolve()` for the same reason as `markdown-docs`:
 
 ###### **Arguments:**
 
-- `<SHELL>` — Shell to emit completions for
+* `<SHELL>` — Shell to emit completions for
 
   Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`
 
+
+
+
 <hr/>
 
 <small><i>
-This document was generated automatically by
+    This document was generated automatically by
-<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
+    <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
 </i></small>

nix/checks.nix

@@ -209,6 +209,9 @@ in
   # committed copy drifted — so a verb / flag / help-string edit
   # that forgets to refresh the doc is caught in CI. Reuses the
   # already-built `packages.<system>.default` (no extra compile).
+  # A doc guarded this way must also be listed in `.prettierignore`:
+  # the generator owns its layout, and a formatter that rewrites it
+  # makes this check unsatisfiable rather than merely stale.
   # Regenerate locally with:
   #   nix build .#default
   #   ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md