diff --git a/hive-c0re/README.md b/hive-c0re/README.md
new file mode 100644
index 00000000..4b6e6e7d
--- /dev/null
+++ b/hive-c0re/README.md
@@ -0,0 +1,49 @@
+# hive-c0re
+
+The unprivileged host daemon (runs as `hive-core`). Owns the sqlite
+broker, the approval/question/schedule queues, the generic job-DAG
+queue, container lifecycle, gateway/forge/matrix provisioning,
+per-container stats, and the axum operator dashboard. Largest crate in
+the workspace — bin-only, no separate lib.
+
+## When to use it
+
+Host-level, cross-container orchestration: spawning/rebuilding/
+destroying agent containers, the approval flow, dashboard-visible
+state, provisioning per-agent forge/matrix/gateway accounts. Agent-side
+behavior (turn loop, MCP tools) lives in `hive-agent`/`hive-agent-mcp`
+instead — this daemon only talks to agents over the socket wire types
+in `hive-sh4re`.
+
+## Shape
+
+Cohesive clusters live in directory submodules, each re-exported at
+the crate root (`crate::broker::…` keeps resolving regardless of which
+subdirectory a module actually lives in). One line each — read the
+module's own `//!` doc-comment for real detail, don't expect this file
+to track it:
+
+- **`dashboard/`** — the operator dashboard (containers, approvals,
+  schedules, questions, logs, topology).
+- **`job_queue/`** — the job-DAG queue + desired-state reconciliation
+  (`docs/coordinator.md`).
+- **`lifecycle/`** — `nixos-container` lifecycle + per-agent config
+  flake generation.
+- **`stores/`** — sqlite-backed stores (broker, queues, audit, power).
+- **`workers/`** — background sweeps (crash watch, scheduled prompts,
+  auto-update, knowledge sync).
+- **`agent_config/`** — per-agent registries (tool groups,
+  capabilities, resource limits, topology).
+- **`stats/`** — dashboard metrics aggregation + OTEL export.
+- **`socket_server/`** — the unix-socket request server shared by
+  per-agent + manager sockets.
+- **`forge/`** — optional Forgejo wiring (`docs/forge.md`).
+- **`coordinator.rs`** — top-level wiring for `serve`.
+- **`meta.rs`**, **`migrate.rs`** — the meta flake + schema/state
+  migrations.
+- **`matrix.rs`**, **`gateway_nginx.rs`**, **`webhook_secret.rs`**,
+  **`priv_client.rs`** — matrix provisioning, gateway vhosts, webhook
+  secrets, and the `hive-priv` client respectively.
+
+See the top-level `CLAUDE.md`/`docs/` index for the full reading-path
+map.
diff --git a/hive-forge/README.md b/hive-forge/README.md
new file mode 100644
index 00000000..fbcb32ce
--- /dev/null
+++ b/hive-forge/README.md
@@ -0,0 +1,30 @@
+# hive-forge
+
+Typed CLI wrapper around the in-cluster Forgejo's REST API — issues,
+PRs, comments, labels, reviews, CI status, attachments, triage.
+Replaces the old bash-script wrapper so agents and operators get
+consistent error handling, exit codes, and JSON shapes. This is the
+**only supported path** to the forge from inside an agent container;
+never `curl` it directly.
+
+Reads credentials from the environment (`HIVE_FORGE_URL`,
+`HIVE_FORGE_REPO`, `HYPERHIVE_STATE_DIR`); `-f/--forge <label>`
+retargets a dashboard-provisioned external forge account instead.
+
+## When to use it
+
+Reach for this crate when adding or changing a forge verb — it's the
+single place issue/PR/comment/CI logic lives for every agent and
+`hivectl`. Adding a *tool* an agent's claude session calls is
+`hive-agent-mcp` wrapping a shellout to this binary, not new logic
+here.
+
+## Shape
+
+- **`verbs/`** — one module per subcommand (clap `Args` + `run`).
+- **`client.rs`** — the Forgejo client wrapper + token loading.
+- **`notify.rs`** — the read-before-comment guard, backed by forge's
+  own notification read-state (no local mirror to drift).
+- **`body.rs`** — shared `--body`/`--body-file`/stdin resolution.
+
+Full verb reference: `docs/tools/forge.md`.
diff --git a/hivectl/README.md b/hivectl/README.md
new file mode 100644
index 00000000..afbbde0e
--- /dev/null
+++ b/hivectl/README.md
@@ -0,0 +1,35 @@
+# hivectl
+
+The operator-facing host CLI. A thin client for the `hive-c0re`
+daemon — speaks the host admin socket protocol (`hive-host-sock`) and
+does not link the daemon crate. Container lifecycle, the approval
+queue, and provisioning verbs all forward to the daemon and need it
+running; a few (`wg`/`peer-config`, `choom`) work off local host state
+instead.
+
+## When to use it
+
+Reach for this crate when adding an operator-run host command — agents
+talk to the daemon over their own MCP tool surface
+(`hive-agent-mcp`), not this binary. `hivectl` is what a human operator
+(or a host-side script) runs.
+
+## Shape
+
+One module per subcommand family; `main.rs` is just the clap parse +
+dispatch:
+
+- **`agents.rs`** — container lifecycle (spawn/kill/rebuild/restart/…).
+- **`approvals.rs`** — the config/init-config/meta-input approval queue.
+- **`dag_progress.rs`** — rebuild-queue progress rendering.
+- **`power.rs`** — restart/start/stop at the container level.
+- **`choom.rs`** — drop into an interactive claude session in a
+  container.
+- **`forge.rs`**, **`matrix.rs`**, **`github.rs`**, **`gateway.rs`** —
+  per-integration account/token provisioning.
+- **`wg.rs`** — WireGuard mesh helpers.
+- **`subvol.rs`** — btrfs state-subvolume ops.
+- **`quota.rs`**, **`util.rs`**, **`completions.rs`**, **`open.rs`** —
+  shared helpers, shell completions, browser-open.
+
+Full verb reference: `docs/tools/hivectl.md`.