MainsKeeper — complete design review

Checkpoint 0.2.0 · Battery Assurance · source-only review checkpoint

0.1.10 — exact monitoring-gap intervals

Browser review was not performed for this checkpoint. This environment does not permit opening, rendering or screenshotting the prototype. No browser journey, responsive width, theme, focus, dialog or overflow check has been run and no screenshot exists. Everything below was verified in Node from source.

What changed and what was verified

Defect: in 0.1.9 the series and hourly-aggregate gaps were found on the 1-minute sample grid and matched to the first overlapping recorded stop. A gap shorter than a minute (15:22:27–15:22:57) had no sample inside it, so the chart joined the line across it and availability said “No unknown time”. With two gaps 15 s apart, the second was lost.
Fix: the persisted stop/resume intervals are authoritative. Series, power lanes, history() and aggregate unknown spans list every gap with its exact boundaries. Chart segments split at each boundary and no point is kept inside a gap. A short observed interval between gaps stays observed, with no invented points. Unknown time and coverage are interval intersections with the selected range, in fractional minutes; only the text is rounded (30 s, 18 min). A non-zero gap never shows as “No unknown time”.
State checks: "$OD_NODE_BIN" product/app/assets/state-checks.js → 203 passed · 0 failed. That is 180 from 0.1.9, with three expectations corrected explicitly (below), plus 23 in the new group 9. Group 9 covers reproductions A and B on the created desk UPS and on the fixture BW Rack UPS on the same collector, clipped ranges, agreement between selectors, later readings, a third cycle and a reload.
Corrected expectations (not widened): Office Desk UPS 15:00–15:22 in witness-down is now 4.2 min observed / 17.8 min unknown (was 5 / 17). Group 8’s two-gap availability is now exactly 11.0 min, not “at least whole minutes − 1”. Group 8’s aggregate check now requires the exact gap total.
CLI generator: product/cli/build-examples.js self-check passed; 151 examples regenerated. Syntax and links: every script passes node --check; local links and anchors resolve.
Not verified: browser journeys, 375 / 768 / 1024 / 1440 px in both themes, keyboard focus, dialogs, overflow, chart legibility, browser errors, screenshots. The unverified checklist and screenshot list remain open and block acceptance.

Route A — immediate off/on (30 s gap)

Reset demo. network-source.html?collector=bw-pi-01 → NUT 192.168.1.20, UPS name deskups → credentials → test → Identify → Use.Expect: first readings at 15:22:27.
collector-config.html?id=bw-pi-01 → UPS monitoring off → save → “Simulate check-in” → UPS monitoring on → save → “Simulate check-in”.Expect: gap 15:22:27–15:22:57, “No records — UPS monitoring disabled”, in the chart (line broken at both ends), power lane, history list and hourly view. 24 h availability: “30 s unknown”, not “No unknown time”. Range 15:22–15:23: coverage 50.0%. BW Rack UPS shows its own gap 15:22:26–15:22:57 (31 s).

Route B — two gaps 15 s apart

As route A step 1, then off → check-in → advance 330 s → on → check-in → advance 15 s → off → check-in → advance 300 s → on → check-in. (The demo clock buttons advance in fixed steps; the 330 s / 15 s / 300 s sequence is the one the state checks drive through MK.store.advanceClock.)Expect: two gaps 15:22:27–15:28:27 and 15:28:42–15:34:12 in every view. The 15 s between them is on utility in the power lane with no chart point. 24 h unknown: exactly 11.5 min (“12 min unknown” after display rounding). Range 15:25–15:30: 4.75 min unknown, 0.25 min observed, coverage 5.0%. BW Rack UPS: 15:22:26–15:28:27 and 15:28:41–15:34:12.
Record more readings, run another short cycle, reload.Expect: the first two gaps keep their boundaries; a third is added; all survive the reload.

Checkpoint 0.1.9 · source-only review checkpoint

0.1.9 — persistent monitoring gaps

Browser review was not performed for this checkpoint. This environment does not permit opening, rendering or screenshotting the prototype, so no browser journey, responsive width, theme, focus, dialog or overflow check has been run and no screenshot exists. Everything below was verified in Node from source.

What changed and what was verified

Fix: every UPS-role-off period keeps its own gap. It starts at the last observation before monitoring stopped (recorded at the check-in that applies the change) and ends at the first observation after it resumed. Later readings never move a closed gap; a second off/on cycle adds a gap and keeps the first; both survive a reload. Series, power lanes, history, hourly aggregates and availability use the same gaps. Previously a later reading stretched the first gap (15:22:27–15:27:57 → …15:33:27) and a second cycle erased it.
State checks: "$OD_NODE_BIN" product/app/assets/state-checks.js → 180 passed · 0 failed (169 from 0.1.8 unchanged; 11 in group 8, including the existing BW Rack UPS on the same collector).
CLI generator: product/cli/build-examples.js self-check passed; 151 examples regenerated.
Syntax and links: every script passes node --check; local links and anchors in the review, notes and launcher pages resolve.
Not verified: browser journeys, 375 / 768 / 1024 / 1440 px in both themes, keyboard focus, dialogs, overflow, chart legibility, browser errors, screenshots. The unverified checklist and screenshot list remain open and block acceptance.

Route — two off/on cycles (bw-pi-01)

Reset demo. network-source.html?collector=bw-pi-01 → NUT 192.168.1.20, UPS name deskups → credentials → test → Identify → Use.Expect: monitoring with first readings at 15:22:27.
collector-config.html?id=bw-pi-01 → UPS monitoring off → save → “Simulate check-in” → “Advance demo clock 5 min” → UPS monitoring on → save → “Simulate check-in”.Expect: gap 15:22:27–15:27:57 on the UPS’s history, labelled “No records — UPS monitoring disabled”.
“Advance demo clock 5 min”, then repeat the off → check-in → advance → on → check-in cycle.Expect: the first gap is unchanged at 15:22:27–15:27:57 and a second gap 15:33:27–15:38:57 appears. BW Rack UPS shows the same two periods (ending 15:27:57 and 15:38:57).
Reload the page.Expect: both gaps unchanged.

Round 7 · checkpoint 0.1.8 · source-only correction pass

0.1.8 corrections — routes, steps and expected outcomes

Press Reset demo before each case. Browser QA was deferred to a separate browser-capable environment: none of the routes below has been opened in a browser for this checkpoint. Expected outcomes come from the shared selectors run in Node.

What was exercised (source / Node only)

State checks: "$OD_NODE_BIN" product/app/assets/state-checks.js → 169 passed · 0 failed. The 136 earlier checks are unchanged and still pass; 33 new checks cover group 6 (UPS role on → off → on) and group 7 (deferred activation).
CLI generator: "$OD_NODE_BIN" product/cli/build-examples.js self-check passes and regenerates the same 151 example files.
Syntax: every changed script passes node --check.
Not exercised: browser journeys, layout at 375 / 768 / 1024 / 1440 px, both themes, keyboard focus, dialogs, overflow, chart labels, browser errors, screenshots. The unverified checklist and “Not captured” screenshot list remain open and block acceptance.

A · UPS role on → off → on (bw-pi-01)

Add and use a NUT source: network-source.html?collector=bw-pi-01 → NUT 192.168.1.20, UPS name deskups → credentials → test → Identify → Use.Expect: monitoring, first readings, “On schedule”.
collector-config.html?id=bw-pi-01 → turn UPS monitoring off → save → review control “Simulate check-in”.Expect: roles Applied (connectivity only). Every UPS read by bw-pi-01 — the new one, BW Rack UPS and BW Office UPS — shows “Monitoring disabled · last known HH:MM”, not current.
Review control “Advance demo clock 5 min” (any collector page), then open the UPS, fleet, sources and history.Expect: the last reading time and values do not move; source “Monitoring disabled — UPS role off”; power lane and charts show “No records — UPS monitoring disabled” from the last reading to now; availability counts it as unknown.
Turn UPS monitoring back on → save.Expect: Pending — still “Monitoring disabled”; nothing resumes before the collector applies it.
“Simulate check-in”.Expect: applied, then one new reading (“readings resumed: …” in the review output); status current again; the disabled span stays a gap between the last reading and the first new reading.

B · Deferred activation — SNMP 10.0.20.16 while bw-pi-01 is offline

network-source.html?collector=bw-pi-01 → review control “Simulate disconnect”.Expect: bw-pi-01 not reporting.
SNMP 10.0.20.16 → credentials Configured → Test read access.Expect: “Test queued — collector not reporting”, never success.
Name it, then Save choice.Expect: “Configured — waiting for collector”, with the name kept.
“Simulate collector reconnect”.Expect: queued test succeeds; the UPS is identified (APC Smart-UPS SMT1500 · AP9631 card, serial AS1811240377); monitoring does not start — “Identified — confirm possible duplicate”, “Possibly the same UPS as BW Rack UPS (serial match)”. No UPS asset is created and no charge is invented.
“It is a separate UPS — start monitoring”.Expect: the UPS is created with your saved name and the identified model; readings are the endpoint’s reported values. A value the device does not report shows “Not reported”, never a default 100 %.

Immediate and deferred activation now pass the same prerequisites: successful read test → identification → duplicate reconciliation → confirmation when needed.

C · Copy and documentation

ESP32 storage: collector-config.html?id=shop-esp32-ups → Local settings read “fixed in firmware … not settings”, badge “Fixed in firmware” (was “change them on the device’s local setup page” / “Set locally”).
Grace: generic wording now says the contact grace is max(5 min, 3 × heartbeat). Specific incident timelines keep “5 min grace”, which is correct for their 30 s heartbeats.
Coverage: 14:30–15:22 = 52 min, 34.2 observed, 17.8 unknown (15:04:12–15:22), coverage 65.8%. 15:00–15:22 (and the 7-day 15:00 hour bucket) = 22 min, 4.2 observed, 17.8 unknown, coverage 19.1%. Corrected in 0.1.10: 0.1.8 quoted minute-sampled values (35 / 17 / 67.3% and 5 / 17 / 22.7%); the exact interval values are above. The 0.1.7 “23 minutes / 18 unknown” sentence and its open question are removed.

Round 6 · checkpoint 0.1.7

0.1.7 corrections — routes, steps and expected outcomes

Press Reset demo before each case. Cases (b) and the home-laptop journey both register the same identity, home-lan|nut|192.168.1.20|3493|rackups. Whichever you run second hits the hard-duplicate block, so reset between them. Cases (a) and (c) use broadwater-lan and do not collide with either. All rules come from shared logic (CONTRACT.md §18); pages only display them.

What was exercised (and what was not)

Shared logic: "$OD_NODE_BIN" product/app/assets/state-checks.js passed 136/136 at build time and again at integration. It drives MK.store and MK.select in Node with an in-memory localStorage. It covers every case below plus the regressions.
Pages (builders report): Node fake-DOM harness checks of the rendered HTML text for each route below.
CLI (builder reports): cli-screens.js self-check and export generation; 151 files in cli/examples/.
Integration: Node probes of the shared selectors for the expected strings quoted here (home-laptop journey, witness-down availability, freshness per scenario). A link check confirmed every local target in this page, the notes and the launcher exists on disk.
Not exercised: clicks and form-submit wiring in a browser, chart drag, layout, visuals and contrast. Nothing was rendered, previewed or screenshotted. See the unverified browser checklist.

1 · Network UPS identity (a / b / c) and untrustworthy serials

Identity = namespace | protocol | host | port | NUT UPS name. A host alone is never a UPS identity. A trustworthy serial match at a different identity can only raise a question. It never blocks.

(a) One server, two UPSs. network-source.html?collector=bw-pi-01 → NUT, host 192.168.1.20, UPS name rackups → save → Simulate credentials “Configured” → Test read access → Identify UPS → Use.Expect: identity broadwater-lan|nut|192.168.1.20|3493|rackups, CyberPower OR1500LCDRM1U, monitoring starts. Then “Add another network UPS” → same host, UPS name deskups: it registers as a second UPS (APC Back-UPS RS 1500).
Untrustworthy serial. The deskups identify step shows serial 000000000000 flagged untrustworthy.Expect: the serial decides nothing. No soft or hard duplicate.
Re-adding rackups on bw-pi-01 (same identity).Expect: blocked before any draft, “Already monitored by bw-pi-01 as <the name you gave rackups>”.
(b) Same address, other network. Reset demo. network-source.html?collector=home-studio&state=calm → NUT 192.168.1.20 rackups.Expect: allowed, key home-lan|nut|192.168.1.20|3493|rackups (Eaton 5P 1550, a different physical UPS). Credential step for home-studio (macOS) shows sudo mainskeeper sources auth … and the macOS Keychain.
(c) Hard duplicate. Reset demo. bw-pi-01 → SNMP 10.0.20.15.Expect: blocked before any draft is created: “Already monitored by bw-pi-01 as BW Office UPS”.
Soft duplicate. Same page → SNMP 10.0.20.16 → credentials → test → Identify UPS.Expect: confirm step “Possibly the same UPS as BW Rack UPS (serial match) — confirm” with continue or cancel. Continue → Use creates a separate UPS. Cancel removes the draft and adds nothing.

Deviations: Identify is required before Use. The soft-duplicate confirmation is page-local, so reloading the page asks again. CLI: add rackups · add deskups · duplicate (exit 1) · serial match (exit 10).

2 · Collector availability and UPS-role gating — home-laptop journey

network-source.html?collector=home-laptophome-laptop is a macOS workstation, connectivity only, asleep since 13:05. Add NUT 192.168.1.20 rackups. Saving works while it sleeps.
Simulate credentials “Configured” → Test read access.Expect: badge “Test queued — collector not reporting”, with “home-laptop is asleep — test will run when it reports”. Neither failure nor success.
collector-config.html?id=home-laptopTurn UPS monitoring on and save. Expect: “pending — desired on, applies at the next check-in”.
Review control “Simulate collector reconnect”.Expect: home-laptop reporting again 15:22:30. The check-in applies the role and the 120 s reporting interval, and the queued test runs: success.
Back on network-source (&source=src-home-laptop-nut-192-168-1-20-rackups resumes it) → Identify UPS → Use.Expect: first readings 15:22:57 (after the reconnect), reading “On schedule · read N s ago · every 120 s”.
collector.html?id=home-laptopSame collector and UPS. “Simulate disconnect (sleep)” → the source reads “Configured — waiting for collector”.
Role off variant. Reset demo. Simulate reconnect first, leave UPS monitoring off, then test → identify → Use.Expect: saved as “Configured — waiting for UPS role”, with a link to Configuration. No readings until the role applies.

Account connectivity-only path (onboarding): Reset demo → welcome.html?scenario=empty → step 2 site “Cabin” (namespace cabin-lan) → step 3 Windows, Connectivity only → approve PLHV-GWCS (den-win-01). Step 7 expects “Enable UPS role later” → configuration. The network branch lists the endpoints reachable in cabin-lan. A network source saved there reads “Configured — waiting for UPS role” until the role applies at a check-in. The macOS studio-mbp equivalent (code WDJB-MJHT) is the store-checked path. CLI: add on studio-mbp · local test, cloud unreachable · use → waiting for UPS role (exit 0) · roles pending · CLI gating.

Deviations: there is no queued-test CLI screen, because the CLI runs on the collector. A collector given the UPS role later shows “No USB UPS found”, and there is no re-discover action.

3 · Witness down — no data after 15:04:12

history.html?site=home&ups=office-desk-ups&scenario=witness-down&from=14:30&to=15:22Expect: power lane on utility to 15:04:12, then “No records — collector not reporting” to 15:22. Charge and load end at 15:04. Coverage 65.8% (17.8 min unknown, shown as “18 min unknown”). The site reachability badge is separate, and Office Desk UPS power is never derived from home-esp32-garage.
…&range=7dExpect: the 15:00 hour bucket covers the 22 minutes elapsed by 15:22 — 4.2 min observed on utility (15:00–15:04:12) and 17.8 min unknown, labelled “No records — collector not reporting”; coverage 19.1%. (The same 4.2 of 22 / 17.8 unknown applies to a 15:00–15:22 range; the 14:30–15:22 range above is 52 min with 17.8 unknown.)
ups.html?id=office-desk-ups&scenario=witness-downExpect: “Stale · last known 15:04 · read 17 min ago · every 30 s”. 24 h availability counts the gap as unknown, not as up or down.

