## Commands

- Install: `uv sync`
- Run app: `uv run python -m pve_vm_setup`
- Run live diagnostics: `uv run python -m pve_vm_setup --doctor-live`
- Run tests: `uv run pytest`
- Run read-only live tests: `uv run pytest -m live`
- Run create-gated live tests: `uv run pytest -m live_create`
- Lint: `uv run ruff check .`
- Format: `uv run ruff format .`

## Live configuration

Start from `.env.example` and provide the Proxmox credentials in `.env`.

Additional live-access controls:

- `PROXMOX_VERIFY_TLS=false` disables certificate verification for internal/self-signed installs
- `PROXMOX_API_BASE=/api2/json` makes the API base explicit
- `PROXMOX_PREVENT_CREATE=false` allows VM creation by default; set it to `true` to block creates
- `PROXMOX_ENABLE_TEST_MODE=true` enables scoped test mode for live creates
- When test mode is enabled, `PROXMOX_TEST_NODE`, `PROXMOX_TEST_POOL`, `PROXMOX_TEST_TAG`, and `PROXMOX_TEST_VM_NAME_PREFIX` are required and are used to constrain and mark created VMs

## Engineering rules

- Write tests before implementation
- Prefer small PR-sized tasks
- Keep business logic out of widgets where possible
- Field-like widgets should default to compact 3-row controls with no empty spacer line between the value row and the border
- Every screen must have empty/loading/error coverage
- Every interactive feature needs at least one Pilot test
- Visual changes should be covered by snapshot tests