wiki: cross-link uos-server <-> pfsense (unifi-wifi skill halves); add uos-server to index

wiki/systems/uos-server.md

@@ -2,8 +2,15 @@
 type: system
 name: uos-server
 display_name: UOS Server (UniFi OS Server)
-last_compiled: 2026-06-15
-compiled_by: GURU-5070/claude-main
+last_compiled: 2026-06-21
+compiled_by: HOWARD-HOME/claude-main
+sources:
+  - session-logs/2026-06/2026-06-21-howard-unifi-pfsense-control-verbs.md
+backlinks:
+  - systems/jupiter
+  - systems/pfsense
+  - clients/cascades-tucson
+  - clients/internal-infrastructure
 ---
 
 # UOS Server (UniFi OS Server)
@@ -78,6 +85,25 @@ There is **no mongo client on the guest host**; the shell is `/usr/bin/mongo` *i
 - **`rogue`** — neighbor/over-the-air BSSIDs seen by APs. **Not ACG gear** — a MAC hit here is someone else's WiFi, ignore it for device hunts.
 - **Pending/unadopted devices:** the controller only persists a discovered device into `device` with `adopted:false`. If `db.device.count({adopted:false})` is `0`, there are **no** pending devices controller-wide — an "unadopted" device that returns nothing here simply has not reached this controller (not on a network it can discover, or managed by a different console). The cloud API and integration API show adopted gear only, so they cannot find it either; locating it then needs L2/DHCP/ARP on the gateway of the site it is physically cabled to.
 
+## Related tooling — pfSense gateway layer (works together)
+
+This UOS controller and the **pfSense gateway tooling** are the two halves of the **`unifi-wifi`
+skill**, and they're designed to be used together at a single site:
+
+- **This UOS server** = the UniFi side — APs/switches/clients across ~49 sites, queried via the
+  Mongo path above (and the `gw-audit`/`gw-control` verbs for UniFi *gateways*).
+- **[[pfsense]]** = the gateway side — when a site's gateway is a pfSense (not a UniFi USG/UXG/UCG),
+  the same `gw-audit`/`gw-control` verbs auto-dispatch to the pfSense SSH backend
+  (`pfsense-ssh.sh` + `pfsense-gwc.php`, cred `clients/<slug>/pfsense-firewall`).
+
+A very common ACG topology is **UniFi APs/switches on this controller behind a pfSense gateway** —
+e.g. [[cascades-tucson]] and the ACG office itself. At such a site you drive WiFi/switch work
+through this UOS Mongo path and gateway work (WAN/firewall/port-forwards/blocking) through the
+pfSense backend; `gw-audit <site>` covers both because it reports `num_gw=0` (no UniFi gateway) and
+then runs the pfSense audit. So one skill spans the whole site regardless of gateway vendor.
+
 ## Backlinks
 - [[jupiter]] — hypervisor (virsh "Unifi" VM) + NPM (`172.16.3.20:7818`, the `:11443` proxy).
 - [[internal-infrastructure]] — ACG internal infra index.
+- [[pfsense]] — the gateway half of the `unifi-wifi` skill (pfSense SSH backend); pairs with this UOS controller.
+- [[cascades-tucson]] — example UniFi-on-UOS-behind-pfSense site (the pfSense backend was validated there).