docs(#2352): regenerate hivectl-cli.md for the new agents/approvals verbs

docs/tools/hivectl-cli.md

@@ -23,6 +23,16 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl agents list`↴](#hivectl-agents-list)
 * [`hivectl agents restart`↴](#hivectl-agents-restart)
 * [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
+* [`hivectl agents spawn`↴](#hivectl-agents-spawn)
+* [`hivectl agents request-spawn`↴](#hivectl-agents-request-spawn)
+* [`hivectl agents kill`↴](#hivectl-agents-kill)
+* [`hivectl agents destroy`↴](#hivectl-agents-destroy)
+* [`hivectl agents rebuild`↴](#hivectl-agents-rebuild)
+* [`hivectl agents set-parent`↴](#hivectl-agents-set-parent)
+* [`hivectl approvals`↴](#hivectl-approvals)
+* [`hivectl approvals pending`↴](#hivectl-approvals-pending)
+* [`hivectl approvals approve`↴](#hivectl-approvals-approve)
+* [`hivectl approvals deny`↴](#hivectl-approvals-deny)
 * [`hivectl wg`↴](#hivectl-wg)
 * [`hivectl wg init`↴](#hivectl-wg-init)
 * [`hivectl wg peer`↴](#hivectl-wg-peer)
@@ -58,6 +68,7 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
 * `github` — GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `github-token` state file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (`hyperhive.github.enable`), so no per-agent config is needed
 * `gateway` — Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (`services.hyperhive.gateway.auth`). Credentials are stored as `BCrypt` hashes — no extra service or PAM required
 * `agents` — Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
+* `approvals` — Operator approval queue: list pending requests, approve / deny them. Requires the hive-c0re daemon to be running (connects to the host admin socket)
 * `wg` — WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`)
 * `peer-config` — Generate the federation peer-config block for THIS hive — the nix a peer operator pastes into their `services.hyperhive.swarm.peers` to trust + reach this hive. Emits `caCert` (+ a `cp` line for the cert) when this hive serves a self-signed CA, the WireGuard public key when the mesh key exists, and the `wireguard{Address,Endpoint}` you pass. The hive's own domain is filled in automatically from the running daemon (`services.hyperhive.domain`). Reads local state (the TLS CA cert, the wg key); never mutates. `wg init` calls this at the end, so a fresh mesh setup prints the hand-over block too
 * `choom` — Open an interactive Claude session inside an agent container
@@ -309,6 +320,12 @@ Agent container management. Requires the hive-c0re daemon to be running (connect
 * `list` — Show all managed agents with their status (running / needs-login / needs-update) and technical state (deployed sha, parent, pending reminders). The host roster overview; reuses the dashboard's per-agent aggregation. Requires the daemon running
 * `restart` — Stop and start a single agent container without rebuilding config. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config. Rides the job queue (serialized against in-flight rebuilds for the same agent); waits with live progress unless `--no-wait`
 * `restart-all` — Restart ALL managed agent containers via one restart DAG each — unrelated agents overlap, each serializes on its own lease. Waits for the whole set with live progress unless `--no-wait`
+* `spawn` — Spawn a new agent container directly (`h-<name>`). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use `request-spawn`
+* `request-spawn` — Queue a spawn request as an approval. The container is created on `hivectl approvals approve <id>` (or the dashboard APPR0VE button)
+* `kill` — Stop a managed container (graceful)
+* `destroy` — Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass `--purge` to also wipe the agent's state dirs (config + creds + notes). No undo
+* `rebuild` — Apply pending config to a managed container
+* `set-parent` — Move an agent in the topology tree. Set `--parent` to a new parent agent name, or pass `--root` to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents
 
 
 
@@ -352,6 +369,133 @@ Restart ALL managed agent containers via one restart DAG each — unrelated agen
 
 
 
+## `hivectl agents spawn`
+
+Spawn a new agent container directly (`h-<name>`). Bypasses the approval queue — operator-on-the-host only. For approval-gated spawns, use `request-spawn`
+
+**Usage:** `hivectl agents spawn <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name (e.g. `iris`)
+
+
+
+## `hivectl agents request-spawn`
+
+Queue a spawn request as an approval. The container is created on `hivectl approvals approve <id>` (or the dashboard APPR0VE button)
+
+**Usage:** `hivectl agents request-spawn <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name
+
+
+
+## `hivectl agents kill`
+
+Stop a managed container (graceful)
+
+**Usage:** `hivectl agents kill <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name
+
+
+
+## `hivectl agents destroy`
+
+Tear down a sub-agent container. The container is removed; persistent state (config repos + Claude credentials) is kept by default. Pass `--purge` to also wipe the agent's state dirs (config + creds + notes). No undo
+
+**Usage:** `hivectl agents destroy [OPTIONS] <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name
+
+###### **Options:**
+
+* `--purge`
+
+
+
+## `hivectl agents rebuild`
+
+Apply pending config to a managed container
+
+**Usage:** `hivectl agents rebuild <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name
+
+
+
+## `hivectl agents set-parent`
+
+Move an agent in the topology tree. Set `--parent` to a new parent agent name, or pass `--root` to promote the agent to root (no parent). Exactly one is required. Refuses cycles and unknown agents
+
+**Usage:** `hivectl agents set-parent [OPTIONS] <CHILD>`
+
+###### **Arguments:**
+
+* `<CHILD>` — Agent to move
+
+###### **Options:**
+
+* `--parent <PARENT>` — New parent agent name. Mutually exclusive with `--root`
+* `--root` — Promote `child` to root (no parent)
+
+
+
+## `hivectl approvals`
+
+Operator approval queue: list pending requests, approve / deny them. Requires the hive-c0re daemon to be running (connects to the host admin socket)
+
+**Usage:** `hivectl approvals <COMMAND>`
+
+###### **Subcommands:**
+
+* `pending` — List pending approval requests submitted by agents
+* `approve` — Approve a pending request by id; the action runs immediately
+* `deny` — Deny a pending request by id
+
+
+
+## `hivectl approvals pending`
+
+List pending approval requests submitted by agents
+
+**Usage:** `hivectl approvals pending`
+
+
+
+## `hivectl approvals approve`
+
+Approve a pending request by id; the action runs immediately
+
+**Usage:** `hivectl approvals approve <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — Approval id (from `hivectl approvals pending`)
+
+
+
+## `hivectl approvals deny`
+
+Deny a pending request by id
+
+**Usage:** `hivectl approvals deny <ID>`
+
+###### **Arguments:**
+
+* `<ID>` — Approval id
+
+
+
 ## `hivectl wg`
 
 WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`).