unify single user and multi user behaviour

docs/deployment/single-user.md

@@ -1,32 +1,65 @@
 # Single-user deployment
 
-One person, one machine, all your data stays with you. This is the default and simplest mode.
+One person, one machine, all your data stays with you. No login, no server process.
+
+## Data layout
+
+All data lives under your instance root in a per-user subdirectory:
+
+```
+~/bincio_data/              ← instance root (output.dir in config)
+  index.json                ← shard manifest (generated by bincio render/dev)
+  yourname/
+    index.json              ← your BAS feed
+    _merged/                ← sidecar-merged output (served to browser)
+    activities/
+    edits/
+    athlete.json
+```
+
+`bincio extract` writes into `yourname/` automatically — pass the instance root to `--output`, not the user directory.
+
+## Local development
+
+```bash
+uv run bincio dev --data-dir ~/bincio_data
+# → http://localhost:4321/u/yourname/
+```
+
+`bincio dev` without an `instance.db` runs in single-user mode: no login, no API server, just `astro dev`.
 
 ## GitHub Pages (free, automated)
 
 ```bash
-uv run bincio render --deploy github
+uv run bincio render --data-dir ~/bincio_data --deploy github
 ```
 
-This builds `site/dist/` and pushes it to the `gh-pages` branch. Requires `npx gh-pages` (`npm install -g gh-pages`).
+Builds `site/dist/` and pushes it to the `gh-pages` branch. Requires `npx gh-pages` (`npm install -g gh-pages`).
 
 Set the repository to serve from the `gh-pages` branch in GitHub → Settings → Pages.
 
 ## Static hosting (Netlify, Vercel, Cloudflare Pages, etc.)
 
-Build locally and deploy the `site/dist/` directory. Or set up CI:
+Build locally and deploy `site/dist/`:
+
+```bash
+uv run bincio render --data-dir ~/bincio_data
+# upload site/dist/ to your host
+```
+
+Or set up CI:
 
 ```yaml
 # .github/workflows/deploy.yml (example)
-- run: uv run bincio render
+- run: uv run bincio render --data-dir ~/bincio_data
 - uses: actions/upload-pages-artifact@v3
   with:
     path: site/dist
 ```
 
-## VPS with nginx
+## VPS with nginx (read-only)
 
-Serve `site/dist/` as a static directory. No server process needed for read-only access.
+Serve `site/dist/` as a static directory:
 
 ```nginx
 server {
@@ -40,7 +73,7 @@ server {
 
 ### Enable the edit UI on a VPS
 
-If you want to edit activities from the browser while on your VPS:
+To edit activities from the browser on your VPS, run `bincio edit` and proxy `/api/*` to it:
 
 ```nginx
 server {
@@ -53,7 +86,6 @@ server {
         try_files $uri $uri/ $uri.html =404;
     }
 
-    # Proxy /api/* to bincio edit (local-only, never exposed directly)
     location /api/ {
         proxy_pass http://127.0.0.1:4041;
         proxy_set_header Host $host;
@@ -61,21 +93,20 @@ server {
 }
 ```
 
-Then run `bincio edit` as a background service:
-
 ```bash
+uv sync --extra edit
 uv run bincio edit --data-dir ~/bincio_data
 ```
 
-And set `PUBLIC_EDIT_URL=` (empty — the proxy makes /api/ same-origin) in your environment before building.
+Set `PUBLIC_EDIT_URL=` (empty — the proxy makes `/api/` same-origin) in your environment before building.
 
 ## Keeping the site up to date
 
 After extracting new activities or editing sidecars:
 
 ```bash
-uv run bincio extract           # process new files
-uv run bincio render            # rebuild site/dist/
+uv run bincio extract --data-dir ~/bincio_data   # process new files
+uv run bincio render --data-dir ~/bincio_data    # rebuild site/dist/
 rsync -av site/dist/ user@server:/var/www/bincio/dist/
 ```