[kazad]

What

A guided tutorial that walks a new owner through the Summary, Home and Configuration pages, together with the page changes the tour was written around: a regrouped Configuration page, updated Summary links, a larger Summary simulator and a reordered Home.

It is one branch with five commits, one per topic, so each can be read on its own. The first four each stand alone on main; the tutorial sits on top of all four.

Why

An owner who finishes the setup wizard 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. Writing the tour showed where the pages themselves were in the way, so those are fixed first.

The five commits

1. Group the Configuration page around how an owner uses a node

The page is now five groups: Node (Identifiers, Mode, Node Claim, Network), Radar (Cached Towers, Tower, Capture, Tracking), ADS-B (ADS-B Truth, tar1090), Other (SSH Access, Setup Wizard) and Support (Cloud Services, Remote Support, How We Reach You).

• Each group is titled in the page with a rule under it, and the side menu's group titles carry the same rule.
• "Tower" is now "Cached Towers" and "Location" is now "Tower". A section has one name, written the same in the menu, its heading and the wizard hints.
• Center Frequency moves from Capture into Tower's transmitter block, after Name.
• Tower shows the receiver's name read-only. It is changed under Identifiers, which also shows the server's identifier for the node.
• The form that Apply changes submits wraps exactly the Radar and ADS-B groups. A radar field left outside the form would be missing from the POST, which the server reads as that setting having been cleared, so tests/test_config_layout.py holds this.

2. Link Summary to the combined dashboard and to our own Discord

• Resources: Offworld Labs, Retina Wiki, Network Map and Dashboard (app.retina.fm), Passive Radar News, blah2 Discord.
• Help: the Retina Discord, then the support email. The blah2 Discord moved to Resources because it is that project's channel, not ours.
• The banner button is "Network Map and Dashboard" and goes to the same address as the card. The separate Retina Dashboard button is gone.

3. Stack the Summary simulator and name it Doppler Mapping Tool

• The sky and the delay-Doppler plot are stacked at full width, sky first, and the sky is drawn 1.3 times further out so the beam at its widest fits.
• The beam reaches a fixed range instead of the edge of the drawing, and the aircraft's heading is smoothed along the drawn path.
• The handle is labelled "Grab to Aim". A mouse or touch grab leaves no focus box; keyboard focus thickens the ring instead.

4. Put Controller last on Home and say how much the Tracker keeps

Cards run Passive Radar, Max-Hold, ADS-B Map, Tracker, Controller. The Tracker card says it keeps up to 4 hours of history.

5. Add a guided tutorial across Summary, Home and Configuration

• /tutorial starts a tour drawn over the real pages. Each step dims the page, lights one region, points an arrow at it and says a sentence or two, with Previous, Next and Skip Tutorial.
• 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 link shows the plain page.
• The owner moves between pages by clicking the lit card or tab.
• The Summary steps only run on a network with more than one node. Every run ends on a closing Summary step. There are 29 steps with the Summary steps and 24 without.
• The wizard's last page recommends the tour, and Configuration gains a Tutorial section under Other that launches it at any time. While the wizard is in progress, /tutorial redirects to it.
• The step about overload describes the reading and help box from 20261007 - Show when the radio is overloaded, now that it keeps running #110.

Testing

