---
phase: quick-260610-czd
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [docs/deployment.md]
autonomous: true
requirements: [DOCS-FIX]
must_haves:
truths:
- 'docs/deployment.md tells a Phase 2+ developer the exact command to run the API + PWA host-side (no Docker)'
- 'The doc explains DB_HOST must be overridden to localhost because root .env sets DB_HOST=mariadb for the Docker network'
- 'The doc states the dev script does not auto-load .env'
artifacts:
- path: 'docs/deployment.md'
provides: 'Host-side (no-Docker) local-dev run instructions for Phase 2+'
contains: 'Running locally'
key_links: []
---
Fix docs/deployment.md so a Phase 2+ developer can run FamilySync host-side (no Docker).
The deployment runbook is Docker-only: it brings the app up via `docker compose up -d --build` and the
"## Dev-auth bypass (Phase 2+ local development)" section explains how to ACTIVATE the bypass but never gives
the command to actually run the API + PWA on the host. This adds a "Running locally (host-side, no Docker)"
subsection with the correct, tested command block.
Purpose: Eliminate the implicitly-wrong/missing local-dev run command. A naive `pnpm --filter @familysync/api dev`
fails because the dev script does not load .env and DB_HOST defaults to 'localhost' — but if env IS sourced from
root .env, DB_HOST=mariadb (the Docker service name) breaks host-side dev. The correct invocation sources .env
then overrides DB_HOST=localhost.
Output: Updated docs/deployment.md.
@$HOME/.claude/gsd-core/workflows/execute-plan.md
@$HOME/.claude/gsd-core/templates/summary.md
@docs/deployment.md
@apps/api/package.json
@apps/api/src/db/client.ts
Task 1: Add "Running locally (host-side, no Docker)" subsection to deployment.md
docs/deployment.md
Insert a new "### Running locally (host-side, no Docker)" subsection immediately after the
"## Dev-auth bypass (Phase 2+ local development)" section (after the existing content ending at the
"What the bypass does" paragraph, ~line 286). DOCS-ONLY — do NOT modify apps/api/package.json or any code.
The subsection MUST cover, in order:
(a) Prerequisite: dev MariaDB must be running with host port 3306 exposed via the dev compose override.
Reference the existing command (already documented in Step 3): `docker compose -f docker-compose.yml
-f docker-compose.dev.yml up -d mariadb`.
(b) 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 (no dotenv, no --env-file), and
db/client.ts defaults DB_HOST to 'localhost' when unset. So env must be sourced AND DB_HOST overridden
to localhost, because root .env sets DB_HOST=mariadb (the Docker service name) for the compose path.
(c) The exact command block. Terminal 1 (API) — build first, then run with env sourced and overrides applied:
pnpm --filter @familysync/api build
set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev
Terminal 2 (PWA):
pnpm --filter @familysync/pwa dev
Run `.env` from the repo root (the gitignored root .env). Transcribe the command block faithfully —
`set -a; source .env; set +a` exports every var from .env, and the trailing `DEV_AUTH_BYPASS=true
DB_HOST=localhost` overrides win for the host-side run.
(d) A short note explaining WHY `--env-file` is not baked into the dev script: auto-loading root .env would
load DB_HOST=mariadb and break host-side dev (that host is only reachable on the Docker network), which
is why env is sourced manually with DB_HOST overridden to localhost instead.
Use fenced ```bash blocks for the commands. Match the surrounding doc's tone and heading depth
(the parent section is `##`, so use `###` for this subsection).
grep -q "Running locally (host-side, no Docker)" docs/deployment.md && grep -q "DB_HOST=localhost pnpm --filter @familysync/api dev" docs/deployment.md && grep -q "pnpm --filter @familysync/pwa dev" docs/deployment.md && grep -q "set -a; source .env; set +a" docs/deployment.md
docs/deployment.md contains a "### Running locally (host-side, no Docker)" subsection after the dev-auth
bypass section that: names the dev-MariaDB prerequisite (host port 3306 via dev compose override); states
the dev script does not auto-load .env and DB_HOST defaults to localhost; gives the exact build → source-env
+ override → run-API command and the second-terminal PWA command; and explains why --env-file is not baked
into the dev script (would load DB_HOST=mariadb and break host-side dev). No code or package.json changes.
- `grep -q "Running locally (host-side, no Docker)" docs/deployment.md` passes.
- The exact API run command (`set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev`) is present.
- The PWA run command (`pnpm --filter @familysync/pwa dev`) is present.
- `git diff --name-only` shows only docs/deployment.md changed (no package.json, no source files).
A Phase 2+ developer reading docs/deployment.md can start the API + PWA host-side (no Docker) using only the
commands in the doc, understands the DB_HOST=localhost override and why it is needed, and the change touches
only docs/deployment.md.