feat(FN-002): complete Step 4 — Documentation Structure and Environment Examples

docs/development.md

@@ -0,0 +1,139 @@
+# Development Guide
+
+## Prerequisites
+
+- **Node.js** ≥ 20 and **pnpm** ≥ 9
+- **Python** ≥ 3.11 with `venv` support
+- **Docker** and **Docker Compose** (for local services)
+
+## Installation
+
+```bash
+# Install Node dependencies and Python virtualenv + packages
+make install
+
+# Or manually:
+pnpm install
+cd apps/api && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+```
+
+## Environment Setup
+
+Copy the root environment example and fill in local values:
+
+```bash
+cp .env.example .env
+```
+
+Copy the frontend environment example:
+
+```bash
+cp apps/web/.env.example apps/web/.env
+```
+
+## Running Locally
+
+### Frontend only
+
+```bash
+cd apps/web
+pnpm dev        # Vite dev server on http://localhost:5173
+```
+
+### Backend only
+
+```bash
+cd apps/api
+.venv/bin/uvicorn app.main:app --reload --port 8000
+```
+
+### Both (via root script)
+
+```bash
+pnpm dev        # Runs frontend and backend in parallel
+```
+
+### With Docker Compose
+
+```bash
+docker compose up --build -d
+```
+
+## Testing
+
+### Frontend
+
+```bash
+pnpm --filter @headquarter/web test
+```
+
+Uses **Vitest** + **Testing Library** + **jsdom**.
+
+### Backend
+
+```bash
+pnpm --filter @headquarter/api test
+```
+
+Or directly with pytest:
+
+```bash
+cd apps/api && .venv/bin/pytest
+```
+
+### All tests
+
+```bash
+make test
+# or
+pnpm test
+```
+
+## Linting and Type Checking
+
+### Frontend
+
+```bash
+pnpm --filter @headquarter/web lint
+pnpm --filter @headquarter/web typecheck
+```
+
+### Backend
+
+```bash
+pnpm --filter @headquarter/api lint
+pnpm --filter @headquarter/api typecheck
+```
+
+### All
+
+```bash
+make lint
+make typecheck
+```
+
+## Building
+
+```bash
+make build
+# or
+pnpm build
+```
+
+## Project Layout
+
+```text
+├── apps/
+│   ├── web/          # Vite React TypeScript frontend
+│   └── api/          # FastAPI Python backend
+├── docs/             # Documentation
+├── deploy/           # Deployment skeleton files
+├── docker-compose.yml
+└── package.json      # Root monorepo scripts
+```
+
+## Conventions
+
+- **Frontend**: React functional components, TypeScript strict mode, ESLint + Ruff-like rules.
+- **Backend**: FastAPI, Pydantic settings, pytest, ruff, mypy.
+- **Commits**: Conventional commits with task ID prefix, e.g. `feat(FN-002): description`.