4 · History range 15:00–15:22 (point / interval rule)

history.html?site=duplex&from=15:00&to=15:22Expect: no yesterday episode (INC-0409) and no 14:03–14:30 episode. The replay receipt event (e-dx-replay) appears at 15:17:40, its receive time.
history.html?from=15:00&to=15:22Expect: only the ongoing BW Rack episode (ep-bw-current). No Home 06:42 event.

Rule: a point is included if from ≤ time ≤ to. An interval is included if start ≤ to and end ≥ from. Its end is the end time, else the last record, else now only while ongoing. Deviations: receipt events sit at their receive time. The default availability period changed. “View this episode” pads the range by 25 min.

5 · Unknown evidence propagates everywhere

Lanes and charts: witness-down history: hatched “No records — collector not reporting”. It is never filled or joined.
Aggregates: 7 d: the hour bucket carries the unknown label and unknown minutes.
Coverage and availability: Office Desk UPS: “18 min unknown — counted as unknown, not up or down” for 14:30–15:22 (17.8 min exactly; 0.1.10 corrects the earlier “17 min”).
Awaiting the next report: BW Office UPS 24 h: after its last 600 s report the series shows “Not reported yet — next report due by 15:25:00 (every 600 s)” rather than a filled value.

6 · Freshness by cadence (30 s vs 600 s)

I = reporting interval, g = max(30 s, I/2). On schedule ≤ I + g · Overdue ≤ 2I + g · Stale · last known beyond that, or when contact is lost. 30 s → ≤ 60 s / ≤ 90 s / > 90 s. 600 s → ≤ 15 min / ≤ 25 min / > 25 min. Heartbeat is judged separately.

BW Office UPS (600 s, read 420 s ago): “On schedule · read 7 min ago · every 10 min” on fleet · site · equipment · ups.html?id=bw-office-ups. It was wrongly shown as Stale before.
30 s source, stale: Shop Bench UPS: “Stale · last known 15:10 · read 11 min ago · every 30 s”.
Legend with worked numbers: component gallery · collector detail (heartbeat 15 s override, judged separately).
CLI: status-bw (“On schedule · 7 min · every 10 min”) · JSON ("freshness": {"state":"on-schedule","ageSeconds":420,"expectedIntervalSeconds":600,"allowanceSeconds":300}).

No fixture UPS is currently Overdue. Use the legend to check that wording.

7 · Platform-specific instructions

Windows: install.html?platform=windows · enroll PLHV-GWCSExpect: Administrator PowerShell (PS>), no sudo; C:\ProgramData\MainsKeeper\collector.toml; DPAPI; Event Viewer and C:\ProgramData\MainsKeeper\logs. CLI: config set (elevated) · unelevated (exit 5) · validate · logs · service
ESP32: install.html?platform=esp32 · enroll MZQD-TCVFExpect: no host command line; the probe’s local setup page (setup access point or http://<device>.local); secrets on the device. CLI: help esp32 (exit 2)
macOS: install.html?platform=macosExpect: sudo; /Library/Application Support/MainsKeeper/collector.toml; macOS Keychain item “MainsKeeper source <id>”; /Library/Logs/MainsKeeper/. CLI: local access · validate · logs
Raspberry Pi / Fedora: install.html?platform=pi · fedora · enroll TJNR-FBQZ (Fedora)Expect: sudo; /etc/mainskeeper/collector.toml; /etc/mainskeeper/secrets.d/; journalctl -u mainskeeperd. CLI: local access (Fedora)
Unknown platform: install.html?platform=bogus → not-found state. Re-enroll: KQPT-RNXV → sudo mainskeeper enroll --reenroll.
CLI · Platforms section · Elevation

Deviation: OS install lines (package names and installers) are page-local; every command, path, secret store and log location comes from MK.cli.platform.

Regression routes (should behave as in 0.1.6)

First-run persistence: walk journey 1, then reload the fleet, garage-pi-02 and the CyberPower UPS. They are still there. First readings appear only after the collector reports with the UPS role applied.
Acknowledgment propagation: acknowledge INC-0412 → the same “jp 15:22:00” acknowledgment on incidents, fleet, equipment and UPS.
Restoration: incident.html?id=INC-0412&step=restored (restored 15:31:00, still open) → step=resolved (15:36:00).
Not-found routes: site · UPS · history · network source.
CLI exports: 151 files (121 in 0.1.6 + 30 new). All are in the checkpoint, and their names are credential-guard-safe (checked by state-checks.js).

Previous round · 0.1.6 (corrected where 0.1.7 changed it)

What changed in 0.1.6

One shared prototype state

Every page reads the fixture merged with a shared store (this browser’s localStorage, key mk-proto-v1). Other open tabs update too.
Acknowledgments, the INC-0412 restoration, created sites, collectors and UPSs, network sources and configuration changes are the same on every page.
Reset demo in each page’s review bar (and in this header) returns to the pristine fixture.
Dataset switch: Demo fleet | Your account (first run).
Unknown ids show a “not found” state instead of another entity.

Journeys completed

First run ends in your own fleet. The new collector and UPS open on their own pages.
New network UPS setup (NUT or SNMP): success, unreachable, rejected credentials, unsupported capability, already monitored (identity-based in 0.1.7), plus the 0.1.7 serial-match confirm and queued test.
Re-enrollment uses mainskeeper enroll --reenroll.
Witness-down scenario and a sleeping workstation (home-laptop).

Corrected semantics

History filters apply to charts, episodes and events. Other UPSs’ episodes appear under “Site context”.
7 d draws hourly aggregates with coverage, not 24 h.
On battery notifies after 60 s. Home’s 38 s episode is “Below 60 s delay — event only”.
Six timestamp labels: First evidence · Grace period started · Declared · Acknowledged · Recovered · Resolved.
Exact backfill policy and replay definition (> 2 min late while reconnecting).
Freshness (0.1.7): relative to each source’s reporting interval: On schedule · Overdue · Stale · last known. See correction 6.
ESP32 values are labelled “Illustrative — validated board/UPS list pending”.

One configuration and CLI contract

One configuration-ownership table for web and CLI: below.
Secrets stay on the collector. The dashboard shows only Configured / Missing / Rejected.
One CLI grammar with elevation per platform. --replace, scan and select are gone.
CLI exports renamed and complete: 121 example files in 0.1.6, now 151 in 0.1.7, all in the checkpoint.

a · Start here

Start here

Open the product

The fleet overview is the landing page. The demo fleet opens on the incident fixture (Wed 30 Sep 2026, 15:22 PDT).

Open MainsKeeper (fleet overview)

Reset demo

The prototype remembers what you do in this browser: acknowledgments, the INC-0412 walkthrough step, configuration changes, network sources and the first-run account. Opening some review links changes this state too. For example, incident.html?id=INC-0412&step=ack acknowledges INC-0412.

Reset demo is in the review bar at the top of every product page and in this page’s header. It asks you to confirm, clears the store and returns to the pristine demo fleet. Reset before each journey to get the results described below.

Dataset switch

The review bar shows Dataset: Demo fleet | Your account (first run).

Demo fleet: Broadwater, Home, Shop and Duplex, in Incident or Calm state, plus the scenarios.
Your account (first run): starts empty (?scenario=empty). It becomes active when you create a site in onboarding. Pages without state/scenario then show your account until you switch back or reset.
Choosing a demo state or scenario switches back to the demo fleet.

Link parameters

Links carry only state, scenario, theme and motion. Entity parameters (id, site, collector, ups, focus) and page states (auth, enroll) are never carried to the next page. An unknown id shows “not found”:

Design system, CLI and brand

Component gallery — both themes side by sideBadges, freshness, staleness legend, incident timestamps, sync meter, charts, tables, inspector, forms
Component gallery — dark only · light only
Shared file contractTokens, components, fixture, store (§12), configuration ownership (§13), CLI grammar (§14), policies (§15), 7 d aggregation (§16), round-6 corrections: identity, gating, history ranges, freshness, platforms, state-checks (§18)
Proposed mainskeeper CLI contractElevation · Configuration ownership · Network UPS · Exit codes
Brand folder README — marks, lockups, icons, clear space, minimum sizes
Design notes — provenance, decisions, limitations, open questions

Brand files

b · Journeys

Required journeys, step by step

Reset demo before each journey. Steps that change the shared state are marked “changes state”. The pages after them reflect the change.

1 · Empty account → site → install → approval → roles & sources → first readings → fleet → same collector and UPS

Sign in with GitHub (Cloudflare Access)
CallbackAn empty account continues to the welcome flow
Empty fleetNo sites, collectors or UPSs; points to setup
Welcome · step 1Progress is kept in the store; ?step= only chooses the step shown. Walk the steps in order.
Step 2 · create the siteName “Home”, time zone America/Los_Angeles. Changes state: the dataset switches to “Your account (first run)”.
Step 3 · choose the collectorRaspberry Pi · both roles (UPS and Connectivity) · site witness
Step 4 · installsudo apt install ./mainskeeper_0.4.2_arm64.deb · detail: install.html?platform=pi
Step 5 · start enrollment on the devicesudo mainskeeper enroll --headless shows code BKTN-XRWP
Step 6 · confirm BKTN-XRWP in the browserApprove changes state: creates collector garage-pi-02 and its discovered USB source
Approved
Step 7 · roles and sourcesUSB branch: “Use this UPS” on the CyberPower CP1500PFCLCD (changes state). Network branch: network-source.html?collector=garage-pi-02&from=welcome (returns to step 8)
Step 8 · first readings100% · est. 38 min · load 18% · 121 V · temperature Unsupported; reading “On schedule · read N s ago · every 30 s” (only after garage-pi-02 reports with the UPS role applied)
Go to fleet · your accountNo state/scenario parameter, so the account dataset shows: “1 of 1 expected collectors reporting”
Same collector · garage-pi-02
Same UPS · CyberPower CP1500PFCLCDAlso: equipment.html?cond=waiting (before the first reading) · sources · configuration

One enrollment code per platform per run. Use Reset demo to enroll the same device again.

2 · On-battery alert → investigation → acknowledgment → utility restoration

Fleet: Broadwater 1 of 2 UPSs on battery
INC-0412 · alertFirst evidence 15:09:00 · Grace period started 15:09:00 · Declared 15:10:00 · email 15:10:04 · push 15:10:05
Investigate the evidence
BW Rack UPS detailUPS estimate vs observed duration; freshness legend
Acknowledge (changes state)jp 15:22:00 “Utility outage on circuit A — checking with the building”; the incident stays open
Incidents list shows the same acknowledgment
Utility restored (changes state)Clock 15:32 · restored 15:31:00 · 22 min observed on battery · recovered, still open until stable
Resolved (changes state)Clock 15:37 · resolved 15:36:00 after 5 min stable
Same state everywhere: fleet · site · equipment · UPS · incidents · history · notifications

Low runtime: rule below 10 min. No fixture UPS crosses it. The round-4 ?runtime=low demo was removed.

3 · Site contact lost → offline recording → recovery → historical backfill (Duplex)

INC-0411 timestampsFirst evidence 13:41:00 (local probe, received 15:02:06) · Grace period started 13:44:00 · Declared 13:49:00 · Acknowledged jp 13:52 · Recovered 15:02:06 · Resolved 15:07:06
Duplex site · local probe evidence
duplex-pi-probe bufferJourney steps: 1 · 2 · 3 · 4 · offline · recording · replay + live
duplex-pi-probe · backlog draining
History 13:30–15:30Replay tagging (> 2 min late while reconnecting), the 14:30–14:52 gap, and the backfill alerting note
Episode: at least 27 minutes on battery; endpoint unknown

Backfill policy: “Historical backfill updates history at observation time and does not generate duplicate or obsolete notifications. Fresh evidence of an active condition remains alertable while a backlog drains. Ordinary transmission latency does not make a reading historical replay.”

4 · Collector online while its UPS source stops reporting

5 · Credential revoked → diagnosis → re-enrollment

6 · Network UPS setup — outcomes, identity and gating

Open network-source.html?collector=bw-pi-01 (demo fleet). Steps: Protocol → Endpoint → Local credentials → Test → Identify → Duplicate check → Use. Credentials must show Configured before the test. The browser never takes a secret. You run the platform’s credential command on the collector (for example sudo mainskeeper sources auth <source> on Linux and macOS, or an Administrator PowerShell on Windows; ESP32 uses its setup page). In the prototype, use the review-only “Simulate” control. A collector that is not reporting queues the test (see correction 2). &source=<id> resumes a draft.

Success · Remote NUT server 192.168.1.20, UPS name rackups (identity broadwater-lan|nut|192.168.1.20|3493|rackups)Also SNMP v3 192.168.1.25 (APC SRT 2200). deskups on the same server is a second UPS (correction 1).
Unreachable endpoint · NUT 192.168.1.99
Rejected credentials · NUT 192.168.1.22, UPS name office (or choose “Entered a wrong secret” in the simulator)
Unsupported capability (partial) · SNMP v2c 192.168.1.26
Already monitored · SNMP 10.0.20.15 (same identity broadwater-lan|snmp|10.0.20.15|161|) → blocked before any draft: “Already monitored by bw-pi-01 as BW Office UPS”. No second asset is created. The same address in another namespace is a different identity.
Possibly the same UPS · SNMP 10.0.20.16 → after Identify: “Possibly the same UPS as BW Rack UPS (serial match) — confirm”. Continue or cancel; never a block.

Onboarding branch: journey 1, step 7.

7 · Witness down vs site contact lost vs locally observed connectivity failure

Fleet · witness downHome: “Site still reachable: home-esp32-garage reporting”
Home site · witness down
INC-0415 · Collector not reporting — home-studio
home-studio · last contact 15:04:12
Collectors · witness down
Relationships · Home, home-studio focused
Shop · site contact lost (all witnesses silent, cause unknown)INC-0413 · relationships focus
Duplex · locally observed connectivity failure (probe evidence 13:41)INC-0411

Compare the two silence panels: INC-0413 and INC-0411.

8 · Workstation sleep

Fleet counts“4 of 6 expected collectors reporting · 1 workstation asleep”
home-laptop · Asleep (ordinary workstation) — no incidentAsleep since 13:05; last contact 13:05:40
Configuration · change pending until next check-inReview controls: Simulate collector reconnect / check-in / disconnect. Full gating journey: correction 2.
Collectors list
bw-desk-ws · relationship only (no agent, normal)

9 · Equipment-filtered history, including 7-day aggregation

Broadwater · BW Office UPS · 24 hBW Rack’s battery episode appears only under “Site context”
BW Office UPS detail · site context separate
Shop · 7 d hourly aggregates“No records” 26 Sep 02:00–06:00
Shop Bench UPS · 7 d
UPS detail · 7 d gap
BW Rack UPS · 7 d
Equipment compare (3 UPSs)

10 · Mobile incident detail · acknowledge

INC-0413 on a phone (≤ 767 px)Fixed action bar: check → evidence → acknowledge (bottom sheet)
Acknowledge with a note (changes state). Then open incidents and the fleet: they show the same record.
INC-0412 on a phone

The action bar is in source only. It has not been checked at 375 px or on a device.

c · Configuration ownership

Configuration ownership (one table for web and CLI)

The table below comes from MK.config.contract when the shared scripts load; otherwise it shows a summary. The same rows are used by collector-config.html?id=bw-pi-01 and the CLI configuration-ownership section. Override example on bw-pi-01: “Effective: 15 s (local override) · Desired in dashboard: 30 s”. Rows are platform-neutral here; each collector’s configuration page resolves paths, elevation and secret store for its own platform (MK.config.contractFor). Other states: failed (shop-esp32-net, max 3 targets) · pending (home-laptop asleep).

Configuration ownership: setting, owner, edit location, effective value source, application behaviour
Setting	Owner	Edit location	Effective value source	Application behaviour
Site, display name, roles, expected availability, heartbeat interval, reporting interval, connectivity targets	Dashboard	Dashboard › Collectors › collector › Configuration	Dashboard (heartbeat: unless a local override is set)	Desired → pending → applied on next check-in, or failed with a reason
Alert rules & notification thresholds	Dashboard (server)	Dashboard › Settings › Alert rules	Server	Server-side, immediate
NUT credentials, SNMP v3 secrets, SNMP community	Local secret	On the collector: `mainskeeper sources auth <source>`, elevated per platform (ESP32: its local setup page)	The platform’s secret store (macOS Keychain · /etc/mainskeeper/secrets.d · Windows DPAPI · on the device)	Dashboard shows only Configured / Missing / Rejected + last test time
Storage path, disk cap, retention target, log level, log path	Local	The platform’s `collector.toml` (macOS /Library/Application Support/MainsKeeper · Linux /etc/mainskeeper · Windows C:\ProgramData\MainsKeeper) or an elevated `mainskeeper config set`	Collector	Read-only in the dashboard, “Set locally”
USB host, flash ring, UPS classes, max targets	Capability	Not editable	Hardware	Shown as capabilities; ESP32 values illustrative

d · Product map

Product map

Every page, what it is for, and direct links to its states. Links without state= or scenario= open the active dataset (the demo incident fixture unless you switched to your account). Add &theme=light to any link for the light theme.

Fleet & sites

index.html — Fleet overviewLanding page. Sites with reachability, open incidents, recoveries, history sync; counts derived from the merged data. Incident Calm Loading Empty account UPS comms lost Collector revoked Witness down

site.html — Site detailUPS cards by circuit, collectors with contact state, reachability, connectivity, history, availability with coverage. Broadwater (on battery)Home Home · witness down Shop (site contact lost)Duplex (local probe)Not found

site-setup.html — Site settingsName and time zone edits; witness changes go through the desired → pending lifecycle; some expectations read-only. Edit Home New site

Equipment & UPS

equipment.html — Equipment workspaceFilter, sort and compare UPSs; freshness column; state in the URL. All UPSs On battery Stale Overdue Waiting for first reading Compare 3 Unsupported readings No UPSs

ups.html — UPS detailReadings with freshness and staleness legend, UPS estimate vs observed duration, charts (24 h minute data, 7 d hourly aggregates), protected equipment. BW Rack (on battery)BW Rack · 7 d BW Office (600 s cadence · On schedule · site context separate)Office Desk · witness down (unknown after 15:04:12)Office Desk (38 s, event only)Shop Bench (stale · last known)Shop Bench · 7 d gap Garage (comms lost)Not found

Incidents & notifications

incidents.html — IncidentsOpen, recovered and resolved incidents; acknowledgments from the shared store. Open Recovered Resolved Notification failures Calm Empty filter result

incident.html — Incident detailSix-label timestamps row, evidence timeline, notifications, acknowledgment with note, silence panels. INC-0412 on battery INC-0413 contact lost INC-0411 recovered INC-0409 resolved INC-0414 UPS comms lost INC-0415 witness down Not found

notifications.html — NotificationsChannels and the delivery log. All Push channel (failing)Failed Retrying Suppressed

maintenance.html — Maintenance windowsWindows stored in the shared store. List New · Home Edit Shop window New · overlap warning New · invalid range

alert-rules.html — Alert rules (Settings)Delays and thresholds configure notifications only; server-side, immediate. List On battery · after 60 s · Home 38 s example Low runtime Validation error

History

history.html — History and investigationSite, UPS and range filter charts, episodes and events alike; “Site context” section; 7 d hourly aggregates with coverage. Duplex 13:30–15:30 (replay)Duplex episode BW Office · site context Shop · 7 d Shop Bench · 7 d Duplex 15:00–15:22 All sites 15:00–15:22 Office Desk · witness down 1 h 24 h 7 d (all sites)Empty range Invalid range Loading Not found

Collectors, coverage & sources

collectors.html — CollectorsContact state, roles, site witnesses vs workstations, buffers, secrets status. All Witness down UPS role · contact lost Shop

collector.html — Collector detailContact vs reading age, staleness legend, roles, sources, targets, buffer, capabilities. bw-pi-01 home-laptop (asleep)home-studio (witness down)shop-esp32-net (illustrative ESP32)duplex-pi-probe (draining)bw-pi-01 revoked Not found

relationships.html — Relationships and coverageReads / powers / checks map; ?site= filters clusters, ?focus=kind:id preselects. Map Focus bw-pi-01 Focus Shop Home · witness down Sleeping workstation Coverage: missing Unknown focus Unknown site

sources.html — UPS sourcesOverview without a collector; per-collector discovery, choice, secrets status and diagnostics; “Add network UPS”. Overview bw-pi-01 · live Credentials rejected Unreachable None found Multiple found Existing NUT service Device busy Partial capability Comms failing Not found

network-source.html — Add network UPS (NUT / SNMP)Protocol → endpoint (identity and hard-duplicate check) → local credentials (status only) → test (queued while the collector is not reporting) → identify → serial-match confirm → use (monitoring, or “Configured — waiting …”). bw-pi-01 home-studio (home-lan)home-laptop (asleep · queued test)ESP32 (not applicable)Revoked Not found

collector-config.html — Collector configurationOwnership table, desired/pending/applied/failed, override, secrets status, local read-only, capabilities. bw-pi-01 (override)shop-esp32-net (failed)home-laptop (pending)home-esp32-garage (ESP32)bw-pi-01 revoked

Sync

sync.html — History syncPer-collector buffer (?collector=); illustrative cases; sync never holds an incident open. duplex-pi-probe Draining Healthy Offline · recording Replay + live Stalled Storage pressure Records lost Not found

Onboarding & enrollment

sign-in.html — Sign-inCloudflare Access with GitHub; ?auth= states (never ?state=). Signed out Redirecting Callback Access denied Session expired Error

welcome.html — First run (8 steps)Empty account to first readings, in the account dataset. See journey 1.

install.html — Install a collectorPer-platform install with elevation. Installers are design targets. macOS Windows Fedora Raspberry Pi ESP32 probe Unknown platform

enroll.html — EnrollmentShort user code, browser approval. Expired, denied and offline are display-only. Waiting Confirm Expired Denied Offline Revoked Re-enroll Unknown code

CLI

cli/index.html — Proposed CLI contractOne grammar with elevation, configuration ownership, network UPS, exit codes, JSON schema and terminal mockups. Monitoring only. Commands Elevation Configuration ownership Network UPS Gating Platforms Exit codes JSON schema Mockups 80 col 120 col Light NO_COLOR

Examples (151 files, all in the checkpoint)Plain text at 80/120 columns and JSON, by category.

Design system

components.html — Component galleryEvery shared component in its important states, both themes. Both Dark Light

tokens.css · CONTRACT.md · brand READMEColour roles, type, spacing, motion, contrast tables, store and policy contracts.

e · State coverage

State-coverage checklist

Designed = built in prototype source and linked. Partial = built with a stated gap. Not designed = absent. No row has been visually verified. Totals: 51 Designed · 8 Partial · 1 Not designed.

State coverage: state, where to see it, status, notes
State	Where	Status	Notes
First use · no devices	Fleet empty Welcome Equipment empty	Designed	Account dataset, empty until you create a site.
First run to your own fleet (same collector and UPS)	Welcome garage-pi-02 CyberPower UPS	Designed	Created entities live in the store. These ids exist only after you walk journey 1. Before that, they show “not found”.
New collector after approval (sources, configuration)	Sources Configuration	Designed	No silent fallback to bw-pi-01.
Dataset switch · Reset demo	Review bar on any page	Designed	Reset asks for confirmation and removes entity params that no longer exist.
Not-found states	Site UPS Incident Sources Sync Relationships	Designed	Never substitutes another entity.
Parameter contract	sign-in ?auth=?focus=	Designed	Carried: state, scenario, theme, motion. Not carried: auth, enroll, id, site, collector, ups, focus.
Initial loading	Fleet History	Partial	Skeletons only on fleet and history.
Healthy	Fleet calm Home Sync healthy	Designed
Partial capabilities (unsupported readings)	BW Office UPS Source Equipment	Designed	“Unsupported” / “Not reported”, never 0.
On battery (notify after 60 s)	BW Rack UPS INC-0412 Rule	Designed	Home 38 s episode: “Below 60 s delay — event only”.
Low runtime	Rule BW Rack UPS	Partial	The rule is designed. No fixture UPS falls below 10 min, and the round-4 page-local demo was removed.
Utility restoration	INC-0412 restored Resolved Unknown restore time	Designed	Store-driven (clock 15:32 / 15:37); every page agrees.
Acknowledged	INC-0412 ack Incidents INC-0411	Designed	One record per incident in the shared store.
Incident timestamps (six labels)	INC-0413 INC-0411	Designed	Resolved = recovered + 5 min stable (decision to confirm).
Witness down (collector failure, site still reachable)	Home INC-0415 home-studio	Designed	“Site still reachable: home-esp32-garage reporting”.
Site contact lost vs locally observed connectivity failure	Shop · cause unknown Duplex · local probe	Designed
UPS comms lost while the collector reports	Garage UPS INC-0414	Designed
Workstation asleep (normal)	home-laptop bw-desk-ws	Designed	Excluded from expected collector counts.
Freshness: On schedule · Overdue · Stale (per cadence)	Shop Bench UPS Equipment stale	Designed	Relative to the reporting interval (30 s: ≤ 60 s · ≤ 90 s · > 90 s; 600 s: ≤ 15 · ≤ 25 · > 25 min), with absolute age and a legend. No fixture UPS is currently Overdue.
Recovery with uploads draining	INC-0411 Sync	Designed
Historical backfill and replay	Duplex history Replay + live	Designed	Exact policy text; replay = > 2 min late while reconnecting.
Storage limits	Pressure Records lost CLI	Designed	ESP32 values illustrative.
History gaps · uncertain timestamps	Duplex 14:30–14:52	Designed	Hatched “No records”; ±90 s until clock sync.
History filtered by UPS (site context separate)	BW Office UPS	Designed
Charts: 7-day hourly aggregates with coverage	Shop 7 d UPS 7 d	Designed	Custom ranges are limited to the last 7 days. The all-sites 7 d SVG is heavy.
Chart range selection on touch	History	Partial	Drag selection off on touch; use the range form.
Network UPS setup (outcomes + identity)	network-source.html	Designed	Success, unreachable, rejected, unsupported, already monitored (same identity), serial-match confirm.
Network identity: same host, different UPS / namespace	bw-pi-01 rackups + deskups home-studio home-lan	Designed	Correction 1 (a)/(b). Untrustworthy serial 000000000000 decides nothing.
Test queued (collector not reporting)	home-laptop	Designed	“Test queued — collector not reporting”; runs at the next check-in. No CLI screen (CLI runs on the collector).
Configured — waiting for UPS role / for collector	home-laptop configuration home-laptop CLI	Designed	Store-enforced; readings only after the role applies and the collector reports.
Unknown evidence after a witness goes silent	History UPS	Designed	Nothing after 15:04:12; unknown in lanes, charts, aggregates, coverage and availability.
Awaiting next report (600 s cadence)	BW Office UPS	Designed	“Not reported yet — next report due by 15:25:00 (every 600 s)”.
Platform instructions (Windows, ESP32, macOS, Pi/Fedora)	Windows ESP32 macOS CLI	Designed	From MK.cli.platform; OS install lines page-local.
Configuration: pending · applied · failed · override	Pending Failed Override	Designed	Applied on next page load (simulated check-in).
Secrets status (Configured · Missing · Rejected)	bw-pi-01 Rejected	Designed	An abandoned network draft can make the summary read Missing until it is removed.
Enrollment: waiting · confirm · approved · expired · denied · offline	Waiting Expired Denied Offline	Partial	Expired, denied and offline are display-only; they don’t change the store.
Enrollment: revoked · re-enroll	Revoked Re-enroll	Designed	`enroll --reenroll`.
Auth expiration	Session expired	Designed
Sign-in states	Signed out Redirecting Callback Denied Error	Designed	`?auth=` no longer collides with the review bar.
Revoked credentials	Collector CLI doctor JSON error	Designed
Maintenance	Windows New · Home Suppressed	Designed
Recovery ≠ acknowledged ≠ resolved	Recovered tab Resolved tab	Designed
Empty results	Incidents History	Designed
Notification failure	Failed Retrying Incidents	Designed
Configuration validation	Alert rule Maintenance Site Range	Designed
Source cases	Live None found Comms failing	Designed	Renamed cases: live, credentials-rejected, unreachable (old names still work).
Sync cases + journey	Cases Journey	Designed
Relationships and coverage (site filter, focus)	Focus Shop Missing	Designed
ESP32 values labelled illustrative	shop-esp32-net home-esp32-garage	Designed	“Illustrative — validated board/UPS list pending”.
Equipment table	Equipment	Partial	Store integration exercised only with a stub harness.
Mobile alert-acknowledge	INC-0413 at ≤ 767 px	Partial	Action bar in source; not checked at 375 px. Dense list rows at 375 px are a risk.
Tablet layout (768–1023)	Any page	Partial	Not reviewed separately.
Dark / light themes	Dark Light Gallery	Partial	Contrast calculated, not visually checked.
Calm state	Incidents Collectors	Designed
Availability with unknown and maintenance	Home History	Designed
Keyboard (shortcuts, Esc, focus)	Equipment inspector	Designed	In source; not tested with assistive technology.
CLI dark · light · NO_COLOR at 80 / 120	80 dark 120 light NO_COLOR	Designed
CLI grammar, elevation, exit codes	Elevation Exit codes Unelevated	Designed	`status` exits 0 when the query succeeds.
CLI JSON	Schema status queue	Designed
Rendered screenshots / visual inspection	Visual checklist	Not designed	Not produced. Rendering is not permitted in this environment.

f · Visual checklist · UNVERIFIED

UNVERIFIED visual checklist

Every item below is “Not verified (rendering not permitted in this environment)”. Nothing has been opened in a browser or on a device. Use this as the checklist for the first visual review: open each journey’s routes at each width in both themes and record defects.

Visual checklist: journey by viewport width and theme. All cells not verified.
Journey	375 px · dark	375 px · light	768 px · dark	768 px · light	1024 px · dark	1024 px · light	1440 px · dark	1440 px · light
1 · Empty account → first readings → fleet	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
2 · On-battery → acknowledgment → restoration	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
3 · Contact lost → backfill (Duplex)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
4 · UPS source stops, collector online	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
5 · Credential revoked → re-enrollment	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
6 · Network UPS setup (5 outcomes)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
7 · Witness down vs contact lost vs local probe	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
8 · Workstation sleep	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
9 · Equipment-filtered history · 7 d	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
0.1.7 corrections (identity, gating, witness-down, ranges, freshness, platforms)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)
10 · Mobile incident acknowledge	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)	Not verified(rendering not permitted in this environment)

