reorg documentation

README.md

@@ -203,7 +203,32 @@ Privacy is enforced at extract time. A `private` activity never enters `index.js
 
 `index.json` is everything the feed page needs — no extra fetches until you open an activity. `{id}.json` contains the full timeseries (elevation, speed, HR, cadence, power at 1 Hz) for charts and the detail map. Both are human-readable and editable with any text editor.
 
-See `SCHEMA.md` for the full specification.
+See [SCHEMA.md](SCHEMA.md) for the full specification.
+
+---
+
+## Multi-user mode (VPS)
+
+Invite friends and run a shared instance where everyone's activities appear in a combined feed.
+
+```bash
+# One-time setup on the VPS
+uv sync --extra serve
+uv run bincio init --data-dir /var/bincio --handle dave --password 'pw' --name "Our Rides"
+
+# Extract your activities into your user shard
+uv run bincio extract --input ~/gpx-files --output /var/bincio/dave
+
+# Build the site
+uv run bincio render --data-dir /var/bincio --site-dir site
+
+# Start the API server (nginx proxies /api/* to this)
+uv run bincio serve --data-dir /var/bincio --site-dir site
+```
+
+Invite users: `bincio init` prints a first invite code. Share `https://example.com/register/?code=XXXXXXXX`. Invited users register themselves and upload their own activities via the browser.
+
+See [Multi-user deployment](docs/deployment/multi-user.md) for the full nginx configuration.
 
 ---
 
@@ -231,6 +256,7 @@ At build time the renderer fetches their public data and renders it under `/frie
 | Extract | Python 3.12, click, fitdecode, gpxpy, lxml |
 | Strava import | requests (optional extra: `uv sync --extra strava`) |
 | Edit server | FastAPI + uvicorn (optional extra: `uv sync --extra edit`) |
+| Serve (VPS) | FastAPI + uvicorn + bcrypt + SQLite (optional extra: `uv sync --extra serve`) |
 | Site framework | Astro 4 (static output) |
 | UI components | Svelte 5 |
 | Styling | Tailwind CSS v3 |