split claude.md into docs/ — per-topic, human-readable

claude.md was eating 400 lines of subsystem detail that's useful
when you're working on that subsystem and noise the rest of the
time. split into:

- docs/conventions.md   naming, identity, async forms, commit style
- docs/gotchas.md       nspawn / nixos-container quirks
- docs/web-ui.md        dashboard + per-agent layouts and endpoints
- docs/turn-loop.md     claude invocation, wake prompt, mcp surface
- docs/approvals.md     approval flow, manager policy, helper events
- docs/persistence.md   sqlite dbs, retention, state dir layout

claude.md is now the entry point — file map, reading paths
("pick the doc that matches your task"), quick reminders that
fit on one screen, and a small scratchpad section for in-flight
context. references the docs; the docs don't reference claude.md.

no content was lost — the docs/ files cover everything the old
claude.md did, plus things i wrote up better while extracting.

docs/persistence.md

@@ -0,0 +1,95 @@
+# Persistence + retention
+
+Where state lives, what survives what, and how it's bounded.
+
+## Two sqlite databases
+
+### `/var/lib/hyperhive/broker.sqlite` (host)
+
+Three tables, all in one file:
+
+- `messages` — every inter-agent / operator-bound message.
+  `sender / recipient / body / sent_at / delivered_at`.
+- `approvals` — the queue. `agent / kind (apply_commit | spawn) /
+  commit_ref / requested_at / status / resolved_at / note`.
+- `operator_questions` — `ask_operator` queue.
+  `asker / question / options_json / multi / asked_at /
+  answered_at / answer`.
+
+Retention:
+
+- `Broker::vacuum_delivered` runs hourly via a tokio task in
+  `hive-c0re::main`. Drops delivered rows older than 30 days.
+  Undelivered rows are always kept (still in flight).
+- Approvals and questions are kept indefinitely — both are
+  audit trails. `actions::destroy` and answered questions stay
+  visible to anything that queries by id.
+
+### `/state/hyperhive-events.sqlite` (per agent)
+
+Lives inside each container's bind-mounted `/state/` dir (host
+path: `/var/lib/hyperhive/agents/<name>/state/hyperhive-events.sqlite`).
+One table:
+
+- `events(id, ts, kind, payload_json)` — every `LiveEvent` the
+  harness emits during turn loop execution.
+
+The harness writes; the host vacuums. `hive-c0re::events_vacuum`
+runs hourly and sweeps every existing agent state dir, applying the
+same two-stage delete to each file: drop rows older than 7 days,
+then trim to the 2000 most-recent. Centralising retention on the
+host means a misbehaving harness can't disable its own vacuum and
+agents don't need any cleanup wiring of their own.
+
+Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/state`
+setups). On open failure the `Bus` falls back to no-store mode
+rather than crashing the harness — events still broadcast over SSE,
+just nothing persisted.
+
+## State dirs (per agent)
+
+Under `/var/lib/hyperhive/agents/<name>/`:
+
+- `config/` — the proposed nix repo (manager-editable).
+- `claude/` — claude OAuth credentials, bind-mounted RW to
+  `/root/.claude` inside the container.
+- `state/` — durable notes + the events.sqlite db, bind-mounted
+  to `/state` inside the container.
+
+Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
+applied repo (`flake.nix` + `agent.nix`) that the container
+actually builds from.
+
+## Destroy vs purge
+
+- `DESTR0Y` (default) — stops + removes the nspawn container,
+  drops the systemd drop-in, fails any pending approvals. State
+  dirs stay put; the agent appears in the dashboard's K3PT ST4T3
+  section as a tombstone with `⊕ R3V1V3` and `PURG3` actions.
+  `R3V1V3` queues a Spawn approval that reuses the kept state on
+  approve (no re-login).
+- `PURG3` (opt-in via the dashboard button or
+  `hive-c0re destroy --purge <name>`) — DESTR0Y plus wipes
+  `/var/lib/hyperhive/{agents,applied}/<name>/`. Config history,
+  claude creds, /state/ notes, and the events db are all gone.
+  No undo.
+
+The manager is non-destroyable from both paths (declarative
+container; would fight with the host's NixOS config).
+
+## Run-time dirs
+
+`/run/hyperhive/` is tmpfs-backed (systemd `RuntimeDirectory=`) but
+preserved across hive-c0re restarts via `RuntimeDirectoryPreserve=yes`.
+Without that, every restart wipes bind sources and existing
+containers can't be started.
+
+- `/run/hyperhive/host.sock` — admin socket (host-side CLI).
+- `/run/hyperhive/manager/mcp.sock` — manager-privileged socket.
+- `/run/hyperhive/agents/<name>/mcp.sock` — per-sub-agent socket
+  (bind-mounted into the container as `/run/hive/mcp.sock`).
+
+On startup, `Coordinator::register_agent` drops any prior socket
+task before rebinding — idempotent so a hive-c0re restart followed
+by `rebuild alice` recreates the agent's socket without a clean
+reinstall.