docs: trim readmes down, stop restating impl detail the module docs already own

hive-c0re/README.md

@@ -1,89 +1,49 @@
 # hive-c0re
 
-The unprivileged host daemon (runs as `hive-core`). This is the biggest
+The unprivileged host daemon (runs as `hive-core`). Owns the sqlite
-crate in the workspace — it owns the sqlite broker, the approval /
+broker, the approval/question/schedule queues, the generic job-DAG
-question / reminder / schedule queues, the generic job-DAG queue,
+queue, container lifecycle, gateway/forge/matrix provisioning,
-lifecycle (`nixos-container` shellouts + per-agent flake generation),
+per-container stats, and the axum operator dashboard. Largest crate in
-gateway/forge/matrix provisioning, per-container stats, and the axum
+the workspace — bin-only, no separate lib.
-operator dashboard.
-
-`hive-c0re` is **bin-only**: this binary owns the whole module tree
-directly (no separate lib crate). The operator CLI used to live here
-too, but moved out to the standalone `hivectl` crate, which talks to
-this daemon over the host admin socket instead of linking it.
 
 ## When to use it
 
-This is where host-level, cross-container orchestration logic lives:
+Host-level, cross-container orchestration: spawning/rebuilding/
-spawning/rebuilding/destroying agent containers, approving config
+destroying agent containers, the approval flow, dashboard-visible
-changes, reconciling desired vs. actual container state, provisioning
+state, provisioning per-agent forge/matrix/gateway accounts. Agent-side
-per-agent forge/matrix/gateway accounts, and serving the dashboard.
+behavior (turn loop, MCP tools) lives in `hive-agent`/`hive-agent-mcp`
-If you're changing what the operator sees on the dashboard, how a
+instead — this daemon only talks to agents over the socket wire types
-container gets spawned or torn down, or anything in the approval flow,
+in `hive-sh4re`.
-it's here. Agent-side behavior (the turn loop, MCP tools) lives in
-`hive-agent`/`hive-agent-mcp` instead — this daemon only talks to
-agents over the unix socket wire types in `hive-sh4re`.
 
 ## Shape
 
-Cohesive clusters live in directory submodules; each child is
+Cohesive clusters live in directory submodules, each re-exported at
-re-exported at the crate root so `crate::broker::…`-style paths keep
+the crate root (`crate::broker::…` keeps resolving regardless of which
-resolving unchanged regardless of which subdirectory a module actually
+subdirectory a module actually lives in). One line each — read the
-lives in.
+module's own `//!` doc-comment for real detail, don't expect this file
+to track it:
 
-- **`dashboard/`** — the axum operator dashboard: managed containers
+- **`dashboard/`** — the operator dashboard (containers, approvals,
-  (with deep-links to each container's own web UI), pending approvals
+  schedules, questions, logs, topology).
-  (unified diff vs. the applied repo + approve/deny), schedules,
+- **`job_queue/`** — the job-DAG queue + desired-state reconciliation
-  questions, journal/build-log viewers, topology, webhook ingest.
+  (`docs/coordinator.md`).
-- **`job_queue/`** — generic job-DAG queue + desired-state
+- **`lifecycle/`** — `nixos-container` lifecycle + per-agent config
-  reconciliation, the host-side wrapper over the domain-agnostic
+  flake generation.
-  `hive_jobq` scheduler. Jobs are nodes in per-request DAGs
+- **`stores/`** — sqlite-backed stores (broker, queues, audit, power).
-  (`templates.rs`); special cases (graceful-stop watcher, deferred-start
+- **`workers/`** — background sweeps (crash watch, scheduled prompts,
-  follow-up, meta-update cascade, topology reparents) collapse into DAG
+  auto-update, knowledge sync).
-  *shapes* over the shared node primitives (`model::NodeKind`). See
+- **`agent_config/`** — per-agent registries (tool groups,
-  `docs/coordinator.md`.
+  capabilities, resource limits, topology).
-- **`lifecycle/`** — `nixos-container` lifecycle (spawn/kill/destroy/
+- **`stats/`** — dashboard metrics aggregation + OTEL export.
-  rebuild/restart) + per-agent config flake generation.
+- **`socket_server/`** — the unix-socket request server shared by
-- **`stores/`** — sqlite-backed host-side stores: the broker
+  per-agent + manager sockets.
-  (`broker.rs`), approval / question / schedule queues, build logs,
+- **`forge/`** — optional Forgejo wiring (`docs/forge.md`).
-  audit trail, power intent, plus the shared connection open/migration
+- **`coordinator.rs`** — top-level wiring for `serve`.
-  helper (`db.rs`).
+- **`meta.rs`**, **`migrate.rs`** — the meta flake + schema/state
-- **`workers/`** — background tasks and periodic sweeps: crash/login
+  migrations.
-  watcher, scheduled-prompt delivery loop, boot-time auto-update
+- **`matrix.rs`**, **`gateway_nginx.rs`**, **`webhook_secret.rs`**,
-  reconcile, the agent-sockets.json writer loop, the MCP socket
+  **`priv_client.rs`** — matrix provisioning, gateway vhosts, webhook
-  listener reconcile loop, knowledge-repo sync.
+  secrets, and the `hive-priv` client respectively.
-- **`agent_config/`** — per-agent configuration registries (tool
-  groups, capabilities, resource limits, topology — all JSON under
-  `/var/lib/hyperhive/meta/`) plus the shared wire-protocol size
-  limits. Note the two similarly-named modules: `limits` caps inline
-  message-body sizes on the sockets, while `resource_limits` holds
-  per-agent CPU/memory caps for the container drop-in (`agentMemoryMax`
-  etc.).
-- **`stats/`** — metrics aggregation for the dashboard: hive-wide
-  turn-stats rollups, host-system probes/server warnings, live
-  per-container cgroup load, OTEL metric export.
-- **`socket_server/`** — the unix-socket request server, shared by the
-  per-agent sockets and the (pure-transport) manager socket. The socket
-  file's existence on disk authenticates the caller — connecting to
-  `<.../agents/foo/mcp.sock>` means you are `foo`. No privilege flag:
-  authority derives from the caller's identity (topology, capabilities,
-  tool-group membership), not a hardcoded name match.
-- **`forge/`** — optional Forgejo wiring: per-agent user + token
-  provisioning, config-repo mirroring, meta read-access grants, the CI
-  runner registration, PR auto-merge. No-op when `hive-forge` (the
-  container) isn't running. Full design: `docs/forge.md`.
-- **`coordinator.rs`** — top-level `Coordinator`/`HiveEnv`/`ServeConfig`
-  wiring that ties the above together for `serve`.
-- **`meta.rs`**, **`migrate.rs`** — the meta flake (agent config repos)
-  and schema/state migrations.
-- **`matrix.rs`**, **`gateway_nginx.rs`**, **`webhook_secret.rs`** —
-  matrix provisioning, gateway nginx vhost rendering, webhook secret
-  management.
-- **`priv_client.rs`** — client for the `hive-priv` privileged-helper
-  socket (the few root operations this unprivileged daemon delegates
-  out — see `docs/boundary.md`).
 
