docs: define Hydra OS terminal experience overhaul

docs/superpowers/plans/2026-10-13-terminal-ux.md

@@ -0,0 +1,103 @@
+# Hydra OS terminal experience implementation plan
+
+> **For agentic workers:** Use superpowers:subagent-driven-development. Tasks
+> are implemented in the shared feature worktree with disjoint owned files,
+> then reviewed and integrated before publication.
+
+**Goal:** Download and open VMs through a concise terminal workflow and ship
+consistent Hydra OS branding with Fastfetch.
+
+**Architecture:** Retain Runtime as the VM lifecycle authority. Add a safe ISO
+download module and explicit launch orchestration. Replace recovery's JSON
+prompt with a terminal menu and use the existing session-refresh boundary to
+focus a selected workspace without changing QEMU lifetimes.
+
+**Tech stack:** Python standard library, existing labwc/Foot/SPICE, Gentoo,
+Fastfetch. No GUI toolkit or host NixOS changes.
+
+**Spec:** `docs/superpowers/specs/2026-10-13-terminal-ux-design.md`
+
+## Global constraints
+
+- Visible product name is **Hydra OS**; preserve technical identifiers and data.
+- No NixOS configuration changes, user-disk replacement or guest input injection.
+- Opening a selected stopped VM is explicit; menu display never starts all VMs.
+- Existing CLI output and runtime ownership guarantees remain compatible.
+- Downloads publish only verified complete ISO files; SHA-256 is optional.
+- New launch preflight reserves 768 MiB of available RAM for the Hydra host.
+
+## Review focus
+
+- Concurrent downloads or interruption must not publish partial ISO files (T1).
+- Existing names/disks and unknown VM identities must not be replaced (T1).
+- Selecting a second VM must focus it and preserve other QEMU processes (T2).
+- Invalid profiles, missing ISO, absent network tools must leave a usable menu (T2).
+- Branding must not invalidate existing IDs or rewrite historical evidence (T3).
+
+## Task 1: Download and explicit launch commands
+
+Owned: `hydra/media.py`, `hydra/launch.py`, `hydra/cli.py`,
+`tests/test_media.py`, `tests/test_launch.py`, relevant new CLI tests.
+
+Interfaces:
+- `media.download_iso(url, *, sha256=None, cache=None, progress=None) -> Path`.
+  `progress(received_bytes, total_bytes_or_none)` is optional.
+- `launch.open_vm(runtime, name, *, windowed=False, no_view=False,
+  manifest=None) -> int`. For a session manifest call
+  `session.request_refresh(manifest, selected=name)` after successful launch;
+  outside a session use existing `session.view`. No GUI check for `no_view`.
+- CLI: `open NAME`, `run SOURCE --name NAME`, `download URL`; plain `hydra`
+  and `hydra menu` call `menu.run_menu(runtime, manifest=...)` lazily.
+- Manifest defaults from `HYDRA_SESSION_MANIFEST` when valid; launch errors
+  remain actionable and never silently restart an unknown/foreign VM.
+
+- [ ] Write and observe failing tests using a local HTTP fixture (ISO, HTML,
+  truncation, checksum, cancellation, cache reuse, collision).
+- [ ] Implement downloader and explicit open/run commands, preserve existing CLI.
+- [ ] Test no accidental overwrite/start, headless operation, RAM preflight and
+  view-only reconnection. Run scoped tests and commit only owned files.
+
+## Task 2: Terminal menu and focused session handoff
+
+Owned: `hydra/menu.py`, `hydra/session.py`, `tests/test_menu.py`,
+`tests/test_session.py`, relevant `dev/session-refresh-smoke.py` extensions.
+
+Interfaces:
+- `menu.run_menu(runtime, *, manifest=None) -> int`: clear readable menu,
+  numbers/names/Enter, persistent last selection, old colon commands, controlled
+  guided `run`/`download`, network and shell actions. Use Task 1's launch API.
+- `session.request_refresh(manifest: Path, *, selected=None) -> int`: backwards
+  compatible empty refresh requests, optional validated selected VM name.
+- Session env carries `HYDRA_SESSION_MANIFEST`; next compositor starts on the
+  requested configured VM. Recovery delegates to menu; automatic clients remain
+  view-only. Errors stay in menu, and operations use fresh runtime profiles.
+
+- [ ] Write failing menu/refresh tests for stopped/running selection, unknown
+  identity, names such as s/q, empty/invalid profiles and second-workspace focus.
+- [ ] Implement terminal flow, visible command previews and recovery fallback.
+- [ ] Run scoped tests plus an isolated session probe where feasible; commit
+  owned files. Existing reserved chords and VM independence remain intact.
+
+## Task 3: Hydra OS branding and Fastfetch
+
+Owned: `image/packages`, `image/rootfs` (Fastfetch config/logo/motd only),
+`hydra/image.py`, `image/grub.cfg`, `session` metadata, new branding tests.
+Coordinate session/CLI visible names with their owners; do not edit their files.
+
+- [ ] Confirm Fastfetch's Gentoo atom, supported logo/config format and search path.
+- [ ] Add original terminal logo and restrained summary configuration; retain
+  technical IDs while updating visible OS/boot/session labels.
+- [ ] Verify config with actual Fastfetch in a temporary/container environment,
+  preview logo, and test resulting image metadata. Commit owned files.
+
+## Task 4: Integration and delivery
+
+Owner: controller. README/install docs, update bundle, isolated validation.
+
+- [ ] Review each task diff with concrete test reports; resolve findings.
+- [ ] Integrate task interfaces; document terminal usage and branded name.
+- [ ] Run complete suite and isolated smoke covering run/open/menu with new code.
+- [ ] Prepare a reversible guest update with exact file inventory and checksums;
+  preserve old ISO and test disk. Assess cached image rebuild and test new output.
+- [ ] Review whole branch, commit/publish authorized repository changes and report
+  exactly which artifacts and guest states have actually been updated.

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

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