[jfremerman]

Re-opened from #118 under the author's own GitHub account, as the reviewer asked; same code (commit eb1e309 on #113, rebased onto current main). Last of the 4 PRs split out of #113. This branch also carries the Configuration page commit from #119, because the tour points at sections that PR adds; once that merges, this PR reduces to the one tutorial commit. #116 and #117 are already on main.

What

/tutorial starts a guided tour drawn over the real Summary, Home and Configuration pages. Each step dims the page, lights one region, points an arrow at it and says a sentence or two in a card, with Previous, Next and Skip Tutorial. The wizard's last page recommends it, and Configuration gains a Tutorial section under Other that launches it at any time.

Why

A new owner finishes the setup wizard and lands on pages nobody has explained: which card opens what, what the dots on the radar display mean, which settings are worth touching, and how to tell a good signal from an overloaded one.

How it works

• The server owns the steps (src/tutorial.py) and every step is a URL, so a reload or the Back button keeps the place and a stale or hand-edited link shows the plain page.
• The owner moves between pages by clicking the lit card or tab, so the tour teaches the navigation it depends on.
• Steps about the radar views and the signal meter carry an example picture.
• The Summary steps only run on a network with more than one node; every run ends on a closing Summary step. 29 steps with Summary, 24 without.
• While the wizard is in progress /tutorial redirects to it, because Home and Configuration both bounce there.
• The card and arrows stay hidden until a smooth scroll has settled; laid out mid-scroll they flashed in the wrong place.
• The overload step describes the reading and help box from 20261007 - Show when the radio is overloaded, now that it keeps running #110.

For the reviewer

• ADS-B picture: static/tutorial/adsb-map.jpg is a real capture, used as is. Jonathan and Josh agreed to keep it uncropped.
• signal-overload.png is rendered from the page with simulated readings and should be replaced with a real capture when there is one.
• The Minimum SNR step states the default as 7; that default is set in retina-node and was not checked from this repository.
• Known limits: the margins only fit the card beside the Configuration page in a window of about 1580 px or wider, narrower than that the card sits over part of the page; at phone width several steps have no arrow.

Testing

