docs: expand development workflow (CI parity + loops + commands)

docs/03-development.md

@@ -3,25 +3,181 @@
 ## Deep dives
 
 - [Testing guide](testing/README.md)
+- [Troubleshooting deep dive](troubleshooting/README.md)
 
-This is the contributor-focused dev workflow for the Mission Control repo.
+This page describes the **canonical contributor workflow** for Mission Control, including local dev loops and CI parity.
 
-## Prereqs
+> Evidence basis: consolidated from repo root `README.md`, `.github/workflows/ci.yml`, `Makefile`, `scripts/with_node.sh`, and `docs/testing/README.md`.
-- Docker + Docker Compose
-- Node (for the frontend)
-- Python (for the backend)
 
-## Common commands
+## Prerequisites
-- See `Makefile` for the canonical targets.
-- Self-host stack (dev-ish): follow the [Quickstart](02-quickstart.md).
 
-## Local services
+- Docker + Docker Compose v2 (`docker compose`)
-- Postgres is provided by Compose (`compose.yml`).
+- Python **3.12+** + `uv`
+- Node.js + npm
+  - CI pins **Node 20** via GitHub Actions (`actions/setup-node@v4` with `node-version: "20"`).
 
-## Debugging tips
+## Repo structure (where to run commands)
-- Backend liveness: `GET /healthz`
-- Backend routes live under `/api/v1/*` (see `backend/app/main.py`).
 
-## Next (to flesh out)
+- Repo root: `Makefile` contains canonical targets.
-- Document the exact backend/frontend dev commands used by maintainers (once finalized).
+- Backend code: `backend/` (FastAPI)
-- Add a “how to run tests” pointer to `docs/testing/README.md`.
+- Frontend code: `frontend/` (Next.js)
+
+## “One command” setup
+
+From repo root:
+
+```bash
+make setup
+```
+
+What it does:
+- Syncs backend deps with `uv`.
+- Syncs frontend deps with `npm` via the node wrapper.
+
+## Canonical checks (CI parity)
+
+### Run everything locally (closest to CI)
+
+From repo root:
+
+```bash
+make check
+```
+
+CI runs two jobs:
+- `check` (lint/typecheck/tests/coverage/build)
+- `e2e` (Cypress)
+
+## Backend workflow
+
+### Install/sync deps
+
+```bash
+cd backend
+uv sync --extra dev
+```
+
+### Run the API (dev)
+
+```bash
+cd backend
+cp .env.example .env
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Backend checks
+
+From repo root:
+
+```bash
+make backend-lint       # flake8
+make backend-typecheck  # mypy --strict
+make backend-test       # pytest
+make backend-coverage   # pytest + scoped coverage gate
+```
+
+### DB migrations
+
+From repo root:
+
+```bash
+make backend-migrate
+```
+
+## Frontend workflow
+
+### Install deps
+
+```bash
+cd frontend
+npm install
+```
+
+(or from repo root: `make frontend-sync`)
+
+### Run the UI (dev)
+
+```bash
+cd frontend
+cp .env.example .env.local
+# Ensure NEXT_PUBLIC_API_URL is correct for the browser:
+# NEXT_PUBLIC_API_URL=http://localhost:8000
+npm run dev
+```
+
+### Frontend checks
+
+From repo root:
+
+```bash
+make frontend-lint       # eslint
+make frontend-typecheck  # tsc
+make frontend-test       # vitest
+make frontend-build      # next build
+```
+
+## Local dev loops
+
+### Loop A (recommended): DB via Compose, backend + frontend in dev mode
+
+1) Start Postgres only:
+
+```bash
+cp .env.example .env
+docker compose -f compose.yml --env-file .env up -d db
+```
+
+2) Backend (local):
+
+```bash
+cd backend
+cp .env.example .env
+uv sync --extra dev
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+3) Frontend (local):
+
+```bash
+cd frontend
+cp .env.example .env.local
+npm install
+npm run dev
+```
+
+### Loop B: all-in-one Docker Compose
+
+```bash
+cp .env.example .env
+
+docker compose -f compose.yml --env-file .env up -d --build
+```
+
+Useful ops:
+
+```bash
+docker compose -f compose.yml --env-file .env logs -f --tail=200
+docker compose -f compose.yml --env-file .env up -d --build backend
+# destructive reset (drops Postgres volume):
+docker compose -f compose.yml --env-file .env down -v
+```
+
+## Cypress E2E workflow (high level)
+
+See the deep dive: [docs/testing/README.md](testing/README.md).
+
+Notes:
+- E2E uses Clerk (official `@clerk/testing` integration); CI injects Clerk env vars.
+
+## Tooling notes
+
+### Node wrapper (`scripts/with_node.sh`)
+
+Many Make targets run frontend commands via `bash scripts/with_node.sh`.
+It checks `node`/`npm`/`npx` and can use `nvm` if present.
+
+## Quick troubleshooting
+
+- UI loads but API calls fail / activity feed blank:
+  - confirm `NEXT_PUBLIC_API_URL` is set and browser-reachable.
+  - see [Troubleshooting](troubleshooting/README.md).