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
-crate in the workspace — it owns the sqlite broker, the approval /
-question / reminder / schedule queues, the generic job-DAG queue,
-lifecycle (`nixos-container` shellouts + per-agent flake generation),
-gateway/forge/matrix provisioning, per-container stats, and the axum
-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.
+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
 
-This is where host-level, cross-container orchestration logic lives:
-spawning/rebuilding/destroying agent containers, approving config
-changes, reconciling desired vs. actual container state, provisioning
-per-agent forge/matrix/gateway accounts, and serving the dashboard.
-If you're changing what the operator sees on the dashboard, how a
-container gets spawned or torn down, or anything in the approval flow,
-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`.
+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 child is
-re-exported at the crate root so `crate::broker::…`-style paths keep
-resolving unchanged regardless of which subdirectory a module actually
-lives in.
+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 axum operator dashboard: managed containers
-  (with deep-links to each container's own web UI), pending approvals
-  (unified diff vs. the applied repo + approve/deny), schedules,
-  questions, journal/build-log viewers, topology, webhook ingest.
-- **`job_queue/`** — generic job-DAG queue + desired-state
-  reconciliation, the host-side wrapper over the domain-agnostic
-  `hive_jobq` scheduler. Jobs are nodes in per-request DAGs
-  (`templates.rs`); special cases (graceful-stop watcher, deferred-start
-  follow-up, meta-update cascade, topology reparents) collapse into DAG
-  *shapes* over the shared node primitives (`model::NodeKind`). See
-  `docs/coordinator.md`.
-- **`lifecycle/`** — `nixos-container` lifecycle (spawn/kill/destroy/
-  rebuild/restart) + per-agent config flake generation.
-- **`stores/`** — sqlite-backed host-side stores: the broker
-  (`broker.rs`), approval / question / schedule queues, build logs,
-  audit trail, power intent, plus the shared connection open/migration
-  helper (`db.rs`).
-- **`workers/`** — background tasks and periodic sweeps: crash/login
-  watcher, scheduled-prompt delivery loop, boot-time auto-update
-  reconcile, the agent-sockets.json writer loop, the MCP socket
-  listener reconcile loop, knowledge-repo sync.
-- **`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`).
+- **`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.
 
-`src/main.rs` is the `hive-c0re` binary entry point: `serve` (the
-daemon) plus the periodic vacuum/sweep loops. See the top-level
-`CLAUDE.md`/`docs/` index for the full reading-path map — this README
-is just the module tour.
+See the top-level `CLAUDE.md`/`docs/` index for the full reading-path
+map.