From 40fa559b02c39c187adde85572995fdd708552ff Mon Sep 17 00:00:00 2001
From: Abhimanyu Saharan <desk.abhimanyu@gmail.com>
Date: Fri, 13 Feb 2026 11:34:41 +0000
Subject: [PATCH] docs: fill in development + testing guides

---
 docs/03-development.md | 57 +++++++++++++++++++++++++++++++++++++++++-
 docs/testing/README.md | 56 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 111 insertions(+), 2 deletions(-)

diff --git a/docs/03-development.md b/docs/03-development.md
index 4949c0c3..35f99072 100644
--- a/docs/03-development.md
+++ b/docs/03-development.md
@@ -1,3 +1,58 @@
 # Development workflow
 
-Placeholder: see root `README.md` for current setup steps.
+This page describes a contributor-friendly local dev loop.
+
+## Prereqs
+
+- Python 3.12+
+- Node 22+
+- Docker + Docker Compose v2 (`docker compose`)
+- `uv` (installed automatically by `make backend-sync` in CI; for local install see https://docs.astral.sh/uv/)
+
+## Fast local loop (DB in Docker, apps on host)
+
+1) Start Postgres (via compose)
+
+```bash
+cp .env.example .env
+# Configure .env as needed (see root README for auth-mode notes)
+
+docker compose -f compose.yml --env-file .env up -d db
+```
+
+2) Install deps
+
+```bash
+make setup
+```
+
+3) Apply DB migrations
+
+```bash
+make backend-migrate
+```
+
+4) Run backend (dev)
+
+```bash
+cd backend
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+5) Run frontend (dev)
+
+In another terminal:
+
+```bash
+cd frontend
+npm run dev -- --hostname 0.0.0.0 --port 3000
+```
+
+Open:
+- Frontend: http://localhost:3000
+- Backend health: http://localhost:8000/healthz
+
+## Notes
+
+- If you want the fully-containerized stack instead, see the root README’s compose instructions.
+- If you add new env vars, prefer documenting them in `.env.example` and linking from docs rather than pasting secrets.
diff --git a/docs/testing/README.md b/docs/testing/README.md
index 80dcee45..9090a432 100644
--- a/docs/testing/README.md
+++ b/docs/testing/README.md
@@ -1,3 +1,57 @@
 # Testing guide
 
-Placeholder: see root `README.md` and `CONTRIBUTING.md` for current commands.
+This repo’s CI parity entrypoint is:
+
+```bash
+make check
+```
+
+That target runs lint + typecheck + unit tests + coverage gate + frontend build.
+
+## Quick commands
+
+From repo root:
+
+```bash
+make setup
+
+# Format + lint + typecheck + tests + build (CI parity)
+make check
+```
+
+Docs-only quality gates:
+
+```bash
+make docs-check
+```
+
+## Backend
+
+```bash
+make backend-lint
+make backend-typecheck
+make backend-test
+make backend-coverage
+```
+
+## Frontend
+
+```bash
+make frontend-lint
+make frontend-typecheck
+make frontend-test
+make frontend-build
+```
+
+## E2E (Cypress)
+
+CI runs Cypress E2E in `.github/workflows/ci.yml`.
+
+Locally, the frontend package.json provides the E2E script:
+
+```bash
+cd frontend
+npm run e2e
+```
+
+If your E2E tests require auth, ensure you have the necessary env configured (see root README for auth mode). Do **not** paste tokens into docs.