docs(tools): add hivectl.md — operator host CLI reference

hivectl has verbs scattered across CLAUDE.md and domain docs (gateway.md
has the gateway subcommands, matrix.md has a brief mention) but no
single cheatsheet. Add docs/tools/hivectl.md covering all subcommands:

- forge create-user: provision/refresh agent or human forge accounts
- matrix create-user / sync-admin / promote-user / reset-password
- gateway create-user / delete-user / list-users (htpasswd management)
- agents restart / restart-all (container lifecycle via admin socket)
- choom <name> [--fresh]: interactive claude session in agent container

Also add a reading-path entry to CLAUDE.md pointing at the new file.

CLAUDE.md

@@ -423,6 +423,9 @@ read them à la carte.
 - **"What verbs does `hive-forge` support? How do I post a comment,
   upload an attachment, manage subscriptions?"** →
   [`docs/tools/forge.md`](docs/tools/forge.md).
+- **"What does `hivectl` do? How do I provision a forge/matrix account,
+  manage gateway users, restart containers, or drop into an agent shell?"** →
+  [`docs/tools/hivectl.md`](docs/tools/hivectl.md).
 - **"How does the matrix-tuwunel container work? What about
   fluffychat-web and per-agent matrix accounts?"** →
   [`docs/matrix.md`](docs/matrix.md).

docs/tools/hivectl.md

@@ -0,0 +1,109 @@
+# hivectl
+
+`hivectl` is the operator-facing host CLI for hyperhive. It lives on the
+host (not inside any container) and requires root for most operations.
+Available via the `hive-c0re` package in the host NixOS config.
+
+Unlike the `hive-c0re` daemon subcommands (which go through the broker),
+`hivectl` covers direct host-side administration: manual provisioning of
+forge + matrix accounts, gateway htpasswd management, container
+lifecycle shortcuts, and interactive agent shell access.
+
+## Forge
+
+Manual entry to the same idempotent provisioning flow `hive-c0re` runs
+at boot. Useful for recovery, ad-hoc re-provisioning, or fixing a single
+agent without bouncing the daemon.
+
+```bash
+hivectl forge create-user iris          # provision (or refresh) forge account for agent `iris`
+hivectl forge create-user mara          # create forge account for a human user; prints token to stdout
+hivectl forge create-user mara --password hunter2  # set a web-login password
+hivectl forge create-user mara --password-stdin    # read password from stdin (safer for scripting)
+```
+
+- For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
+  token is persisted to `<state>/forge-token`. Re-running refreshes the
+  token (idempotent — scope always matches current `TOKEN_SCOPES`).
+- For **non-agents** (humans): creates the account and prints the token to
+  stdout; no state dir is created. Re-running after account already exists
+  re-mints the token and prints it again — safe for password resets.
+- Without `--password` / `--password-stdin` a random throwaway password
+  is used (fine for agents — they auth by token).
+
+## Matrix
+
+Manual entry to the same idempotent matrix provisioning flow
+`hive-c0re` runs at boot. Requires the `hive-matrix` container to be
+running (`services.hyperhive.matrix.enable = true`).
+
+```bash
+hivectl matrix create-user iris         # provision (or re-provision) matrix account for agent `iris`
+hivectl matrix create-user mara         # create matrix account for a human; prints access_token to stdout
+hivectl matrix create-user mara --password hunter2  # set a client-login password
+hivectl matrix sync-admin               # provision / refresh the hive internal admin account
+hivectl matrix promote-user mara        # promote an existing matrix user to homeserver admin
+hivectl matrix reset-password iris      # generate and set a new random password for `iris`; prints it
+```
+
+- `create-user`: for agents, persists the `access_token` to
+  `<state>/matrix-token`. Skips registration when the file already
+  exists — delete it first to force re-registration.
+- `sync-admin`: ensures the hive's internal admin matrix user exists
+  (used by `hive-c0re` for admin-room commands). Token persisted to the
+  admin token path. Safe to run again — idempotent.
+- `promote-user`: promotes an already-registered user to homeserver
+  admin via the matrix admin API. Requires `sync-admin` to have run
+  first (needs a valid admin token).
+- `reset-password`: calls the matrix admin API to set a new random
+  password and prints it to stdout. Useful if an agent or human lost
+  credentials.
+
+## Gateway
+
+Manage users in the gateway's HTTP Basic auth htpasswd file
+(`services.hyperhive.gateway.auth`). All commands default to
+`/var/lib/hyperhive/gateway/gateway.htpasswd`; pass `--file` to target
+a different path.
+
+```bash
+hivectl gateway create-user alice --password-stdin  # add (or update) user; read password from stdin
+hivectl gateway create-user bob --password hunter2  # add user inline (visible in shell history)
+hivectl gateway delete-user bob                     # remove user
+hivectl gateway list-users                          # list all usernames, one per line
+```
+
+Passwords are hashed with BCrypt (cost 12). The file is created if it
+does not exist. Re-running `create-user` with the same username updates
+the password hash in place.
+
+## Agents
+
+Container lifecycle shortcuts that go through the host admin socket.
+Requires the `hive-c0re` daemon to be running.
+
+```bash
+hivectl agents restart iris        # stop + start the `iris` container (no rebuild)
+hivectl agents restart-all         # stop + start every managed agent container in sequence
+```
+
+`restart` is the manual equivalent of the MCP `restart` tool — useful
+when you need to kick a container from the host without going through
+the agent hierarchy. Failures on `restart-all` are collected and
+reported at the end rather than aborting mid-run.
+
+## Choom
+
+Drop into an interactive Claude session inside an agent container.
+Replaces the current process with `machinectl shell h-<name>` running
+`claude --continue`. Requires root (same as all `machinectl shell`
+operations).
+
+```bash
+hivectl choom iris                # join iris's ongoing Claude session (--continue)
+hivectl choom iris --fresh        # start a new Claude session instead
+```
+
+Without `--fresh`, `--continue` is passed so the operator joins the
+agent's live context window. With `--fresh` a clean session starts.
+The container must be running.