docs: let the crate README own the technical detail, point at it

Per review: crate READMEs will be served on the docs page, so the same
technical content in docs/swarm.md and the repo map is redundancy, not
thoroughness.

docs/swarm.md keeps only what is operator-facing and specific to it --
the option, and why enable is not derived from services.hyperhive.enable
-- and points at the README for the socket-directory constraint. The repo
map keeps the one-line warning and the pointer, not the argument.

This is the same correction as the AgentWindow comments: I had written
the socket rationale into five places and called it coverage. Correcting
every copy is what preserves the cause.

CLAUDE.md

@@ -145,13 +145,9 @@ hand-maintained per-file tree drifts out of sync with the code.
   (`services.hyperhive.swarm.controller.enable`). Where `hive-c0re` owns
   the agents on **one** host, this owns what is true **across** hives; a
   swarm runs one of them, so most hives leave it off. Serves HTTP over a
-  unix socket (never a TCP port) that the gateway's nginx proxies to.
-  ⚠️ The socket lives in its **own** `RuntimeDirectory`: it is `0666`
-  (nginx is a different user and `connect(2)` needs write), so the
-  containing directory — bind-mounted wholesale into the gateway
-  container — is the only access control there is. Never move it under a
-  directory shared with anything else, `/run/hyperhive` (host admin
-  socket) above all. A unit test pins the path.
+  unix socket the gateway's nginx proxies to — ⚠️ **the socket's
+  directory is its access control**; the constraint that governs it is in
+  the crate's README, and a unit test pins the path.
 
 ### External dependencies with no directory here
 

docs/swarm.md

@@ -238,32 +238,15 @@ migrating agent keeps one unbroken incremental chain. See
 ## Swarm controller
 
 `services.hyperhive.swarm.controller.enable` runs the `swarm-controller`
-daemon on this host. It is **off by default and deliberately not derived
-from `services.hyperhive.enable`**: a swarm has one controller, so
-enabling it is a statement about swarm topology, not about whether
-hyperhive is installed. Every hive runs `hive-c0re` (which owns the
-agents on that host); one hive additionally runs this (which owns what is
-true across hives).
+daemon on this host. **Off by default and deliberately not derived from
+`services.hyperhive.enable`**: a swarm has one controller, so enabling it
+is a statement about swarm topology, not about whether hyperhive is
+installed. Every hive runs `hive-c0re` (the agents on that host); one
+hive additionally runs this (what is true across hives).
 
-It serves HTTP over a unix socket — `socketPath`, default
-`/run/swarm-controller/controller.sock` — rather than a TCP port. The
-gateway's nginx is the only intended client and reaches the socket
-through a bind-mount, and a listener that is never bound to an address
-cannot be reached from off-host by mistake.
-
-⚠️ **The socket's directory is its access control.** The socket itself is
-`0666`, because nginx runs as a different user and `connect(2)` needs
-write — the same arrangement hive-c0re uses for the per-agent sockets.
-What keeps that safe is that the directory holds one socket and is
-bind-mounted into exactly one container. Pointing `socketPath` at a
-directory that carries anything else — `/run/hyperhive`, which holds the
-host **admin** socket, above all — exposes everything in it to every
-consumer that mounts it. Changing `socketPath` therefore means
-re-checking the gateway bind-mount, not just the daemon.
-
-Today the daemon serves a single `/health` endpoint and holds no state:
-the unit exists so the swarm-level surfaces that follow have somewhere to
-land.
+What it serves, why it is a unix socket rather than a port, and the
+socket-directory constraint that governs where `socketPath` may point:
+[`swarm-controller/README.md`](../swarm-controller/README.md).
 
 ## Cross-references