diff --git a/Cargo.lock b/Cargo.lock
index 2fae8eac..128cacf4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -497,6 +497,15 @@ dependencies = [
  "clap_derive",
 ]
 
+[[package]]
+name = "clap-markdown"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2a2617956a06d4885b490697b5307ebb09fec10b088afc18c81762d848c2339"
+dependencies = [
+ "clap",
+]
+
 [[package]]
 name = "clap_builder"
 version = "4.6.0"
@@ -1266,6 +1275,7 @@ dependencies = [
  "base64",
  "bcrypt",
  "clap",
+ "clap-markdown",
  "hive-sh4re",
  "libc",
  "listenfd",
diff --git a/hive-c0re/Cargo.toml b/hive-c0re/Cargo.toml
index 83d70e24..867691a4 100644
--- a/hive-c0re/Cargo.toml
+++ b/hive-c0re/Cargo.toml
@@ -12,6 +12,7 @@ base64.workspace = true
 bcrypt.workspace = true
 reqwest.workspace = true
 clap.workspace = true
+clap-markdown = "0.1"
 hive-sh4re.workspace = true
 libc.workspace = true
 listenfd = "1"
diff --git a/hive-c0re/src/bin/hivectl.rs b/hive-c0re/src/bin/hivectl.rs
index 3cb9f157..d356b931 100644
--- a/hive-c0re/src/bin/hivectl.rs
+++ b/hive-c0re/src/bin/hivectl.rs
@@ -90,6 +90,15 @@ enum Cmd {
         #[arg(long)]
         fresh: bool,
     },
+    /// Emit the full CLI reference as `CommonMark` to stdout.
+    ///
+    /// Hidden tooling command (not part of day-to-day operator admin):
+    /// walks this binary's own clap command tree and renders every verb,
+    /// flag, and help string as markdown. Used by the docs build to keep
+    /// the published `hivectl` reference in lockstep with the code — no
+    /// hand-maintained command list to drift out of date.
+    #[command(hide = true)]
+    MarkdownDocs,
 }
 
 #[derive(Subcommand)]
@@ -330,6 +339,10 @@ async fn main() -> Result<()> {
             AgentsCmd::RestartAll { socket } => agents_restart_all(&socket).await,
         },
         Cmd::Choom { name, fresh } => choom(&name, fresh),
+        Cmd::MarkdownDocs => {
+            print!("{}", clap_markdown::help_markdown::<Cli>());
+            Ok(())
+        }
     }
 }