From 55648c26e99a6f7813d5fda19661b44382356727 Mon Sep 17 00:00:00 2001
From: Codex <codex@localhost>
Date: Tue, 13 Oct 2026 05:35:51 +0300
Subject: [PATCH] docs: explain first-use VM workflow and host controls

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 1b09329..315fa31 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,47 @@ a refresh-rate setting does not prove delivered FPS.
 
 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; `nmtui` configures the host's network connections.
+Guest operating systems are supplied by you:
+
+```sh
+hydra add work --iso /absolute/path/ubuntu.iso --memory 8192 --cpus 4
+hydra start work
+hydra add experiments --iso /absolute/path/gentoo.iso
+hydra start experiments
+exit
+```
+
+Back at `hydra recovery>`, enter `:refresh` to show the newly created guests.
+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
+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+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
+guest controls its own services and firewall. Host Internet access is separate
+from this local guest network.
+
+Profiles live in `~/.config/hydra`, disks in `~/.local/state/hydra`; system defaults
+for new profiles are in `/etc/hydra/defaults.toml`. Use `hydra --help` for overrides.
+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.
+
 ## Run the prototype
 
 ```sh