From ac62fe47a27fb9e7109b7ce20dfc069c9797ea3d Mon Sep 17 00:00:00 2001 From: Lior Date: Tue, 26 May 2026 18:58:13 -0400 Subject: [PATCH] =?UTF-8?q?docs(backlog):=20B-0832=20=E2=80=94=20installer?= =?UTF-8?q?=20nmtui=20WiFi=20rescan/refresh=20path=20(empirical=20anchor?= =?UTF-8?q?=20from=20physical=20hardware-support=20test=202026-05-26;=2020?= =?UTF-8?q?+=20overlapping=20networks)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First empirical UX feedback from operator's physical hardware-support test 2026-05-26 — validates B-0831's reframing of physical-test as first-class hardware-compatibility-matrix substrate. Per operator: "in the network manager i can refresh wifi connections if i don't see mine initially i have like 20 overlapping networks in my location so i was unable to select the one i wanted but moving foward but we need some sort of way to refresh thoughs?" Issue: zeta-first-boot service auto-launches nmtui when no ethernet; in dense-WiFi environments (20+ networks) the initial scan may miss target SSID; nmtui has no obvious rescan path. 3-layer mitigation approaches scoped (smallest first): - Approach A: documentation banner before nmtui launch naming F5 rescan + Esc re-launch paths - Approach B: pre-scan + post-nmtui re-launch loop in zeta-first-boot - Approach C: bypass nmtui entirely; prompt-driven nmcli flow P2 priority — UX friction, not hard blocker (operator continued the test via "moving forward" workaround). Composes_with B-0831 (this row IS the empirical validation that B-0831 predicted: physical hardware-support test surfaces real-world issues CI emulation cannot reproduce — QEMU has no concept of dense-WiFi channel-contention). Co-Authored-By: Claude Opus 4.7 --- docs/BACKLOG.md | 1 + ...26-05-26-physical-hardware-support-test.md | 158 ++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 docs/backlog/P2/B-0832-installer-nmtui-wifi-rescan-refresh-button-overlapping-networks-empirical-aaron-2026-05-26-physical-hardware-support-test.md diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index f35ab6ed2e..2e07e7d57f 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -765,6 +765,7 @@ are closed (status: closed in frontmatter)._ - [ ] **[B-0827](backlog/P2/B-0827-runme-md-jit-triage-three-register-cells-pattern-runbook-as-evolving-substrate-aaron-kestrel-2026-05-26.md)** runme.md + JIT triage 3-register-cell workflow pattern — runbook as evolving substrate - [ ] **[B-0828](backlog/P2/B-0828-multi-ai-shared-checkout-convention-human-maintainer-surface-plus-always-up-to-date-main-for-society-aaron-2026-05-26.md)** Multi-AI shared-checkout convention — human-maintainer surface + always-up-to-date-with-main for society - [ ] **[B-0829](backlog/P2/B-0829-schemas-as-rows-cluster-fork-as-trust-boundary-fsharp-type-providers-from-live-cluster-foundation-for-runme-bcl-ontology-kestrel-aaron-2026-05-26.md)** Schemas-as-rows + cluster-fork-as-trust-boundary + F# type providers from live cluster — foundation layer for Runme BCL ontology capability +- [ ] **[B-0832](backlog/P2/B-0832-installer-nmtui-wifi-rescan-refresh-button-overlapping-networks-empirical-aaron-2026-05-26-physical-hardware-support-test.md)** installer nmtui WiFi step needs visible rescan/refresh path — empirical from operator's physical hardware-support test 2026-05-26 (20+ overlapping networks; target SSID not initially in scan list) (Aaron 2026-05-26) ## P3 — convenience / deferred diff --git a/docs/backlog/P2/B-0832-installer-nmtui-wifi-rescan-refresh-button-overlapping-networks-empirical-aaron-2026-05-26-physical-hardware-support-test.md b/docs/backlog/P2/B-0832-installer-nmtui-wifi-rescan-refresh-button-overlapping-networks-empirical-aaron-2026-05-26-physical-hardware-support-test.md new file mode 100644 index 0000000000..e41132fef8 --- /dev/null +++ b/docs/backlog/P2/B-0832-installer-nmtui-wifi-rescan-refresh-button-overlapping-networks-empirical-aaron-2026-05-26-physical-hardware-support-test.md @@ -0,0 +1,158 @@ +--- +id: B-0832 +priority: P2 +status: open +title: installer nmtui WiFi step needs visible rescan/refresh path — empirical from operator's physical hardware-support test 2026-05-26 (20+ overlapping networks; target SSID not initially in scan list) (Aaron 2026-05-26) +effort: S +ask: aaron 2026-05-26 +created: 2026-05-26 +last_updated: 2026-05-26 +depends_on: + - B-0754 +composes_with: + - B-0831 +tags: [installer, first-boot, networkmanager, nmtui, wifi, physical-hardware-support-test, empirical-anchor, operator-ux] +--- + +## Problem + +Empirical from operator's physical hardware-support test 2026-05-26 +(the first physical test post-zflash; B-0831 reframing — +physical-test-becomes-hardware-support-test in action): + +Operator framing: *"in the network manager i can refresh wifi +connections if i don't see mine initially i have like 20 overlapping +networks in my location so i was unable to select the one i wanted but +moving foward but we need some sort of way to refresh thoughs?"* + +The installer's zeta-first-boot service (per `full-ai-cluster/usb-nixos-installer/zeta-first-boot.sh`) +auto-launches `nmtui` if no ethernet internet is detected. In nmtui's +"Activate a connection" view, the WiFi scan happens at launch and the +list is populated once. In dense-WiFi environments (operator's +location has 20+ overlapping networks), the initial scan may not +include the target SSID — either because the scan completed before the +target AP responded, OR because the dense channel-contention dropped +the target AP's beacon during the scan window. + +nmtui has no obvious refresh/rescan button visible in the activate +view. The operator was unable to select their target network on the +first scan. The mitigation operator used: "moving forward" (probably +proceeded with another method, possibly ethernet attempt OR retry). + +## Proposed mitigation + +Three layered approaches, pick smallest first: + +### Approach A — document the existing rescan keybind + +Per `nmtui` docs, `` or `` may trigger rescan in some +versions, OR exiting nmtui + relaunching forces a fresh scan. Add a +banner before nmtui launches: + +```text +TIP: If your WiFi network is not in the list, press to rescan. + If that does not work, press to exit nmtui and the + installer will re-launch it with a fresh scan. +``` + +This is documentation-only; no code change beyond the banner text. + +### Approach B — pre-scan + re-launch loop in zeta-first-boot + +Modify `zeta-first-boot.sh` to: + +1. Run `nmcli device wifi rescan` BEFORE launching nmtui (warms up the + scan list) +2. After nmtui exits, if no connection was established, offer to + re-launch (with an explicit `nmcli device wifi rescan` between + launches) + +This adds a small loop but eliminates the operator's typing burden if +the first scan misses the target. + +### Approach C — bypass nmtui for WiFi entirely; use nmcli directly + +Replace the nmtui invocation with a prompt-driven nmcli flow: + +1. Run `nmcli device wifi rescan` +2. `nmcli device wifi list` (filtered + sorted by signal strength) +3. Prompt operator for SSID +4. Prompt for password +5. `nmcli device wifi connect password ` + +Removes the nmtui dependency entirely; more controlled UX but more +code in `zeta-first-boot.sh`. + +## Acceptance + +Approach A acceptance (minimum): + +- Banner appears before nmtui launches naming the F5 + Esc re-launch + paths +- Physical hardware-support test in dense-WiFi environment confirms + operator can rescan + find target SSID within ~30 seconds + +Approach B acceptance (preferred): + +- All Approach A criteria +- `nmcli device wifi rescan` runs before nmtui launch (warmed scan + list) +- If nmtui exits without connection established, re-launch loop fires + with explicit rescan between launches +- Maximum 3 re-launches before falling back to manual operator + intervention + +Approach C acceptance (deferred): + +- Full nmcli-driven WiFi flow replaces nmtui +- Operator types only SSID + password (no nmtui keyboard navigation) +- Composes with broader 0-human-typing direction at install scope + +## Composes with + +- `full-ai-cluster/usb-nixos-installer/zeta-first-boot.sh` (the + substrate this row touches) +- B-0754 (zero-typing first-boot scope; this row extends the + zero-typing path to dense-WiFi environments) +- B-0831 (CI cascade #6 full-install + cluster-auto-join — physical + hardware-support test that surfaced this issue is exactly the + reframed role for physical tests per B-0831) +- nmtui upstream documentation (verify F5/Ctrl+R keybind across + nmtui versions on nixpkgs 25.11) +- Physical hardware-support-test as first-class substrate + (operator-driven; surfaces real-world UX issues like dense-WiFi + environments that CI cascade #6 cannot emulate) + +## Substrate-honest framing + +This row is empirically-anchored: operator literally hit the issue +during their physical hardware-support test 2026-05-26 (the test that +B-0831 reframed as first-class hardware-compatibility-matrix substrate). + +The operator's "moving forward" indicates they have a workaround AND +the test continued — the issue is UX friction, not a hard blocker. +P2 priority reflects this: real UX issue worth fixing but doesn't +block the install flow. + +The dense-WiFi case (20+ overlapping networks) is increasingly common +(urban density, multi-tenant residential, office buildings) and the +fix benefits any operator in similar environments. + +This row IS what B-0831 predicted: physical hardware-support test +surfaces real-world issues that CI emulation cannot reproduce (QEMU +has no concept of dense-WiFi channel-contention). The substrate- +engineering value of physical-as-hardware-support-test is now empirically +validated. + +## Operational discipline for future-Otto cold-boots + +When operator forwards UX feedback from physical hardware-support +test: + +1. Capture verbatim (preserve operator framing in row body) +2. Identify the substrate location (script / module / config) the + issue touches +3. Layer mitigations smallest-first (Approach A → B → C) +4. Note priority based on whether issue blocks vs friction-only +5. Cross-ref to B-0831 (physical-as-hardware-support-test substrate) + so future cold-boots see the empirical anchor pattern