# AGENTS.md

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

## Project Coding Rules (Non-Obvious Only)

- Always use `tomlkit` instead of standard `toml` for configuration file operations (preserves formatting and comments)
- All configuration write operations must call `create_backup()` before making changes
- Mirror URLs must end with `/simple` - this is enforced at the Pydantic model level
- Mirror names can only contain letters, numbers, hyphens and underscores (validated in Mirror model)
- Built-in mirrors cannot be deleted - only custom mirrors can be added/removed
- Use `field_validator` instead of deprecated `validator` for Pydantic v2 models
- Mirror comparison is case-insensitive based on name (implemented in `__eq__` method)
- Speed testing uses fixed 100KB download of `requests-2.31.0-py3-none-any.whl` for consistency
- Async speed testing uses `asyncio.Semaphore` with max 5 concurrent requests
- Cache expiration is 24 hours - filter by timestamp when loading cache
- CLI commands must use specific exit codes: EXIT_SUCCESS(0), EXIT_ERROR(1), EXIT_INVALID_ARGS(2)
- Rich console output required for all user-facing commands with emoji indicators
- Dangerous operations (delete, reset) must use `typer.confirm()` for user confirmation
- Unit tests must disable network calls using `pytest-socket`
- Test isolation requires mocking `platformdirs` API paths using `temp_uv_home` fixture
- All async operations must use `aiohttp` for HTTP requests
- URL validation uses Pydantic `HttpUrl` type with custom `/simple` suffix validator
- Configuration paths must use `platformdirs` for cross-platform compatibility
- Note: `user_config_path()` is a property, not a method (API compatibility issue)