• Full suite on this branch (with the other three merged in, before 20261014 - Link Summary to the combined dashboard and rework the Doppler Mapping Tool #116 and 20261014 - Put Controller last on Home and say how much the Tracker keeps #117 merged): 1096 passed, 1 failed (test_an_unwritable_location_reports_rather_than_raises, the root-only sandbox failure that also fails on untouched main). ruff check . and the vulture hook pass.
• New: tests/test_tutorial.py (step order and numbering, one or two sentences per step, every target present on its page, image sizes matching the files, the single-node run, the wizard redirect, stale links).
• In a browser, off-device: every step walked at 1920, 1280 and 390 px wide, checking each highlight covers its target and does not overlap a neighbour.
• On a test node with an RSPduo attached (combined 20261007 - Add a guided tutorial and regroup the Configuration page #113 build, before 20261008 - Stop blah2 before restarting the SDRplay service #111, 20261008 - Rename routes/mode.py to routes/sdr.py #112 and 20261013 - Show the Tracker at +/-300 Hz by default and flag tracks beyond it #114 merged): the service restarted cleanly with no traceback or HTTP 500, all 29 step pages loaded with something to highlight, every example image was served, settings files unchanged, radar stack stayed up; the tour was then looked over by eye on that node.
• Not verified: the 24-step single-node run in a browser (tests only); the wizard's last page on hardware; the overload help box during a real overload; this branch rebased onto current main on hardware.

Docs

New docs/features/tutorial.md, added to the map in docs/README.md; docs/architecture.md, docs/features/config-editor.md, docs/features/fleet-and-naming.md and docs/features/setup-wizard.md updated.

After this

A real overload capture, and the setup wizard update to match the regrouped Configuration page.

Review fixes (20261020)

Three commits: the Minimum SNR copy, the three blocking items, and the Tracker's
Below SNR layer.

Minimum SNR copy

The Configuration tour's fifth tuning step, "Tracking: Minimum SNR", lit the Tracking section and
its side-nav link, both of which are gone in #119, so the step had nothing to point at. The tuning
run is four steps again and keeps its order: what to watch, what too far looks like, and what to
change.

The Home tour's Tracker step also offered "tracks below the SNR threshold" as a way to sort the
Tracker. retina-tracker v0.5.0 tracks every detection and has no per-site SNR gate, so that layer
is always empty and the step was recommending a filter that can never show anything. The step now
names only the sorts that still do something. The layer itself is handled in #119.

The Tracker's Below SNR layer

Carried over from the Configuration review fixes: the rest of that work merged in #119, and this
is the part of it that had not landed, so it rides here rather than on a branch of its own.

The Tracker's Below SNR layer is removed. The same v0.5.0 change made the below_snr class
permanently empty, while the page still described it as detections "dropped at the SNR gate before
the tracker considered it at all" — a filter worth trying, that can only ever show nothing. An
owner who picked it saw an empty scope and had no way to tell that from a quiet sky.

Nothing is lost. The class is still read from the stream, still counted against the untracked cap
and still drawn under All, so a node on an older tracker shows those detections with the rest
instead of behind their own button. A layer remembered in localStorage falls back to All unless
the page still offers it, so an owner who had Below SNR selected does not open on an empty layer,
and a hand-edited value cannot select one either.

Start tutorial could send the owner back into the wizard

The last step offered Start tutorial and Go to dashboard from the moment it rendered, while
the two requests that end the wizard were still in flight with their failures swallowed.
save-step {complete} is the one that clears the step file and writes the completion flag, and
until it lands is_setup_wizard_in_progress is still true, so home.index, the config blueprint
and tutorial.start all redirect back to /set-up. An owner who clicked too quickly, or at all
if the save had failed, went straight back into the wizard they had just finished.

showStep now skips the generic save for the last step, and enterHooks.complete calls
finishSetup, which awaits that one save and reveals the two links only once it has returned. A
failure shows the server's reason and a Try again button rather than nothing, and costs
nothing else: the step file still holds the previous step, so a reload resumes there.
/set-up/complete is still posted without being awaited, after the gate — it brings the radar
stack up, takes tens of seconds, never raises, and nothing on the step depends on it.

A run could be renumbered while it was open

A step is addressed by its number in the run, and the run is 28 steps long when Summary is toured
and 23 when it is not, so the number means nothing without the list. _include_summary asked
discovered_nodes on every request, so a peer appearing or dropping mid-tour swapped the list
underneath the owner: the same ?tutorial=6 stopped being Home's first step and became
Configuration's welcome.

The question is asked once now, by start, and the answer travels in the URL as summary=1 the
way demo=1 already does, with demo implying it. A link carrying a number but no shape is read
as a single node's run, and payload already renders the plain page when the number does not name
a step there.

Skip did not stick

Each page of a tour was a pushed history entry carrying ?tutorial=, and close cleans only the
entry it is standing on, so one press of Back brought the tour straight back. Moves within a run
now use location.replace, so a whole run occupies the single entry it started in: there is one
entry to clean, and Back leaves the tour rather than walking it backwards. Nothing records the
dismissal and nothing needs to, because Back now lands on the page from before the tour, which
carries no parameter.

Testing

test_tutorial.py gains a peer appearing and a peer dropping mid-run, both asserting the payload
is unchanged; that every step URL carries the run's shape; that a demo link works carrying only
demo=1; that the script holds no location.assign; and that the wizard's last step starts with
both links hidden, offers a retry, and does not fire-and-forget the completion save. Four existing
tests now pass summary=1 where they relied on the node count being re-read. Full suite passed on
the rebased stack, ruff clean.

Not run in a browser or on a node. All three fixes are browser behaviour at heart — a button
reveal, a history entry, a URL parameter — so a manual pass on a node is the real verification.

Docs

tutorial.md: "Which steps run" records that the shape is decided once and carried in the URL, and
why a step number is meaningless without it; "How a run moves" says navigation replaces rather than
pushes; a new "Skip" section explains the single history entry and what used to go wrong.
setup-wizard.md: "Completion" is rewritten around the gate — why nothing on the last step is
clickable before the save lands, what a failure does, and why /set-up/complete is still not
awaited.

---

Generated by Claude Code

[Purple10101]

I've used the tour by hand on a test node and it's great: the copy is clear, the pictures help, and moving between pages by clicking the lit card teaches the navigation nicely. What needs work is how it interacts with the rest of the node's state, so this review is mostly about how those interactions were found and proven, because that's the part worth carrying into future changes here.

How to find the interactions

In retina-gui, a page is rarely just a page. Most bugs come from state the feature reads but doesn't own, changing between two requests. For this PR I listed every piece of state the tour depends on, then asked three questions of each one.

1. What does the feature read, and who else writes it?

The tour reads	Who else writes it
Whether the wizard is in progress (setup-wizard.json, via is_setup_wizard_in_progress())	setup.js on every step change (save-step); /set-up/save-step {complete}; the 24 h expiry
How many nodes there are (discovered_nodes())	The mDNS browser and the /healthz prober, continuously, on their own threads
Whether a calibration is running	Auto-Calibrate and Quick Calibrate; the before_request hold redirects GETs while it runs
The radar mode (mode.txt)	/api/mode, /set-up/complete, and the reset on every retina-gui restart
The step number in the URL	The browser: reload, Back and Forward, bookmarks, autocomplete

2. Can any of those change between two requests of one tour? A tour is many requests over minutes. Anything recomputed on every request (_include_summary()) or redirected by a hook (/ and /config while the wizard runs, the calibration hold) can disagree with the request before it.

3. What is in flight at the moment the user can click? Look at the code around your entry point, not just your own code. doTransition() in static/setup.js shows the last page's buttons before save-step {complete} and /set-up/complete have returned. Both are fire-and-forget, and their failures are swallowed. Also remember the browser's own rules: navigating away cancels in-flight fetches, location.assign adds a history entry, and replaceState only rewrites the current one.

How each one was verified

Reading the code gives the suspicion. Hardware gives the proof. Every finding below was reproduced on a test node with an RSPduo, running the current dev release, driven in a real Chromium browser over a remote link. Each time I checked the node's own state, not just the page: the files under /data/retina-gui, the retina-gui journal, and where /, /config and /tutorial redirected afterwards. Where timing mattered, I forced the ordering rather than hoping to hit it:

• Slow or lost requests: held or aborted one request inside the browser (Playwright page.route) while the page carried on.
• Exact interleavings: stepped through each request from a shell, so the order was certain.
• A node leaving or joining: withdrew and restored a second node's mDNS advert, which flips the node count within a few seconds.
• Wizard and calibration states: seeded setup-wizard.json at a chosen step, and started then cancelled a Quick Calibrate.

The node's settings files were restored byte for byte afterwards.

Blocking

1. Start tutorial can send the owner back into the wizard, sometimes from step 1.
Found by: question 3. The button is live before the node has recorded complete, and /tutorial redirects to /set-up while the wizard is in progress.
Verified: starting on Calibrate, Skip to the last page, click Start tutorial, in four ways:

• Normal link, click within 60 ms: no race. The save landed first.
• save-step {complete} held 2.5 s: the click redirected to /set-up, and the navigation cancelled the held save, so it never reached the server (the journal confirms this). The wizard reopened on Calibrate and saved that step again. /, /config and /tutorial all redirected to the wizard.
• The save lost, click 3 s later: the same outcome, after the page had said "You're all set".
• Redirect decided just before the save, wizard page rendered just after: the wizard found no resume point, restarted at Agreements, and wrote a fresh setup-wizard.json. Every page then sends the owner back into setup, for up to 24 h or until they finish it again.

The underlying reason it bites so hard: merely loading /set-up saves its first step. A stale /set-up?tutorial=1 link was enough to put the node back "in setup". "Go to dashboard" has always had this exposure, but this PR makes Start tutorial the recommended way out, so far more owners will take it.
Fix: don't reveal the last page's buttons until save-step {complete} has succeeded, and show a retry if it fails. Better, have /set-up/complete record completion itself, in one request the page waits for.

2. The step list can change mid-tour.
Found by: question 2. _include_summary() re-reads the node count on every request, and step numbers are positions in a 28- or 23-step list.
Verified:

• Peer leaves: with the tour on "Open your node" (step 5 of 28), I hid the second node and clicked the lit card. The tour landed on "Step 6 of 23: Max-Hold", silently skipping five steps.
• Peer appears: in a single-node run on "Open Configuration" (step 10 of 23), I brought it back and clicked Config. /config?tutorial=11 loaded with no tour.

A neighbour rebooting for an update is enough to trigger this. A peer whose GUI is down also drops out and comes back.
Fix: decide once in /tutorial and carry the decision in every step URL, as demo=1 already is.

3. Skip doesn't stick.
Found by: question 1, the URL row. Every page of a tour is a history entry with ?tutorial=N, and Skip only cleans the current one.
Verified: Skip on Configuration, then browser Back, and the tour reappeared at step 15. A bookmark or autocomplete taken mid-tour does the same.
Fix: use location.replace for page changes within a tour, or have Skip remember that the tour was dismissed.

Smaller

• The Tracker step still says you can sort by "tracks below the SNR threshold" (src/tutorial.py). retina-tracker v0.5.0 no longer drops anything at an SNR gate, so that layer is always empty.
• Keyboard users are stuck on the click-through steps. On "Open your node", ArrowRight, Enter and Space do nothing. Tab only reaches Previous and Skip, so the only way on is to quit. Letting Enter or Space on a focused lit target advance would fix it.
• Pictures. Clicking quickly through Max-Hold, ADS-B Map and Tracker, the picture didn't update until I clicked on it. Each picture took about 0.43 s to arrive over the remote link the first time, and a single <img> is reused with only its src swapped, often while the card is faded out. Preloading the tour's pictures at the start, and giving each step a fresh <img> (or awaiting decode()), should cure it.
• Step 4 would be better interactive. The overlay swallows every click, so the simulator it describes can't be tried. A per-step flag that lets pointer events through the lit region would do it.
• Skip in a demo run leaves ?demo=1 in the URL.
• During a calibration, the hold redirects /?tutorial=N and /tutorial to /config without the tour. Rare, since the overlay blocks starting one, but worth a line in the docs.

Checked and fine

• The whole tour: all 28 steps at 1920, 1280 and 390 px, each on the right page with its target ringed, and Finish closing on Summary.
• Navigation: Previous from 28 back to 1 across pages, the arrow keys, the Tab trap, reload keeping your place, and Escape.
• Bad links: stale and hand-edited links (out of range, wrong page, junk values) show the plain page.
• The other runs: the 23-step single-node run, and a 28-step demo run that keeps demo=1.
• Clicks during the tour:
  • A click on the lit node tab stays on this host, although the tab links to the node's .local name.
  • Lit service cards don't open mid-tour.
  • The wiki links open in a new tab with rel="noopener".
• Modes and settings: Spectrum mode gives the "nothing to point at" note instead of breaking, and reduced motion never hides the card.
• Cost: tour pages render within about 15 ms of the same pages without a tour.
• A real end of the wizard at human speed: Towers, a real /towers/select Apply, Skip Calibrate, a pause, then Start tutorial. The tour ran all 28 steps while /set-up/complete finished restarting the radar. By the Configuration steps the live signal meter was reading normally, and the wizard ended up completed.

A checklist for next time

Before a change here is ready, it's worth asking, and then proving on a node:

• State: does it read wizard state, the node count, calibration, mode, or the restart lock? What happens if that changes between two of my requests?
• In-flight work: what is still in flight when the user can first click? What if that request is slow, lost, or cancelled by a navigation?
• The browser: does it survive reload, Back and Forward, a stale or bookmarked link, and a second tab?
• Conditions: does it work on a single node, in Spectrum and SDRconnect, during a calibration, over a slow remote link, and with only a keyboard?

[Purple10101]

Thanks for the fixes. I've re-tested all three on a node and they hold: the wizard can no longer send an owner back into setup, a peer joining or leaving mid-tour keeps the step list, and Skip sticks.

They did open one new gap, which I've fixed directly in 2ae5ac0 on this branch. /set-up/complete now went out at the same moment the two links appeared, so an immediate click could cancel it in the browser. On a node in Spectrum, with that request held 2.5 s, it never reached the server and the node finished setup with no radar. It's now sent with keepalive and before the links show. Re-run on the same node, the radar came back. Details are in the commit and in setup-wizard.md#completion.

Please pull before you push again, so it isn't lost in a force-push.