Cross-cutting checks

Cross-cutting visual and interaction checks, all not verified
Check	What to look for	Status
Keyboard navigation	Tab order, skip link, shortcuts, review bar, dataset switch, Reset demo	Not verified(rendering not permitted in this environment)
Focus	Visible focus ring in both themes; focus returns after dialogs, inspector and bottom sheet	Not verified(rendering not permitted in this environment)
Overflow	No page-level horizontal scroll at 375/768/1024/1440; tables scroll inside their wrappers; long ids wrap	Not verified(rendering not permitted in this environment)
Chart labels	Axis and band labels legible; “No records” hatch, coverage bands, Site context; 7 d aggregates at 375 px	Not verified(rendering not permitted in this environment)
Dialogs	Reset demo, acknowledge, network hard-duplicate card and serial-match confirm; Esc closes; focus trapped and restored	Not verified(rendering not permitted in this environment)
Forms	Site, network source endpoint, alert rule, maintenance; validation messages next to fields; 44 px targets on mobile	Not verified(rendering not permitted in this environment)
Terminal readability	Onboarding command blocks and CLI mockups at 80/120 columns in dark, light and NO_COLOR	Not verified(rendering not permitted in this environment)
Click and submit wiring	Every 0.1.7 button (Simulate reconnect/check-in/disconnect, Test, Identify, Use, confirm/cancel, role switch save) does what correction cards 1–7 describe	Not verified(rendering not permitted in this environment)
Reduced motion	No animation with prefers-reduced-motion	Not verified(rendering not permitted in this environment)
Contrast in place	Status colours and muted text on real surfaces in both themes	Not verified(rendering not permitted in this environment)

