docs: update changelog, CLI reference, user guide, and elevation notes

- CHANGELOG: document hysteresis elevation fix and DEM recalculation feature
- docs/reference/cli.md: add --dem-url to bincio edit and bincio serve tables
- docs/user-guide.md: document "Recalculate from terrain map" button in edit drawer
- docs/elevation.md: mark both short-term and medium-term fixes as implemented

CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [Unreleased] — 2026-04-20
+
+### Improvement — Elevation gain accuracy (hysteresis accumulation)
+
+The previous algorithm accumulated every positive elevation delta between
+consecutive track points, counting GPS jitter and barometric quantization
+noise as real climbing. This consistently overestimated gain — in extreme
+cases by 100% on flat coastal routes.
+
+The new algorithm uses **hysteresis dead-band accumulation**: elevation is
+only committed when it changes by more than a source-specific threshold from
+the last committed value. GPS noise is suppressed without losing real climbs.
+
+- **`bincio/extract/models.py`** — `ParsedActivity` gains an `altitude_source`
+  field (`"barometric"` / `"gps"` / `"unknown"`)
+- **`bincio/extract/parsers/fit.py`** — detects whether any record frame used
+  `enhanced_altitude` (barometric altimeter) vs `altitude` (GPS-derived) and
+  sets `altitude_source` accordingly
+- **`bincio/extract/parsers/gpx.py`**, **`tcx.py`** — both set
+  `altitude_source = "gps"`
+- **`bincio/extract/metrics.py`** — `_elevation()` replaced with hysteresis
+  accumulator; thresholds: **5 m** for barometric, **10 m** for GPS/unknown
+- **`tests/test_metrics.py`** — 5 new parametric tests: flat GPS noise
+  suppression, barometric vs GPS threshold difference, real climb approximation,
+  unknown-treated-as-gps invariant
+
+### New feature — DEM-based elevation recalculation from the edit drawer
+
+A new **"Recalculate from terrain map (DEM)"** button in the activity edit
+drawer replaces noisy GPS altitude with SRTM terrain data, then re-applies
+hysteresis accumulation to compute corrected gain/loss.
+
+This is the recommended fix for activities that still show inaccurate
+elevation after the hysteresis improvement (e.g. activities recorded before
+re-extracting from sources, or uploads where the source file had severe GPS
+altitude noise).
+
+How it works:
+1. The server subsamples the activity's 1 Hz GPS track (one point every 10 s)
+2. Queries an Open-Elevation-compatible API for terrain elevation
+3. Linearly interpolates DEM elevation back to every GPS-valid second
+4. Applies 5 m hysteresis to compute the corrected gain and loss
+5. Writes the updated `elevation_m` array to the timeseries (chart updates)
+6. Patches `elevation_gain_m` / `elevation_loss_m` in the activity JSON and
+   `index.json` summary
+
+- **`bincio/extract/dem.py`** (new) — `lookup_elevations()` (batched HTTP POST,
+  Open-Elevation wire format) + `recalculate_elevation()` (full pipeline above)
+- **`POST /api/activity/{id}/recalculate-elevation`** — on both `bincio serve`
+  (auth-gated, triggers `merge_one` + rebuild) and `bincio edit` (no auth)
+- **`bincio serve --dem-url URL`** / **`bincio edit --dem-url URL`** — override
+  the default DEM endpoint (also read from `DEM_URL` env var)
+- Default DEM endpoint: **`https://api.open-elevation.com`** — works out of the
+  box with no configuration
+- **`GET /api/me`** response gains `dem_configured: bool`
+- **`EditDrawer.svelte`** — button with spinner, shows `↑ Xm ↓ Ym` on success
+  or an inline error (e.g. if the DEM API is unreachable)
+
+---
+
 ## [Unreleased] — 2026-04-16
 
 ### New feature — Self-service user settings page