Document HA latency switching margins and NB_HA_RELAYED_SWITCH_DELAY

src/pages/client/environment-variables.mdx

@@ -35,6 +35,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se
 | `NB_DISABLE_CUSTOM_ROUTING` | All | Revert to the routing behavior from before exit node support was added. No exclusion routes or fwmark-based socket routing will be used; all dialers and listeners fall back to plain `net.Dial`/`net.Listen`. Routes with a prefix of /7 or larger (e.g. default routes, 0.0.0.0/0) will be rejected. |
 | `NB_ROUTE_PROTO_FLAG` | macOS, BSD | Set a custom route flag on routes the client adds to the routing table. Accepted values: `2` (RTF_PROTO2) or `3` (RTF_PROTO3); defaults to RTF_PROTO1. Not used on Linux (Linux uses netlink with its own protocol field). |
 | `NB_DISABLE_ROUTE_CACHE` | Windows | Disable the 2-second cache on Windows routing table lookups. The client reads the OS routing table (via Win32 API) when adding or removing routes; without the cache, each operation triggers a fresh read. Only needed for debugging route conflicts. |
+| `NB_HA_RELAYED_SWITCH_DELAY` | All | How long a routing peer that dropped from a direct connection to a relayed one keeps the route before it moves to an equivalent direct routing peer. Accepts a Go duration (e.g. `60s`), `0` to switch immediately, or `never` to keep the route on a relayed peer for as long as it stays connected. Default `30s`. Failover and metric changes always switch immediately. See [High availability](/manage/networks/how-routing-peers-work#latency-switching-equal-metrics). |
 
 ## WireGuard and interface
 

src/pages/manage/networks/how-routing-peers-work.mdx

@@ -98,7 +98,7 @@ The routing peer must have direct network reachability to the resources it serve
 
 ## High availability
 
-Multiple routing peers can serve the same network or route. Behavior depends on the **metric** you assign each routing peer in the dashboard. There are no tunable thresholds — the metric is the only high availability control.
+Multiple routing peers can serve the same network or route. Behavior depends on the **metric** you assign each routing peer in the dashboard. The metric is the main high availability control.
 
 ### Primary / failover (different metrics)
 
@@ -108,10 +108,16 @@ The lower-metric peer carries all traffic. The higher-metric peer is held in res
 
 ### Latency switching (equal metrics)
 
-When two routing peers share the same metric, each client picks the one with lower latency. A switch only happens when the latency difference exceeds **20 ms**, which prevents flapping between peers that are roughly equivalent.
+When two routing peers share the same metric, each client prefers the one with lower latency. A route only moves to another peer when that peer is at least **20 ms** and **20%** faster, which prevents flapping between peers that are roughly equivalent. After a latency-based move, the route stays on the new peer for at least **30 seconds** before it can move again for latency. Failover and metric changes still switch immediately.
 
 Useful when routing peers are geographically distributed and you want each client to land on the closest one automatically — for example, an EU-based peer and a US-based peer serving the same network, with users on both continents.
 
+### Direct to relayed fallback
+
+A switch resets the TCP connections that use the route, so a routing peer that briefly drops from a direct connection to a relayed one keeps the route for a grace period, 30 seconds by default. If its direct connection comes back within that time, nothing changes. If it is still relayed after the delay, the route moves to an equivalent routing peer with a direct connection.
+
+Change the grace period with the `NB_HA_RELAYED_SWITCH_DELAY` environment variable on the client. Accepted values are a duration such as `60s`, `0` to switch immediately, or `never` to keep the route on a relayed peer for as long as it stays connected.
+
 ### Failure domains
 
 Place highly available peers in different failure domains within the same network: separate AZs in cloud, separate hypervisors or hosts on-prem.
@@ -221,7 +227,7 @@ Specifics:
 
 When a peer is `Connected` but a resource behind it is still unreachable, [Troubleshooting resource connectivity](/help/troubleshooting-resource-connectivity) walks these checks in order, from the peer through to the TCP handshake at the resource.
 
-- `netbird status -d` shows the connection type, status, and details for every peer the client is connected to.
+- `netbird status -d` shows the connection type, status, and details for every peer the client is connected to. Routing peer switches are recorded as system events, so they also appear here.
 - `netbird networks ls` shows which networks the client is currently using.
 - `netbird debug trace` simulates a packet against the firewall rules without sending real traffic. Useful when policies look right but traffic is dropped. On Linux this is most informative when the kernel firewall backend is active.
 - On the routing peer host: