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/swarm/README.md

@@ -75,7 +75,7 @@ domains can share one. `hiveName` surfaces in the same places but is
 distinction — one names this hive, the other names the group it belongs
 to.
 
-See `docs/conventions.md` § Hive identity for the env-var chain
+See `docs/process/conventions.md` § Hive identity for the env-var chain
 and `qualify()` / `qualified_label()` semantics.
 
 ## Swarm CA
@@ -166,7 +166,7 @@ evaluates cleanly points at a real machine that isn't the one you meant.
    key must never enter the store), so there is no build-time name for
    it. Bridging that needs a runtime mechanism and is tracked as its own
    issue. Until then, federation needs CA-issued certs (ACME). See
-   `docs/matrix.md` for federation firewall + TLS requirements.
+   `docs/integrations/matrix.md` for federation firewall + TLS requirements.
 
 3. **WireGuard mesh** (optional) — `swarm.wireguard.enable` reads each
    entry's `wireguardPublicKey`/`wireguardEndpoint`/`wireguardAddress`
@@ -279,7 +279,7 @@ port}` tells this hive where the swarm's `btrfs receive` endpoint is, so
 It is genuinely swarm-scoped rather than per-peer — a swarm has exactly
 one store, because the receiver keys destinations by *agent* so a
 migrating agent keeps one unbroken incremental chain. See
-[snapshot-store.md](../snapshot-store.md).
+[snapshot-store.md](../networking/snapshot-store.md).
 
 ## Swarm controller
 
@@ -385,7 +385,7 @@ Nothing to configure. The hooks are registered only when this host also
 serves the swarm UI vhost — that is what publishes the endpoint, and a
 hook the forge cannot reach would collect failed deliveries while
 looking healthy. The HMAC secret is generated on first start and kept
-(see [`docs/persistence.md`](../persistence.md)).
+(see [`docs/agent-lifecycle/persistence.md`](../agent-lifecycle/persistence.md)).
 
 To check it is working, push to `internal/knowledge` and look for
 `webhook: verified delivery` in `journalctl -u swarm-controller`. A
@@ -393,13 +393,13 @@ refused delivery logs `webhook: refused delivery` with the reason.
 
 ## Cross-references
 
-- `docs/snapshot-store.md` — the swarm's `btrfs receive` endpoint, and
+- `docs/networking/snapshot-store.md` — the swarm's `btrfs receive` endpoint, and
   the `swarm.snapshotStore` option that points a hive at it
-- `docs/conventions.md` § Hive identity — env vars, qualified labels
-- `docs/matrix.md` — matrix federation, TLS cert auto-generation,
+- `docs/process/conventions.md` § Hive identity — env vars, qualified labels
+- `docs/integrations/matrix.md` — matrix federation, TLS cert auto-generation,
   firewall posture
 - `docs/swarm/ui.md` — the swarm-wide hive roster, now the operator
   surface for "what hives exist" (superseded the per-hive dashboard's
   old "peer hives" display)
-- `docs/gateway.md` — nginx vhosts and the `.well-known/matrix/`
+- `docs/networking/gateway.md` — nginx vhosts and the `.well-known/matrix/`
   auto-discovery scheme

docs/swarm/services.md

@@ -183,5 +183,5 @@ refused at eval — a tier that receives samples and drops them looks
 healthy while losing data.
 
 Agent-side configuration, and what a hive's own collector does, are in
-[`../observability.md`](../observability.md).
+[`../scheduler/observability.md`](../scheduler/observability.md).
 

docs/swarm/sso.md

@@ -16,7 +16,7 @@ authelia binds loopback only. The **gateway** on the host running it
 publishes it as `auth.<swarm.domain>` — vhost, dnsmasq record and TLS
 name all follow `deploy.authelia`, so there is nothing to turn on
 separately. (Details, including why a client hive must not declare that
-vhost: [`../gateway.md`](../gateway.md).)
+vhost: [`../networking/gateway.md`](../networking/gateway.md).)
 
 **Authelia does not start until at least one user exists.** The user
 store is generated empty — deliberately, since seeding a default account

docs/swarm/ui.md

@@ -38,7 +38,7 @@ fine and still gets bounced.
 swarmctl user add <you> --group admins
 ```
 
-`admins` deliberately, not a new word: [`../setup.md`](../setup.md) has
+`admins` deliberately, not a new word: [`../getting-started/setup.md`](../getting-started/setup.md) has
 told every operator to create exactly that group since the bootstrap step
 existed, so an account made by following the guide already passes. This
 is the first rule that *consumes* a group name — inventing a second one
@@ -111,4 +111,4 @@ popover.
 ## Cross-references
 
 - [`sso.md`](sso.md) — the authelia instance itself, and the user store.
-- [`../gateway.md`](../gateway.md) — the full vhost map and TLS modes.
+- [`../networking/gateway.md`](../networking/gateway.md) — the full vhost map and TLS modes.