diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ad6ce4f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,38 @@
+# 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
+```