Refactor Proxmox settings validation and enhance dotenv loading logic; update README for clarity on configuration requirements

README.md

@@ -23,7 +23,7 @@ Textual TUI for creating Proxmox VMs with live reference data, guarded create co
 
 ## Typical usage
 
-1. Copy `.env.example` to `.env`.
+1. Copy `.env.example` to `~/.config/pve-vm-setup/.env` or `.env`.
 2. Fill in the Proxmox connection settings.
 3. Decide whether this machine should be allowed to create VMs at all.
 4. Optionally enable test mode if you want live creates restricted to a known node/pool and auto-tagged.
@@ -64,12 +64,20 @@ Use this when you want live creates, but only inside a constrained sandbox.
 
 Start from `.env.example`. The table below describes every supported variable that is currently parsed by the app.
 
+Configuration source order:
+
+1. Process environment variables
+2. `~/.config/pve-vm-setup/.env`
+3. `.env` in the current working directory
+
+Higher entries override lower ones.
+
 | Variable | Required | Default | Recommended | Purpose |
 | --- | --- | --- | --- | --- |
-| `PROXMOX_URL` | Required for live access | none | Yes | Base Proxmox URL, for example `https://pve.example.com:8006`. |
-| `PROXMOX_REALM` | Required for live access | none | Yes | Proxmox auth realm, for example `pam`, `pve`, or `ldap`. |
-| `PROXMOX_USER` | Required for live access | none | Yes | Username used for API login. If it does not contain `@realm`, the configured realm is appended automatically. |
-| `PROXMOX_PASSWORD` | Required for live access | none | Yes | Password for the Proxmox user. |
+| `PROXMOX_URL` | Required for live access | none | Yes | Base Proxmox URL, for example `https://pve.example.com:8006`. This is the only setting required to make the interactive app use the real Proxmox backend instead of fake mode. |
+| `PROXMOX_REALM` | Optional | none | Recommended | Default realm for login. If unset, the login view loads realms from Proxmox and lets you choose one manually. Still required for non-interactive doctor login checks. |
+| `PROXMOX_USER` | Optional | none | Recommended | Default username shown in the login form. If unset, you can type it manually. Still required for non-interactive doctor login checks. |
+| `PROXMOX_PASSWORD` | Optional | none | Usually no | Default password shown in the login form. If unset, you can type it manually. Still required for non-interactive doctor login checks. |
 | `PROXMOX_VERIFY_TLS` | Optional | `false` | Yes, if your certificates are valid | Controls TLS certificate verification for API calls. Set to `true` for properly trusted certificates. Set to `false` only for internal or self-signed setups you explicitly trust. |
 | `PROXMOX_API_BASE` | Optional | `/api2/json` | Usually leave as-is | API base path appended to `PROXMOX_URL`. Only change this if your deployment needs a different base path. |
 | `PROXMOX_REQUEST_TIMEOUT_SECONDS` | Optional | `15` | Usually yes | Request timeout used for API calls and task polling. Increase it if your environment is slow. |
@@ -146,7 +154,9 @@ PROXMOX_TEST_VM_NAME_PREFIX=codex-e2e-
 
 ## Notes and caveats
 
-- Live access requires `PROXMOX_URL`, `PROXMOX_USER`, `PROXMOX_PASSWORD`, and `PROXMOX_REALM`.
+- Interactive live access only requires `PROXMOX_URL`.
+- `PROXMOX_USER`, `PROXMOX_PASSWORD`, and `PROXMOX_REALM` act as login defaults for the UI.
+- `--doctor-live` still requires `PROXMOX_URL`, `PROXMOX_USER`, `PROXMOX_PASSWORD`, and `PROXMOX_REALM` because it performs a full non-interactive login.
 - Test mode is not the same as read-only mode. Test mode still performs real creates when creation is allowed.
 - If `PROXMOX_PREVENT_CREATE=true`, the confirm step validates but actual creation is blocked.
 - `PROXMOX_TEST_POOL` is currently required when test mode is enabled.