docs: Reformat README to project conventions

1 files changed, 68 insertions, 46 deletions

diff --git a/README.md b/README.md
index 0b2aa83..97c022e 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,76 @@
-# Bike software
+# biking_home — cycling ride analysis
+
+A Go toolkit for analyzing cycling rides from GPX exports: parse rides, detect climbs, score their difficulty, match the same climb across rides, and download French mountain passes into SQLite.
 
 ## Features
 
-- [ ] Detect similar climbs + PRs
-- Compute a ride difficulty score (Cotacol method): split into 100m segments, each scores 0.1km × slope²
-- On this climb (examples/activity_18679866717.gpx), the climb algo should detect several possible climbs and let you choose
-- Once you have chosen, new activities should have remembered the choice (looking into the index should be enough)
-- Handling my historical data
-- Blog with pictures and markdown
-- Storing GPX
-- Export mountain pass from OSM and auto detect when pass is crossed
-  - https://www.jmspae.se/write-ups/kebabs-train-stations/
-- Download French mountain passes from centcols.org into a SQLite database (`go run . -download`, resume with `-resume`)
-- Auto detect climbs from GPX
-- Compute estimated power
-- Export data from Strava, Garmin
-  - Garmin GPX exports has elevation, time, temp, heart rate, cadence
-  - Garmin TCX export has stats (cal, heart rate, time, cadence), time, pos, alt, distance, hr, cadence, speed
-  - Garmin Fit export has (time, sport, lap/split, gps, sensor, events)?
-  - KML ?
-- Strava seems the simpler to use
-- in a single chart, plot (speed, slope) for all segments. color with heartbeat
-
-## Implementation
-
-- Golang for showcase
-- Keep improving personal lib (+ documentation)
-- Get back what is interesting in previous projects
-  - Go bike:
-    - Only tooling for golang, project is different
-  - Django bike
-- https://github.com/paulmach/osm
-- https://github.com/tkrajina/gpxgo
-- https://github.com/tormoder/fit
-- https://github.com/brendangregg/FlameGraph
-- `go tool pprof -http=":8081"`
-- https://developer.garmin.com/gc-developer-program/activity-api/
-- https://github.com/matin/garth
-- https://developers.strava.com/docs/webhooks/
-- https://developers.strava.com/docs/getting-started/
-- https://connect.garmin.com/modern/activities to CSV
-- https://github.com/SamR1/FitTrackee
-- https://github.com/jovandeginste/workout-tracker
+- **GPX parsing** — reads elevation-tracked rides from Garmin/Strava GPX exports into a `Ride` model
+- **Climb detection** — automatically finds climbs within a ride, each scored and categorized (Cat 4 … HC)
+- **Difficulty score (Cotacol)** — scores any ride or climb by splitting it into 100 m segments and summing `0.1 km × slope²` per segment
+- **Similar-climb matching** — finds the same climb across rides by matching start/end coordinates, so times can be compared
+- **Mountain pass download** — imports French mountain passes from centcols.org into a SQLite database
+- **Plots** — renders elevation and score-profile charts as PNG
+
+## Getting started
+
+```bash
+go build -o biking_home .
+```
+
+## Usage
+
+```bash
+# Download French mountain passes into biking_home.db (SQLite)
+./biking_home -download
+
+# Resume an interrupted download, reusing departments already cached on disk
+./biking_home -download -resume
+
+# Run the climb-similarity and difficulty-score demo on the example rides
+./biking_home -demo
+
+# Profile the demo with Go's CPU profiler
+./biking_home -demo -cpuprofile /tmp/cpu.prof
+```
+
+## Options / Configuration
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `-download` | Download mountain passes into the database | `false` |
+| `-resume` | Skip departments already cached on disk | `false` |
+| `-demo` | Run the climb-similarity demo | `false` |
+| `-cpuprofile` | Write a CPU profile to file | `""` |
+
+## Architecture
+
+- Go 1.23; SQLite via `mattn/go-sqlite3`; charts via `gonum.org/v1/plot`
+- `ride` — GPX parsing, climb detection, difficulty scores (KOM + Cotacol), similarity index
+- `mountain_pass` — centcols.org department CSV download into SQLite, with disk caching and retries
+- **Notable choices** — the difficulty score follows the Cotacol method: the ride is split into fixed 100 m segments and each scores `distance_km × slope²`, so steep sections weigh exponentially more than long flat ones
+
+## Development
+
+```bash
+go vet ./...
+go test ./...
+```
 
 ## TODO
 
-- CI / Tooling
-- Tests
-- linter for calls to `make([]..., n)` that then use append
+- Compute estimated power
+- Export data from Strava / Garmin (GPX, TCX, FIT)
+- Auto-detect when a mountain pass is crossed
+- Plot speed and slope per segment, colored by heart rate
+- Persist the chosen climb variant across activities
+- Handle historical data
+- Blog with pictures and markdown
+- Store GPX files
 
-## Examples
+## Resources
 
-**[Pogacar 21 july 2022](https://www.strava.com/activities/7505784085)**
+- [Climbfinder: difficulty points](https://climbfinder.com/en/difficulty-points) — the Cotacol formula behind the difficulty score
+- [centcols.org](https://www.centcols.org) — French mountain pass reference used for the SQLite data
+- [Pogacar 21 July 2022](https://www.strava.com/activities/7505784085) — example ride used for climb detection
+- [gpxgo](https://github.com/tkrajina/gpxgo) — GPX parsing library
+- [geodist](https://github.com/jftuga/geodist) — haversine distance used for climb matching