Hydra-OS/docs/superpowers/specs/2026-10-13-terminal-ux-design.md

Hydra OS terminal experience

The user requested a general UX overhaul inside Hydra, clarified that the interface should stay in the terminal for control, and specifically requested one command to download and launch an ISO from a URL. They also requested Fastfetch with a custom logo and consistent visible branding as Hydra OS. Earlier autonomous-development authorization continues to apply. This work must not modify the current NixOS configuration or existing user VM disks.

Experience

• The existing recovery terminal becomes a readable VM menu, with names, running/stopped/error states and memory allocations instead of raw JSON. A number or name opens one VM; Enter chooses the remembered selection (or the only VM). Opening explicitly starts a stopped VM and reconnects a running one. Merely displaying or refreshing the menu never starts VMs.
• Keep :shell, :refresh, :quit and VM names compatible. Offer discoverable actions for new VM setup, ISO downloading, networking (sudo nmtui) and help. Existing CLI commands remain usable and JSON-compatible.
• hydra open NAME starts if needed and displays an existing VM. Selecting a VM must actually focus its workspace, including a VM other than the first. Existing independent QEMU lifecycle and identity/locking protections remain.
• hydra run SOURCE --name NAME accepts a local ISO or HTTP(S) URL and performs download (when necessary), profile creation, startup and display. Options expose RAM, CPUs, disk size, SHA-256 and --no-view for headless use. An existing name is never replaced: report how to use hydra open NAME instead.
• hydra download URL [--sha256 HEX] stores a reusable ISO locally, reports progress and final path, and supports Ctrl+C cancellation. Explain direct image URLs versus HTML download pages. Never treat HTML as an ISO.
• Check available RAM with a 768 MiB host reserve before an explicit new launch through the new UX. Refuse an obviously insufficient budget clearly; this is a preflight estimate, not a guarantee against future memory pressure.
• Clear actionable errors, no startup of all VMs, no forced VM shutdowns.

Downloads and storage

Use Python standard-library HTTP(S), no network service or new daemon. Cache under the user's XDG cache directory in hydra/iso, keyed by URL hash and a safe basename. Reject URL credentials and non-HTTP(S) remote schemes. Download to a private temporary file; check HTTP status, content length when supplied, ISO9660/UDF volume signature and optional SHA-256 before atomic publication. Never overwrite an existing unrelated file. Cancelled/failed downloads cannot be mistaken for complete images. Check disk space; reuse validated cached images. Render safe progress and errors without leaking URL query credentials.

Branding

Visible product name is Hydra OS. Preserve technical identifiers such as hydra, hydra-os, service names, existing profile formats, disk directories and EFI installation paths. Historical release manifests/evidence keep their original contents. Add an original compact multi-headed hydra ASCII logo for Fastfetch, a restrained color scheme and an intentionally short useful system summary. Include Fastfetch in the Gentoo image, not on NixOS.

Delivery and validation

Work in feat/ux under .worktrees/ux. Keep the original ISO and manual test disk. Use meaningful regression tests for download failures/cache integrity, explicit launch behavior and menu/session focus. Run the existing full suite once integrated, and an isolated real graphical/VM smoke test where available. Prepare a reviewable update bundle for the already installed guest and update the image sources; rebuild/test a new ISO when feasible without a cold toolchain build. Never claim the running user guest or an old ISO already contains new code. No keystroke injection into the user's desktop or guest sessions.