diff --git a/README.md b/README.md
index 36ab9a2..59ff6de 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,7 @@ This directory is the source of truth. The live system files live under `/etc`,
 - `wrede.pvt` resolves over ZeroTier when off the home LAN. Mechanism: `allowDNS=1` (prereq) + `zerotier-systemd-manager` writes `99-ztuga7c2kh.network`, networkd applies it to resolved.
 - Verify: `resolvectl status ztuga7c2kh` shows `DNS` scope + the two servers + `wrede.pvt`.
 - NOTE: ZeroTier's *native* DNS push is a no-op on Linux (`setDns ... not implemented`), which is why the manager is required.
+- The ZT link carries `RequiredForOnline=no` (drop-in `…network.d/required-for-online.conf`) so it does **not** gate `network-online.target` — see Gotchas.
 
 ### Cockpit dashboard
 - `https://<wayback>:9090` → "Van Router". Reload the browser after deploying plugin changes (Cockpit caches packages per session).
@@ -161,6 +162,7 @@ Two things `deploy.sh` does **not** do (one-time, manual):
 - **Per-WAN probing needs `curl --interface if!<dev>`** (forces `SO_BINDTODEVICE`); plain `--interface <name>` only sets the source IP and still routes via the default WAN. `rp_filter` is loose (`2`), required for this.
 - **`arp_ignore`/`arp_announce`** matter only when two WANs share a subnet (a home-LAN test artifact; Starlink + neighbour-wifi will be on different subnets in the van). Harmless to keep.
 - **dnsmasq uses `bind-dynamic` bound to the AP iface** so it coexists with systemd-resolved (no port-53 fight) — resolved stays intact for the host.
+- **ZeroTier must be `RequiredForOnline=no`** or it deadlocks boot. `systemd-networkd-wait-online` waits for every *managed* networkd link to go routable; the ZT link `ztuga7c2kh` only appears once `zerotier-one` starts, but `zerotier-one` is ordered `After=network-online.target`. The loop breaks only via wait-online's 120s timeout — adding ~2min to every boot and delaying ZeroTier (the recovery path). The drop-in excludes the ZT link from the gate; real uplink readiness is covered by `NetworkManager-wait-online` (networkd here owns only the AP + ZT links, neither a true uplink). The AP link is already `RequiredForOnline=no`.
 
 ---
 
diff --git a/deploy.sh b/deploy.sh
index 01528db..009c750 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -27,7 +27,8 @@ install -D -m0755 failover/50-disable-eee       /etc/NetworkManager/dispatcher.d
 install -D -m0644 failover/99-van-arp.conf      /etc/sysctl.d/99-van-arp.conf
 
 echo "== zerotier managed dns =="
-install -D -m0644 dns/zt-search.conf /etc/systemd/network/99-ztuga7c2kh.network.d/search.conf
+install -D -m0644 dns/zt-search.conf             /etc/systemd/network/99-ztuga7c2kh.network.d/search.conf
+install -D -m0644 dns/zt-required-for-online.conf /etc/systemd/network/99-ztuga7c2kh.network.d/required-for-online.conf
 
 echo "== cockpit plugin =="
 install -d /usr/share/cockpit/vanrouter
diff --git a/dns/zt-required-for-online.conf b/dns/zt-required-for-online.conf
new file mode 100644
index 0000000..0fff87a
--- /dev/null
+++ b/dns/zt-required-for-online.conf
@@ -0,0 +1,7 @@
+[Link]
+# The ZeroTier overlay must NOT gate network-online.target. The ztuga7c2kh interface
+# only exists once zerotier-one starts, but zerotier-one is ordered After=network-online.target.
+# Without this, systemd-networkd-wait-online blocks on the (not-yet-existing) ZT link until its
+# 120s timeout, delaying boot and ZeroTier by ~2min every reboot. Real uplink readiness is
+# covered by NetworkManager-wait-online, not networkd. Drop-in (manager regenerates the main file).
+RequiredForOnline=no