# Local Development Runbook

## Prerequisites

Python 3.13, uv, Docker Engine and Docker Compose.

## Bootstrap

```bash
cp .env.example .env
uv sync --all-extras --group dev
docker compose up -d postgres qdrant
uv run python scripts/wait_for_services.py
uv run pytest tests/api/test_health.py tests/unit/test_config.py
uv run uvicorn ragcore.main:app --reload
```

Worker in a second terminal:

```bash
uv run python -m ragcore.worker
```

## Normal task cycle

```bash
python scripts/backlog.py next
python scripts/backlog.py start <task>
# implementation
bash scripts/codex_verify.sh  # PowerShell: .\scripts\codex_verify.ps1
python scripts/backlog.py done <task> --evidence artifacts/evidence/<task>
```

## Reset disposable state

```bash
docker compose down -v
rm -rf .state
```

Never apply this reset to production paths.