# AGENTS.md

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

## Project Architecture Rules (Non-Obvious Only)

- CLI commands flow through MirrorManager → UVConfig → file operations (single responsibility chain)
- Speed testing is architecturally isolated: CLI → SpeedTester → async HTTP requests → Results → Cache
- Built-in mirrors loaded from constants, custom mirrors from separate config - merged at runtime
- Configuration system has blocking compatibility issue with `platformdirs` API (property vs method)
- Async speed testing uses semaphore pattern to limit concurrent requests to 5 (prevents server overload)
- Cache architecture: JSON-based with timestamp filtering, 24-hour expiration, automatic cleanup
- Mirror validation happens at Pydantic model level - URL must end with `/simple`, name restrictions enforced
- Configuration operations use backup/restore pattern - automatic backup before any write operation
- Testing architecture: 4-layer isolation (unit/integration/e2e/performance) with 90% coverage gate
- Mock architecture: `temp_uv_home` fixture isolates XDG_CONFIG_HOME, prevents developer machine pollution
- Error handling architecture: Specific exception types mapped to user-friendly messages with exit codes
- Data flow: All mirror operations go through MirrorManager for consistency and validation
- Plugin architecture: Built-in mirrors are immutable, custom mirrors stored in user config directory
- Cross-platform architecture: `platformdirs` handles config paths, but has API compatibility issues
- Performance architecture: Speed testing uses fixed-size download (100KB) for consistent measurements
- CLI architecture: Typer for command structure, Rich for formatting, specific exit codes for automation
- Dependency architecture: Core dependencies minimal, dev dependencies comprehensive for quality assurance