Document the Hints screen; phase 4 spec from the implementation

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

1 files changed, 16 insertions, 4 deletions

diff --git a/README.md b/README.md
index e6434c9..e1f93cc 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # sb-builder
 
 Desktop GUI for managing a Slackware SlackBuilds build VM from one place. It
-runs slackrepo builds, overlay syncs (sbpull, sbshadow), hintfile work
-(mkhint) and SBo orphan discovery on the VM over ssh, as background jobs that
+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.
@@ -12,10 +12,9 @@ Work in progress. See `docs/superpowers/specs/` for the design.
 ## Requirements
 
 - Desktop: Python 3.11 or newer, PyQt6 (with QtDBus), ssh access to the VM,
-  optionally `virsh` for starting the VM
+  optionally `virsh` for starting the VM and `nvchecker` for upstream checks
 - 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
 
@@ -58,6 +57,19 @@ Every key is optional. `File > Reload config` rereads the GUI config.
   the package's last attempt (slackrepo keeps one per command: `build.log`,
   `update.log`, `rebuild.log`, `remove.log`), where it reports the failure,
   with its `resource.log` (load, memory, tmp over the build).
+- **Hints** (ribbon): every package with a hint or an nvchecker stanza, with
+  hint, `.info` and upstream version. **Check upstream** runs nvchecker on the
+  desktop over `nvchecker.toml` in this repo (stanza name = package name, edit
+  it by hand to track a package; `hints.nvchecker_keyfile` gives it a GitHub
+  token) and ticks the outdated packages. **Update selected** rewrites their
+  hints on the VM (version, URLs, md5 of the downloaded source; **no download**
+  writes `DOWNLOAD="no"` instead; a hint sbshadow wrote, `DELREQUIRES` only,
+  gets the `.info` version lines added). **Delete hint** keeps a `.bak`. The Packages detail pane has **New hint** for a package
+  without one.
+- After a hint job a dialog shows the diff of each changed hint, with
+  **Revert** per package and **Build these** (a slackrepo update preview).
+  neovim and openvino are refused for now: their bundled deps still need
+  mkhint on the VM.
 - Real runs sign the repository. When the package signing key is locked
   (status bar 🔒), the GUI asks for its passphrase first and hands it to the
   VM's gpg-agent; it is never stored.