docs: add a top-level docs/README.md index, point README.md at it

Fixes hyperhive#3014.

docs/README.md is a genuine hand-written index for the docs/ tree -
task-oriented reading paths grouped by topic, covering every top-level
doc plus the three subdirectories that already have their own landing
page (web-ui/, tools/, turn-loop/). Adapted from CLAUDE.md's existing
"Reading paths" section (already curated and kept current) rather than
written from scratch, reorganized into headed groups since this is a
landing page, not a flat reference list. Explicitly covers
docs/tools/matrix.md and docs/github.md, per the note on hyperhive#3014
about the content that moved out of README.md's deleted section on
PR #3006 not going undiscoverable.

Top-level README.md's reading-path table (enumerating every doc)
replaced with a single prominent docs-site link, per mara's "replace
docs links table in readme md with a prominent link to the docs
(public host and git relative path)" - both forms present (rendered
site URL, git-relative docs/ path).

Verified every link in docs/README.md resolves to a real file (33
files checked). nix fmt clean, tracker-tag grep clean.

Companion to hyperhive/website#47/#48 - this is what that PRs "index.html
half" needs to exist before it can render, per atlas's note on #48.

README.md

@@ -39,19 +39,13 @@ host (NixOS, runs hive-c0re.service)
 ```
 
 **[→ website](https://hyperhive.darkest.space)** ·
+**[→ docs](https://hyperhive.darkest.space/docs/)** ·
 **[→ options reference](https://hyperhive.darkest.space/options/)**
 
-Depth lives in [`docs/`](docs/) — pick the one matching your task:
-
-| reading path                            | doc                                                                                                                                        |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| dashboard layout + endpoints            | [`docs/web-ui.md`](docs/web-ui.md) ([shape](docs/web-ui/shape.md) · [dashboard](docs/web-ui/dashboard.md) · [agent](docs/web-ui/agent.md)) |
-| claude turn loop + MCP tools            | [`docs/turn-loop/`](docs/turn-loop/README.md)                                                                                              |
-| config-edit + approval state machine    | [`docs/approvals.md`](docs/approvals.md)                                                                                                   |
-| what survives destroy / purge / restart | [`docs/persistence.md`](docs/persistence.md)                                                                                               |
-| naming, wire protocol, commit style     | [`docs/conventions.md`](docs/conventions.md)                                                                                               |
-| nginx vhost map + sub-domain routing    | [`docs/gateway.md`](docs/gateway.md)                                                                                                       |
-| NixOS / nspawn gotchas                  | [`docs/gotchas.md`](docs/gotchas.md)                                                                                                       |
+Depth lives in [`docs/`](docs/) (rendered at
+[hyperhive.darkest.space/docs/](https://hyperhive.darkest.space/docs/)) —
+start at [`docs/README.md`](docs/README.md) and pick the page matching
+your task rather than reading front to back.
 
 ## Quick start
 

docs/README.md

@@ -0,0 +1,96 @@
+# hyperhive docs
+
+Depth reference for hyperhive — the substrate, not the pitch (that's the
+[top-level README](../README.md) / [website](https://hyperhive.darkest.space)).
+Every page here stands alone; pick the one matching your task rather than
+reading top to bottom. For the auto-generated NixOS options reference
+(every `services.hyperhive.*` / `hyperhive.*` option, host and agent), see
+[the options site](https://hyperhive.darkest.space/options/) instead —
+this tree is prose, that one's generated straight from the module
+declarations.
+
+## Getting started
+
+- **Bringing a fresh hive online?** → [`setup.md`](setup.md) (first-run
+  `hivectl` bootstrap).
+- **What does the dashboard look like, and how do I use it?** →
+  [`web-ui/`](web-ui/README.md) — the operator-facing starting point;
+  its own sub-pages ([`shape`](web-ui/shape.md),
+  [`dashboard`](web-ui/dashboard.md), [`agent`](web-ui/agent.md),
+  [`css-vars`](web-ui/css-vars.md)) go deeper into implementation.
+- **What tools does an agent (or the operator) have available?** →
+  [`tools/`](tools/README.md) — `hivectl` (yours) plus every agent's MCP
+  tool surface (bash, forge, lifecycle, matrix, scheduling).
+
+## Dashboard & agent UI internals
+
+- **How does the per-agent terminal classify + colour events?** →
+  [`terminal-rendering.md`](terminal-rendering.md).
+
+## Turn loop, config, approvals
+
+- **How does claude get its prompt, and what tools does it have?** →
+  [`turn-loop/`](turn-loop/README.md) — the loop, binary shape, turn
+  outcomes; sub-pages: [`claude-invocation`](turn-loop/claude-invocation.md),
+  [`config`](turn-loop/config.md), [`mcp`](turn-loop/mcp.md).
+- **How do config changes flow from manager to operator to container?** →
+  [`approvals.md`](approvals.md) (two-step spawn, approval state machine,
+  `flake.lock` validation).
+- **What state survives destroy / purge / restart?** →
+  [`persistence.md`](persistence.md).
+
+## Trust boundary & security
+
+- **What's the operator/agent trust boundary? What's a capability?** →
+  [`boundary.md`](boundary.md).
+- **Agent trust model, prompt-injection threat model, credential
+  isolation?** → [`security.md`](security.md).
+- **Who can do what to whom — agent hierarchy and privilege?** →
+  [`agent-hierarchy.md`](agent-hierarchy.md).
+
+## Accounts & integrations
+
+- **How do per-agent forge accounts work? What does `forge_notify` poll,
+  and how does it format wake messages?** → [`forge.md`](forge.md) (the
+  hive's own Forgejo); [`tools/forge.md`](tools/forge.md) for the
+  `hive-forge` CLI verbs agents actually call.
+- **How does the matrix-tuwunel container work? Multiple accounts per
+  agent?** → [`matrix.md`](matrix.md) (the homeserver);
+  [`tools/matrix.md`](tools/matrix.md) for the MCP tool surface and
+  `hyperhive.matrixAccounts`.
+- **How do I give an agent a GitHub account (`gh` + `git push`)? How is
+  the PAT injected?** → [`github.md`](github.md).
+- **What does `hivectl` do? Provisioning, gateway users, container
+  shells?** → [`tools/hivectl.md`](tools/hivectl.md) (the curated guide);
+  [`tools/hivectl-cli.md`](tools/hivectl-cli.md) for the exhaustive,
+  auto-generated flag reference.
+
+## Networking & swarms
+
+- **What nginx vhosts does the gateway serve? How does matrix
+  discovery work?** → [`gateway.md`](gateway.md).
+- **How does DNS resolution work in agent containers? What's the
+  bridge network for?** → [`network.md`](network.md).
+- **How do I connect two hives into a swarm?** → [`swarm.md`](swarm.md)
+  (peer hives, TLS trust).
+- **Where do agent snapshots go? How does the swarm's `btrfs receive`
+  endpoint authenticate a pushing hive?** →
+  [`snapshot-store.md`](snapshot-store.md).
+
+## Scheduler, CI, observability
+
+- **How does the rebuild queue work? What are queue kinds and
+  sources?** → [`coordinator.md`](coordinator.md).
+- **How does the CI runner work? What's the auto-registration flow?** →
+  [`ci.md`](ci.md).
+- **How do I export Claude Code metrics (tokens, cost, tool calls) to
+  Prometheus/Grafana?** → [`observability.md`](observability.md).
+
+## Process & conventions
+
+- **Naming, commit style, wire protocol, the `data-async` pattern?** →
+  [`conventions.md`](conventions.md).
+- **Why does the nspawn flag look like that?** → [`gotchas.md`](gotchas.md)
+  (bind mounts, conf flags, other NixOS/nspawn quirks).
+- **What is `/knowledge`? How does the hive-wide knowledge repo sync,
+  and how do I contribute a document?** → [`knowledge.md`](knowledge.md).