hive-forge: add markdown-docs generator and CI freshness check

.prettierignore

@@ -6,6 +6,7 @@
 # what made swarmctl's fail.
 docs/tools/hivectl-cli.md
 docs/tools/swarmctl-cli.md
+docs/tools/forge-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

Cargo.lock

@@ -1739,6 +1739,7 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "clap",
+ "clap-markdown",
  "forgejo-api",
  "libc",
  "reqwest",

docs/tools/README.md

@@ -31,6 +31,9 @@ debug agent behavior.
 - **[forge](forge.md)** — the `hive-forge` Forgejo CLI every agent has
   for issues, PRs, and comments. Not an MCP tool — a binary agents
   shell out to instead of ad-hoc curl.
+- **[forge-cli](forge-cli.md)** — the exhaustive, auto-generated
+  flag-by-flag reference for `hive-forge`, kept in lockstep with the
+  binary by CI the same way `hivectl-cli.md` is.
 - **[lifecycle](lifecycle.md)** — kill/start/restart/update for an
   agent's own direct children, plus the approval-gated config-change
   tools.

docs/tools/forge.md

@@ -4,6 +4,14 @@
 container (installed via `nix/agent-modules/forge.nix`, on `PATH` as a
 proper Rust binary). Use it instead of ad-hoc curl pipelines.
 
+This page is the curated guide. For the exhaustive flag-by-flag reference
+auto-generated from the binary's own command tree, see
+[`forge-cli.md`](forge-cli.md) — emitted by the hidden `hive-forge
+markdown-docs` subcommand and kept in lockstep with the code by the
+`hive-forge-docs` flake check (CI fails if the committed copy drifts).
+Regenerate with `nix build .#hive-forge && ./result/bin/hive-forge
+markdown-docs > docs/tools/forge-cli.md`.
+
 ## Credentials and repo defaults
 
 - Credentials: `$HYPERHIVE_STATE_DIR/forge-token`

hive-forge/Cargo.toml

@@ -11,6 +11,7 @@ path = "src/main.rs"
 [dependencies]
 anyhow = { workspace = true }
 clap = { workspace = true }
+clap-markdown = "0.1"
 # `sync` = blocking client (hive-forge is a blocking CLI). TLS backend comes
 # from feature unification on reqwest — which only works because forgejo-api
 # and this crate now resolve to the SAME reqwest version; cargo unifies

hive-forge/src/main.rs

@@ -195,6 +195,13 @@ enum Verb {
     /// remote URL.
     #[command(hide = true)]
     CredentialHelper(verbs::credential_helper::Args),
+    /// Emit the full CLI reference as Markdown, walking hive-forge's own
+    /// clap command tree.
+    ///
+    /// Hidden tooling command used by the docs build to keep the published
+    /// `hive-forge` reference in lockstep with the code.
+    #[command(hide = true)]
+    MarkdownDocs,
 }
 
 /// Wrapper over [`run`] that owns how a failure reaches the operator.
@@ -245,6 +252,13 @@ fn run() -> Result<()> {
     if let Verb::CredentialHelper(args) = verb {
         return verbs::credential_helper::run(args, cli.forge.as_deref());
     }
+    // Same reasoning as `credential-helper` above: no repo, no forge
+    // credentials — just a pure render of the clap tree the docs build
+    // pipes into `docs/tools/forge-cli.md`.
+    if let Verb::MarkdownDocs = verb {
+        print!("{}", clap_markdown::help_markdown::<Cli>());
+        return Ok(());
+    }
     let client = client::Client::from_env(cli.repo, cli.json, cli.forge)
         .context("initialize forge client")?;
     // Attach the resolved repo to every verb's error uniformly here,
@@ -330,7 +344,7 @@ fn dispatch(client: &client::Client, verb: Verb) -> Result<()> {
         Verb::CiLog(a) => verbs::ci_log::run(client, a),
         Verb::CiRerun(a) => verbs::ci_rerun::run(client, a),
         Verb::CiRuns(a) => verbs::ci_runs::run(client, a),
-        Verb::CredentialHelper(_) => {
+        Verb::CredentialHelper(_) | Verb::MarkdownDocs => {
             unreachable!("handled in `run` before client construction")
         }
     }

nix/checks.nix

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