[danielededo]

Why

A read-through of README.md, docs/DESIGN.md and demo/README.md, checking every claim against the code rather than against the last time it was true. Every API row, script name, flag, version and count in here was verified against what the repository actually contains.

The one that mattered

The documented development setup did not work. The README said:

cp .env.example .env             # point DATABASE_URL at a PostgreSQL instance

.env.example contained no DATABASE_URL, and the setting has no default on purpose — a test asserts it must fail at boot rather than fall back. So following the README literally ends in a pydantic ValidationError at import time with nothing to suggest the fix is to add a line. I reproduced it, fixed it, and reproduced the fix: the copied file now loads, with display_timezone, default_first_name and duplicate_window_seconds resolving to their documented values.

DATABASE_URL is now in .env.example, commented out, saying that Compose builds it from the POSTGRES_* values above and that a local run is the case that needs it. DEFAULT_FIRST_NAME and DUPLICATE_WINDOW_SECONDS were documented in prose and absent from the file too; both are there now.

Stale facts

• The upload endpoint still advertised .tcx or .gpx only.
• The test count said 311. It is 343.
• The repository tree omitted database.py, schemas/, services/archives.py and hooks/ — archives.py in particular, with archive import a headline feature.
• "CORS never comes into it either way" sat next to a wired CORSMiddleware. The middleware is for the case that sentence was not describing, so it now says which case each one covers.

Repetition

• The phone bullet in What you get and the caption under the phone screenshot said the same sentence twice, sixty lines apart.
• Why it works the way it does was a section whose entire content was a link to docs/DESIGN.md — immediately after a paragraph linking to docs/DESIGN.md. One signpost now, in the section that earns it.

Smaller

• docs/DESIGN.md listed its last two sections in the wrong order. A check now confirms the contents match the heading order exactly.
• demo/README.md had a paragraph with a broken wrap, and said nothing about why the demo set has no FIT file now that the app reads FIT.

Verified

Backend 343 tests, frontend 223, ruff check, ruff format --check and eslint clean. The README's mermaid diagram was re-rendered in a browser after its label changed, and the twelve referenced screenshots all resolve.

One correction to my own work in here: I first described hooks/ as "the data each panel needs, fetched once" from assumption. It holds one hook that reports whether the viewer is in dark mode, and that is what the tree says now.

---

Generated by Claude Code