• Full suite on this branch merged with current main (which has gained 20261008 - Stop blah2 before restarting the SDRplay service #111 and 20261008 - Rename routes/mode.py to routes/sdr.py #112 since the branch was made): 1090 passed, 1 failed. The one failure is tests/test_node_name.py::test_an_unwritable_location_reports_rather_than_raises, which fails in the sandbox the suite ran in because it runs as root there, and fails the same way on untouched main. ruff check . and the vulture hook pass. The branch merges without conflicts.
• New tests: tests/test_config_layout.py, tests/test_home_services.py and tests/test_tutorial.py; tests/test_fleet.py gains the links and simulator tests.
• In a browser, off-device: every step walked at 1920, 1280 and 390 px wide, checking that each highlight covers its target and does not overlap a neighbour.
• On a test node with an RSPduo attached, deployed over SSH on top of main as of 20261005 - Say what each notch filter blocks and when to leave it on #109 plus 20261007 - Show when the radio is overloaded, now that it keeps running #110: the service restarted cleanly with no traceback or HTTP 500 in its log, all 29 step pages loaded with something to highlight, the page layouts matched, the settings files were unchanged and the radar stack stayed up. The tour was then looked over by eye in a browser on that node.

Not verified

• Applying a changed setting through the rearranged form on hardware. The tests cover which fields the form posts; no setting was changed on the node by the automated checks.
• The wizard's last page on hardware. The wizard was not run on the node.
• The overload help box during a real overload.
• The 24-step single-node run in a browser. It is covered by tests only.
• This branch merged with 20261008 - Stop blah2 before restarting the SDRplay service #111 and 20261008 - Rename routes/mode.py to routes/sdr.py #112 on hardware. The node test predates them.
• The tutorial's statement that the Minimum SNR default is 7. That default is set in retina-node and was not checked from this repository.

For the reviewer

• The Retina Discord link is an invite that expires on 6 November 2026. It needs replacing with a permanent invite before a release carries this.
• The example pictures in static/tutorial are real captures, used unaltered, except signal-overload.png, which is rendered from the page with simulated readings and should be replaced with a real capture when there is one. Please confirm you are content for the captures to be public.
• Known limits of the tour: 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.
• Known limit of the simulator: steered far to one side at its widest, the beam still runs off the bottom of the panel.
• This is five topics on one branch, which departs from one topic per branch. The commits are ordered so it can be split if you prefer.

Docs

• New: docs/features/tutorial.md, added to the map in docs/README.md.
• Updated: docs/features/config-editor.md (new Page layout section, renamed sections), docs/features/fleet-and-naming.md (Resources and Help links), docs/architecture.md (simulator, Home cards, tutorial), docs/features/setup-wizard.md, docs/features/device-state-and-telemetry.md and docs/features/remote-access.md (renamed sections).

After this

• A permanent Retina Discord invite.
• A real overload capture for the tutorial.
• The setup wizard is due an update to match the regrouped Configuration page (naming the node, cached towers, a simpler calibration explanation).

🤖 Generated with Claude Code

https://claude.ai/code/session_01AoHZhvWU7Ge89Cm6YgrExB

---

Generated by Claude Code

[Purple10101]

Thanks for this. Before I review in depth, could you split it into four PRs, one topic each? The commits already line up:

1. Group the Configuration page (3206489)
2. Summary links and the Doppler Mapping Tool (cafb558 + f84f2a6)
3. Home card order (f498ced)
4. The guided tutorial (eb1e309). This one depends on the other three, so please open it last, on top of them.

PRs 1-3 each apply cleanly to current main and pass the full suite on their own.

Two things will block merging, so it's worth fixing them while you split:

• PR 2: the Retina Discord invite expires on 6 November. It needs to be a permanent invite before this merges, not just before a release. fleet-and-naming.md already says it must be permanent.
• PR 4: static/tutorial/adsb-map.jpg shows where a real node is. Please crop it so the receiver marker and the town names can't be seen.

I've tested this branch on a node and found issues that need fixing in the Configuration and tutorial changes. I'll leave detailed notes on each PR once they're open.

[kazad]

Split into four PRs as requested: #115 (Configuration page), #116 (Summary links and the Doppler Mapping Tool), #117 (Home card order) and #118 (the guided tutorial, which carries the other three until they merge). All four are rebased onto current main and each passes the full suite on its own. Jonathan and Josh agreed to keep the ADS-B picture as it is; the permanent Retina Discord invite is still to come on #116. Closing this one in favour of those.

---

Generated by Claude Code