Document the Packages tab, publishing and signing key unlock

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

2 files changed, 29 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 34c40ba..9113e34 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,14 @@ Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
 - Jobs run detached on the VM (`setsid`, `stdin=/dev/null`), one at a time
   under a flock, logging to `<state_dir>/jobs/<id>/`. The GUI can disconnect
   and reattach with `job-follow <id> <offset>`.
+- Exception, by design: `gpg-unlock` reads the signing key passphrase from
+  stdin (`remote.call(..., stdin=...)`) and feeds it to
+  `gpg-preset-passphrase`. Every other subprocess in the helper runs with
+  `stdin=DEVNULL`, so nothing can read the passphrase off the ssh channel.
+  Never put the passphrase in argv, env, logs or files.
+- Hints are parsed (`shlex`), never sourced. `sb_builder/hints.py` mirrors
+  slackrepo's own rules (`../GITHUB/slackrepo/libexec/functions.d/parsefunctions.sh`);
+  check that file when changing it.
 - Jobs never get input. Any tool run as a job must be non-interactive
   (`--yes`/`--no` style flags). If a tool needs a flag it lacks, add it in
   that tool's own repo (e.g. `slackrepo_setup` for sbshadow, `mkhintfile`
@@ -42,6 +50,12 @@ Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
 
     python3 -m unittest discover -s tests
 
+`test_gui.py` forces `QT_QPA_PLATFORM=offscreen` (the desktop session sets
+its own, and a modal dialog on the real display blocks the run). A fake
+remote must answer every call a test triggers: an unanswered call returns
+"ssh: connection failed", which opens a warning dialog that blocks forever
+offscreen.
+
 Headless (`test_gui.py` sets `QT_QPA_PLATFORM=offscreen`), no VM needed.
 `test_remote.py` loads `remote/sbb-remote` with `SourceFileLoader` (no `.py`
 extension) and points it at a temp state dir through `SBB_CONFIG`. Two
diff --git a/README.md b/README.md
index 1ff0cc7..56cb829 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,21 @@ Every key is optional. `File > Reload config` rereads the GUI config.
   preview that lists `shadow:` or `unshadow:` lines, "Apply shadowing" runs
   `sbshadow --yes`.
 
+- **Open > Packages** (or click the Packages tile): 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. The detail pane shows the
+  package's versions, its dependencies after hints (dropped ones struck
+  through), and what its hint file does, section by section.
+- Tick packages (or select one row) and press Build, Update, Rebuild or
+  Remove; Update all updates everything. Each first runs a slackrepo
+  `--preview` job. When the preview is fine, **Run it** in the Jobs tab starts
+  the real run; untick **publish** to keep the packages local and press
+  **Publish** later to push them.
+- 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.
+
 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.