wiki: document dev environment (WSL networking, workflow)

Capture hard-won dev knowledge that was only in commit messages:

- wsl-dev-networking: WSL2 NAT blocks UDP broadcast (device discovery can't
  reach the LAN); fix is mirrored networking (.wslconfig, Win11 22H2+), plus the
  gotchas that remained after — multiple interfaces, subnet-directed broadcast,
  localhost->IPv6 stall. Alternatives for non-mirrored setups.
- local-dev-workflow: first-time setup, pnpm dev, and the gotchas (the
  strip-types dev-server hang -> tsx, the 127.0.0.1 proxy fix, .env loading,
  seeding into the right DB).
- device-discovery: corrected the old "broadcast permission (EACCES)" note — the
  real cause was the lib not enabling SO_BROADCAST for global 255.255.255.255;
  documented the three verified broadcast gotchas + I/O serialization.
- schema: add a `reference` page type; new "Dev environment" index section; log.

Links lint clean; both new pages well-connected.

wiki/concepts/device-discovery.md

@@ -23,10 +23,30 @@ as optional; the setup catalog returns a `discoverable` list of driver ids.
 ## UHPPOTE discovery
 
 The [[uhppote-controller]] supports discovery natively: a **UDP broadcast** (`get-devices` on
-`255.255.255.255:60000`) that **every controller on the LAN answers** with its serial, IP,
-netmask, gateway, MAC, firmware version, and date. The official `uhppoted` lib exposes this as
-`getDevices(ctx)`; the `uhppote` driver maps each result into a `DiscoveredDevice` (serial → id,
-IP → host).
+port `60000`) that **every controller on the LAN answers** with its serial, IP, netmask, gateway,
+MAC, firmware version, and date. The official `uhppoted` lib exposes this as `getDevices(ctx)`;
+the `uhppote` driver maps each result into a `DiscoveredDevice` (serial → id, IP → host).
+**Verified on real hardware** (serial 225088491).
+
+### Broadcast gotchas (learned the hard way — see [[wsl-dev-networking]])
+
+These cost real debugging time; the `uhppote` driver now handles all three:
+
+1. **Broadcast to the *subnet-directed* address, not the global `255.255.255.255`.** The
+   `uhppoted` lib only calls `setBroadcast(true)` when the target matches a **local interface's
+   subnet broadcast** (e.g. `10.0.10.255`). For the global address it skips it, so the `send`
+   fails with **`EACCES`**. The driver computes the subnet broadcast from `os.networkInterfaces()`.
+2. **A host with multiple interfaces must broadcast on *all* subnets.** With several NICs (LAN,
+   VPN/Tailscale, docker bridges) the controller is on only one. Picking the first interface
+   misses it; the driver broadcasts on every subnet and dedupes by serial.
+3. **For *unicast* ops (status / open), the lib's `Config` broadcast must match the target's
+   subnet** — it governs reply routing, so a mismatched broadcast makes `getStatus` time out even
+   though `openDoor` "succeeds". The driver sets the broadcast per the target host's subnet. (This
+   was the health-check "offline/timeout" bug: a 5 s timeout dropped to 24 ms once fixed.)
+
+Also: concurrent `uhppoted` calls collide on the `:60001` reply-listener port (EACCES / dropped
+replies), so the driver **serializes** all controller I/O. Override the broadcast with
+`UHPPOTE_BROADCAST` for unusual setups.
 
 ## Flow
 
@@ -38,9 +58,9 @@ IP → host).
 
 ## Deployment notes
 
-- UHPPOTE discovery is a **broadcast** — the host socket needs broadcast permission (a raw
-  `send EACCES …:60000` means the OS blocked it). Works on the isolated device VLAN
-  ([[network-isolation]]) where the controller and host share an L2 segment.
+- Discovery is an **L2 broadcast**: the host and controller must share a layer-2 segment. Works
+  on the isolated device VLAN ([[network-isolation]]). A routed/NAT'd network (e.g. WSL2 NAT mode
+  — see [[wsl-dev-networking]]) blocks it entirely.
 - Discovery shares the same unauthenticated UDP exposure as everything else UHPPOTE — another
   reason the controllers live on an isolated VLAN ([[uhppote-udp-protocol]]).
 - Cameras (Hikvision/Dahua via ONVIF/WS-Discovery) could implement the same interface later.