docs: migrate reminder/gateway/crash-watch/migrate prose to docs (#715)

docs/gateway.md

@@ -114,6 +114,35 @@ TCP loopback upstream in `agents.conf` (deterministic port from
 `agent_web_port(name)`). A future cleanup will drop the TCP fallback
 once every agent's flipped.
 
+## Agent port map (`agent-ports.json`)
+
+`/var/lib/hyperhive/agent-ports.json` is a flat JSON object keyed by
+logical agent name → TCP web port:
+
+```json
+{
+  "iris":     8178,
+  "atlas":    8304,
+  "argus":    8267,
+  "damocles": 8549
+}
+```
+
+Written alongside `agents.conf` on every topology change. Ports come from
+`lifecycle::agent_web_port(name)` — a pure FNV-1a hash of the name,
+reproducible from the name alone. The manager is excluded: the gateway
+routes `/` directly to c0re's dashboard upstream, not through a
+per-agent `/agent/<name>/` prefix.
+
+The file doubles as a human-readable audit artifact — `cat agent-ports.json`
+shows every registered sub-agent and its deterministic port assignment. TCP
+loopback upstreams in `agents.conf` reference these ports for agents that
+haven't opted into unix-socket mode yet.
+
+Both `agent-ports.json` and `agents.conf` use atomic `<path>.tmp` +
+`rename()` writes so a crashing c0re process never leaves a partial or
+unparseable file behind.
+
 ## Dashboard link shape (gateway vs direct)
 
 When the gateway is in front, the SW4RM tab builds per-agent links