# 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.