igneum/docs/plans/miner-ui-3-audit.md

Igneum Miner UI 3: the audit, 6 October 2026

the project lead, 18:00 UTC: "run another audit of the miner app and make it as gorgeous as possible and as simple as possible but not lacking any features, think of this as an Apple product in terms of UI and UX, with tuning easy, buttons to tune each card again, or if automated then fair enough." Branch miner-ui-3, worktree ../igneum-wt-miner-ui-3, from master b79f2cb. The design is docs/plans/miner-ui-3.md; this file is what was found.

1. How it was looked at

What	How
The installed 0.3.13 app on this Mac	its URL from ~/Library/Application Support/Igneum/app/app.url, opened in the built-in browser pane and shot headless with Playwright's own chromium (never Chrome.app). The miner is paused on the project lead's order and was not resumed; /api/state read only.
The states this Mac cannot show (an NVIDIA rig, syncing, a node restart, a clock block, no cards, the setup screens)	tools/ui-mock/server.mjs on port 4317 from this worktree (the one on 4310 is another agent's and serves the old one-page UI; do not read it as master), scenarios fresh, nvidia, syncing, nodedown, nocards, clock.
The update card and the strips	the UI's own ?update= and ?job= sample states on the live app (client side only, nothing posted).
Sizes	1280 x 820 (the shipped window), 900 x 600 (the hosts' floor), 390 x 844 (a narrow Windows window, a phone).

Screenshots: docs/plans/miner-ui-3/00-*.png to 26-*.png, named below. The live app's state while shooting: Apple M5 Max, paused, node synced at 109,859 blocks with 6 peers, 23,056 lifetime blocks, proving off, external node.

2. What a first-time home miner sees, screen by screen

Rating: 10 = nothing to change. The three questions per screen: what does it say in jargon, which number has no unit or no meaning, which 0 or blank has no reason word.

2.1 Welcome (00-welcome.png), 7/10

Good: one heading, one lead, three tiles, one button. The eyebrow "devnet v4 · nothing is bought or sold" is honest.

Problem	Where
"Mined by GPUs. Proven by fire." is an aphorism (copy law).	lead
"Syncs the chain from the seed node", "A new program every hour. The next one compiles while you mine", "EVM address", "seed" (the last line) are jargon a home miner has never met.	the three tiles, the seed line
The coin is the retired ringed coin (brand/README.md: "the old ringed coin. Retired as a source"). The app icon is the plain square.	the hero
The welcome has no idea what the user will earn or spend; the one question a home miner has ("is this worth running?") is unanswered until the third screen.	whole screen

Apple would: keep one line of what it does, three tiles in plain words (runs in the background, uses your graphics card, pays an address you own), the button. Drop the seed line (there is no seed phrase in this app; it is a key).

2.2 Set up, step 1, your GPU (01-setup-gpu.png), 7/10

Good: one row per card, the switch, a sentence. The integrated-GPU rule is explained.

Problem	Where
"worker Metal", "40 GPU cores", "64 GB unified": three facts, none the user chose or can change. "worker" is internal.	the row's meta line
"Each card you switch on gets its own worker" is engine talk.	the help note
The NVIDIA note about the 80% cap and the administrator prompt appears only when an NVIDIA card is present; that is right, but it is 44 words for a decision the user is not taking here.	#cards-power
No number: the row does not say what the card is expected to make. The fleet priors (site/miner-priors.json) know the model's MH/s and W; the row could say "about 120 MH/s at 290 W" for a known model.	the row

Apple would: one row, name, switch, one line under the list. The cap note goes to the card where it applies.

2.3 Set up, step 2, where rewards go (02-setup-address.png), 8/10

Good: two options, one recommended, the paste box opens on choice, one button.

Problem	Where
"EVM address", "secp256k1 key", "0x followed by 40 hex characters": the first is unavoidable once, the second is jargon that helps nobody.	the lead, option 1
The dev-fee sentence sits here, on the address screen, as a surprise. It belongs where the fee is switched (Settings) and on the earnings line.	the lead
"Start mining" on this screen does not start mining when "Make me an address" is chosen: the key sheet comes first. The button lies once.	the primary button

2.4 The key sheet (03-setup-key.png), 8/10

Good: shown once, both values with Copy, the file path, the checkbox gate.

Problem	Where
"On devnet the vote keys are test keys derived from the miner's label. Mainnet vote keys will be random and stored like this wallet." is an internal note on a user's first sheet.	the second note
"Settings can show it again": the key lives on Rewards, not Settings (r-key-card). Wrong page named.	the first note
The address box repeats what the next screen shows; the sheet could show the key alone, with the address beneath in small.	the two boxes

2.5 Mine (04-mine-live.png, rig: 15-mine-nvidia-rig.png), 6/10

What a home miner sees first after setup. Good: the big button, the rate, the rows, the blocks strip.

Problem	Where
Four tiles compete with the big button: hash rate, blocks found, next program. "Next program 49:52 · next program not known yet (…)" is a countdown to an internal event, cut off mid-sentence. A home miner does not need an epoch timer on the first screen.	hero row
The card row's numbers are n/a three times on this Mac (hash rate, temperature, power), in ember, which reads as an error. Apple silicon reports no temperature or power, so the words should be "not reported on Apple silicon", once, not three red n/a.	GPU row
The row says "off · 64 GB unified" while the switch is ON and the big button says "Start mining": three states on one row. The card is on; the miner is paused. The row needs the word "paused".	GPU row
0.0 MH/s in ember with "paused" under it: the number is right, but the eye reads a red zero. The rule (the project lead, 6 October 2026, ember-tune.md 6a): a card never shows 0 MH/s without a reason word. The tile does carry "paused", so it passes, but in grey, under a red 0.	hash rate tile
No money anywhere. The page shows MH/s, W, °C, blocks. It never says what a block is worth, what the electricity costs, or what the machine made today. The one number a home miner wants is missing.	whole page
MH/W (efficiency) is on Settings, not on the row where the rate and the watts are.	GPU row
"Your blocks": "last 10 min 0 · last hour 0 · dev fee 0 · chain 109.8k". Four bare counts; "chain 109.8k" is the chain height with no label of what it means; "dev fee 0" is the count of blocks mined for the dev fee, with no unit word (the tooltip has it).	blocks card head
The blocks strip is 170 px of empty canvas for most of a home miner's day (one block an hour on a small card). The legend has three items for one kind of mark.	blocks card
Activity shows raw engine lines: "consensus parameters from the signed manifest: {"difficulty_v2_activation_daa":33000, ..." as a JSON blob, "remote job: update check now; a newer version installs at once". The feed is a developer log, not a user's activity.	Activity
The rig shot: the 4070 row says "restart in 4 s · 12 GB · 6783 blocks · ne…" and the hash reads n/a in ember; the second sentence is cut. The reason for the restart (the engine's message) is not on the row.	15
"A power cap is not applied yet: Settings has a Retry for the administrator prompt." A problem on the Mine page sends the user to another page to fix it. Two taps minimum.	the note under the rows
The top bar repeats the pill: "paused · node synced · up 24 min" and then a pill saying PAUSED.	top bar
"1 OF 1 ON" eyebrow in capitals is a count of switches, not of cards mining.	card head

Apple would: one hero (the big button and the live total: MH/s, W, £ a day), the card rows as the only list, a one-line "today" (blocks, £, kWh), and move the blocks strip and the activity feed behind one "Activity" view.

2.6 Prove (05-prove-live.png), 5/10

Problem	Where
95 words of explanation before the switch: "short mathematical proof, in pieces called shards. The chain assigns shards to your keys ... a full shard needs 20.4 GB of GPU memory, measured". A home miner wants one sentence: can my card do this, and do I earn from it.	lead card
Two paragraphs say "Off" twice ("Off. Switch it on and this machine proves...").	lead card
Four tiles with 0: state Off, assigned 0, proven 0, paid 0 "0.0000 IGN earned". Three zeros with no reason word. The reason is on the first tile ("off") and nowhere near the others.	the strip
"Verifier: off: relay only" in ember, then 50 words on what a verifier is, then "external node: the app did not start it, so it set no verifier". Internal plumbing.	Verifier card
"Program · pinned guest", "shard program id", "aggregator id": two 66-character hashes with Copy. Nobody at home copies these.	Program card
"Proving on; the first shard arrives within a minute" toast, "needs setup, one-time install, about 20 minutes" row: the only user-facing decision (install the prover) is a small button in the lead card.	pv-setup

Apple would: one card. A tier sentence per card ("RTX 5090 proves while it mines", "RTX 4070 (12 GB) cannot prove: a proof needs 20.4 GB", "Apple M5 Max proves on the CPU, slowly"), the switch, and one earnings line ("0.0000 IGN from 0 proofs"). The ids and the verifier go behind "Details".

2.7 Rewards (06-rewards-live.png), 6/10

Problem	Where
"Balance: --, shown in the wallet, not here yet". A placeholder on the money page. The engine has no balance field (miner-ui-2 follow-up, never built).	balance tile
"This run: 0 since the app started, 24 min a…" cut off.	tile
No money. Blocks found 23,056 with no value. No reward per block, no IGN total, no £.	whole page
"Save your key" is a card with ember "ONCE" every time the page opens, even after the key is saved and acknowledged.	key card
"Use another address" is an open text box with Change next to it, on the same screen as the key. Pasting a wrong address and tapping Change moves every future block with no confirmation.	address card
The dev-fee line sits under the address box, in the "Use another address" card, where it has nothing to do.	r-devfee-line
"Open the wallet page" is a ghost button at the bottom of the second card. The wallet is where the balance is.	r-wallet

Apple would: one card, money first (IGN earned, blocks found, £ a day at today's rate when a price exists), the address with Copy, then "Change address" and "Show my key" as two rows that confirm in place.

2.8 Node (07-node-live.png, syncing 18-node-syncing.png, clock 21-node-clock.png), 5/10

Problem	Where
Four tiles, four cards, eleven numbers: headers, DAA score, difficulty, tips, blue score, digest, next switch, last lock, age, votes sent, peers. A home miner needs one line: "the node is synced, 6 peers".	whole page
"DAA score", "blue score", "tips", "difficulty 137.73M", "consensus digest not printed yet", "finality miner-only", "last lock none yet", "age n/a", "votes sent 0 · waiting for the miner": every one is jargon or a 0 without a reason (the finality 0 has one, in a note, in grey).	Chain, Consensus, Finality
"Synced" appears three times (the tile, the Sync card, the top bar).	tiles, Sync card
The Sync card repeats the node tile's sentence word for word.	Sync card
The clock block (21) is right in shape (a card with Sync clock and the manual hint) but sits on the Node page; a home miner whose clock is wrong is looking at Mine, where the hash is 0. The rule here says the strip carries the clock only on the setup screens.	n-clock
"Read 5 s ago", "read every 10 s": two staleness marks for one reading.	tile, Chain eyebrow

Apple would: one line on Mine ("Node synced · 6 peers · 109,859 blocks") and a Details view for the rest, since the digest and the switches are needed when something is wrong, not every day.

2.9 Updates (08-updates-live.png, job strips 13, 14), 6/10

Problem	Where
"Consensus upgrade at height 198,000." under the version with no meaning (the height is behind the node already: 198,490).	the lead line
The remote-jobs card: 60 words of explanation, a Check now, a 20-row table with columns job / kind / started / exit / report, job ids like update-now-0313-switch-d937c69d, "done (0)", "uploaded". This is the fleet operator's console, shown to every user.	Remote jobs
"signing key sha256:8f186e37b48…" at the foot.	s-jobs-key
Two "Check now" buttons on one page, one per card, both the same words.	both cards
The switch "Install updates by itself" and the paragraph under it are right.	lead card

Apple would: one card: the version, "up to date, checked 13 min ago", the switch, Check. The jobs go into a history row ("Igneum ran 20 jobs on this machine, the last 16:36") that opens the table.

2.10 Settings (09-settings-live.png, rig 16-settings-nvidia-rig.png), 4/10

The page with the most work in it and the hardest to use.

Problem	Where
The per-card block mixes a slider, two status lines, a tune line with a button, and an identities stepper with 30 words of help, per card. On the rig shot each card is 370 px tall; three cards fill two screens.	set-card
"Power cap 80% · 460 W", "cap applied: 460 W", "draw 441 W GPU 71 °C memory 92 °C efficiency n/a": the same watts three times; efficiency n/a while draw and rate are both known (the engine's eff_mhw was 0 in the mock; live it is computed).	set-card lines
"tuning: not run yet (starts after 120 s of steady mining)" with a Tune now button; nothing says when the next scheduled tune is, or when the last one ran.	tune line
Ember Tune's switch has a 118-word paragraph under it: the power ladder, the clock ladder, 75 s a step, 1% tolerance, rejected hashes, hot GPUs, dragged memory clocks, fleet priors, privacy. This is the engineering spec, on a switch.	s-sweep help
Power control: three sentences, then the same sentence again from the state ("Off: NVIDIA cards measure only; AMD cards need no rights." twice in the live shot).	s-power-control help
"Identities: Each identity votes and is paid on its own. 8 suits a big card, 2 a small one, 1 an integrated GPU. Changing it restarts that card's worker." A stepper 1 to 64 for a concept the user cannot picture. The engine picks a default per card already.	ids
"cap not applied (needs the administrator prompt) Retry" in ember: this is the one thing a Windows NVIDIA user must do, and it is a tiny button inside the second card's fourth line.	16, the 4070
"name: a name for this machine · Rename. A label for you only. Keys come from the machine id d937c69d, never from the name." Jargon for a text box.	This machine
"Vote on finality checkpoints: Your miner signs a checkpoint every 30 s. Votes are what lock the chain; leave it on." A switch whose help says never to touch it.	s-vote
"Trust proof records without verifying them" under Advanced: devnet only, restarts the node.	s-trust
"Dev fee 1% (1 block in 100)" with a switch: right, but the fee's own line is "Dev fee 1% (1 block in 100); the miner names the address when it starts".	s-devfee
Logs: two buttons and two file paths. Right, but the log is also in the rail.	Logs card
No electricity price anywhere, so nothing in the app can say £.	whole page

Apple would: Settings as a list of plain rows: Tuning (goal, Power control, schedule), Start at login, Updates, Remote jobs, Dev fee, Electricity price, This machine's name, Logs, Advanced. The per-card controls live on the card, on Mine, where the numbers are.

2.11 The update card (11-update-card-ready.png), 9/10

The best screen in the app: the mark with a ring, the name, one line, three notes, the size, two buttons. It says "Igneum Ember 0.3.7" while the app is "Igneum Miner" everywhere else (UpdateCard.NAME). Keep it, fix the name.

2.12 The notices strip (12-strip-update-downloading.png, 13-strip-job-running.png, 14-strip-job-failed.png), 7/10

One notice at a time, actions on the right, a close. Right. Two problems: the job strip shows raw RESULT shard=2 prove_s=39.8 lines as the detail (engine output to a user), and the strip pushes the whole page down 100 px when it appears (the hero row jumps).

2.13 The log drawer (10-logs-drawer-live.png), 8/10

Chips, search, a time jump, last error, last swap, wrap, copy, follow, a ruler. Complete and quick (virtualised). It is a developer's tool and it is fine as one. "WATCH" as a source chip means nothing to a user; the lines under it are the observer's. Keep, rename nothing, hide behind Logs as now.

2.14 The tray and the menu bar item

macOS (app/mac/IgneumMiner.swift): Open Igneum Miner, Pause mining / Resume mining, "Node: synced, 109,859 blocks, 6 peers", "Blocks found: 23,056", Quit Igneum Miner. Windows (app/windows/host.cpp): the tip "Igneum Miner: 17.0 MH/s, 8,058 blocks found, node synced", a menu with Open, Pause and Quit, and a balloon "The window is in the tray. Right-click the icon to pause or quit." Both fine. Neither shows money or watts; both get them when the state has them (the Rust side formats the tip from hash_total, accepted_total, node.state; a watts_total and a pounds_per_day field would complete it; owed, not built here).

2.15 Narrow (22-narrow-900-mine.png, 23, phone 24-phone-mine.png, 25)

900 x 600: the rail folds to icons, the hero goes two by two, the rows drop the power column. Usable. 390 wide: the rail still takes 150 px, "Stop mining" is cut to "Stop minin", the GPU row's numbers overflow the card to the right (413 half off screen), the tiles truncate every sub-line. The Windows window can be dragged to 400 px wide and the layout breaks there. No phone layout exists.

2.16 Light mode (26-light-scheme-mine.png)

There is none. <meta name="color-scheme" content="dark">, one token set on :root, no prefers-color-scheme block. The page is dark whatever the OS says.

3. Every feature the old UI has (the build's tick list)

#	Feature	Where it is today	Route
1	Welcome, GPU pick, address choice, key sheet	the three setup screens	api/detect, api/cards, api/setup, api/key/saved, api/start
2	Start / stop mining	Mine big button	api/pause, api/resume
3	Per-card on/off switch	Mine row, setup row	api/cards (the whole list)
4	Hash rate, temperature, power per card; totals	Mine row, hero tiles	state
5	Blocks found, this run, last 10 min, last hour, dev fee count, chain height	Mine tiles and blocks card	state
6	Next program countdown and epoch	Mine tile	program
7	Blocks strip (10 min canvas)	Mine	state found
8	Activity feed	Mine	events
9	Hot-plug states: new card, removed, not usable (Code 43)	Mine row, strip	state
10	Proving switch, setup button, state/assigned/proven/paid, segments line, verifier, program ids	Prove	api/prove, api/prove/setup
11	Rewards address with Copy, source, blocks, this run, balance placeholder	Rewards	state
12	Show / hide the private key, the wallet file path	Rewards	api/key/reveal
13	Change the rewards address	Rewards	api/settings {address}
14	Open the wallet page	Rewards	api/open
15	Node state, height, peers, version, chain numbers, digest with Copy, switches list, next switch, finality, sync ETA	Node	state
16	Clock skew card with Sync clock and the manual hint	Node, setup strip	api/clock/sync
17	Version, update note, Check now, Install now, auto-update switch	Updates	api/update/check, install, auto, open
18	The update card (modal) and the strip notices	everywhere	same
19	Remote jobs: allow switch, Check now, note, history table, signing key	Updates, Settings	api/jobs/allow, api/jobs/check
20	Per-card power cap slider (NVIDIA), applied / not applied + Retry, draw and temperatures, efficiency	Settings card	api/cards {power_pct}, api/power/apply
21	Per-card identities stepper	Settings card, setup row	api/cards {identities}
22	Ember Tune switch, per-card Tune now / Stop / Unpin, the tune line	Settings	api/sweep/enable, start, stop, pin
23	Power control switch	Settings	api/power/control
24	Start at login, vote, dev fee, machine name, trust mode, live page	Settings	api/settings
25	Copy the log, show the log, the log and chain folders	Settings	api/log
26	The log drawer (chips, search, time, last error, last swap, wrap, copy, follow, ruler, resize)	rail	api/log
27	Quit (with a confirm dialog)	rail	api/quit
28	The pill, the top status, the rail foot (name, address, version, chain)	chrome	state
29	Keyboard: arrow keys on the rail, Escape on the card, Enter on the time box	chrome	none
30	?page=, ?screen=, ?update=, ?job=, ?logs=1, ?visible=1, ?debug=1, ?host=mac	URL	none

Ember's new fields (ember-tune e9738dd, from the agent): tune_step, tune_steps, tune_eta_s, tune_plan (full | confirm | baseline | climb), tune_curve, tune_mem_mhz, mem_cap_mhz, card states tuning and held; settings.tune_goal (efficiency | balanced | rate), settings.power_price_pence, settings.tune_climb, settings.tune_period_s; POST /api/tune/goal {goal, price_pence, climb}. No next-tune field: next = sweep_at + tune_period_s, "due now" when sweep_at is 0.

4. The top ten findings

#	Finding	Consequence per tier
1	No money anywhere. No electricity price, no £ a day, no IGN earned on Mine or Rewards.	Every tier. A home miner with one card cannot tell whether the app pays for its power; a rig owner cannot compare cards.
2	Three red n/a per card row on Apple silicon, 0.0 MH/s in ember, "off" on a row whose switch is on. A paused Mac looks broken.	macOS, every card. Apple silicon never reports W or °C, so every Mac user sees this forever.
3	Tuning is split: the schedule and the switch on Settings, the row on Mine, the tune line per card on Settings, no "tuned 2 h ago, next Sunday", no Tune all, no goal.	Every tier with a tunable card (NVIDIA, AMD on Windows).
4	Settings per-card block is 370 px per card: slider, identities, tune line, telemetry. A six-card rig scrolls through 2,200 px of controls.	Rigs most; single cards get a page that looks like a rig's.
5	Prove is 95 words plus four zeros plus two hashes. The tier sentence ("this card cannot prove: 12 GB") is not said anywhere.	8, 12 and 16 GB cards see a switch that will fail; 24 and 32 GB cards do not see that they can.
6	Node is eleven numbers for one fact. DAA, blue score, tips, digest, lock, votes: all jargon with no reason words.	Every tier; nothing to do per tier.
7	The remote-jobs history table and the signing key are on every user's Updates page.	Every tier sees the fleet console.
8	Fixes live on another page: "cap not applied, Settings has a Retry", "Switch a GPU on below first", "Settings turns it off". Two taps for every fix.	Windows NVIDIA most (the administrator prompt).
9	No light mode; no layout under 900 px (the Windows window can be narrower; the rail eats 150 px at 390).	Windows laptop users with a half-screen window.
10	Developer lines leak into user surfaces: the Activity feed's JSON, the job strip's RESULT lines, "Igneum Ember" on the update card, "worker Metal", "pinned guest", "miner-only", "shown in the wallet, not here yet".	Every tier.

Smaller, fixed in the build with no mention elsewhere: the key sheet says "Settings can show it again" (it is Rewards); "Start mining" on the address screen opens the key sheet instead; "Synced" three times on Node; two "Check now" on Updates; "Once" eyebrow on the key card forever; the retired ringed coin on Welcome; "Mined by GPUs. Proven by fire." (aphorism); the quit confirm() dialog (the viewer never shows dialogs: the rule in the brief).

5. What the previous redesign (miner-ui-2) set out to do and what it achieved

It set out to split one page into sections, put every setting on a section with one line of help, and lay out from 900 x 600. It achieved all three: the rail works, the keyboard works, nothing was lost, the update card and the strip are good. What it did not do, by its own section 4: the balance, the pause-while-I-use-it switch, the log export. What it did not see: it moved the controls off the cards and on to a page, so the thing the user tunes (a card) and the controls that tune it are two sections apart; it kept the engine's vocabulary on every page; and it never put a currency on screen. UI 3 keeps the rail's sections as views, puts the card back at the centre, and adds the money.