docs: refresh project documentation against current codebase

docs/GETTING-STARTED.md

@@ -48,15 +48,23 @@ cp .env.example .env
 Open `.env` and fill in the required values. See [docs/CONFIGURATION.md](CONFIGURATION.md) for the full variable reference. At minimum for local development you need:
 
 - `DB_PASSWORD` and `DB_ROOT_PASSWORD` — pick any local passwords
-- `APP_PASSWORD_ENCRYPTION_KEY` — 64 hex characters; generate with:
+- `APP_PASSWORD_ENCRYPTION_KEY`, `SESSION_SECRET`, `LOCAL_SESSION_SECRET`, and VAPID keys — generate all at once with:
+
+  ```bash
+  pnpm generate-secrets
+  ```
+
+  Paste the output into your `.env`. Alternatively, generate `APP_PASSWORD_ENCRYPTION_KEY` alone with:
 
   ```bash
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   ```
 
-- `DEV_AUTH_BYPASS=true` — bypasses the live Authelia OIDC flow for local dev
+- `DEV_AUTH_BYPASS=true` — bypasses the live Authelia OIDC flow for local dev. When this is set, `LOCAL_SESSION_SECRET` is not required at startup (bypass mode skips the local-auth JWT path entirely).
 - `DB_HOST=localhost` — the dev Docker Compose exposes MariaDB on the host at `localhost:3306`
 
+> **Note:** If you run without `DEV_AUTH_BYPASS=true` (local-auth mode), `LOCAL_SESSION_SECRET` must be set to a value of at least 32 characters. The API will refuse to start otherwise. `pnpm generate-secrets` always produces a valid value.
+
 ---
 
 ## First Run
@@ -124,6 +132,11 @@ Or set `DB_HOST=localhost` directly in your `.env` for host-side dev.
 **API starts but all requests return 401 / redirect to Authelia**
 `DEV_AUTH_BYPASS` is not set or is not being exported to the process. Make sure you source `.env` with `set -a; source .env; set +a` or prefix the command with `DEV_AUTH_BYPASS=true`. The bypass only works when `NODE_ENV` is not `production`.
 
+**`[FATAL] LOCAL_SESSION_SECRET is not set or is shorter than 32 characters`**
+The API refuses to start in non-bypass mode without a valid `LOCAL_SESSION_SECRET`. Either:
+- Set `DEV_AUTH_BYPASS=true` in `.env` for local dev (bypass mode exempts the requirement), or
+- Run `pnpm generate-secrets` and add the generated `LOCAL_SESSION_SECRET` value to `.env`.
+
 **PWA shows a blank screen after first load**
 Run the API build step first (`pnpm --filter @familysync/api build`). The dev script runs `dist/index.js`; if `dist/` is missing or stale, the API process exits immediately.
 
@@ -136,4 +149,5 @@ Another local MySQL/MariaDB service is running. Stop it before starting Docker C
 
 - [docs/ARCHITECTURE.md](ARCHITECTURE.md) — System design, component diagram, data flow
 - [docs/CONFIGURATION.md](CONFIGURATION.md) — All environment variables, defaults, and per-environment guidance
+- [docs/DEVELOPMENT.md](DEVELOPMENT.md) — Build commands, code style, and contribution workflow
 - [docs/deployment.md](deployment.md) — Production deployment on Unraid via Docker Compose