---
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: []
---

<objective>
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.
</objective>

<execution_context>
@$HOME/.claude/gsd-core/workflows/execute-plan.md
@$HOME/.claude/gsd-core/templates/summary.md
</execution_context>

<context>
@docs/deployment.md
@apps/api/package.json
@apps/api/src/db/client.ts
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add "Running locally (host-side, no Docker)" subsection to deployment.md</name>
  <files>docs/deployment.md</files>
  <action>
    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).

  </action>
  <verify>
    <automated>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</automated>
  </verify>
  <done>
    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.
  </done>
</task>

</tasks>

<verification>
- `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).
</verification>

<success_criteria>
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.
</success_criteria>

<output>
Create `.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md` when done
</output>
