improve configs, update docs

CHEATSHEET.md

@@ -3,13 +3,16 @@
 ## Daily workflow
 
 ```bash
-# 1. Drop new .fit / .gpx / .tcx files into your input dir, then:
-uv run bincio extract
+# Option A — local files (Karoo / Garmin / Wahoo)
+uv run bincio extract          # processes new/changed files, skips unchanged
 
-# 2. Rebuild the site (merges any sidecar edits, then builds)
+# Option B — pull from Strava (incremental; credentials in extract_config.yaml)
+uv run bincio import strava    # fetches only activities since last sync
+
+# Rebuild the site (merges any sidecar edits, then builds)
 uv run bincio render
 
-# 3. Done — copy site/dist/ to your host
+# Done — copy site/dist/ to your host
 ```
 
 ---
@@ -29,6 +32,47 @@ To force a full re-extract: `rm -rf ~/bincio_data && uv run bincio extract`
 
 ---
 
+## Import from Strava
+
+```bash
+# Install (one-time)
+uv sync --extra strava
+
+# Add credentials to extract_config.yaml (gitignored — safe for secrets):
+#   import:
+#     strava:
+#       client_id: 12345
+#       client_secret: your_secret
+
+# First run — opens browser for OAuth, then imports all activities:
+uv run bincio import strava
+
+# Subsequent runs are incremental (only fetches since last sync):
+uv run bincio import strava
+
+# Other options:
+uv run bincio import strava --since 2025-01-01   # explicit date cutoff
+uv run bincio import strava --reauth             # force new OAuth flow
+uv run bincio import strava --output ~/other_dir # override output dir
+```
+
+Credentials resolution order:
+1. `--client-id` / `--client-secret` flags
+2. `STRAVA_CLIENT_ID` / `STRAVA_CLIENT_SECRET` env vars
+3. `import.strava.client_id` / `client_secret` in `extract_config.yaml`
+
+Tokens saved to `~/.config/bincio/strava.json` and auto-refreshed (6h TTL).
+Sync state (imported IDs + last sync timestamp) in `data_dir/_strava_sync.json`.
+
+---
+
+## File upload (web UI)
+
+When `PUBLIC_EDIT_URL` is set in `site/.env`, a `↑` button appears in the nav.
+Drag a FIT/GPX/TCX onto the modal → the activity is extracted and appears immediately.
+
+---
+
 ## Render
 
 ```bash
@@ -111,6 +155,8 @@ IDs are stable — safe to use in bookmarks and links.
 
 ## extract_config.yaml — key fields
 
+This file is **gitignored** — copy from `extract_config.example.yaml` and add your credentials safely.
+
 ```yaml
 owner:
   handle: yourname
@@ -130,6 +176,11 @@ track:
   rdp_epsilon: 0.0001       # GPS simplification — larger = fewer points
   timeseries_hz: 1          # samples/sec in stored JSON (1 = 1 Hz)
 
+import:
+  strava:
+    client_id: 12345        # from strava.com/settings/api
+    client_secret: abc      # Authorization Callback Domain must be: localhost
+
 athlete:
   max_hr: 182               # used for context; zones below are authoritative
   ftp_w: 280                # functional threshold power in watts
@@ -249,12 +300,13 @@ print(len(others), 'total')
 
 | File | Purpose |
 |---|---|
-| `extract_config.yaml` | Main config (input dirs, output dir, privacy) |
-| `site/.env` | Site env vars (`BINCIO_DATA_DIR`, `PUBLIC_EDIT_URL`) — copy from `.env.example` |
+| `extract_config.yaml` | Main config — input dirs, output dir, athlete zones, Strava credentials. **Gitignored.** Copy from `.example`. |
+| `site/.env` | Site env vars (`BINCIO_DATA_DIR`, `PUBLIC_EDIT_URL`) — copy from `site/.env.example`. Gitignored. |
 | `SCHEMA.md` | BAS format specification |
 | `CLAUDE.md` | Dev notes, gotchas, design decisions |
 | `bincio/render/merge.py` | Sidecar overlay logic — `parse_sidecar`, `merge_all` |
-| `bincio/edit/server.py` | FastAPI edit API — GET/POST activity, image upload |
+| `bincio/edit/server.py` | FastAPI edit API — GET/POST activity, image upload, file upload (`POST /api/upload`) |
+| `bincio/import_/strava.py` | Strava OAuth2 client + stream → BAS conversion |
 | `bincio/extract/sport.py` | Sport name normalisation + mapping |
 | `bincio/extract/metrics.py` | Distance, speed, HR, elevation computation |
 | `bincio/extract/parsers/fit.py` | FIT file parser |