Panel P4.3: equipment hub — device registry, agent identity, guided setup wizards

.superpowers/sdd/p4.3-board-5a-5d-extract.md

@@ -0,0 +1,146 @@
+# P4.3 board extract — screens 5a–5d "Equipment hub"
+
+Source: `docs/design-briefs/idento-event-check-in-landing/project/Idento Panel.dc.html`,
+turn `t5` (lines 454–662), group headers: *"Hub — org-level page · this
+computer's agent + saved devices that survive reloads"* (5a, 5d) and
+*"Guided setup — one small flow per device class, replaces the 1,002-line
+wall"* (5b, 5c).
+
+Turn title: *"Equipment hub — agent as a citizen of the UI, per-device
+guided setup & test flows, honest disconnected state"*.
+
+## Placement in the board
+
+Unlike 2a–2d (a flow sequence) and 7e (a single screen), t5 is two pairs:
+the hub in its two agent states (5a connected / 5d down) and the two
+wizards (5b printer / 5c scanner). All four are fully drawn. The board's
+footer note (t5, monospace) is load-bearing:
+
+> "One AgentStatus model (1b) drives the hub card, the badge editor's
+> Test print (4a) and the launch ceremony (2a). Devices + the
+> default-printer rule live on the server per machine — reload-safe
+> (WEB-QUAL-04/05). Each device class gets its own 3-step flow (5b, 5c)
+> with a physical verification step; a passed printer test marks the
+> pipeline's Equipment step ready (1f)."
+
+## 5a — Equipment hub (1280px, full app chrome)
+
+- Full app shell: top nav with **Equipment tab active** (org-level page,
+  sibling of Events / Team / Organization) — matches the panel's existing
+  `/equipment` placeholder route.
+- Page header: `Equipment` h2 + inline caption *"Devices are per
+  computer — the agent on each machine talks to its own hardware."* +
+  right-aligned primary **"+ Add device"** button.
+- **Agent card** (green-tinted border `#c6e6d6`, full-width, above the
+  device grid): agent icon in a green tile; title **"Idento Agent — this
+  computer"** + green **Connected** pill (check icon + text);
+  mono subline `localhost:3000 · v1.8.2 · REG-DESK-01 · uptime 3 h 12 m`
+  (⇒ agent must expose version / hostname / uptime — none exist today);
+  right-aligned secondary button **"Agent settings"** (nothing behind it
+  anywhere on the board — no settings screen exists).
+- **Two-column device grid** below the agent card:
+  - **Printers card** (header: bold "Printers" + mono count `2` +
+    right-aligned green text-button **"+ Set up printer"**):
+    - Row 1 (highlighted: `#f6faf8` bg + 3px green left border): green
+      dot · **Zebra ZD421** + **DEFAULT** chip (small green bordered
+      badge) · mono meta `network · 192.168.1.44:9100 · 300 dpi · ribbon
+      OK` · secondary **Test print** button · `⋯` overflow menu.
+    - Row 2 (amber): amber dot · **Godex G500** `· backup` (muted
+      inline suffix on the name) · amber text *"Saved · not seen since
+      Jul 8 — check power & network"* · secondary **Retry** button · `⋯`.
+    - Card footer (gray strip): *"Default = what check-in stations on
+      this computer use. One rule, stored on the server."*
+  - **Scanners & cameras card** (header: bold "Scanners & cameras" +
+    mono `2` + green **"+ Set up scanner"**):
+    - Row 1: green dot · **Honeywell Voyager 1200g** · mono meta
+      `USB-HID · keyboard wedge · suffix: Enter` · **Test scan** · `⋯`.
+    - Row 2: green dot · **Built-in camera** · *"Fallback QR reader ·
+      permission granted"* · **Test scan** · `⋯`.
+    - Card footer: *"Saved devices persist on the server — a reload
+      never empties this list."*
+- Reading of the two states in the Printers card: green = saved device
+  currently visible to the live agent; amber = saved in the registry but
+  NOT currently visible ("not seen since <date>") — i.e. the hub
+  reconciles the server registry against the agent's live list and shows
+  per-device liveness with a date, never silently dropping saved rows.
+
+## 5d — Same hub, agent down (620px, content region only)
+
+- Label: *"Same hub, agent down — saved devices stay visible (grayed),
+  the failure explains itself · no more silent empty lists"*.
+- **Agent card in red** (`#f5cfcf` border, red icon tile): title
+  **"Agent not reachable"** + red **Disconnected** pill (✕ icon + text);
+  subline *"Printing and scanning are unavailable on this computer until
+  it's running."*
+- **"Start the agent" card**: numbered steps —
+  `1 · Find Idento Agent in the system tray — if missing, launch it from
+  the Start menu`, `2 · Still nothing? Download the agent for this
+  computer` (link) — then a primary **Retry connection** button + mono
+  caption **"auto-retry in 8 s"** (⇒ automatic reconnect polling with a
+  visible countdown).
+- **Saved devices at opacity .55**: Printers card header gains a muted
+  *"saved · unreachable"* caption; rows keep name + DEFAULT chip
+  (grayed) but dots go gray and all action buttons disappear. Only the
+  Printers card is drawn in the mock (620px crop) — the pattern applies
+  to both cards.
+- ⇒ Saved devices must be renderable WITHOUT the agent: the registry
+  (and the machine's identity) must be readable when the agent is down.
+
+## 5b — Printer setup wizard (700px, modal over dimmed bg)
+
+- Modal header: **"Set up a printer"** + inline 3-step progress
+  `✓ Find — 2 Test — 3 Save` (steps 1–2 green, 3 gray — the mock shows
+  the Test step) + ✕ close.
+- **Find result row** (green-tinted): green dot · **Zebra ZD421** · mono
+  `found on network · 192.168.1.44:9100 · 300 dpi` · right link
+  **"Enter IP manually"** (underlined escape hatch).
+- **Test block** (2-col): left — a test-label preview placeholder
+  (hatched, mono "test label"); right — bold **"Did the test label print
+  correctly?"** + copy *"A label with alignment marks and «Кириллица
+  123» is printing now. Check darkness, position and that the text is
+  readable."* + three buttons: primary **"Yes, looks right"**, secondary
+  **"Print again"**, amber-bordered **"Something's off…"**.
+- **Default checkbox** (checked in mock): *"Make this the default
+  printer for check-in stations on this computer"*.
+- Footer: secondary **"← Back"**, primary **"Save printer"**.
+- ⇒ Physical verification is IN the flow: a human confirms the label
+  before Save; the Cyrillic sample is deliberate (encoding truth).
+
+## 5c — Scanner setup wizard (700px, modal)
+
+- Modal header: **"Set up a scanner"** + segmented toggle
+  **"USB / COM scanner"** (active) | **"Camera"** + ✕ close.
+- **Listen panel** (large, dashed green border): scan-frame icon ·
+  bold **"Listening… scan any barcode now"** · copy *"Point the scanner
+  at the test code below or at any badge. We'll detect the input mode
+  and terminator for you."* · a drawn test barcode.
+- **Detection result row** (green-tinted): ✓ · **"Scan received —
+  `TEST-4471`"** · mono `keyboard wedge · suffix: Enter · 34 ms` ·
+  underlined **"Scan again"**.
+- **Two fields**: "Device name" text input (`Honeywell Voyager — desk
+  2`) · "Terminator" select showing `Enter · detected`.
+- Footer: secondary **Cancel**, primary **"Save scanner"**.
+- ⇒ The wedge test runs in the browser (keystroke capture + timing);
+  detection output = input mode + terminator + keystroke latency. The
+  toggle names COM in the same tab ("USB / COM scanner") — COM flows
+  through the agent's serial endpoints instead.
+
+## Cross-references the board makes
+
+- 1b: AgentStatus model (already shipped as `@idento/ui` agent-status).
+- 4a: badge editor Test print (P3.2 — already consumes useAgentPrinters).
+- 2a: launch ceremony (P4.1 — already consumes useAgentPrinters).
+- 1f: readiness pipeline Equipment step (backend stub `not_done` today).
+- WEB-QUAL-04/05: the audit findings this design answers (localStorage
+  network-printer restore bug; default-printer priority triplicated).
+
+## Deviations decided at brainstorm (user-approved 2026-07-19)
+
+- **Camera dropped entirely** (no "Built-in camera" row, no Camera tab):
+  camera scanning at the station has been backlog since P4.1 ("vestigial
+  even in web") — showing a "Fallback QR reader" the station cannot use
+  fails the honesty rule. Registry schema reserves the class.
+- **"Agent settings" button dropped**: no settings surface exists
+  anywhere on the board; shipping a dead button fails the same rule.
+- Scanners card is therefore titled "Scanners" (not "Scanners &
+  cameras") until camera ships.