docs: define Hydra OS terminal experience overhaul

2026-10-13 15:05:28 +03:00
parent 78cdedf220
commit 9abedf29f0
2 changed files with 167 additions and 0 deletions
@@ -0,0 +1,64 @@
+# 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.