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

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`