diff --git a/docs/tools/hivectl-cli.md b/docs/tools/hivectl-cli.md
index 62e230f4..19dd5673 100644
--- a/docs/tools/hivectl-cli.md
+++ b/docs/tools/hivectl-cli.md
@@ -21,6 +21,8 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl agents restart`↴](#hivectl-agents-restart)
 * [`hivectl agents restart-all`↴](#hivectl-agents-restart-all)
 * [`hivectl choom`↴](#hivectl-choom)
+* [`hivectl stop`↴](#hivectl-stop)
+* [`hivectl start`↴](#hivectl-start)
 
 ## `hivectl`
 
@@ -35,6 +37,8 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
 * `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)
 * `choom` — Open an interactive Claude session inside an agent container
+* `stop` — Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **everything** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
+* `start` — Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). Requires the hive-c0re daemon
 
 
 
@@ -297,6 +301,49 @@ Pass `--fresh` to start a new Claude session instead of continuing the most rece
 
 
 
+## `hivectl stop`
+
+Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **everything** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
+
+**Usage:** `hivectl stop [OPTIONS]`
+
+###### **Options:**
+
+* `--agents` — All sub-agent containers
+* `--agent <NAME>` — A specific sub-agent by name. Repeatable: `--agent a --agent b`
+* `--ci` — The CI runner container (`hive-ci`)
+* `--forge` — The forge container (`hive-forge`)
+* `--gateway` — The gateway container (`hive-gateway`)
+* `--matrix` — The matrix container (`hive-matrix`)
+* `--graceful` — Gracefully quiesce each agent (finish the current turn, drain the inbox) before stopping, instead of a hard stop.
+
+   NOTE: not yet effective — the per-agent quiesce is still being implemented (see the graceful-agent-stop tracker), so today this falls through to a hard stop. The flag is accepted now so the wire/CLI shape is stable when the quiesce lands.
+* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
+
+  Default value: `/run/hyperhive/host.sock`
+
+
+
+## `hivectl start`
+
+Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). Requires the hive-c0re daemon
+
+**Usage:** `hivectl start [OPTIONS]`
+
+###### **Options:**
+
+* `--agents` — All sub-agent containers
+* `--agent <NAME>` — A specific sub-agent by name. Repeatable: `--agent a --agent b`
+* `--ci` — The CI runner container (`hive-ci`)
+* `--forge` — The forge container (`hive-forge`)
+* `--gateway` — The gateway container (`hive-gateway`)
+* `--matrix` — The matrix container (`hive-matrix`)
+* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
+
+  Default value: `/run/hyperhive/host.sock`
+
+
+
 <hr/>
 
 <small><i>