diff --git a/README.md b/README.md
index 07f4566..bd33c9b 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,14 @@ export HOOKDECK_EG_API_KEY=...        # provisions connections
 export HOOKDECK_EG_WEBHOOK_SECRET=... # verifies deliveries
 ```
 
+CLI mode is the default, and it needs the [Hookdeck CLI](https://hookdeck.com/docs/cli) — a separate binary, not bundled with this plugin and not installed by pip:
+
+```bash
+brew install hookdeck/hookdeck/hookdeck   # or: npm install -g hookdeck-cli
+```
+
+You do not need to run `hookdeck login`. The gateway authenticates a CLI session of its own from `HOOKDECK_EG_API_KEY` and keeps it in `~/.hermes/hookdeck/`, so it never touches a session you use for other work — and cannot end up forwarding from a different project than the one it provisions. [Push mode](docs/operations.md) needs no CLI at all.
+
 Then create a route and check the setup:
 
 ```bash
@@ -47,6 +55,8 @@ hermes hookdeck setup my-route
 hermes hookdeck doctor
 ```
 
+`doctor` is the check that everything above landed: it reports a missing or too-old CLI, a secret that is not set, and a CLI pointed at the wrong project.
+
 A [free Hookdeck account](https://dashboard.hookdeck.com/signup) is enough for development and small production workloads.
 
 ## How it works
diff --git a/docs/operations.md b/docs/operations.md
index a358274..8fe1a23 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -10,6 +10,18 @@ The default. The Hookdeck CLI holds an outbound connection and forwards events
 to a loopback listener, so a laptop or a homelab box behind NAT works without
 ngrok or a VPS.
 
+The CLI is a separate binary — `brew install hookdeck/hookdeck/hookdeck`, or
+`npm install -g hookdeck-cli`. It is not bundled with this plugin and pip does
+not install it, so a gateway that has everything else right still refuses to
+start in `cli` mode without it:
+
+```
+✗ Hookdeck CLI 'hookdeck' not found — install it, set
+  platforms.hookdeck.extra.cli_binary, or switch to mode: push
+```
+
+`hermes hookdeck doctor` reports the same thing before you get that far.
+
 **A CLI destination is not a durable buffer.** With no listener attached,
 events become `CLI_DISCONNECTED` ignored events and the request is discarded —
 not queued, not retried. An *abnormal* disconnect gets a short server-side