diff --git a/docs/gotchas.md b/docs/gotchas.md
index 998dbcb1..275919f1 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -30,19 +30,28 @@ Not `boot.isContainer = true`. Renamed in nixos-25.11+.
 
 …in the `.conf`. The start script's `if HOST_ADDRESS set →
 --network-veth` branch then forces a private netns — silently fatal
-for our web UIs (the bind is invisible from the host). By default we
-force-clear `HOST_ADDRESS` / `LOCAL_ADDRESS` / `HOST_ADDRESS6` /
-`LOCAL_ADDRESS6` / `HOST_BRIDGE` and set `PRIVATE_NETWORK=0`
-(`hive-priv`'s `write_nspawn_flags`).
+for our web UIs (the bind is invisible from the host).
+`hive-priv`'s `write_nspawn_flags` rewrites these vars every time it
+touches the conf file, and which way it writes them depends on
+`HIVE_NETWORK_ISOLATION`:
 
-When `HIVE_NETWORK_ISOLATION=1` is set (the `hive-network.nix` module's
-`isolateContainers` option), the same function takes the opposite
-branch instead: `PRIVATE_NETWORK=1` plus a veth pair onto the host
-bridge, `HOST_ADDRESS` set to the bridge gateway IP (so
-`nixos-container`'s in-container init installs a default route before
-the DHCP lease arrives), and the rest left for DHCP. Isolation is a
-per-host opt-in, not the default — most hosts still take the
-force-clear branch above.
+- **Every real deployment today**: `hive-network.nix` sets
+  `HIVE_NETWORK_ISOLATION=1` unconditionally whenever hyperhive is
+  enabled — there's no opt-out any more (`isolateContainers` and the
+  module's own `enable` option were both removed via
+  `lib.mkRemovedOptionModule`; "network isolation is the only mode" is
+  the removal message itself). So `write_nspawn_flags` takes the
+  `isolation: Some` branch: `PRIVATE_NETWORK=1` plus a veth pair onto
+  the host bridge, `HOST_ADDRESS` set to the bridge gateway IP (so
+  `nixos-container`'s in-container init installs a default route
+  before the DHCP lease arrives), rest left for DHCP.
+- The `None` branch — force-clear `HOST_ADDRESS` / `LOCAL_ADDRESS` /
+  `HOST_ADDRESS6` / `LOCAL_ADDRESS6` / `HOST_BRIDGE` and
+  `PRIVATE_NETWORK=0` — only fires when `HIVE_NETWORK_ISOLATION` isn't
+  `"1"` at all (env var unset) or the bridge subnet fails to parse
+  (`bridge_gateway_ip` returns `None`, logged as a warning). Not a
+  supported alternate mode any more, just what the code falls back to
+  outside the one path every host actually takes.
 
 ### systemd service PATH ≠ host PATH