From b1d43fc1e7ff6eb7d067be07691b711f37a50b31 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:43:31 +0200
Subject: [PATCH] docs(web-ui): point port-hash detail at gotchas.md instead of
 restating it

---
 docs/web-ui.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/web-ui.md b/docs/web-ui.md
index 61901099..37513f7d 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -1,8 +1,10 @@
 # Web UI
 
 Two web surfaces share the same skeleton: the dashboard (port 7000)
-and the per-agent UIs (every container hashes into :8100-8999 via
-`lifecycle::agent_web_port`'s FNV-1a).
+and the per-agent UIs (each container's port is a deterministic hash
+in :8100-8999 — see
+[`gotchas.md#web-ui-ports-collide-on-hash`](gotchas.md#web-ui-ports-collide-on-hash)
+for the mechanics and the collision caveat).
 Both are SPAs — `GET /` returns a static shell, `/api/state`
 returns JSON, JS renders. No full-page reloads.