20260929 - Move the design notes out of the code and into docs/

[Purple10101]

What

Most of what retina-gui knows about itself lived in docstrings and block comments: 37% of the lines under src/, and half of calibrator.py. It now lives in docs/, written for developers:

Doc	Covers
docs/README.md	Index, and a map from every source file to the doc that covers it
docs/architecture.md	Startup, blueprints, sessions and CSRF, the apply service, stack reconcile, the restart lock and its couplings to other repos
docs/features/*.md	Auto-Calibrate, setup wizard, device state and telemetry, remote access, fleet and naming, config editor, OTA updates, SDR mode, towers, tracker
docs/operations/node-files.md	Where the GUI lives on a node, the files it reads and writes, environment variables, the CARTO key (moved out of the README)
docs/history/	The old .plans/ design notes and toggle.md, kept as an archive with an index

The code keeps a one-line summary, the invariants the next editor has to see in place (safety limits, lock ordering, values shared with other repos) and a See docs/...#anchor pointer for the rest.

	Before	After
src/	10,193 lines	about 8,350
src/calibrator.py	1,860	about 1,290

No code changes outside the tests

Every changed file under src/, static/ and templates/ was checked against main with its comments and docstrings stripped:

• Python: syntax trees with docstrings removed are identical.
• JavaScript: token streams, comments excluded, are identical.
• Templates: markup with HTML, Jinja and script comments removed is identical.

Two tests in test_towers.py use a setup.js comment as a slicing marker. That comment is unchanged. A small block of comments in tracker.html was left as it was because the check could not verify that region.

Where the old prose disagreed with the code, the docs describe the code, and about a dozen stale comments were corrected (for example a lock timeout quoted as 30 minutes where the constant is 40).

Test data

The tests and test-data/ carried values copied from real nodes and accounts. They are replaced with invented ones, applied consistently, so the tests are unchanged in what they check.

Repo rules

A new CLAUDE.md:

• Makes updating the docs part of every change, using the file map in docs/README.md.
• Records the branch, commit and PR conventions this repo already follows.
• Forbids real data in code, docs, tests, test data, commits and PR descriptions, with a table of invented values to use instead.

Found along the way, not fixed here

• ?demo=1 in the wizard still calls the real node for the contact, claim, tower search and calibrate steps, so a demo can write real records or start a real calibration.
• Saving /config drops any key in the five form sections of user.yml that the form does not post.
• login.html's hint points at a password control on the Configuration page that does not exist.
• A node's own fleet tab shows its node id instead of its friendly name until discovery sees it.

Verification

• Full suite: 1018 passed. Ruff clean. node --check passes on the edited JS.
• Every docs/...#anchor pointer and Markdown link resolves: 519 checked.
• Rebased onto Save Auto-Calibrate results without asking #104. Its removal of the Persist button and preflight notice is reflected in the docs.
• Not verified: pages loaded in a browser. The change is comments only, so no rendering difference is expected, but it has not been looked at on a node.

🤖 Generated with Claude Code