-`src/main.rs` is the `hive-c0re` binary entry point: `serve` (the
+See the top-level `CLAUDE.md`/`docs/` index for the full reading-path
-daemon) plus the periodic vacuum/sweep loops. See the top-level
+map.
-`CLAUDE.md`/`docs/` index for the full reading-path map — this README
-is just the module tour.

hive-forge/README.md

@@ -1,58 +1,30 @@
 # hive-forge
 
-Typed CLI wrapper around the in-cluster Forgejo's REST API. Replaces
+Typed CLI wrapper around the in-cluster Forgejo's REST API — issues,
-the prior bash script (`hive-forge-tools.nix`) so that agents and
+PRs, comments, labels, reviews, CI status, attachments, triage.
-operators get the same error handling, exit codes, and JSON shapes
+Replaces the old bash-script wrapper so agents and operators get
-regardless of how the bash mood was that day — this is the **only
+consistent error handling, exit codes, and JSON shapes. This is the
-supported path** to the forge from inside an agent container; never
+**only supported path** to the forge from inside an agent container;
-`curl` it directly.
+never `curl` it directly.
 
-Single binary, one verb subcommand per forge operation (issues, PRs,
+Reads credentials from the environment (`HIVE_FORGE_URL`,
-comments, labels, reviews, CI status, attachments, triage). Reads
+`HIVE_FORGE_REPO`, `HYPERHIVE_STATE_DIR`); `-f/--forge <label>`
-credentials from the environment: `HIVE_FORGE_URL` (base URL),
+retargets a dashboard-provisioned external forge account instead.
-`HIVE_FORGE_REPO` (default repo), `HYPERHIVE_STATE_DIR` (state dir —
-`forge-token` lives here). The global `-f/--forge <label>` flag
-retargets a dashboard-provisioned *external* forge account instead,
-reading `forge-<label>-token` + `forge-<label>.json` from the state
-dir rather than the internal-forge pair.
 
 ## When to use it
 
-Reach for this crate when you're adding a new forge verb or changing
+Reach for this crate when adding or changing a forge verb — it's the
-how an existing one behaves — it's the single place issue/PR/comment/
+single place issue/PR/comment/CI logic lives for every agent and
-CI logic lives for every agent and `hivectl`. If you're instead adding
+`hivectl`. Adding a *tool* an agent's claude session calls is
-a *tool* an agent's claude session calls, that's `hive-agent-mcp`
+`hive-agent-mcp` wrapping a shellout to this binary, not new logic
-wrapping a shellout to this binary, not new logic here.
+here.
 
 ## Shape
 
