# unifi-wifi — per-client / per-cred onboarding (the "one step once you have X" procedures)

Prep for the ROADMAP items that are blocked only on an external input (an account, a cred, site reach).
Each is written so it's a single, copy-paste step the moment the input exists. Run all vault writes via the
`vault` skill helper. Paths assume repo root.

---

## §D — read-only controller cred (least privilege)

**Why:** `gw-audit.sh` logs into the UniFi controller for a READ-ONLY audit. It currently falls back to the
RW admin (`infrastructure/uos-server-network-api-rw`) and prints a hint. The moment a read-only cred is
vaulted at `infrastructure/uos-server-network-api`, `gw-audit` uses it automatically — **no code change**.

1. Create a read-only controller admin: UniFi OS (`https://unifi.azcomputerguru.com`, or `:11443`) ->
   **Settings -> Admins & Users -> Admins -> Add** -> role **View Only** (limited admin). Use a local
   account (not SSO) so it works for the REST login. Set a strong password.
2. Vault it:
   ```bash
   bash .claude/skills/vault/scripts/vault-helper.sh new infrastructure/uos-server-network-api \
     --kind generic --name 'UOS controller read-only API' --tag unifi \
     --set username=<ro-user> --set password=<pw>
   ```
3. Verify: `bash .claude/skills/unifi-wifi/scripts/gw-audit.sh <site>` — the "using RW controller cred"
   hint should be gone (it now uses the RO cred). Writes (`gw-control --apply`) still use the RW cred.

---

## §B — enable a client for AP-side collectors (and pfSense gateway control)

`sites.sh` shows readiness; this is the full enable path. Controller-side scripts (audit-site, live-stats,
model-rank, optimize-radios, apply-radio, channel-plan) already work on ANY UOS site with zero setup — the
steps below are only for the **AP-side collectors** and the **pfSense gateway** backend.

### B1. AP device-auth cred (for neighbor-collect / survey-collect / dfs-check / watch-ap)
1. Get the site's Device Authentication user/pass: UniFi OS -> **Settings -> System -> Device
   Authentication** (per site).
2. Ensure **L3 reach** to that site's AP mgmt VLAN (site VPN / route) from the machine running the script.
3. Vault it:
   ```bash
   bash .claude/skills/vault/scripts/vault-helper.sh new clients/<slug>/unifi-ap-ssh \
     --kind generic --name '<Client> UniFi AP device-auth SSH' --tag unifi \
     --set username=<u> --set password=<pw>
   ```
4. Verify: `bash .../scripts/neighbor-collect.sh <site> clients/<slug>/unifi-ap-ssh` (or pass the cred path
   as the script's vault-path arg). `sites.sh` will show the client as `[ready]`.

### B2. pfSense gateway control (if the site's gateway is a pfSense, not a UniFi USG/UXG/UCG)
1. Vault the pfSense admin cred (add `port` only if non-22, e.g. 2248 for the ACG office):
   ```bash
   bash .claude/skills/vault/scripts/vault-helper.sh new clients/<slug>/pfsense-firewall \
     --kind generic --name '<Client> pfSense firewall' --tag pfsense \
     --set host=<ip> --set username=<admin> --set password=<pw> [--set port=2248]
   ```
   (Infra-vaulted boxes work too — e.g. `infrastructure/pfsense-firewall`; pass the full path, option A.)
2. Find the site_id and bind it for AUTO-SELECT (no `--pfsense` needed afterwards):
   ```bash
   bash .claude/skills/unifi-wifi/scripts/gateway-map.sh suggest    # shows the site_id + that the cred is now vaulted
   # add a TAB-separated row to references/site-gateways.tsv:
   #   <site_id>\t<cred_path>\t<port|->\t<site_name>
   bash .claude/skills/unifi-wifi/scripts/gateway-map.sh validate    # confirm the row resolves
   ```
3. Verify: `bash .../scripts/gw-audit.sh '<UOS site name>'` auto-selects the pfSense backend;
   `bash .../scripts/gw-control.sh '<site>' fw-list` lists its rules. One-off without a map row:
   add `--pfsense <slug-or-vault-path>`.

---

## Quick readiness check
```bash
bash .claude/skills/unifi-wifi/scripts/sites.sh            # AP-cred readiness + gateway map
bash .claude/skills/unifi-wifi/scripts/gateway-map.sh suggest   # unmapped pfSense sites + unbound creds
```
