# Project Instructions

## Python Environment

- Always use `uv` to run Python scripts and manage dependencies — never use `pip` or `python` directly
- Run scripts with `uv run python script.py` instead of `python script.py`
- Install packages with `uv add package-name` instead of `pip install`
- To run one-off commands: `uv run <command>`
- The project uses `uv` for virtual environment management; do not create venvs manually with `python -m venv`

## Common Commands

- `uv run python script.py` — run a script
- `uv add <package>` — add a dependency
- `uv sync` — install all dependencies from lockfile
- `uv run pytest` — run tests