# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## Project Documentation Rules (Non-Obvious Only)

- The project is a UV mirror manager tool - NOT a general Python package manager
- Built-in mirror sources are defined in `uvm/constants.py` as Mirror objects
- Custom mirrors stored separately from built-in mirrors in user config directory
- Configuration files use `tomlkit` to preserve formatting and comments (not standard toml)
- Speed testing downloads a specific file: `requests-2.31.0-py3-none-any.whl` (100KB)
- Cache location: `~/.cache/uv-mirror/.uvm-cache.json` with 24-hour expiration
- CLI commands use Rich library with emoji indicators (✅ ❌ 📍 🔗)
- Mirror URLs must end with `/simple` - enforced at model level, not just documentation
- Project has a known blocking issue: `platformdirs` API compatibility in config.py
- Test structure: unit/ (isolated), integration/ (CLI), e2e/ (real uv), performance/ (benchmarks)
- All tests require 90% coverage threshold enforced by CI
- Unit tests disable network calls to prevent external dependencies
- Mirror comparison is case-insensitive based on name, not URL
- Built-in mirrors cannot be deleted - this is enforced in the code logic
- Async operations use `aiohttp` with semaphore limiting to 5 concurrent requests
- Configuration operations create automatic backups before making changes
- Exit codes are specific: 0=success, 1=error, 2=invalid args, 3=network error, 4=config error
- The tool only modifies `uv.toml` index_url setting - doesn't touch other uv configurations