# AGENTS.md

Notes for coding agents working in this repository.

## Re-sync the uv environment before doing anything

The checked-out `.venv` is **not** portable. It is built by `uv sync`, and its
`python` symlink points at a uv-managed interpreter path belonging to whichever
machine created it (for example `/home/node/.local/share/uv/python/...`). When
the repository is re-synced from the host, that interpreter is gone, the
symlink dangles, and every `.venv/bin/*` command fails with:

    .venv/bin/python: No such file or directory

So always re-sync first — before tests, lint, the app, or any tooling:

```bash
uv sync
```

If it still fails, rebuild the environment once:

```bash
rm -rf .venv && uv sync
```

There is no project Python on `PATH`; use `uv run <command>` or the freshly
synced `.venv/bin/python` explicitly.

## Commands

```bash
uv sync                                # resync the environment (do this first)
uv run pytest                          # full test suite
uvx ruff check .                       # lint (ruff is not a project dependency)
uv run beefy-player --list             # station ids for the current catalogue
uv run python tools/ansi_art.py ...    # regenerate a provider's header art
```