Docs ready to publish: VM setup, specs in docs/designHEADmaster

README says what the GUI does today and what is planned, which defaults
are the author's setup, and how to set up the VM. The specs move to
docs/design/; the implementation plans are dropped (working files, now
kept out of git). AGENTS.md links slackrepo upstream instead of a local
clone path.

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

1 files changed, 40 insertions, 8 deletions

diff --git a/README.md b/README.md
index fb4fd05..938dbc6 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,23 @@
 # sb-builder
 
 Desktop GUI for managing a Slackware SlackBuilds build VM from one place. It
-runs slackrepo builds, overlay syncs (sbpull, sbshadow), hint file updates
-and SBo orphan discovery on the VM over ssh, as background jobs that
-keep running when the GUI disconnects and can be reattached later. A
-dashboard shows VM and repository state, and the GUI can start the VM through
-libvirt when it is off.
-
-Work in progress. See `docs/superpowers/specs/` for the design.
+runs slackrepo builds, overlay syncs (sbpull, sbshadow) and hint file updates
+on the VM over ssh, as background jobs that keep running when the GUI
+disconnects and can be reattached later. Upstream versions are checked with
+nvchecker on the desktop. A dashboard shows VM and repository state,
+including the packages SBo lists without a maintainer, and the GUI can start
+the VM through libvirt when it is off.
+
+It is built around one setup: a Slackware64-current VM building a personal
+repository with [slackrepo](https://github.com/aclemons/slackrepo), laid out
+by [slackrepo_setup](https://forge.slackware.nl/danix/slackrepo_setup) (the
+SBo tree plus overlays as git subtrees). The defaults (VM `buildsystem`,
+repository `SBo-danix`, overlays `personal` and `pentesting`) are the
+author's; every one of them is a config key. `nvchecker.toml` is the
+author's list of tracked packages.
+
+Still to come: a guarded full repository rebuild, and an SBo orphans screen.
+The design, one spec per phase, is in `docs/design/`.
 
 ## Requirements
 
@@ -16,6 +26,27 @@ Work in progress. See `docs/superpowers/specs/` for the design.
 - VM: Python 3.11 or newer, root ssh login, the
   [slackrepo_setup](https://forge.slackware.nl/danix/slackrepo_setup) tools (`sbpull`, `sbshadow`)
 
+## VM setup
+
+1. A Slackware64-current VM with Python 3.11 or newer (stock), reachable over
+   ssh as root with a key. A host alias in `~/.ssh/config` keeps the GUI config
+   short. For start and resume from the GUI, a libvirt domain on the desktop.
+2. slackrepo and slackrepo-hints (SBo) installed on the VM.
+3. The repository and its slackrepo config from
+   [slackrepo_setup](https://forge.slackware.nl/danix/slackrepo_setup): follow
+   its Install section, fill `/etc/slackrepo/SBo-danix.local`, then run
+   `slackrepo_setup_SBo-danix.sh` once to build the repository.
+4. Package signing: a gpg key in root's keyring, `/root/.genreprc` with
+   `USE_GPGAGENT=1` and `REPOSOWNERGPG=<fingerprint>` (read by slackrepo's
+   `gen_repos_files.sh`), and slackrepo_setup's `gpg-agent.conf`, which lets
+   the GUI unlock the key for jobs.
+5. `./install.sh --remote` from the desktop (below) installs the helper and
+   `/etc/sb-builder/config.toml`. For another repository, set `repo_dir`,
+   `overlays`, `slackrepo_repo`, `slackrepo_db`, `hintdir` and
+   `slackrepo_logdir` there.
+6. The phantom deps list (`/etc/sb-builder/phantom-deps`) starts empty; fill it
+   from Hints, Phantom deps.
+
 ## Install
 
     ./install.sh             # ~/bin/sb-builder and menu entry -> this repo, GUI config if missing
@@ -58,7 +89,8 @@ reopens it.
 - **Packages**: every package of the repository, with built version and
   status (`ok`, `failed`, `never`, `outdated`). Search by name or summary, or
   with `cat:`, `maint:`, `req:`, `status:`; toggle the overlay and status
-  chips, and **orphaned** for the packages SBo lists without a maintainer. The detail pane shows the package's versions, its dependencies after
+  chips, and **orphaned** for the packages SBo lists without a maintainer.
+  The detail pane shows the package's versions, its dependencies after
   hints (dropped ones struck through), what its hint file does, and a link
   to it in Hints. **Build**, **Update**, **Rebuild**, **Remove** and **Update
   all** run a slackrepo `--preview` first; **New hint** creates hints, pinned