docs: restructure into topic subdirectories, collapse duplicated index

Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):

Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
  getting-started/  setup.md
  agent-lifecycle/  agent-hierarchy.md, approvals.md, persistence.md
  trust-boundary/   boundary.md, security.md
  integrations/     forge.md, matrix.md, github.md, knowledge.md
  networking/       gateway.md, network.md, snapshot-store.md
  scheduler/        jobq.md, coordinator.md, ci.md, observability.md
  process/          conventions.md, gotchas.md, pr-review-gate.md
  web-ui/           terminal-rendering.md (moved into the EXISTING dir,
                    per mara's correction to the original getting-started
                    guess -- it's UI implementation detail, not onboarding)

The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).

Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).

Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).

Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.

nix fmt clean, both pre-push lints clean.

docs/README.md

@@ -11,55 +11,53 @@ declarations.
 
 ## Getting started
 
-- **Bringing a fresh hive online?** → [`setup.md`](setup.md) (first-run
-  `hivectl` bootstrap).
+- **Bringing a fresh hive online?** → [`getting-started/setup.md`](getting-started/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.
+  [`css-vars`](web-ui/css-vars.md), [`terminal-rendering`](web-ui/terminal-rendering.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
+## Agent lifecycle
 
+- **How do config changes flow from manager to operator to container?** →
+  [`agent-lifecycle/approvals.md`](agent-lifecycle/approvals.md) (two-step spawn, approval
+  state machine, `flake.lock` validation).
+- **What state survives destroy / purge / restart?** →
+  [`agent-lifecycle/persistence.md`](agent-lifecycle/persistence.md).
+- **Who can do what to whom — agent hierarchy and privilege?** →
+  [`agent-lifecycle/agent-hierarchy.md`](agent-lifecycle/agent-hierarchy.md).
 - **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).
+  [`trust-boundary/boundary.md`](trust-boundary/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).
+  isolation?** → [`trust-boundary/security.md`](trust-boundary/security.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
+  and how does it format wake messages?** → [`integrations/forge.md`](integrations/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);
+  agent?** → [`integrations/matrix.md`](integrations/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).
+  the PAT injected?** → [`integrations/github.md`](integrations/github.md).
+- **What is `/knowledge`? How does the hive-wide knowledge repo sync,
+  and how do I contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.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,
@@ -68,25 +66,25 @@ declarations.
 ## Networking & swarms
 
 - **What nginx vhosts does the gateway serve? How does matrix
-  discovery work?** → [`gateway.md`](gateway.md).
+  discovery work?** → [`networking/gateway.md`](networking/gateway.md).
 - **How does DNS resolution work in agent containers? What's the
-  bridge network for?** → [`network.md`](network.md).
+  bridge network for?** → [`networking/network.md`](networking/network.md).
 - **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.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).
+  [`networking/snapshot-store.md`](networking/snapshot-store.md).
 
 ## Scheduler, CI, observability
 
 - **What is the job queue, as a general idea (not hive-c0re specifics)?** →
-  [`jobq.md`](jobq.md) — operator-facing, no implementation detail.
+  [`scheduler/jobq.md`](scheduler/jobq.md) — operator-facing, no implementation detail.
 - **How does the rebuild queue work? What are the concrete step kinds,
-  queue sources, scheduler internals?** → [`coordinator.md`](coordinator.md).
+  queue sources, scheduler internals?** → [`scheduler/coordinator.md`](scheduler/coordinator.md).
 - **How does the CI runner work? What's the auto-registration flow?** →
-  [`ci.md`](ci.md).
+  [`scheduler/ci.md`](scheduler/ci.md).
 - **How do I export Claude Code metrics (tokens, cost, tool calls) to
-  Prometheus/Grafana?** → [`observability.md`](observability.md).
+  Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md).
 
 ## Crate reference
 
@@ -98,8 +96,8 @@ declarations.
 ## 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)
+  [`process/conventions.md`](process/conventions.md).
+- **Why does the nspawn flag look like that?** → [`process/gotchas.md`](process/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).
+- **What does a PR review verdict actually gate?** →
+  [`process/pr-review-gate.md`](process/pr-review-gate.md).