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.