initial commit; layout Plan for agentic development

2026-03-08 00:13:24 +01:00 · 2026-03-08 00:13:24 +01:00 · a34229a6ae
commit a34229a6ae
14 changed files with 1125 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,104 @@
 # Project
 .env
 # Linux
 *~
 # temporary files which can be created if a process still has a handle open of a deleted file
 .fuse_hidden*
 # Metadata left by Dolphin file manager, which comes with KDE Plasma
 .directory
 # Linux trash folder which might appear on any partition or disk
 .Trash-*
 # .nfs files are created when an open file is removed but is still being accessed
 .nfs*
 # Log files created by default by the nohup command
 nohup.out
 # General
 .DS_Store
 __MACOSX/
 .AppleDouble
 .LSOverride
 Icon[
 ]
 # Thumbnails
 ._*
 # Files that might appear in the root of a volume
 .DocumentRevisions-V100
 .fseventsd
 .Spotlight-V100
 .TemporaryItems
 .Trashes
 .VolumeIcon.icns
 .com.apple.timemachine.donotpresent
 # Directories potentially created on remote AFP share
 .AppleDB
 .AppleDesktop
 Network Trash Folder
 Temporary Items
 .apdisk
 # Windows thumbnail cache files
 Thumbs.db
 Thumbs.db:encryptable
 ehthumbs.db
 ehthumbs_vista.db
 # Dump file
 *.stackdump
 # Folder config file
 [Dd]esktop.ini
 # Recycle Bin used on file shares
 $RECYCLE.BIN/
 # Windows Installer files
 *.cab
 *.msi
 *.msix
 *.msm
 *.msp
 # Windows shortcuts
 *.lnk
 # Swap
 [._]*.s[a-v][a-z]
 # comment out the next line if you don't need vector files
 !*.svg
 [._]*.sw[a-p]
 [._]s[a-rt-v][a-z]
 [._]ss[a-gi-z]
 [._]sw[a-p]
 # Session
 Session.vim
 Sessionx.vim
 # Temporary
 .netrwhist
 *~
 # Auto-generated tag files
 tags
 # Persistent undo
 [._]*.un~
 .vscode/*
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
 !.vscode/*.code-snippets
 !*.code-workspace
 # Built Visual Studio Code Extensions
 *.vsix
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@ -0,0 +1,415 @@
 # Architecture
 ## Status
 This repository currently contains product and implementation planning documents, not an implemented application. The architecture described here is therefore the intended architecture inferred from:
 - `SPEC.md`
 - `TASKS.md`
 - `README.md`
 - The screen mockups in `SPEC/`
 Where the sources are incomplete, this document calls that out explicitly instead of inventing behavior.
 ## Purpose
 The system is a terminal user interface (TUI) application that guides a user through authenticating against a Proxmox VE server and creating a virtual machine through a multi-step wizard.
 Primary responsibilities:
 - Authenticate a user against Proxmox
 - Load server-side reference data needed for VM setup
 - Collect VM configuration across several wizard steps
 - Validate and summarize the configuration
 - Translate the collected state into Proxmox API requests
 - Execute VM creation and report progress, success, and failure
 ## High-Level Shape
 The intended design is a layered Textual application with a strict separation between UI, workflow/domain state, and Proxmox integration.
 ```text
 Textual App Shell
  -> Wizard Screens
    -> Reusable Widgets
      -> Domain / Workflow State
        -> Service Layer
          -> Proxmox API
 ```
 This structure is directly supported by `TASKS.md`, which requires separation of:
 - app shell
 - screens
 - widgets
 - models
 - services
 - a central state or domain module for the VM configuration workflow
 ## System Context
 ### External system
 The only explicit external dependency is the Proxmox VE API.
 Expected external interactions:
 - authentication realm discovery
 - login / authentication
 - loading nodes
 - loading next free VM ID
 - loading resource pools
 - loading existing tags
 - loading storage backends
 - loading available ISO images
 - creating the VM
 - updating VM configuration after creation
 ### User
 The user operates the application interactively through a terminal UI. The wizard is expected to be keyboard-friendly and stateful across steps.
 ## Main Runtime Flow
 The workflow described in `SPEC.md` and `TASKS.md` is:
 1. Login
 2. General VM configuration
 3. OS selection
 4. System configuration
 5. Disk configuration
 6. CPU configuration
 7. Memory configuration
 8. Network configuration
 9. Confirmation
 10. VM creation submission
 11. Post-creation serial-console configuration
 Each step is expected to support explicit UI states where relevant:
 - default
 - loading
 - success
 - empty
 - error
 That state coverage is called out repeatedly in `README.md` and `TASKS.md`, so it is a core architectural requirement, not a UI detail.
 ## Architectural Layers
 ### 1. App Shell
 The app shell owns application startup and top-level navigation.
 Expected responsibilities:
 - start the Textual application
 - manage high-level routing between login, wizard, and submission/result states
 - provide shared app context to screens
 - coordinate back/next/confirm navigation
 The current run command placeholder in `README.md` and `TASKS.md` is `uv run python -m your_app`, so the real package/module name is still unresolved.
 ### 2. Screens
 Each wizard step should be implemented as a dedicated screen. Based on the spec, those screens are:
 - Login screen
 - General screen
 - OS screen
 - System screen
 - Disks screen
 - CPU screen
 - Memory screen
 - Network screen
 - Confirm screen
 Responsibilities of screens:
 - render step-specific controls and feedback
 - bind widgets to workflow/domain state
 - trigger service-backed loading actions through a non-UI layer
 - show validation, loading, empty, and error states
 Non-responsibilities:
 - direct Proxmox API calls
 - business rule ownership
 - payload assembly for VM creation
 That separation is explicitly required by the repository guidance.
 ### 3. Reusable Widgets
 Widgets should contain presentation logic and local interaction behavior only.
 Likely widget candidates inferred from the screens:
 - step navigation/footer
 - form rows and field groups
 - async loading/error message blocks
 - tag editor
 - disk list editor
 - summary panels
 The repo guidance says to keep business logic out of widgets where possible, so widgets should consume already-shaped state instead of deriving backend rules themselves.
 ### 4. Domain Model / Workflow State
 The domain layer is the center of the application. `TASKS.md` explicitly asks for a central state or domain module for the VM configuration workflow.
 This layer should model:
 - authentication state
 - selected realm and authenticated session context
 - VM configuration collected across steps
 - per-step validation results
 - derived defaults
 - submission status
 Core sub-models implied by the spec:
 - `AuthenticationConfig`
 - `GeneralConfig`
 - `OsConfig`
 - `SystemConfig`
 - `DiskConfig` plus a disk collection
 - `CpuConfig`
 - `MemoryConfig`
 - `NetworkConfig`
 - `VmConfig` as the aggregate root
 This layer should also own workflow-specific rules such as:
 - default VM ID is the next free ID above 100
 - default OS type/version
 - default machine, BIOS, SCSI controller, CPU, memory, bridge, and other screen defaults
 - derived memory defaults
 - incremental disk device naming such as `scsi0`, `scsi1`, ...
 - selecting the latest matching NixOS minimal ISO when available
 ### 5. Service Layer
 The service layer isolates Proxmox integration and gives the UI a testable interface. This is explicitly required in Task 1 and repeated in later tasks.
 Expected service responsibilities:
 - define an interface or protocol used by the UI/domain layers
 - encapsulate Proxmox HTTP/API interaction
 - map Proxmox responses into application-friendly data structures
 - expose task-oriented methods rather than raw API calls where possible
 - surface structured errors
 Likely service capabilities:
 - `load_realms()`
 - `login()`
 - `load_nodes()`
 - `load_next_vm_id()`
 - `load_pools()`
 - `load_tags()`
 - `load_storages()`
 - `load_isos(storage)`
 - `create_vm(config)`
 - `configure_vm_serial_console(node, vmid)`
 The service layer should also contain or delegate to a request/payload builder that converts `VmConfig` into the final Proxmox API request shape.
 It also needs orchestration logic for the post-create step so partial-success cases are represented explicitly.
 ### 6. Proxmox API Adapter
 Below the service layer, the application will need a concrete Proxmox adapter/client.
 Concerns at this level:
 - authentication/session handling
 - request execution
 - response parsing
 - API-specific error translation
 This layer should remain narrow and infrastructure-focused. It should not know about Textual or screen behavior.
 ## Data Flow
 ### Reference data loading
 Several screens depend on live server data.
 Examples:
 - login screen loads authentication realms
 - general screen loads nodes, next VM ID, pools, and tags
 - OS screen loads storages and ISO images
 - creation step submits the final VM request
 Expected data flow:
 ```text
 Screen action
  -> domain/controller update
    -> service call
      -> Proxmox API
    -> mapped result or structured error
  -> state update
  -> UI rerender
 ```
 ### Submission flow
 The final submission path should be:
 ```text
 Collected per-step config
  -> aggregate VmConfig
    -> validation
      -> Proxmox request payload builder
        -> create VM API call
          -> update VM config with serial0/vga
            -> success/failure state shown in UI
 ```
 Because the serial console is configured after creation, the application should treat submission as a short request sequence instead of a single atomic API call.
 ## State Management
 The documents strongly suggest a single workflow state instead of screen-local business state.
 Why this matters:
 - the confirmation screen needs the full configuration
 - back/next navigation should preserve user input
 - defaults and validation span multiple steps
 - submission requires one aggregate payload
 Recommended state boundaries inferred from the requirements:
 - screen-local transient UI state: focus, open dialog, temporary edit row
 - workflow state: all persisted user choices and loaded reference data
 - service state: request progress, responses, and errors
 ## Validation Strategy
 Validation should live in the domain/workflow layer, not in widgets.
 Validation categories implied by the spec:
 - required fields such as credentials, VM name, node, and other mandatory Proxmox inputs
 - numeric constraints for VM ID, disk size, CPU, memory, VLAN, MTU, rate limit, and multiqueue
 - conditional rules, for example ISO selection only when media type is ISO
 - cross-field rules, such as minimum memory defaults and disk device uniqueness
 The confirmation screen is explicitly responsible for showing validation issues or missing required inputs before submission.
 ## Error Handling Model
 Error handling is a first-class architectural concern in the available documents.
 The system should distinguish at least:
 - authentication failures
 - reference data loading failures
 - empty-result states that are valid, such as no pools or no ISOs
 - validation failures before submission
 - VM creation API failures
 - post-creation serial-console configuration failures after the VM already exists
 Errors should be represented in a structured way so screens can render meaningful messages without parsing raw exceptions.
 ## Testing Architecture
 The repository guidance defines the testing strategy clearly.
 ### Unit tests
 Target:
 - domain models
 - default and derived-value logic
 - validation
 - payload building
 - service behavior with fakes/mocks
 ### Textual interaction tests
 Target:
 - screen flows using `run_test()` and `Pilot`
 - navigation
 - user input handling
 - async loading and error transitions
 - submission success/failure behavior
 ### Snapshot tests
 Target:
 - default states
 - loading states
 - empty states
 - error states
 - key visual summary/submission states
 This testing strategy reinforces the separation between UI and business logic: business rules should be testable without rendering the Textual UI.
 The create-then-configure request sequence is especially important to cover in service tests.
 ## Suggested Repository Structure
 `TASKS.md` does not prescribe exact paths, but it does require a separation of concerns. A structure consistent with the current requirements would be:
 ```text
 your_app/
  __main__.py
  app.py
  screens/
  widgets/
  models/
  services/
  domain/
  testing/
 tests/
  unit/
  integration/
  snapshots/
 ```
 This is illustrative, not authoritative. The final module name and exact layout remain open.
 ## Important Defaults and Rules From the Spec
 These defaults are central enough to architecture because they belong in domain/service logic rather than ad hoc widget code.
 - Authentication realm defaults to PAM
 - VM ID defaults to next free ID above 100
 - General screen defaults: HA enabled, start at boot disabled
 - OS screen defaults: storage `cephfs`, latest matching NixOS minimal ISO when available, guest type Linux, guest version `6.x - 2.6 Kernel`
 - System screen defaults: machine `q35`, BIOS `OVMF (UEFI)`, EFI disk enabled, EFI storage `ceph-pool`, SCSI controller `VirtIO SCSI single`, Qemu Agent enabled
 - Disk defaults: SCSI bus, incrementing device numbers, storage `ceph-pool`, size 32 GiB, format RAW, IO thread enabled, SSD emulation enabled, backup enabled, async IO `io_uring`
 - CPU defaults: 2 cores, 1 socket, type `host`
 - Memory defaults: 2048 MiB, min memory equals memory, ballooning enabled, KSM enabled
 - Network defaults: bridge `vmbr9`, model `virtio`, firewall enabled
 ## Open Questions
 The available resources leave several architectural details unresolved:
 - What concrete Python package/module name should replace `your_app`?
 - Which Proxmox authentication mechanism should be used under the hood: ticket/cookie, API token, or both?
 - How should session persistence work across screens and retries?
 - Does the app target a single Proxmox node/cluster endpoint or support multiple saved endpoints?
 - How should physical disc drive selection work in a terminal UI, given it is listed as a valid OS media option but not described further?
 - What exact validation rules are required for optional numeric fields such as startup delay, shutdown timeout, MTU, rate limit, and multiqueue?
 - What is the expected behavior when API-provided defaults such as `cephfs`, `ceph-pool`, or `vmbr9` do not exist?
 - Does the app need to document guest-side operating system changes required for a working serial login, or is the scope limited to Proxmox-side serial-console configuration only?
 ## Architectural Summary
 The intended architecture is a Textual wizard application with:
 - a thin app shell for navigation
 - per-step screens for presentation
 - reusable widgets with minimal business logic
 - a central workflow/domain state model
 - a service layer that isolates Proxmox integration
 - strong test coverage across unit, interaction, and snapshot levels
 This design matches the current repository guidance and is the clearest path to implementing the spec without coupling Textual UI code directly to Proxmox API behavior.
--- a/README.md
+++ b/README.md
@ -0,0 +1,17 @@
 ## Commands
 - Install: `uv sync`
 - Run app: `uv run python -m your_app`
 - Run tests: `uv run pytest`
 - Lint: `uv run ruff check .`
 - Format: `uv run ruff format .`
 ## Engineering rules
 - Write tests before implementation
 - Prefer small PR-sized tasks
 - Keep business logic out of widgets where possible
 - 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
--- a/SPEC.md
+++ b/SPEC.md
@ -0,0 +1,208 @@
 # Proxmox VM Setup Script Specification
 This document outlines the specifications for a script that automates the setup of virtual machines (VMs) using the Proxmox API. The script will allow users to create and configure VMs based on predefined templates, manage resources, and handle authentication.
 ## API Documentation
 Proxmox API Documentation: https://pve.proxmox.com/wiki/Proxmox_VE_API
 Proxmox API Schema: https://pve.proxmox.com/pve-docs/api-viewer/index.html
 ## Features
 ### Authentication
 The script will prompt users to authenticate using their Proxmox credentials (username and password). It will also allow users to select the Authentication Realm from the available options provided by the API.
 Default: The PAM realm will be selected by default, but users can choose other realms if needed.
 [!Login screen](/SPEC/00_login.png)
 ### VM Creation/Configuration
 Users will be able to create VMs by selecting from predefined templates. The script will handle the necessary API calls to create and configure the VM based on user input.
 #### General
 This screen will show the general configuration options for the VM, such as:
 - Node
 - VM ID
  - Default: next free VM ID above 100
 - Name
 - Resource Pool
  - Default Empty
  - Empty is allowed
  - Get available Ressource pools from the server (could be empty / zero / nothing)
 - Tags
  - List the existing ones
  - Allow to add new ones one by one
  - Allow also the user to remove tags
 - High Availability (HA) (enabled/disabled)
  - Default: enabled
 - start at boot (enabled/disabled)
  - Default: disabled
 - start/shutdown order (optional)
 - startup delay (optional)
 - shutdown timeout (optional)
 [!VM Creation General screen](/SPEC/01_create_vm_general.png)
 #### OS
 This screen will allow users to select the operating system ISO for the VM. Users can choose from a list of available OS ISO's provided by the API.
 - Ask the user if they want to use a CD/DVD disc image file (iso)
  - Valid choices are
    - ISO
    - Physical disc drive
    - No
 - If they've chosen "ISO"
  - Let them choose the storage from which they want to use the iso from (get available from the API)
    - Default: cephfs
  - Let them choose the iso (load available iso's available at the storage via the api, when the storage changes load the ISO's again, the could be empty)
    - Default: the latest available nixos-minimal iso (schema nixos-minimal-<two digit year>-<two digit month>.<some alphanumeric id or hash>.<architecture e.g. x86_64>-linux.iso
 - Let the user select the Guest type and Version
  - Default Type: Linux
  - Default Version: 6.x - 2.6 Kernel
 [!VM Creation OS screen](/SPEC/02_create_vm_os.png)
 #### System
 This screen will allow users to configure the system settings for the VM, such as Graphic card, Machine, Firmware BIOS, Add EFI Disk, EFI storage, Pre-Enroll keys, SCSI Controller, Qemu Agent and if a TPM should be added.
 - Graphic card
  - Default: Default
 - Machine
  - Default: q35
 - Formware BIOS
  - Default: OVMF (UEFI)
 - Add EFI Disk (enabled/disabled)
  - Default: enabled
 - EFI storage
  - Default: ceph-pool
 - Pre-Enroll keys (enabled/disabled)
  - Default: disabled
 - SCSI Controller
  - Default: VirtIO SCSI single
 - Qemu Agent (enabled/disabled)
  - Default: enabled
 - TPM (enabled/disabled)
  - Default: disabled
 [!VM Creation System screen](/SPEC/03_create_vm_system.png)
 #### Disks
 This screen will allow users to configure the disk settings for the VM, such as Disk size, Storage, and Format.
 - Allow the user to add zero to multiple disks
 - For each disk, ask the user for the following information:
  - Allow the user to add/modify/remove disks one by one
  - Bus/Device
    - Default BUS: SCSI
    - Default Device: increasing integer starting from 0 (e.g. SCSI0, SCSI1, ...)
  - Storage
    - Default: ceph-pool
  - Disk size (GiB)
    - Default: 32 GiB
  - Format
    - Default: RAW (not changeable)
  - Cache
    - Default: no chache
  - Discard
    - Default: disabled
  - IO Thread
    - Default: enabled
  - SSD emulation
    - Default: enabled
  - Backup
    - Default: enabled
  - Skip replication
    - Default: disabled
  - Async IO
    - Default: io_uring
 [!VM Creation Disks screen](/SPEC/04_create_vm_disks.png)
 #### CPU
 This screen will allow users to configure the CPU settings for the VM, such as Cores, Sockets, and CPU Type.
 - Cores
  - Default: 2
 - Sockets
  - Default: 1
 - CPU Type
  - Default: host
 [!VM Creation CPU screen](/SPEC/05_create_vm_cpu.png)
 #### Memory
 This screen will allow users to configure the memory settings for the VM, such as Memory size and Ballooning.
 - Memory size (MiB)
  - Default: 2048 MiB
 - Min Memory (MiB)
  - Default: same as Memory size
 - Ballooning (enabled/disabled)
  - Default: enabled
 - Allow KSM (enabled/disabled)
  - Default: enabled
 [!VM Creation Memory screen](/SPEC/06_create_vm_memory.png)
 #### Network
 This screen will allow users to configure the network settings for the VM, such as Network Model, Bridge, and VLAN.
 - No Network device (enabled/disabled)
  - Default: disabled
 - Bridge
  - Default: vmbr9
 - VLAN Tag
  - Default: none
 - Model
  - Default: virtio
 - MAC Address
  - Default: auto-generated by the API
 - Firewall (enabled/disabled)
  - Default: enabled
 - Disconnected (connected (enabled)/disconnected (disabled))
  - Default: disabled
 - MTU
  - Default: none (Same as the bridge)
 - Rate Limit (MB/s)
  - Default: none (unlimited)
 - Multiqueue (integer)
  - Default: none
 [!VM Creation Network screen](/SPEC/07_create_vm_network.png)
 #### Confirm
 This screen will display a summary of the VM configuration and allow users to confirm the creation of the VM.
 - Start at boot (enabled/disabled)
  - Default: disabled
 - Display a summary of the VM configuration, including all the settings configured in the previous steps.
 - Provide a "Create VM" button that, when clicked, will send the API request to create the VM with the specified configuration.
 - After the VM has been created successfully, run the required follow-up configuration to enable the Proxmox VE serial console in the web UI.
  - Add a serial port using `serial0` with value `socket`
  - Set the display to `serial0` so the Proxmox VE web console opens the serial terminal via xterm.js
  - If the follow-up serial-console configuration fails, show that clearly as a separate post-creation error state because the VM itself may already exist
 [!VM Creation Confirm screen](/SPEC/08_create_vm_confirm.png)
 ### Error Handling
 The script will include error handling to manage API errors, authentication failures, and other potential issues that may arise during the VM setup process.
 ### Testing
 The script will be tested using Textual interaction tests with run_test() and Pilot. Business logic will be kept in a central module, and testing will include running pytest, ruff check .., and ruff format .. .
 Add snapshot coverage for default, loading, and error states.
 ### Documentation
 The script will be well-documented, summarizing changes and any unresolved UX concerns.
--- a/SPEC/00_login.png
+++ b/SPEC/00_login.png
--- a/SPEC/01_create_vm_general.png
+++ b/SPEC/01_create_vm_general.png
--- a/SPEC/02_create_vm_os.png
+++ b/SPEC/02_create_vm_os.png
--- a/SPEC/03_create_vm_system.png
+++ b/SPEC/03_create_vm_system.png
--- a/SPEC/04_create_vm_disks.png
+++ b/SPEC/04_create_vm_disks.png
--- a/SPEC/05_create_vm_CPU.png
+++ b/SPEC/05_create_vm_CPU.png
--- a/SPEC/06_create_vm_memory.png
+++ b/SPEC/06_create_vm_memory.png
--- a/SPEC/07_create_vm_network.png
+++ b/SPEC/07_create_vm_network.png
--- a/SPEC/08_create_vm_confirm.png
+++ b/SPEC/08_create_vm_confirm.png
--- a/TASKS.md
+++ b/TASKS.md
@ -0,0 +1,381 @@
 # TASKS
 ## Codex working agreement
 Use these rules for every implementation task in this repository:
 - Write tests first.
 - Use `uv` for all Python commands and dependency management.
 - Use `ruff` for linting and formatting.
 - Prefer small vertical slices that can be implemented and verified independently.
 - Keep Proxmox API and business logic out of Textual widgets where possible.
 - Every screen must have explicit default, loading, success, empty, and error states where applicable.
 - Every interactive screen must be covered by Textual interaction tests using `run_test()` and `Pilot`.
 - Important visual states should be covered by snapshot tests.
 - At the end of each task, summarize what changed and list unresolved UX concerns.
 ## Repository commands
 Codex should use these commands:
 - Install dependencies: `uv sync`
 - Run app: `uv run python -m your_app`
 - Run tests: `uv run pytest`
 - Run lint checks: `uv run ruff check .`
 - Format code: `uv run ruff format .`
 ## Implementation backlog
 ### Task 1: Bootstrap the Textual app and project structure
 Create the initial Textual application structure and make the repository runnable and testable.
 Requirements:
 - Create the application entrypoint used by `uv run python -m your_app`.
 - Set up a project structure that separates app shell, screens, widgets, models, and services.
 - Add the initial test setup for unit tests, Textual interaction tests, and snapshot tests.
 - Add a central state or domain module for the VM configuration workflow.
 - Add a service interface for Proxmox API access so UI code can be tested with fakes or mocks.
 Definition of done:
 - Add or update tests first.
 - `uv run pytest` passes.
 - `uv run ruff check .` passes.
 - `uv run ruff format .` has been run.
 - The app opens a minimal Textual shell screen.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 2: Implement authentication screen and Proxmox login flow
 Build the login screen shown in `SPEC.md` and authenticate before the VM creation workflow starts.
 Requirements:
 - Ask the user for username and password.
 - Load available authentication realms from the Proxmox API.
 - Let the user choose the authentication realm.
 - Default the authentication realm to Linux PAM standard authentication.
 - Handle authentication failure and loading states.
 - Prevent the wizard from continuing until authentication succeeds.
 Definition of done:
 - Add or update tests first.
 - Add service tests for realm loading and login handling.
 - Add Textual interaction tests using `run_test()` and `Pilot` for the login flow.
 - Add snapshot coverage for default, loading, and authentication-error states.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 3: Implement the general VM configuration screen
 Build the general configuration screen from `SPEC.md`.
 Fields:
 - Node
 - VM ID
  - Default: next free VM ID above 100
 - Name
 - Resource Pool
  - Default: empty
  - Empty is allowed
  - Load available resource pools from the server
  - The pool list may be empty
 - Tags
  - List existing tags
  - Allow adding tags one by one
  - Allow removing tags
 - High Availability (HA)
  - Default: enabled
 - Start at boot
  - Default: disabled
 - Start/shutdown order
  - Optional
 - Startup delay
  - Optional
 - Shutdown timeout
  - Optional
 Definition of done:
 - Add or update tests first.
 - Cover default values, validation, optional fields, and empty pool lists.
 - Add service tests for loading nodes, next VM ID, pools, and existing tags.
 - Add Textual interaction tests using `run_test()` and `Pilot`.
 - Add snapshot coverage for the default general screen and an empty-pool state.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 4: Implement the OS selection screen
 Build the OS configuration screen from `SPEC.md`.
 Requirements:
 - Ask whether the user wants to use installation media.
 - Valid choices:
  - ISO
  - Physical disc drive
  - No
 - If the user selects ISO:
  - Load available storages from the Proxmox API
  - Default storage to `cephfs`
  - When the storage changes, reload the available ISOs
  - The ISO list may be empty
  - Let the user choose the ISO
  - Default ISO to the latest available NixOS minimal ISO matching this pattern:
    - `nixos-minimal-<two digit year>-<two digit month>.<some alphanumeric id or hash>.<architecture>-linux.iso`
 - Let the user select guest type and version
  - Default type: Linux
  - Default version: 6.x - 2.6 Kernel
 Definition of done:
 - Add or update tests first.
 - Add service tests for storage and ISO loading and NixOS ISO default selection.
 - Add Textual interaction tests for switching media type, storage, and ISO selection.
 - Add snapshot coverage for:
  - default OS screen
  - ISO selected with results
  - ISO selected with no results
 - Summarize what changed and list unresolved UX concerns.
 ### Task 5: Implement the system configuration screen
 Build the system configuration screen from `SPEC.md`.
 Fields:
 - Graphic card
  - Default: Default
 - Machine
  - Default: q35
 - Firmware BIOS
  - Default: OVMF (UEFI)
 - Add EFI Disk
  - Default: enabled
 - EFI storage
  - Default: ceph-pool
 - Pre-Enroll keys
  - Default: disabled
 - SCSI Controller
  - Default: VirtIO SCSI single
 - Qemu Agent
  - Default: enabled
 - TPM
  - Default: disabled
 Definition of done:
 - Add or update tests first.
 - Model system settings separately from widgets.
 - Add Textual interaction tests using `run_test()` and `Pilot`.
 - Add snapshot coverage for the default system screen.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 6: Implement the disks configuration screen
 Build the disks configuration screen from `SPEC.md`.
 Requirements:
 - Allow the user to configure zero to multiple disks.
 - Allow the user to add, modify, and remove disks one by one.
 - For each disk, support:
  - Bus/Device
    - Default bus: SCSI
    - Default device: increasing integer starting from 0 such as `scsi0`, `scsi1`, ...
  - Storage
    - Default: `ceph-pool`
  - Disk size in GiB
    - Default: 32
  - Format
    - Default: RAW
    - Not changeable
  - Cache
    - Default: no cache
  - Discard
    - Default: disabled
  - IO Thread
    - Default: enabled
  - SSD emulation
    - Default: enabled
  - Backup
    - Default: enabled
  - Skip replication
    - Default: disabled
  - Async IO
    - Default: `io_uring`
 Definition of done:
 - Add or update tests first.
 - Model disk configuration separately from widgets.
 - Add service tests for available storage loading if required by the UI.
 - Add Textual interaction tests for add, edit, and remove disk flows.
 - Add snapshot coverage for the default disk state and a multi-disk state.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 7: Implement the CPU configuration screen
 Build the CPU configuration screen from `SPEC.md`.
 Fields:
 - Cores
  - Default: 2
 - Sockets
  - Default: 1
 - CPU Type
  - Default: host
 Definition of done:
 - Add or update tests first.
 - Cover default values and validation.
 - Add Textual interaction tests using `run_test()` and `Pilot`.
 - Add snapshot coverage for the default CPU screen.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 8: Implement the memory configuration screen
 Build the memory configuration screen from `SPEC.md`.
 Fields:
 - Memory size in MiB
  - Default: 2048
 - Min Memory in MiB
  - Default: same as Memory size
 - Ballooning
  - Default: enabled
 - Allow KSM
  - Default: enabled
 Definition of done:
 - Add or update tests first.
 - Cover default values, derived defaults, and validation.
 - Add Textual interaction tests using `run_test()` and `Pilot`.
 - Add snapshot coverage for the default memory screen.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 9: Implement the network configuration screen
 Build the network configuration screen from `SPEC.md`.
 Fields:
 - No Network device
  - Default: disabled
 - Bridge
  - Default: `vmbr9`
 - VLAN Tag
  - Default: none
 - Model
  - Default: virtio
 - MAC Address
  - Default: auto-generated by the API
 - Firewall
  - Default: enabled
 - Disconnected
  - Default: disabled
 - MTU
  - Default: none
 - Rate Limit in MB/s
  - Default: none
 - Multiqueue
  - Default: none
 Definition of done:
 - Add or update tests first.
 - Cover defaults, validation, and no-network behavior.
 - Add Textual interaction tests using `run_test()` and `Pilot`.
 - Add snapshot coverage for the default network screen and the no-network state.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 10: Implement the confirmation screen
 Build the confirmation screen from `SPEC.md`.
 Requirements:
 - Display a summary of the full VM configuration collected in previous steps.
 - Clearly show all relevant settings before submission.
 - Show validation issues or missing required inputs.
 - Provide a `Create VM` button.
 Definition of done:
 - Add or update tests first.
 - Add Textual interaction tests for reaching the confirmation step.
 - Add snapshot coverage for a fully populated confirmation screen and a validation-error state.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 11: Implement VM creation against the Proxmox API
 Submit the VM creation request after confirmation.
 Requirements:
 - Translate the collected workflow state into the correct Proxmox API request payload.
 - Use the Proxmox VE API to create the VM.
 - After VM creation succeeds, send the required follow-up configuration request(s) to:
  - add `serial0: socket`
  - set `vga: serial0`
 - Treat serial-console configuration as part of the overall success criteria because it is required for using the Proxmox VE xterm.js serial console.
 - Handle API request errors cleanly.
 - Distinguish between:
  - VM creation failure before the VM exists
  - post-creation serial-console configuration failure after the VM already exists
 - Show progress, success, and failure states.
 - Preserve enough information in the UI so the user can understand what failed.
 Definition of done:
 - Add or update tests first.
 - Add service tests for payload building, request sequencing, and error handling.
 - Add Textual interaction tests for submission, full success, VM-create failure, and post-create serial-console failure flows.
 - Add snapshot coverage for submission, success, VM-create error, and post-create serial-console error states.
 - Summarize what changed and list unresolved UX concerns.
 ### Task 12: Polish navigation, error handling, and documentation
 Improve the overall wizard experience and repository documentation.
 Requirements:
 - Ensure step-to-step navigation is clear and keyboard-friendly.
 - Make back/next/confirm actions predictable across screens.
 - Standardize loading, empty, success, and error messaging.
 - Update `README.md` if the real module name or run command differs from the placeholder.
 - Document any remaining constraints, assumptions, or known gaps.
 Definition of done:
 - Add or update tests first where behavior changes.
 - Add or update interaction tests for navigation flows.
 - Add snapshot coverage for any changed visual states.
 - Summarize what changed and list unresolved UX concerns.
 ## API references
 - Proxmox API documentation: `https://pve.proxmox.com/wiki/Proxmox_VE_API`
 - Proxmox API schema / viewer: `https://pve.proxmox.com/pve-docs/api-viewer/index.html`
 ## Suggested prompt template for Codex
 Use this prompt pattern for each task:
 > Implement `TASKS.md` task N.
 > First add or update tests.
 > Use Textual interaction tests with `run_test()` and `Pilot`.
 > Add snapshot coverage for relevant default, loading, empty, success, and error states.
 > Use `uv` for commands and `ruff` for linting / formatting.
 > Keep Proxmox API logic in a service layer.
 > Run `uv run pytest`, `uv run ruff check .`, and `uv run ruff format .`.
 > Summarize what changed and list unresolved UX concerns.