initial commit

CLAUDE.md

@@ -0,0 +1,648 @@
+# CLAUDE.md
+
+Reference document for future Claude sessions (and humans reading the
+repo cold). Captures what's actually built, the MCMS API quirks
+discovered along the way, and the things that don't work or were
+deliberately skipped.
+
+For run instructions and user-facing scope, see `README.md` — this file
+is the engineering counterpart.
+
+---
+
+## 1. What this app does
+
+Electron desktop client for bulk ONU firmware upgrades against **Ciena
+MCMS 6.2** PON Manager. Reference deployment: GNXS / Tibit MicroPlug ONUs
+running Interos Everest (EV051xxR / EV052xxR firmware family).
+
+End-to-end operator workflow:
+
+1. Connect with email + password against the MCMS web URL.
+2. Browse the ONU fleet with rich filters (status, down-duration,
+   version, equipment ID, PON mode).
+3. Either select ONUs and continue to the upgrade campaign view, **or**
+   delete stale ONUs (Deregistered / Dying Gasp / etc.) from MCMS.
+4. In the campaign view: pick a firmware `.bin` already uploaded to
+   `/files/onu-firmware/` (or upload one), preview the planned writes,
+   and commit. The Preview step also runs a FEC pre-flight health
+   check on every selected ONU.
+5. On Execute, the plan is auto-saved as a CSV to `~/Downloads/`.
+6. After the upgrade has had time to roll, open the saved CSV in the
+   verify view to compare before/after and auto-save a verification
+   CSV alongside.
+
+---
+
+## 2. Quickstart
+
+```bash
+cd pon-fleet-upgrader
+npm install
+npm start          # launch Electron
+npm run check      # node --check on every JS file (cheap smoke test)
+```
+
+Environment:
+
+- `PON_FLEET_VERBOSE=0` — silence the per-request log lines in the
+  Electron terminal. Default is verbose because the log dumps headers
+  and full response bodies on non-2xx, which has been invaluable for
+  debugging.
+
+DevTools: **Ctrl+Shift+I** (Cmd+Opt+I on macOS). Reload renderer after
+editing `renderer/`: **Ctrl+R**.
+
+---
+
+## 3. Architecture
+
+Standard Electron three-process model with strict isolation:
+
+```
++-----------+   IPC invoke    +-----------+   HTTPS    +-----------+
+| Renderer  | ──────────────► |   Main    | ────────►  |   MCMS    |
+| (browser) |  via preload    |  (Node)   |            |  (web UI) |
++-----------+ ◄─────────────  +-----------+ ◄────────  +-----------+
+                streaming events / responses
+```
+
+- **Renderer** (`renderer/app.js`, `index.html`, `app.css`) — vanilla
+  DOM, no framework. Calls into `window.api.*` exposed by the preload.
+  Has no Node access and never sees raw cookies.
+- **Preload** (`preload.js`) — `contextBridge` whitelist; the only
+  bridge from renderer to main. Adding a new IPC channel requires
+  touching this file.
+- **Main** (`main.js`) — owns the `McmsClient`, the cookie jar, file
+  IO, and the Electron `dialog` / `app.getPath()` APIs.
+- **MCMS client** (`src/mcms-api.js`) — raw `https` + `tough-cookie`.
+  No third-party HTTP client; the only npm dep is `tough-cookie`. See
+  §5 for the quirks this client works around.
+- **Bank strategy** (`src/bank-strategy.js`) — pure logic for picking
+  the inactive bank to write to. See §7.
+
+### File layout
+
+```
+pon-fleet-upgrader/
+├── package.json                # electron, tough-cookie, npm scripts
+├── main.js                     # Electron main process + IPC handlers
+├── preload.js                  # contextBridge whitelist
+├── README.md                   # user-facing run docs
+├── CLAUDE.md                   # this file
+├── src/
+│   ├── mcms-api.js             # HTTPS client, FEC extractor, time helpers
+│   └── bank-strategy.js        # inactive-bank + plan computation
+└── renderer/
+    ├── index.html              # login / fleet / campaign / verify views
+    ├── app.css                 # dark theme, status pill classes
+    └── app.js                  # UI state, all renderer logic
+```
+
+### IPC channel list
+
+All channels are `invoke`-style (request/response). A few additionally
+stream progress events back to the renderer.
+
+| Channel | Purpose | Streams |
+|---|---|---|
+| `api:login` / `api:logout` | session auth | — |
+| `api:listFleet` | ONU-CFG + ONU-STATE + OLT-STATE merged | — |
+| `api:fetchStates` | per-ONU state fallback if bulk failed | `states:progress` |
+| `api:listOnuConfigs` / `api:getOnuConfig` | direct CFG access | — |
+| `api:listOnuFirmware` / `api:uploadFirmware` | firmware inventory | — |
+| `api:planUpgrade` | dry-run plan for selected ONUs | — |
+| `api:executePerOnu` | Procedure 7 — per-ONU PUTs | `upgrade:progress` |
+| `api:executeBulkTask` | Procedure 8 — single AUTO-TASK-CFG | — |
+| `api:getTaskConfig` / `api:getUpgradeStatus` | poll helpers | — |
+| `api:deleteOnus` | bulk delete (CFG + best-effort STATE) | `delete:progress` |
+| `api:fetchFecHealth` | pre-flight FEC pre/post + optical | `fec:progress` |
+| `api:savePlanCsv` | auto-save plan on Execute | — |
+| `api:saveCsvFile` | generic CSV writer | — |
+| `api:openCsvFile` | open dialog → return text | — |
+| `api:fetchOnuSnapshot` | verify-flow: state + cfg per ONU | `verify:progress` |
+
+---
+
+## 4. Features actually implemented
+
+### Fleet view
+
+- Login with email / password, accept-self-signed-TLS toggle (essential
+  for lab MCMS installs).
+- Bulk fleet load: `listAllOnuConfigs` + `listAllOnuStates` +
+  `listAllOltStates`, all paginated via the `next` cursor at page size
+  100 (see §5).
+- Filters: text (name/address/serial), Equipment ID, PON mode,
+  active version, exclude active version, model/version family,
+  registration status (incl. "Down" aggregate and "Unknown" buckets),
+  down-for-at-least-N-days.
+- Columns: serial, name/address, equipment ID, PON mode,
+  **status** (colour-coded from OLT-STATE bucket), **last seen**
+  (relative time from `ONU-STATE.Time`), active slot, active version,
+  inactive version.
+- Bulk select / clear / select-all-matching.
+- **Delete** — `DELETE /v1/onus/configs/<id>/` per ONU at concurrency 5,
+  then best-effort `DELETE /v1/onus/states/<id>/`. Two-step confirm
+  (alert + typed `DELETE`). Streams progress per ONU.
+
+### Campaign view
+
+- Firmware picker bound to `/files/onu-firmware/`, inferring version
+  from filename (regex `[A-Z]{2}\d{5}[A-Z]?`).
+- Upload firmware via Electron `dialog.showOpenDialog`.
+- Execution mode toggle: **bulk task** (Procedure 8 — recommended) or
+  **per-ONU PUT** (Procedure 7 — per-device feedback).
+- Scheduled-start datetime-local picker (converts local → UTC string
+  `YYYY-MM-DD HH:MM:SS`).
+- **Dry-run preview** with FEC pre-flight: each selected ONU is
+  re-fetched (`getOnuState`) at preview time, and the resulting FEC
+  pill + optical levels + raw counters are rendered in a new column.
+- **CSV auto-save on Execute** — writes
+  `~/Downloads/pon-upgrade-<version>-<mode>-<count>onus-<stamp>.csv`
+  the moment Execute is clicked, *before* any MCMS write. See §10.
+- Soft FEC gate in the Execute confirmation dialog: warns (but doesn't
+  block) when any selected ONU is showing post-FEC errors or the
+  pre==post buggy signature.
+
+### Verify view (after-upgrade comparison)
+
+- **Open plan CSV…** — file dialog defaulted to `~/Downloads`. Parser
+  is lenient — needs only an `ONU ID` column, everything else is
+  optional.
+- For each ONU listed, fetches **both** ONU-STATE (fresh FEC + optical)
+  and ONU-CFG (to confirm `FW Bank Ptr` flipped and the active version
+  now equals the recorded target). Concurrency 8.
+- Renders a comparison table with target→active, "Applied?" badge,
+  before/after FEC pills + counters, before/after optical RX/TX, and
+  a one-line verdict per ONU.
+- **Auto-saves** the comparison to
+  `~/Downloads/pon-verify-<trailing-of-source>-<stamp>.csv` the moment
+  the comparison finishes, so it sorts next to the original.
+- Side-panel summary: counts of applied/not-applied, fixed/improved,
+  still-buggy, regressed, still-healthy.
+
+### FEC health rules
+
+(`extractOnuHealth` in `src/mcms-api.js`)
+
+| Flag | Meaning | Trigger |
+|---|---|---|
+| `ok` | green | All four FEC counters present and 0 |
+| `pre` | yellow | Any pre-FEC counter > 0, all post-FEC = 0 |
+| `post` | red | Any post-FEC counter > 0 (uncorrected errors) |
+| `buggy` | blue | ONU pre>0 AND post>0 AND `post/pre >= 0.95` |
+| `nodata` | grey | No FEC counters found in STATS |
+| `error` | grey | Per-ONU fetch threw |
+
+**Buggy detection note.** Real-world example from a GNXS Everest ONU:
+`Pre-FEC BER = 22,388,041,291`, `Post-FEC BER = 22,379,111,198`. Those
+differ by 0.04%, which is well into "FEC isn't doing anything" territory.
+Exact-equality detection would miss this; the 0.95 ratio threshold
+catches it. The condition is intentionally one-sided — we treat ONU
+side as the bug source (the OLT side counters are computed by the OLT
+firmware which we trust).
+
+### Optical thresholds
+
+From the PON Manager User Guide green-LED criteria (323-1961-302 p149):
+
+| Field | Green | Yellow | Red |
+|---|---|---|---|
+| ONU RX | ≥ −28 dBm | −28 to −30 dBm | < −30 dBm |
+| ONU TX | ≥ 3 dBm | — | < 3 dBm |
+
+Yellow is a margin band we added — the user guide is binary (≥ −30 vs
+< −30), but operators want a warning before the link is actually broken.
+
+---
+
+## 5. MCMS API quirks
+
+These are the gotchas worth knowing. Many were diagnosed empirically
+against MCMS 6.2 + Interos Everest 5.11/5.12. **If something behaves
+oddly, check this section first.**
+
+### 5.1 User-Agent header is required
+
+Node's `https.request` doesn't send a User-Agent by default. **Some MCMS
+middleware dereferences `HTTP_USER_AGENT` without a guard and 500s when
+it's absent.** Reproducible via `curl -A '' https://mcms/api/v3/...`.
+
+→ `src/mcms-api.js` sends `User-Agent: pon-fleet-upgrader/0.1.0` on
+every request. Do not remove.
+
+### 5.2 CSRF cookie name is `__Host-csrftoken`
+
+MCMS 6.2 uses RFC 6265bis `__Host-` cookie prefix (Secure + Path=/).
+The cookie names are:
+
+- `__Host-csrftoken`
+- `__Host-sessionid`
+- `__Host-sessionexpire`
+
+Older MCMS builds shipped bare `csrftoken`. The client looks for both:
+
+```js
+const csrf = jarCookies.find(
+  (c) => c.key === 'csrftoken' || c.key === '__Host-csrftoken',
+);
+```
+
+The token value still goes in the `X-CSRFToken` header (no prefix).
+
+### 5.3 Pagination: use `next`, not `skip`
+
+`/v3/onus/configs/?skip=N` has been observed returning HTTP 500 on this
+MCMS build. Use the `next` cursor: pass the last document's `_id` as
+the `next` query param to get the page that *excludes* all IDs up to
+and including that one.
+
+→ See `McmsClient._listPaginatedByNext`.
+
+### 5.4 Bulk-list page size 100
+
+`/v3/onus/configs/?limit=1000` times out at the Apache front-end on
+~1500-ONU fleets, before Django even logs the request. Full ONU-CFG
+documents are ~30 KB each, so a 1000-row page is ~30 MB and the proxy
+gives up.
+
+→ Default page size is 100. Each response is ~3 MB and lands in well
+under the proxy timeout.
+
+### 5.5 Path prefix is `/api/v1/...`
+
+The dev guide writes "GET `/v1/users/authenticate/`" as shorthand. The
+real HTTP path is `/api/v1/users/authenticate/`. The client normalises
+this internally — pass either form.
+
+### 5.6 Request body envelope
+
+PUT/POST bodies are wrapped: `{ "data": { ...payload } }`. The login
+endpoint accepts both wrapped and unwrapped on observed builds (the
+client tries wrapped first, falls back on 400). Everything else is
+strictly wrapped.
+
+### 5.7 PUT is full-document replace, not patch
+
+`PUT /v1/onus/configs/<id>/` replaces the entire `ONU-CFG`. The client
+fetches the doc, mutates the FW fields in place, and PUTs the result.
+**Do not use PATCH** — MCMS PATCH endpoints are not used by this app
+and the dev guide is explicit about PUT-as-replace for CFG updates.
+
+### 5.8 Timestamp format
+
+MCMS emits and accepts: `"YYYY-MM-DD HH:MM:SS[.ffffff]"` in **UTC**
+with a literal space separator (not ISO-8601 `T`).
+
+Used on: `ONU-STATE.Time`, alarm timestamps,
+`AUTO-TASK-CFG.Task.Scheduled Start Time`, query-param timestamps.
+
+→ Helpers in `src/mcms-api.js`: `formatMcmsTime(date)` and
+`parseMcmsTime(str)`. The renderer also coerces the space-form to ISO
+before passing to `new Date()` to avoid Node's local-time
+interpretation.
+
+### 5.9 Server-side filtering on `query`/`projection` is brittle
+
+Mongo-style server filters get rejected (or silently return nothing)
+when the URL-encoded JSON has spaces in field names, certain escape
+patterns, or projection paths that don't exist on every document
+version. **We load the full fleet and filter entirely client-side.**
+
+If you need server filtering, the safest pattern is no quotes around
+field names and `%20` for spaces (not `+`). The client's
+`_encodeQuery` uses `encodeURIComponent` for exactly this reason.
+
+### 5.10 ONU registration status lives on OLT-STATE, not ONU-STATE
+
+The 9 registration buckets (Registered, Deregistered, Dying Gasp,
+Disabled, Disallowed Admin/Error/Reg ID, Unspecified, Unprovisioned)
+appear under `OLT-STATE["ONU States"][bucket] = [onuId, ...]`. See
+323-1961-306 Procedure 2.
+
+→ `listAllOltStates` pulls these, and `api:listFleet` builds a
+`onuId → { status, oltMac }` map from the buckets. On duplicates we
+prefer a non-Registered bucket (the interesting signal).
+
+### 5.11 FEC counters live on ONU-STATE, not `/onus/stats/`
+
+`/v1/onus/stats/<id>/` is the time-series PM collection — `start-time`
+is required, returns historical samples. **The current FEC/optical
+values are already in ONU-STATE:**
+
+```
+state_collection.STATS["ONU-PON"]["RX Pre-FEC BER"]
+state_collection.STATS["ONU-PON"]["RX Post-FEC BER"]
+state_collection.STATS["ONU-PON"]["RX Optical Level"]    # dBm
+state_collection.STATS["ONU-PON"]["TX Optical Level"]    # dBm
+state_collection.STATS["OLT-PON"]["RX Pre-FEC BER"]
+state_collection.STATS["OLT-PON"]["RX Post-FEC BER"]
+```
+
+→ The pre-flight fetch (`api:fetchFecHealth`) and the verify fetch
+(`api:fetchOnuSnapshot`) both call `getOnuState(id)` and extract via
+`extractOnuHealth`. The time-series stats endpoint is **not used**
+anywhere — earlier code that hit it has been removed.
+
+`extractOnuHealth` accepts both shapes: the bare state doc
+(`{STATS: ...}`) and the UI-helper wrapped form
+(`{state_collection: {STATS: ...}}`), since `/api/onu/summary` returns
+the wrapped shape.
+
+### 5.12 Login body shape
+
+The PON Manager web app POSTs `{"data": {"email": ..., "password": ...}}`
+to `/v1/users/authenticate/`. Some build variants accept the unwrapped
+form too — the client tries wrapped first.
+
+---
+
+## 6. ONU-STATE schema cheat-sheet (observed, not specced)
+
+The MCMS dev guide doesn't formally document the ONU-STATE shape on this
+build. From observation on GNXS / Interos Everest ONUs:
+
+```jsonc
+{
+  "_id": "GNXS05057fee",          // serial / device ID
+  "Time": "2026-05-04 21:51:57.394127",  // last update (UTC)
+  "ONU": {
+    "Equipment ID": "FT-XGS2110",
+    "Vendor": "GNXS",
+    "PON Mode": "GPON",
+    "FW Bank Files":    ["...bin", "...bin"],
+    "FW Bank Versions": ["EV05110R", "EV05100R"],
+    "FW Bank Ptr": 0,             // active slot (0 | 1 | 65535)
+    "FW Version": "EV05110R",
+    "FW Upgrade Status": { /* progress, status, etc */ },
+    // ...
+  },
+  "STATS": {
+    "ONU-PON": {
+      "RX Pre-FEC BER":  22388041291,
+      "RX Post-FEC BER": 22379111198,
+      "RX Optical Level": -17.544,   // dBm
+      "TX Optical Level": 5.532       // dBm
+    },
+    "OLT-PON": {
+      "RX Pre-FEC BER":  0,
+      "RX Post-FEC BER": 0,
+      "TX Optical Level": 5.6,
+      "RX Optical Level": -18.3
+    },
+    "ONU-EnhancedFecPmHistData-32769": {  // NOT used by extractor —
+      "uncorrectable_code_words": 1829,   // these are corrected/
+      "corrected_bytes": 181,             // uncorrectable code-word
+      "corrected_code_words": 181         // counts, not BER values
+    },
+    // ... many more sub-objects
+  }
+}
+```
+
+The renderer's display field `Equipment ID` is sometimes also on the CFG,
+not just the STATE — `equipmentId(cfg)` in `app.js` checks both paths.
+
+---
+
+## 7. Firmware bank semantics
+
+(Full version of the table in `README.md`.)
+
+ONU has two flash slots. `FW Bank Ptr` identifies the active one.
+MCMS triggers a firmware download by:
+
+1. Writing the new file + version into the target slot's
+   `FW Bank Files[slot]` / `FW Bank Versions[slot]`.
+2. Setting `FW Bank Ptr` to that slot.
+
+The ONU then downloads, and on completion MCMS flips `FW Bank Ptr` to
+the new slot (so the ONU boots into the new image on its next reboot).
+
+The bank-strategy module always writes to the **inactive** slot. If
+`FW Bank Ptr` is unset (65535) it writes to slot 1, leaving slot 0 as
+the factory fallback.
+
+For the bulk-task path (Procedure 8), MCMS needs a single bank number
+per task. So if a selection has ONUs with different active banks, we
+bucket by `writeSlot` and create one task per bucket — each task has
+a Procedure-8-shaped `AUTO-TASK-CFG.Task Details.ONU.FW Bank Ptr`.
+
+---
+
+## 8. CSV file formats
+
+Both kinds of CSV the app produces are written with the same
+`writeCsvFile` helper in `main.js`:
+
+- Always UTF-8 BOM (Excel auto-detects encoding → Norwegian Æ/Ø/Å
+  survive on Windows).
+- Always CRLF line endings.
+- Every cell quoted (defensive against commas in addresses, embedded
+  quotes in operator-typed names, embedded newlines from copy/paste).
+- Saved to `app.getPath('downloads')` (`~/Downloads` on macOS/Linux,
+  `C:\Users\<you>\Downloads` on Windows).
+
+### Plan CSV — `pon-upgrade-<hint>-<stamp>.csv`
+
+Auto-saved when Execute is clicked, **before** any MCMS write — so
+even if the API call fails mid-way there's a record of intent.
+
+Columns (20): ONU ID, Name, Address, PON Mode, Active slot (before),
+Write slot (target), Slot 0 version (before), Slot 1 version (before),
+Target version, Target file, FEC health, ONU RX Pre-FEC BER,
+ONU RX Post-FEC BER, OLT RX Pre-FEC BER, OLT RX Post-FEC BER,
+ONU RX Optical (dBm), ONU TX Optical (dBm), FEC sample time, Mode, Notes.
+
+The hint is derived from `<targetVersion>-<mode>-<count>onus`.
+
+### Verify CSV — `pon-verify-<sourcehint>-<stamp>.csv`
+
+Auto-saved after the verify comparison finishes. Hint reuses the
+trailing descriptor of the source CSV (strip `pon-upgrade-` prefix and
+`.csv` suffix), so the verify file sorts next to its source in the
+filesystem.
+
+Columns (23): identifiers, Target version, Active version (after),
+Upgrade applied?, FEC health (before), FEC health (after), all four
+BER counters before+after (ONU + OLT, pre + post), ONU RX/TX optical
+before+after, After sample time, Verdict, Fetch error.
+
+### Verdict strings (in the Verify CSV)
+
+| Verdict | Trigger |
+|---|---|
+| `fixed (was buggy)` | `buggy → ok` |
+| `still buggy (firmware bug persists)` | `buggy → buggy` |
+| `improved (no longer mirroring counters)` | `buggy → pre` |
+| `changed: now reporting genuine post-FEC errors` | `buggy → post` |
+| `still healthy` | `ok → ok` |
+| `improved` | `pre|post → ok` |
+| `improved (post→pre)` | post→pre |
+| `regressed (now post-FEC errors)` | `ok → post` |
+| `regressed (now buggy)` | `ok → buggy` |
+| `regressed (now marginal)` | `ok → pre` |
+| `regressed (pre→post)` | pre→post |
+| `still has post-FEC errors` | `post → post` |
+| `still marginal (pre-FEC only)` | `pre → pre` |
+| `upgrade NOT applied (active version unchanged)` | `cfg.activeVersion !== target` |
+| `fetch failed` | per-ONU snapshot threw |
+| `no current FEC data` | flag=nodata |
+
+**The raw before/after counter values are misleading on their own**
+because ONU FEC counters typically reset on the upgrade reboot. The
+verdict is computed from the **flag transition**, not the delta.
+
+---
+
+## 9. Known limitations / not implemented
+
+- **No task-progress polling.** Once a bulk task is submitted, MCMS
+  owns the rollout and the app doesn't poll `/v3/tasks/states/<id>/`.
+  Operators use the verify view (or the PON Manager UI) to confirm.
+- **No post-execute results CSV.** The plan CSV captures intent
+  pre-write. Per-ONU success/failure (in Procedure 7 mode) and task
+  submission errors (in Procedure 8 mode) are visible on screen but
+  not dumped to disk. Add-on candidate.
+- **No offline / cached fleet snapshot.** Every `Load fleet` hits MCMS.
+- **`/v1/onus/<id>/upgrade/status/`** is referenced in some MCMS spec
+  documents but returns 404 on this build. Fallback: poll
+  `GET /v1/onus/configs/<id>/` and watch `FW Bank Versions` /
+  `FW Bank Ptr` flip.
+- **PATCH not used** — MCMS requires full-document PUT for CFG updates
+  (dev guide is explicit about this).
+- **Server-side query/projection not used** — see §5.9.
+- **No time-series PM data shown.** We use the live snapshot from
+  ONU-STATE (§5.11). `GET /onus/stats/<id>/` exists but is not wired
+  up.
+- **No retries on transient HTTP errors** beyond the per-ONU
+  best-effort delete-state. Bulk delete and per-ONU PUTs surface
+  errors per row but don't auto-retry.
+- **Schedule field is UTC only.** The datetime-local picker converts
+  from the browser's local TZ. Operators in different TZs see different
+  inputs producing the same `Scheduled Start Time` value in the task —
+  intentional, but worth noting.
+
+---
+
+## 10. Conventions
+
+### Adding a new IPC channel
+
+Touch three files in order:
+
+1. **`src/mcms-api.js`** — add the method on `McmsClient` if it talks
+   to MCMS.
+2. **`main.js`** — `ipcMain.handle('api:foo', ...)`. Wrap errors via
+   `toWireError` so the renderer never sees stack traces.
+3. **`preload.js`** — add `foo: (opts) => call('api:foo', opts)` to
+   the `window.api` contract. **The renderer cannot call channels not
+   listed here.**
+4. **`renderer/app.js`** — use `window.api.foo(...)`.
+
+For streaming progress events, also add an `onFooProgress(handler)`
+function in the preload (returns an unsubscribe function).
+
+### CSS conventions
+
+Status colour classes (declared in `app.css`):
+
+| Class | Meaning | CSS var |
+|---|---|---|
+| `.status-ok` | success / healthy | `--ok` (green) |
+| `.status-warn` | margin / pre-FEC | `--warn` (yellow) |
+| `.status-err` | failure / post-FEC / regressed | `--danger` (red) |
+| `.status-info` | informational / buggy ONU | `--info` (blue) |
+| `.status-pending` | in-flight / unknown | `--fg-dim` (grey) |
+| `.muted` | secondary text | `--fg-dim` (grey) |
+
+`.fec-cell` and `#verify-table tbody td` override
+`white-space: nowrap` to allow stacked content (pill on top, counters
+underneath).
+
+### Verbose logging
+
+`McmsClient(verbose: true)` (default in this app) logs every request:
+
+- Method + path + cookie names (cookie values redacted)
+- All outgoing headers (`X-CSRFToken` redacted)
+- On non-2xx: full response headers + full response body
+
+The combination is enough to diff against a working `curl` for
+"why is this 500?" investigations. **Turn off via
+`PON_FLEET_VERBOSE=0`** if logs are leaking secrets to a shared
+terminal.
+
+---
+
+## 11. Testing
+
+There's no formal test runner. Two cheap signals:
+
+1. `npm run check` — `node --check` on every JS file. Catches syntax
+   errors before launching Electron.
+2. Inline `node -e '...'` fixtures for pure functions (FEC extractor,
+   CSV roundtrip, verdict logic). Vendor the function bodies into the
+   test snippet rather than importing from `renderer/app.js` — that
+   file expects `window` / `document`.
+
+When refactoring `extractOnuHealth`, re-test against the GNXS
+real-world fixture (post=22379111198, pre=22388041291): it must flag
+as `buggy`. That ratio (0.9996) is the edge case the 95% threshold
+was designed to catch.
+
+---
+
+## 12. Reference documents
+
+Stored alongside the project in the parent `PON-API` folder:
+
+- `323-1961-306_mcms_6_2_rest_api_developer_guide.pdf` — REST API
+  reference. Cited as "the dev guide".
+- `323-1961-302_mcms_6_2_pon_manager_user_guide.pdf` — UI guide.
+  Procedures 7, 8, 38, 43 referenced from code comments.
+- `323-1963-105_mcms_6_2_onu_planning_guide.pdf` — ONU planning
+  context (PON design, link budgets).
+
+Key procedure citations:
+
+- **Procedure 2** (REST API dev guide) — determining ONU registration
+  status via OLT-STATE buckets.
+- **Procedure 7** (REST API dev guide) — per-ONU firmware upgrade via
+  full-doc PUT.
+- **Procedure 8** (REST API dev guide) — bulk firmware upgrade via
+  `AUTO-TASK-CFG`.
+- **Procedure 38** (PON Manager User Guide) — Resetting bit error
+  rate values; identifies the four FEC counters in the UI.
+- **Procedure 43** (PON Manager User Guide) — Deleting an ONU.
+
+---
+
+## 13. History / non-obvious design choices
+
+- **CSV is auto-saved BEFORE the API write, not after.** Intentional:
+  capture intent even if the write fails. A "results CSV" with
+  per-ONU success/failure is an obvious add-on but not yet wired.
+- **Plan CSV uses 20 columns even for trivial cases.** Wide is fine
+  for spreadsheets; narrow forces splits later.
+- **FEC pre-flight only runs on the selection, not the fleet.**
+  Originally implemented to query the whole fleet at preview time,
+  but operator preference is "right before commit, not for the
+  entire fleet" — keeps `/v3/onus/states/<id>/` calls bounded to N
+  selected.
+- **Buggy detection uses ratio, not equality.** See §4 — real
+  observed buggy pairs aren't bit-identical (timing windows differ),
+  so `post == pre` misses the case. `post / pre >= 0.95` catches it.
+- **Optical thresholds add a yellow margin band** beyond the user
+  guide's binary green/red. Operators want a warning before a link
+  actually fails.
+- **`__Host-` cookie prefix support was added retroactively** —
+  initial code only matched `csrftoken`, causing intermittent 500s
+  on session refresh.
+- **User-Agent header was the root cause of one prolonged debugging
+  session.** Documented in §5.1 so we don't lose that knowledge.
+
+---
+
+*Last updated: 2026-05-26.*