Document the Packages tab, publishing and signing key unlock

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

1 files changed, 14 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