Document the Hints screen; phase 4 spec from the implementation

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

1 files changed, 10 insertions, 3 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 9113e34..9a8918c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,7 +17,8 @@ Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
 
 - Every GUI action is `ssh <target> sbb-remote <cmd> [args]`; the helper
   answers with JSON. `sb_builder/remote.py` is the only code that runs ssh
-  (and local `virsh`).
+  (and local `virsh`). `sb_builder/upstream.py` runs the local `nvchecker`
+  over the repo's `nvchecker.toml`; the VM never sees the GitHub token.
 - Trust boundary: the helper runs only a fixed table of job kinds and builds
   argv itself from validated args. Never pass shell strings or paths from the
   GUI to the helper.
@@ -32,10 +33,16 @@ Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
 - 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.
+- Hint editing lives in the helper (`hint-update`, `hint-new` jobs run the
+  helper's own `_hint` command): text edits, `.bak` before each
+  write, a final `SBB-RESULT {json}` log line read back with `job-result`.
+  It replaces mkhint, which stays on the VM for neovim and openvino
+  (bundled deps, `manifest_packages`) and for the `DELREQUIRES` hints
+  sbshadow regenerates with `mkhint -F` after every sync, until phase 4b.
 - 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`
-  for mkhint) rather than working around it here.
+  that tool's own repo (e.g. `slackrepo_setup` for sbshadow) rather than
+  working around it here.
 
 ## Conventions