Agent Instructions

# Agent Instructions

### For AI Agents

When working on this codebase:

1. **Always use `uv`** instead of `pip` or `python -m venv`
2. **Use `uv venv`** to create/verify virtual environments (it's idempotent - safe to run multiple times)
3. **Use `uv sync`** to install dependencies from `pyproject.toml`
4. **Use `uv run`** to execute Python scripts (no activation needed)
5. **Use the Makefile** targets (`make install`, `make run`, etc.) when available

### Examples

```bash
# Setup new environment
uv venv && uv sync

# Run tests
uv run pytest

# Run the example
uv run example.py

# Or use make targets
make install
make run
make test
```

## Project Conventions

- Dependencies are managed in `pyproject.toml`
- Lock file is `uv.lock` (committed to repo)
- Virtual environment is `.venv/` (gitignored)
- Generated data files go in `data/` (gitignored)
- **Use Polars, not Pandas** - All data manipulation uses `polars` for performance and consistency
- Strongly prefer altair over matplotlib and pathlib over os.path
- **Tests use plain functions, not classes** - Use `def test_foo(tmp_path):` not `class TestFoo`

Be extremely concise. Sacrifice grammar for the sake of concision.