-- **`verbs/`** — one module per subcommand, each exposing a clap-derived
+- **`verbs/`** — one module per subcommand (clap `Args` + `run`).
-  `Args` struct and a `run(&Client, Args) -> Result<()>` fn. Splitting
+- **`client.rs`** — the Forgejo client wrapper + token loading.
-  one verb per module keeps each handler small and avoids the bash
-  script's monolithic `case` statement. Notable ones:
-  - **`lint.rs`** — `lint <subcommand>` triage queries (unassigned,
-    no-reviewer, stale-branches, assignments), always JSON-able via the
-    global `--json` flag.
-  - **`pr_status.rs`** — the merge-readiness verdict command
-    (`pr-status --pr <n>` / `--sha <commit>`); its exit code IS the
-    verdict, not just a report.
-  - **`comment.rs`** / **`comments.rs`** — post (refuses on unread
-    thread activity) / read (marks forge's own notification read as a
-    side effect) — see `notify.rs` for why that's safe to rely on.
-- **`client.rs`** — the app-level Forgejo client wrapper. Identity is
-  the per-agent token under `${HYPERHIVE_STATE_DIR}/forge-token`. REST
-  calls go through the typed `forgejo_api::sync::Forgejo` client
-  (`Client::api`); a minimal raw `reqwest` client remains for the few
-  *web-router* routes Forgejo doesn't serve under `/api/v1/`
-  (attachment downloads, Actions artifact/log routes).
 - **`notify.rs`** — the read-before-comment guard, backed by forge's
-  own notification read-state rather than a local mirror (which would
+  own notification read-state (no local mirror to drift).
-  drift across container restarts). "Is there unread activity here?"
+- **`body.rs`** — shared `--body`/`--body-file`/stdin resolution.
-  is just "does forge still have an unread notification for this
-  thread?" — forge is the single source of truth.
-- **`body.rs`** — body-input resolution shared by every verb that
-  posts a body: exactly one source between `--body`, `--body-file`,
-  and piped stdin (matches the old bash `resolve_body` helper);
-  passing both `--body` and `--body-file` is a clear error.
 
-Full verb reference (with worked examples): `docs/tools/forge.md`.
+Full verb reference: `docs/tools/forge.md`.

hivectl/README.md

@@ -1,65 +1,35 @@
 # hivectl
 
-The operator-facing host CLI for hyperhive. A thin client for the
+The operator-facing host CLI. A thin client for the `hive-c0re`
-`hive-c0re` daemon: it speaks the host admin socket protocol
+daemon — speaks the host admin socket protocol (`hive-host-sock`) and
-(`hive-host-sock`) and does **not** link the daemon crate.
+does not link the daemon crate. Container lifecycle, the approval
-
+queue, and provisioning verbs all forward to the daemon and need it
-Container lifecycle + the approval queue (`agents <spawn|kill|rebuild|
+running; a few (`wg`/`peer-config`, `choom`) work off local host state
-restart|…>`, `approvals <pending|approve|deny>`, `stop`/`start`) and
+instead.
-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
+Reach for this crate when adding an operator-run host command — agents
-command, not an agent-run one — agents talk to the daemon over their
+talk to the daemon over their own MCP tool surface
-own per-agent MCP tool surface (`hive-agent-mcp`), not this binary.
+(`hive-agent-mcp`), not this binary. `hivectl` is what a human operator
-`hivectl` is what a human operator (or a script on the host) runs.
+(or a host-side script) runs.
 
 ## Shape
 
 One module per subcommand family; `main.rs` is just the clap parse +
-top-level dispatch match.
+dispatch:
 
-- **`cli.rs`** — the clap `Cli`/`Cmd` derive tree every other module's
+- **`agents.rs`** — container lifecycle (spawn/kill/rebuild/restart/…).
-  `Args` hangs off of.
+- **`approvals.rs`** — the config/init-config/meta-input approval queue.
-- **`client.rs`** — the host admin socket client (`request`), split out
+- **`dag_progress.rs`** — rebuild-queue progress rendering.
-  so it lives with `hivectl` rather than in the daemon crate.
+- **`power.rs`** — restart/start/stop at the container level.
-- **`agents.rs`** — `agents <spawn|kill|destroy|rebuild|restart|list|
+- **`choom.rs`** — drop into an interactive claude session in a
-  set-parent|…>` — container lifecycle.
+  container.
-- **`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
+  per-integration account/token provisioning.
-  (`forge create-user`, `matrix …`, `github set-token`, `gateway
+- **`wg.rs`** — WireGuard mesh helpers.
-  create-user|delete-user|list-users`).
+- **`subvol.rs`** — btrfs state-subvolume ops.
-- **`wg.rs`** — `wg`/`peer-config`: WireGuard mesh helpers — generate
+- **`quota.rs`**, **`util.rs`**, **`completions.rs`**, **`open.rs`** —
-  this hive's key + the nix snippets to enable the mesh, add a peer,
+  shared helpers, shell completions, browser-open.
-  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`.