g · Screenshots

Requested screenshots

None captured, in any round: rendering is not permitted in this environment. Exact routes to capture are below. Reset demo first, and walk journey 1 before the first-run shot.

Requested screenshots, route to capture and status
Screenshot	Route to capture	Status
Fleet overview	app/index.html?state=incident light	Not captured
First-run enrollment	app/enroll.html?scenario=empty&enroll=confirm&code=BKTN-XRWP&from=welcome(after welcome steps 1–5)	Not captured
Network source setup	app/network-source.html?collector=bw-pi-01(NUT 192.168.1.20 · rackups; also the four failure outcomes)	Not captured
Incident acknowledgment and recovery	app/incident.html?id=INC-0412&step=ack …&step=restored	Not captured
Equipment-filtered history	app/history.html?site=broadwater&ups=bw-office-ups&range=24h 7 d	Not captured
Mobile incident detail	app/incident.html?id=INC-0413(375 px viewport)	Not captured
Network identity · hard duplicate and serial-match confirm	app/network-source.html?collector=bw-pi-01(SNMP 10.0.20.15 blocked; 10.0.20.16 confirm)	Not captured
Queued test and waiting states	app/network-source.html?collector=home-laptop configuration (pending)	Not captured
Witness-down history (unknown after 15:04:12)	app/history.html?site=home&ups=office-desk-ups&scenario=witness-down&from=14:30&to=15:22	Not captured
Freshness at 600 s cadence	app/ups.html?id=bw-office-ups	Not captured
Windows and ESP32 instructions	install · Windows install · ESP32	Not captured
CLI status and enrollment	cli/index.html?w=80#g-status #g-enroll status-bw.80.txt enroll-headless.80.txt	Not captured

