docs: README + TODO split; trim CLAUDE.md; fix async form 415

README.md

@@ -0,0 +1,49 @@
+# hyperhive
+
+Multi-Claude-Code-agent orchestration on **nixos-containers**.
+
+A host-side Rust daemon (`hive-c0re`) spawns nspawn-isolated agent
+containers and brokers messages between them. A manager agent (`hm1nd`)
+coordinates the swarm and gates lifecycle changes on user approval via git
+commits, surfaced through a vibec0re-styled HTTP dashboard.
+
+```
+                     ┌────────────────────────┐
+                     │  hive-c0re (Rust)      │
+        operator ──▶ │  • lifecycle           │ ─▶ nixos-containers
+                     │  • broker (sqlite)     │     ├── hm1nd       (manager)
+                     │  • approvals (sqlite)  │     ├── h-alice     (sub-agent)
+                     │  • dashboard :7000     │     └── h-bob       ...
+                     │  • per-agent sockets   │
+                     └────────────────────────┘
+```
+
+Each container runs a harness binary that drives `claude --print --continue`
+in a turn loop, exposes a per-agent web UI with a live event stream, and
+talks to the broker over a bind-mounted unix socket via an embedded MCP
+server claude calls into.
+
+## Read next
+
+- **[CLAUDE.md](CLAUDE.md)** — developer reference: conventions, gotchas,
+  per-subsystem design, file map.
+- **[TODO.md](TODO.md)** — open work items.
+
+## Build / deploy
+
+```sh
+# inside the repo (devshell first; no global cargo)
+nix develop -c cargo check
+nix develop -c cargo clippy --workspace --all-targets -- -D warnings
+
+# evaluate everything (rust+nix+toml fmt + clippy)
+nix flake check
+
+# deploy to a host that imports `hyperhive.nixosModules.hive-c0re`
+cd ~/Repos/<nixos-config-repo>
+nix flake update --update-input hyperhive
+sudo nixos-rebuild switch --flake .#<host>
+```
+
+The host config also needs `hyperhive.overlays.default` applied — the
+module's default `package = pkgs.hyperhive` requires the overlay.