diff --git a/docs/gotchas.md b/docs/gotchas.md
index 4c106d3d..998dbcb1 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -30,9 +30,19 @@ 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). We
+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`.
+`LOCAL_ADDRESS6` / `HOST_BRIDGE` and set `PRIVATE_NETWORK=0`
+(`hive-priv`'s `write_nspawn_flags`).
+
+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.
 
 ### systemd service PATH ≠ host PATH
 
diff --git a/hive-priv/src/main.rs b/hive-priv/src/main.rs
index 5038d839..4511050a 100644
--- a/hive-priv/src/main.rs
+++ b/hive-priv/src/main.rs
@@ -2578,12 +2578,6 @@ fn validate_bind_path(path: &str) -> Result<()> {
     Ok(())
 }
 
-/// Update `/etc/nixos-containers/<container>.conf`: strips network-isolation
-/// vars (`PRIVATE_NETWORK`, `HOST_ADDRESS*`, `LOCAL_ADDRESS*`, `HOST_BRIDGE`,
-/// Update `/etc/nixos-containers/<container>.conf`: strip old network vars,
-/// write network isolation settings, then append `EXTRA_NSPAWN_FLAGS`.
-/// When `isolation` is `Some`, writes `PRIVATE_NETWORK=1` + veth wiring;
-/// when `None`, writes `PRIVATE_NETWORK=0`.
 /// `--tmpfs=<mount>/.git` for every bound git repo, hiding its metadata
 /// from inside the container.
 ///
@@ -2613,6 +2607,12 @@ fn git_overlay_flags(binds: &[BindMount]) -> Vec<String> {
         .collect()
 }
 
+/// Update `/etc/nixos-containers/<container>.conf`: strip old network vars
+/// (`PRIVATE_NETWORK`, `HOST_ADDRESS*`, `LOCAL_ADDRESS*`, `HOST_BRIDGE`),
+/// write the current network-isolation settings, then append
+/// `EXTRA_NSPAWN_FLAGS`. When `isolation` is `Some`, writes
+/// `PRIVATE_NETWORK=1` + veth wiring; when `None`, writes
+/// `PRIVATE_NETWORK=0`.
 fn write_nspawn_flags(
     container: &str,
     binds: &[BindMount],