Add launcher, install script and usage docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 37 insertions, 2 deletions

diff --git a/README.md b/README.md
index 5f98567..1ff0cc7 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,43 @@ Work in progress. See `docs/superpowers/specs/` for the design.
 
 ## Requirements
 
-- Desktop: Python 3, PyQt6, ssh access to the VM, optionally `virsh`
-- VM: Python 3.11 or newer, the slackrepo_setup and mkhint tools
+- Desktop: Python 3.11 or newer, PyQt6 (with QtDBus), ssh access to the VM,
+  optionally `virsh` for starting the VM
+- VM: Python 3.11 or newer, root ssh login, the
+  [slackrepo_setup](https://forge.slackware.nl/danix/slackrepo_setup) tools (`sbpull`, `sbshadow`)
+  and mkhint
+
+## Install
+
+    ./install.sh             # ~/bin/sb-builder -> this repo, GUI config if missing
+    ./install.sh --remote    # helper to the VM, its config if missing (asks first)
+
+`BINDIR` changes the launcher directory, `SBB_TARGET` the ssh destination for
+`--remote` (default `buildsystem`). Configs:
+
+- GUI: `~/.config/sb-builder/config.toml`, see `config.example.toml`
+- VM: `/etc/sb-builder/config.toml`, see `remote/config.example.toml`
+
+Every key is optional. `File > Reload config` rereads the GUI config.
+
+## Usage
+
+    sb-builder
+
+- **Dashboard**: VM load, uptime and free disk, package counts, slackrepo
+  build results, last overlay pull, recent jobs. Refreshes while visible.
+- **Open > Jobs**: start a job from the Start menu (`sbpull <overlay>`
+  preview, `sbshadow` preview or apply), follow its log live, kill it. After a
+  preview that lists `shadow:` or `unshadow:` lines, "Apply shadowing" runs
+  `sbshadow --yes`.
+
+Jobs run on the VM detached from the ssh session, one at a time. Closing the
+GUI or losing the connection does not stop them; reopening the job resumes
+the log. Job state and logs live in `/var/lib/sb-builder/jobs/` on the VM.
+
+When ssh fails and `vm.domain` is set, the status bar shows the libvirt state
+of the VM and offers to start or resume it. Desktop notifications report
+finished, failed, killed and lost jobs, and the VM coming up.
 
 ## License