docs: add missing readmes for hive-c0re, hive-forge, hivectl

hivectl/README.md

@@ -0,0 +1,65 @@
+# hivectl
+
+The operator-facing host CLI for hyperhive. A thin client for the
+`hive-c0re` daemon: it speaks the host admin socket protocol
+(`hive-host-sock`) and does **not** link the daemon crate.
+
+Container lifecycle + the approval queue (`agents <spawn|kill|rebuild|
+restart|…>`, `approvals <pending|approve|deny>`, `stop`/`start`) and
+provisioning (`forge`/`matrix`/`github`/`gateway`) all forward to the
+daemon, which owns the broker, the credentials, and the provisioning
+logic — a running daemon is required for those verbs. A few verbs work
+off local host state directly instead, so they don't need the socket:
+`wg`/`peer-config` read the mesh key + TLS CA, and `choom` execs into a
+container.
+
+## When to use it
+
+Reach for this crate when you're adding a new operator-run host
+command, not an agent-run one — agents talk to the daemon over their
+own per-agent MCP tool surface (`hive-agent-mcp`), not this binary.
+`hivectl` is what a human operator (or a script on the host) runs.
+
+## Shape
+
+One module per subcommand family; `main.rs` is just the clap parse +
+top-level dispatch match.
+
+- **`cli.rs`** — the clap `Cli`/`Cmd` derive tree every other module's
+  `Args` hangs off of.
+- **`client.rs`** — the host admin socket client (`request`), split out
+  so it lives with `hivectl` rather than in the daemon crate.
+- **`agents.rs`** — `agents <spawn|kill|destroy|rebuild|restart|list|
+  set-parent|…>` — container lifecycle.
+- **`approvals.rs`** — `approvals <pending|approve|deny>` — the config/
+  init-config/meta-input approval queue.
+- **`dag_progress.rs`** — rebuild-queue progress rendering: everything
+  that polls the daemon's DAG queue (`HostRequest::QueueDag`) and
+  renders per-DAG / per-node progress (spinner or plain), split out
+  because `agents.rs` was already large.
+- **`power.rs`** — `restart`/`start`/`stop` at the container level.
+- **`choom.rs`** — `hivectl choom <agent>`: drop into an interactive
+  Claude session inside an agent container by exec-ing `machinectl
+  shell` running claude as the agent user, mirroring the harness's own
+  per-turn claude invocation.
+- **`forge.rs`**, **`matrix.rs`**, **`github.rs`**, **`gateway.rs`** —
+  per-agent account/token provisioning for each integration
+  (`forge create-user`, `matrix …`, `github set-token`, `gateway
+  create-user|delete-user|list-users`).
+- **`wg.rs`** — `wg`/`peer-config`: WireGuard mesh helpers — generate
+  this hive's key + the nix snippets to enable the mesh, add a peer,
+  print the block a peer pastes to federate with us, show the live
+  interface.
+- **`subvol.rs`** — `agents subvol`: btrfs state-subvolume ops (migrate
+  a plain-dir agent state root to a subvolume, snapshot create/delete/
+  send).
+- **`quota.rs`** — resource-quota reporting/enforcement helpers shared
+  across the above.
+- **`open.rs`** — `open <url>`: opens a hive URL (dashboard, agent UI)
+  in the operator's browser.
+- **`completions.rs`** — shell-completion generation
+  (`clap_complete`/`clap-markdown`).
+- **`util.rs`** — small shared helpers (formatting, table rendering)
+  used across subcommand modules.
+
+Full verb reference: `docs/tools/hivectl.md`.