h · CLI examples

CLI examples by category (151 files)

Generated from one source (cli/cli-screens.js). Added in 0.1.7 (15 screens × 80/120 col = 30 files): config-set-windows-unelevated, config-validate-macos, config-validate-windows, help-esp32, logs-macos, logs-windows, roles-show-pending, sources-add-deskups, sources-add-rackups, sources-add-studio, sources-local-access-fedora, sources-local-access-macos, sources-test-offline, sources-test-serial-match, sources-use-waiting. Renamed in 0.1.6: error-credential-revoked.json → error-enrollment-revoked.json; sources-auth.* → sources-access-rejected.*; roles-perm.* → sources-test-unelevated.*; sources-partial.* → sources-show.*. All files are in the checkpoint archive.

mainskeeper (bare) (2)

bare · 80 col · 120 col

help (6)

help · 80 col · 120 col
help-esp32 · 80 col · 120 col
help-queue · 80 col · 120 col

Usage error (2)

usage-error · 80 col · 120 col

version (2)

version · 80 col · 120 col

enroll (16)

enroll-approved · 80 col · 120 col
enroll-denied · 80 col · 120 col
enroll-desktop · 80 col · 120 col
enroll-expired · 80 col · 120 col
enroll-headless · 80 col · 120 col
enroll-offline · 80 col · 120 col
enroll-reenroll · 80 col · 120 col
enroll-waiting · 80 col · 120 col

status (11)

status-bw · 80 col · 120 col
status-bw-pi-01 · JSON
status-duplex · 80 col · 120 col
status-duplex-pi-probe · JSON
status-studio · 80 col · 120 col
status-studio-mbp · JSON
status-watch · 80 col · 120 col

sources (46)

sources-access-rejected · 80 col · 120 col
sources-add-deskups · 80 col · 120 col
sources-add-duplicate · 80 col · 120 col
sources-add-nut · 80 col · 120 col
sources-add-rackups · 80 col · 120 col
sources-add-studio · 80 col · 120 col
sources-add-unreachable · 80 col · 120 col
sources-existing · 80 col · 120 col
sources-list · 80 col · 120 col
sources-local-access-fedora · 80 col · 120 col
sources-local-access-macos · 80 col · 120 col
sources-local-access-prompt · 80 col · 120 col
sources-multi · 80 col · 120 col
sources-none · 80 col · 120 col
sources-owned · 80 col · 120 col
sources-show · 80 col · 120 col
sources-test-offline · 80 col · 120 col
sources-test-ok · 80 col · 120 col
sources-test-partial · 80 col · 120 col
sources-test-serial-match · 80 col · 120 col
sources-test-unelevated · 80 col · 120 col
sources-use · 80 col · 120 col
sources-use-waiting · 80 col · 120 col

roles (6)

roles-set · 80 col · 120 col
roles-show · 80 col · 120 col
roles-show-pending · 80 col · 120 col

config (20)

config-set-local · 80 col · 120 col
config-set-managed · 80 col · 120 col
config-set-override · 80 col · 120 col
config-set-windows · 80 col · 120 col
config-set-windows-unelevated · 80 col · 120 col
config-show · 80 col · 120 col
config-show-effective · 80 col · 120 col
config-validate · 80 col · 120 col
config-validate-macos · 80 col · 120 col
config-validate-windows · 80 col · 120 col

queue (11)

queue-draining · 80 col · 120 col
queue-dropped · 80 col · 120 col
queue-duplex-pi-probe · JSON
queue-lab-pi-dropped · JSON
queue-lab-pi-stalled · JSON
queue-pressure · 80 col · 120 col
queue-stalled · 80 col · 120 col

doctor (14)

doctor-cloud · 80 col · 120 col
doctor-comms · 80 col · 120 col
doctor-hw · 80 col · 120 col
doctor-ok · 80 col · 120 col
doctor-perm · 80 col · 120 col
doctor-revoked · 80 col · 120 col
doctor-service · 80 col · 120 col

service (6)

service-launchd · 80 col · 120 col
service-systemd · 80 col · 120 col
service-windows · 80 col · 120 col

logs (8)

logs · 80 col · 120 col
logs-group · 80 col · 120 col
logs-macos · 80 col · 120 col
logs-windows · 80 col · 120 col

JSON errors (1)

error-enrollment-revoked · JSON

i · Design system

Design-system summary

Colour roles (current theme)

Ground--mk-bg · #101418 / #F4F6F8

Surface--mk-surface-1

Text--mk-text · #E9EEF2 / #101418

Mint — live, observed, OK, links#7FE0C4 / #0B7358

Sodium — brand, selection, focus only#FF9F43 / #A34D00

Critical — on battery#FF6B6B / #C02F2F

Warning — contact lost#E8D85C / #6E6100

Unknown, last known, unsupported#A3B0BC / #4F5C69

Connectivity — local probe evidence#5CB8F5 / #1D66A8

Sync — pending, replayed#A99CF7 / #5747C2

Maintenance#B4BFCA / #56626E

“Powers” lines#C5CFD8 / #56626E

Dark is the default; light uses [data-theme="light"]. Every text role is ≥4.5:1 on bg, surface-1 and surface-2 in both themes, calculated in CONTRACT §3.2. Warning yellow differs from sodium by 24–25° of hue and uses a different glyph. Type: Sora (UI), DM Mono with tabular numerals (data). Body 16 px, dense cells 14 px, minimum 12 px.

Status glyph conventions

Status is always glyph + word. Colour supports the meaning but never carries it alone.

