Document terminal workflows and provide a backed-up guest runtime update

README.md

@@ -1,4 +1,4 @@
-# HydraOS
+# Hydra OS
 
 Gentoo-based host for concurrent virtual desktops. Its default session shows one
 VM fullscreen and switches between guests with keyboard shortcuts. Other host
@@ -31,9 +31,37 @@ Build outputs, VM disks, runtime state and credentials stay outside Git.
 ## First use
 
 Follow the [installation guide](docs/install.md) to install from the live ISO.
-The initial empty graphical session opens a recovery terminal. Enter `:shell`
-for an ordinary host shell; `sudo nmtui` configures host network connections.
-Guest operating systems are supplied by you:
+The session opens a terminal VM menu. Choose a machine by number or name;
+Enter opens the remembered selection, or the only machine. Opening a stopped
+machine starts it; opening a running one reconnects its screen. Merely opening
+the menu does not start every VM. `:shell` opens an ordinary host shell and
+`:network` opens NetworkManager's connection menu. The existing VM disks and
+command-line controls remain available.
+
+From a Hydra shell, a direct installer URL can become a running VM in one
+command. Replace the example URL with an actual ISO download link:
+
+```sh
+hydra run 'https://example.org/distribution.iso' --name work --memory 4096 --cpus 2
+hydra open work
+```
+
+`run` also accepts a local ISO path. It refuses to replace an existing VM name;
+use `open` for subsequent starts. Add `--no-view` for a headless launch. A
+download-page URL returning HTML is rejected. Downloads show progress, can be
+cancelled with Ctrl+C, and become reusable cache entries only after validation.
+Supply the publisher's SHA-256 when available:
+
+```sh
+hydra download 'https://example.org/distribution.iso' --sha256 PUBLISHER_SHA256
+```
+
+The cache lives under `$XDG_CACHE_HOME/hydra/iso` (normally
+`~/.cache/hydra/iso`). Without a publisher checksum, ISO format validation
+does not establish publisher authenticity. New launches through this workflow
+check available RAM with a 768 MiB host reserve; this cannot guarantee against
+later memory pressure. In a nested test, leave RAM available on the outer host
+too. The original lower-level commands remain useful for manual control:
 
 ```sh
 hydra add work --iso /absolute/path/ubuntu.iso --memory 8192 --cpus 4
@@ -43,7 +71,7 @@ hydra start experiments
 exit
 ```
 
-Back at `hydra recovery>`, enter `:refresh` to show the newly created guests.
+Back in the terminal menu, select the new guest to open its screen.
 Guests remain running while you switch, reconnect viewers or leave the host
 graphical session. Shut a guest down from inside its OS, or request an orderly
 shutdown with `hydra shutdown NAME`. Check `hydra status NAME` before detaching
@@ -52,14 +80,14 @@ its installer with `hydra media NAME --detach` and starting it again.
 | Shortcut | Action |
 | --- | --- |
 | Ctrl+Alt+Shift+Left / Right | Switch guest workspaces |
-| Ctrl+Alt+Shift+Escape | Open local recovery |
+| Ctrl+Alt+Shift+Escape | Open the terminal VM menu |
 | Ctrl+Alt+Shift+R | Release viewer input capture |
 | Ctrl+Alt+Shift+U | Choose a USB device to redirect |
 | Brightness keys | Adjust host backlight |
 
 New guests share `hydrabr0` (`10.203.0.0/24`) and have distinct persistent MAC
 addresses. Services can communicate between guests without per-port forwarding;
-access from your LAN requires a router route through the HydraOS host. Each
+access from your LAN requires a router route through the Hydra OS host. Each
 guest controls its own services and firewall. Host Internet access is separate
 from this local guest network.
 
@@ -69,6 +97,11 @@ Other host desktops can use `hydra start NAME` and `hydra view NAME --windowed`
 without entering the minimal labwc session. Ordinary Gentoo administration and
 Portage remain available through the recovery shell.
 
+Fastfetch displays the **Hydra OS** system summary and its custom terminal
+logo. It is included in the new image; the first published ISO predates this
+interface update. See [terminal usage](docs/terminal-usage.md) for networking,
+installation media and common recovery steps.
+
 ## Build the ISO
 
 Follow the [isolated Gentoo build instructions](image/README.md). Outputs are