reorg documentation

docs/getting-started.md

@@ -0,0 +1,88 @@
+# Getting started
+
+BincioActivity turns a folder of GPX/FIT/TCX files into a static website you host yourself. No database. No cloud dependency. No account.
+
+## Prerequisites
+
+- Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)
+- Node ≥ 20 and npm (for the site)
+- Your activity files (Strava export, Garmin export, Karoo, etc.)
+
+## Install
+
+```bash
+git clone https://github.com/brutsalvadi/bincio-activity.git
+cd bincio-activity
+uv sync
+```
+
+## Configure
+
+```bash
+cp extract_config.example.yaml extract_config.yaml
+$EDITOR extract_config.yaml
+```
+
+Minimum configuration:
+
+```yaml
+owner:
+  handle: yourname       # used in URLs and federation
+  display_name: Your Name
+
+input:
+  dirs:
+    - ~/your-activity-data/activities
+
+output:
+  dir: ~/bincio_data
+```
+
+The config file is gitignored — safe to store Strava credentials here.
+
+## Extract
+
+```bash
+uv run bincio extract
+```
+
+This reads all GPX/FIT/TCX files (including `.gz` variants), deduplicates them, and writes a BAS data store to `~/bincio_data/`.
+
+Re-running is safe — unchanged files are skipped (hash-based). To force a full re-extract: `rm -rf ~/bincio_data && uv run bincio extract`.
+
+## Build the site
+
+```bash
+cd site && npm install && cd ..
+cp site/.env.example site/.env
+# Edit site/.env: set BINCIO_DATA_DIR=~/bincio_data
+uv run bincio render
+```
+
+Output is in `site/dist/` — a folder of static files. Drop it anywhere: GitHub Pages, Netlify, a Raspberry Pi, a USB stick.
+
+## Dev mode
+
+```bash
+uv run bincio render --serve    # → http://localhost:4321
+```
+
+## Enable the edit UI
+
+The edit UI lets you rename activities, add descriptions, upload photos, and sync from Strava — all from the browser.
+
+```bash
+uv sync --extra edit
+uv run bincio edit              # starts on http://localhost:4041
+# Add to site/.env:
+# PUBLIC_EDIT_URL=http://localhost:4041
+```
+
+An Edit button and an Upload ↑ button appear in the nav.
+
+## Next steps
+
+- [Single-user deployment](deployment/single-user.md) — serve your site on a VPS or GitHub Pages
+- [Multi-user deployment](deployment/multi-user.md) — invite friends, shared feed
+- [CLI reference](reference/cli.md) — all commands and options
+- [BAS schema](../SCHEMA.md) — the data format and federation protocol