On battery: Critical. Battery glyph.
On utility: OK. Filled circle.
Contact lost: Warning. Dashed circle with “?”. Server-observed, cause unknown.
Connectivity failure: Connectivity blue. Bars with ×. Confirmed by local probe.
UPS comms lost: Warning. The collector still reports.
Last known: Dashed hollow circle, always with time and age. Stale beyond 2 × the reporting interval + allowance, or when contact is lost.
Unsupported: Hatched dash. Never 0.
Received late · replayed: Sync violet. Received more than 2 min after observation while reconnecting. Backfill does not send duplicate or obsolete notifications.
Recovered: Outlined check.
Maintenance: Wrench, hatched band.
Not acknowledged: Neutral, dashed. Acknowledgment changes nothing on equipment.
Selected: Sodium ring plus tint. Never a status.

Chart conventions

Measured: Solid line, mint.
Estimate: Dashed line, labelled “est.” (UPS estimate).
Received late: Hollow marker plus received time.
No records: Hatched band. Never interpolated, never drawn as zero.
History arriving: Periwinkle hatch: records exist on the collector but are not yet uploaded.
Uncertain: Bracket with ±seconds.
Maintenance / battery: Background bands.
Live edge: “Now” marker at 15:22.

Coverage model

Directly monitored: A collector reads it now.
Relationship recorded — no direct monitoring expected: For example, a sleeping workstation with no agent behind a monitored UPS.
Measurement unsupported: The UPS or source cannot report this value.
Expected collector/source missing: Something that should report is not reporting.

Links are reads (collector → UPS), powers (UPS → equipment) and checks (collector → target). All are marked “configured”, not measured.

Wording glossary

Contact lost — cause unknown: Server stopped hearing; no local evidence.
Connectivity failure confirmed by local probe: Probe records show targets failing.
On schedule · Overdue · Stale · last known 15:10: Relative to the reporting interval I with allowance g = max(30 s, I/2): ≤ I + g · ≤ 2I + g · beyond. Always with “read N ago · every I”.
No records — collector not reporting: Unknown, never filled, joined or counted as up or down.
Configured — waiting for UPS role / for collector: A saved network source that cannot be read yet.
Possibly the same UPS as … (serial match) — confirm: A trustworthy serial match at a different identity. A question, never a block.
Unsupported / Not reported: Cannot report / supported but missing.
UPS estimate (est.): A prediction, not “runtime remaining”.
Observed on battery: Measured between observed transitions.
At least 27 minutes on battery; endpoint unknown: No observed end.
Received late · replayed: Received more than 2 min after observation while the collector reconnected from its buffer. Normal latency is not replay.
History arriving / No records / No records received: Pending upload / none exist / nothing since last contact.
Site witness: Always-on collector that carries site expectations.
Asleep (ordinary workstation) — no incident: A workstation that is not a witness; excluded from expected counts.
Site still reachable: home-esp32-garage reporting: A witness is down but another collector at the site still reports.
First evidence · Grace period started · Declared · Acknowledged · Recovered · Resolved: Incident timestamps. Resolved = recovered and stable for 5 min.

Avoid “offline” for contact lost, “down”, “battery health” for charge, “0%” for missing data, and any control verbs.

Checkpoint 0.2.3 · Battery Assurance History filters

Battery Assurance — review scenarios

Press Reset demo before each case. Browser verification and screenshots skipped by user request. Visual and browser-interaction acceptance remain unverified. Outcomes below come from shared selectors in Node (state-checks.js groups 10–12 · 294 passed at 0.2.3; groups 10–11 · 277 passed at 0.2.2 remain historical).

0.2.3 fixes: History "all" site/UPS normalization for manual records; date-only range uses day-interval overlap (noon is not a known clock time); exact timestamps keep the point rule.

0.2.2 fixes (historical): historical association / predates-installation; investigating stays counted; resolution evidence validation + observation text; policy true-patch; awaitingEvidence from composed state; date-only display; standalone History records.

Monitoring only: no control starts a UPS self-test, transfer test, shutdown, reboot, or outlet switch. Current power/charge stay separate from battery-operation evidence, policy age, and unresolved findings.

ups.html?id=bw-office-ups&scenario=assurance-no-evidenceFull charge on utility, no battery-operation evidence. Expect: “No battery-operation evidence recorded.” Not Verified/Certified.
…scenario=assurance-self-testUPS-reported PASS only; test date unknown. Polling must not refresh age.
…duplex-utility-ups&scenario=assurance-observedBattery operation under load ending in utility restoration (17m · ~29% load).
…scenario=assurance-unknown-end · historyTelemetry ended during battery operation; outcome unknown. Collector silence ≠ failure.
…shop-bench-ups&scenario=assurance-transfer-fail · equipment filterOperator-reported transfer failure unresolved while utility is back. Resolve only with documented evidence.
…scenario=assurance-overdue · assurance reminder ruleEvidence overdue under 60-day policy. Reminder ≠ device failure.
…office-desk-ups&scenario=assurance-replacedBattery replacement recorded; new battery awaiting evidence. Prior successes do not qualify.

Also on the default incident fixture: BW Rack live battery operation · Garage Unsupported self-test · BW Office undated cached PASS · fleet Assurance pulse · CLI assurance excerpt.

Workflow: Failure recorded → investigation → validation pending → explicit resolution with documented support (evidence ids and/or authored observation). Empty resolutions are rejected. Utility restore / ack / snooze / replacement do not auto-resolve. Resolved findings remain listed.

j · Scenario

Scenario summary (from the fixture)

Now = Wed 30 Sep 2026 15:22:00 PDT. Fictional demonstration data. The counts below are read from the demo incident fixture (MK.select.fleetCounts(MK.data('incident','default'))) when scripts load, whatever dataset is active. Store changes such as acknowledgments still apply.

4 of 6expected collectors reporting · 1 workstation asleep

5 of 6UPSs communicating

1UPS on battery

2open incidents (1 critical, 1 warning; 0 acknowledged)

1recovery today

Two open incidents + one recent recovery

INC-0412 · Broadwater · BW Rack UPS on batteryCritical · open · not acknowledged · not recovered · first evidence 15:09:00 · declared 15:10:00 · UPS estimate 18 min est. (initial 34) · email and push delivered
INC-0413 · Shop · Contact lost with 2 of 2 probes — cause unknownWarning · open · last contact 15:10:02 · first evidence 15:10:32 · declared 15:15:02 after the 5 min grace · email 15:15:03 · push failed 15:15:04, retrying
INC-0411 · Duplex · Contact lost — recovered 15:02:06First evidence 13:41:00 (local probe) · declared 13:49:00 · acknowledged 13:52 by jp · resolved 15:07:06 · records still arriving, shown separately

Site summaries

Broadwater: 1 of 2 UPSs on battery · 1 on utility (separate circuit)
Home: Healthy
Shop: Contact lost · last known 15:10
Duplex: Recovered 15:02 · history arriving (1,248 pending)

Duplex 14:30–14:52

13:41: Local probe: all 3 targets fail (confirmed). Received 15:02:06.
13:44: Server: contact lost, cause unknown.
14:03: UPS on battery, recorded locally. Received 15:17:40 · replayed (historical backfill, no duplicate or obsolete notification).
14:30–14:52: Probe offline: no records. Connectivity unknown. Power is a gap. “At least 27 minutes on battery; endpoint unknown.”
14:52:10: First post-gap observation: utility present, charge 41%, ±90 s until clock sync at 14:54. Restoration happened at an unknown time between 14:30 and 14:52.
15:02:06: Fresh contact and probe evidence → INC-0411 recovered; resolved 15:07:06 after 5 min stable. Backlog keeps draining.

k · Preserved exploration

Preserved exploration (unchanged references)

Rounds 1–3 explored nine directions. They are kept unchanged for reference. This design takes its identity from concept 8 and its equipment workflows from concept 7; see the notes for provenance.

Comparison canvases and notes

Concepts 1–9

Concept 1 · identity · dashboard · mobile · CLI
Concept 2 · identity · dashboard · mobile · CLI
Concept 3 · identity · dashboard · mobile · CLI
Concept 4 · identity · dashboard · mobile · CLI
Concept 5 · identity · dashboard · mobile · CLI
Concept 6 · identity · dashboard · mobile · CLI
Concept 7 · identity · dashboard · mobile · CLI
Concept 8 · identity · dashboard · mobile · CLI
Concept 9 · identity · dashboard · mobile · CLI