docs/deployment.md

@@ -283,3 +283,60 @@ Sets `c.set('user', DEV_USER)` in the Hono context before `oidcAuthMiddleware` r
 read `c.get('user')` receive a fixed dev user `{ id: 1, displayName: 'Dev User', color: '#4A90D9' }`.
 Routes that call `getAuth(c)` from `@hono/oidc-auth` will still return null (no OIDC cookie is
 present) — those routes must be updated to prefer `c.get('user')` when building Phase 2+.
+
+### Running locally (host-side, no Docker)
+
+Use this when you want to run the API and PWA directly on the host (no `docker compose up` for the
+app containers), e.g. during Phase 2+ feature development with the dev-auth bypass active.
+
+**Prerequisite: dev MariaDB must be running with the host port exposed.**
+
+Use the dev compose override from Step 3 — it binds MariaDB to `localhost:3306`:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mariadb
+```
+
+**Why a plain `pnpm --filter @familysync/api dev` is not enough:**
+
+The API `dev` script is `node --watch dist/index.js`. It does **not** auto-load `.env` — there is
+no `dotenv` call and no `--env-file` flag in the script. Without any env vars, `db/client.ts`
+defaults `DB_HOST` to `'localhost'`, which works for a host-side run. However, once you source the
+root `.env` to pick up OIDC secrets and other variables, the problem surfaces: root `.env` sets
+`DB_HOST=mariadb` (the Docker service name, only resolvable inside the Docker network). On the
+host, `mariadb` does not resolve, so the DB connection fails.
+
+The fix is to source `.env` for all the other variables and then immediately override `DB_HOST` back
+to `localhost`.
+
+**Run the API and PWA:**
+
+Open two terminals from the repo root.
+
+Terminal 1 — API:
+
+```bash
+# Build first (the dev script runs the compiled output, not ts-node)
+pnpm --filter @familysync/api build
+
+# Source root .env, then override DB_HOST and activate the bypass
+set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev
+```
+
+Terminal 2 — PWA:
+
+```bash
+pnpm --filter @familysync/pwa dev
+```
+
+The `set -a; source .env; set +a` idiom exports every variable from the root `.env` into the shell
+environment. The `DEV_AUTH_BYPASS=true DB_HOST=localhost` prefix on the same command line then
+overrides those two specific vars for the `pnpm` child process — `DB_HOST=localhost` wins over the
+`DB_HOST=mariadb` that was exported from `.env`.
+
+**Why `--env-file` is not baked into the dev script:**
+
+If `--env-file .env` were added to the API `dev` script, it would load `DB_HOST=mariadb`
+automatically on every `pnpm dev` invocation. That value only works inside the Docker network; on
+the host it resolves to nothing and the DB connection fails. Keeping `.env` loading out of the
+script is intentional — the developer sources it manually and overrides `DB_HOST` as shown above.