# 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

## Hugging Face Deployment

- `.stl` files must be tracked by Git LFS (`*.stl filter=lfs` in `.gitattributes`)
- Verify Git LFS is available before push: `git lfs version`
- Confirm tracked LFS files: `git lfs ls-files`
- Standard push sequence: `git push origin main` then `git push hf-space main`
- If Hugging Face rejects binaries, re-check `.gitattributes` and LFS status before retrying
- `git lfs migrate` rewrites history; only use it intentionally and coordinate with collaborators first