unify single user and multi user behaviour

docs/getting-started.md

@@ -23,11 +23,11 @@ cp extract_config.example.yaml extract_config.yaml
 $EDITOR extract_config.yaml
 ```
 
-Minimum configuration:
+Set your handle and input directory at minimum:
 
 ```yaml
 owner:
-  handle: yourname       # used in URLs and federation
+  handle: yourname          # used in URLs: /u/yourname/
   display_name: Your Name
 
 input:
@@ -35,54 +35,86 @@ input:
     - ~/your-activity-data/activities
 
 output:
-  dir: ~/bincio_data
+  dir: ~/bincio_data        # instance root; activities go into ~/bincio_data/yourname/
 ```
 
 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/`.
+Reads all GPX/FIT/TCX files and writes a BAS data store to `~/bincio_data/yourname/`. Re-running is safe — unchanged files are skipped (hash-based).
 
-Re-running is safe — unchanged files are skipped (hash-based). To force a full re-extract: `rm -rf ~/bincio_data && uv run bincio extract`.
+> `--output` overrides `output.dir` from the config and is the **instance root**,
+> not the user directory. The handle is always appended automatically:
+> `bincio extract --output ~/bincio_data` → writes to `~/bincio_data/yourname/`.
 
-## Build the site
+---
+
+## Single-user — no login, static site
 
 ```bash
+# Build and preview
 cd site && npm install && cd ..
-cp site/.env.example site/.env
-# Edit site/.env: set BINCIO_DATA_DIR=~/bincio_data
-uv run bincio render
+uv run bincio dev --data-dir ~/bincio_data
+# → http://localhost:4321
 ```
 
-Output is in `site/dist/` — a folder of static files. Drop it anywhere: GitHub Pages, Netlify, a Raspberry Pi, a USB stick.
+`bincio dev` merges edits, builds the shard manifest, and starts `astro dev`. No login required — the site opens directly at `/u/yourname/`.
 
-## Dev mode
+To build for deployment (no live server):
 
 ```bash
-uv run bincio render --serve    # → http://localhost:4321
+uv run bincio render --data-dir ~/bincio_data
+# output: site/dist/
 ```
 
-## Enable the edit UI
+See [Single-user deployment](deployment/single-user.md).
 
-The edit UI lets you rename activities, add descriptions, upload photos, and sync from Strava — all from the browser.
+---
+
+## Multi-user — shared instance, login required
+
+```bash
+uv sync --extra serve
+
+# One-time: create the instance database and admin account
+uv run bincio init --data-dir ~/bincio_data --handle yourname
+
+# Start everything
+uv run bincio dev --data-dir ~/bincio_data
+# → http://localhost:4321  (login with the password set during init)
+```
+
+`bincio dev` detects the `instance.db` and automatically starts `bincio serve` alongside `astro dev`. Ctrl+C stops both.
+
+See [Multi-user deployment](deployment/multi-user.md).
+
+---
+
+## Enable the edit UI (single-user)
+
+The edit UI lets you rename activities, add descriptions, upload photos, and sync from Strava — from the browser.
 
 ```bash
 uv sync --extra edit
-uv run bincio edit              # starts on http://localhost:4041
+uv run bincio edit --data-dir ~/bincio_data
 # Add to site/.env:
 # PUBLIC_EDIT_URL=http://localhost:4041
 ```
 
-An Edit button and an Upload ↑ button appear in the nav.
+In multi-user mode the edit UI is always available via `bincio serve` — no extra step needed.
+
+---
 
 ## 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
+- [Single-user deployment](deployment/single-user.md) — GitHub Pages, Netlify, VPS
+- [Multi-user deployment](deployment/multi-user.md) — VPS with nginx, inviting users
 - [CLI reference](reference/cli.md) — all commands and options
 - [BAS schema](../SCHEMA.md) — the data format and federation protocol