UI guidelines in AGENTS.md; README for the new frame

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

4 files changed, 72 insertions, 40 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 9a8918c..f55d952 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,6 +44,27 @@ Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
   that tool's own repo (e.g. `slackrepo_setup` for sbshadow) rather than
   working around it here.
 
+## UI guidelines
+
+Every tab follows these (design: `docs/superpowers/specs/2026-10-20-sb-builder-ui-design.md`).
+
+1. Tabs are permanent and load their data lazily on first show (`loaded`,
+   `reload()`); the ribbon never opens or closes tabs.
+2. Main ribbon: the tab's actions (`tab.actions`) in workflow order. Small
+   ribbon: view controls (`tab.view_actions`). Build them with
+   `sb_builder/ui.py` `action()`. Nothing actionable lives inside a view
+   except navigation links.
+3. Change actions act on ticked rows, view actions on the highlighted row. A
+   row click toggles its tick; Ctrl+A / Ctrl+Shift+A select visible / clear.
+4. An inapplicable action is disabled with `ui.enable(action, reason)`, the
+   reason in its tooltip; never hidden.
+5. When a job this session started ends, its next step opens as a non-modal
+   dialog where the user is (`MainWindow.mine`, `NextStep`,
+   `HintResultDialog`); starting a job never switches tab; the Jobs tab shows
+   activity; a dismissed step can be taken again from the ribbon.
+6. A modal confirm only for destructive or outward steps (delete hint,
+   publish, apply shadowing).
+
 ## Conventions
 
 - GUI config: `$XDG_CONFIG_HOME/sb-builder/config.toml`. Helper config:
diff --git a/README.md b/README.md
index 366b740..ccf5edd 100644
--- a/README.md
+++ b/README.md
@@ -33,45 +33,54 @@ Every key is optional. `File > Reload config` rereads the GUI config.
 
     sb-builder
 
+The window has five tabs, always open: Dashboard, Packages, Hints, Results,
+Jobs (Ctrl+PgUp/PgDn cycle them). The ribbon at the top holds the current
+tab's actions, in the order a task uses them; the smaller bar under it holds
+its view controls (select, clear, refresh). An action that does not apply is
+greyed out, its tooltip says why. Actions act on the **ticked** rows: a click
+anywhere on a row ticks or unticks it, Ctrl+A ticks every visible row,
+Ctrl+Shift+A unticks all.
+
+Starting a job keeps you where you are; the Jobs tab shows "(running)" and
+then the end status. When a job you started ends, its next step comes to you
+as a dialog: after a preview, its log with **Run it** (and a **publish** box);
+after a hint change, the diff with **Revert** and **Build these**. **Not
+now** loses nothing: **Run it** in the Jobs tab, on a finished preview,
+reopens it.
+
 - **Dashboard**: VM load, uptime and free disk, package counts, slackrepo
   build results, last overlay pull, recent jobs. Refreshes while visible.
-- **Open > Jobs**: start a job from the Start menu (`sbpull <overlay>`
-  preview, `sbshadow` preview or apply), follow its log live, kill it. After a
-  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. Ctrl+A ticks every visible
-  package, Ctrl+Shift+A unticks all (here and in Hints). 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 and press Build, Update, Rebuild or Remove (they act on the
-  ticked packages only); 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.
-- **Results** (ribbon, or click a result in the Dashboard's slackrepo bar or
-  legend): slackrepo's last build attempt per package, newest first, filterable
-  by result. **Show build log** (or double-click) opens the end of the log of
-  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** removes the ticked
-  packages' hints, each kept as a `.bak`. The Packages detail pane has **New hint** for a package
-  without one.
-- After a hint job or a delete 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.
+  The tiles open Packages, Results (one result kind) and Jobs.
+- **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. 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
+  at the `.info` version, for the ticked packages without one; **Publish**
+  pushes the package repository (untick **publish** at Run it to hold a run
+  back and publish later).
+- **Hints**: 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; with
+  **No download** on, `DOWNLOAD="no"` instead; a hint sbshadow wrote,
+  `DELREQUIRES` only, gets the `.info` version lines added). **Delete hint**
+  removes the ticked packages' hints, each kept as a `.bak`, revertable from
+  the dialog that follows. neovim and openvino are refused for now: their
+  bundled deps still need mkhint on the VM.
+- **Results**: slackrepo's last build attempt per package, newest first,
+  filterable by result. **Show build log** (or double-click) opens the end of
+  the log of 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).
+- **Jobs**: every job with its live log. **Pull overlay** (`sbpull <overlay>`)
+  and **Check shadowing** (`sbshadow`) run as previews; when one finds
+  `shadow:` or `unshadow:` lines, its dialog offers **Apply shadowing**.
+  **Kill** stops the selected running job.
 - 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.
diff --git a/docs/superpowers/specs/2026-10-20-sb-builder-phase4-design.md b/docs/superpowers/specs/2026-10-20-sb-builder-phase4-design.md
index 775b0c4..b746044 100644
--- a/docs/superpowers/specs/2026-10-20-sb-builder-phase4-design.md
+++ b/docs/superpowers/specs/2026-10-20-sb-builder-phase4-design.md
@@ -136,7 +136,8 @@ New key `manifest_packages` (below). `remote/config.example.toml` shows it.
   built as `hint-new` does. The last log line is
   `SBB-RESULT {"ok": [pkg...], "failed": [[pkg, why]...]}`. Exit status 1
   when any package failed.
-- `hint-new <pkg> [<ver>] [--no-dl]`: refuses when the hint exists. Builds
+- `hint-new <pkg> [<ver>] [--no-dl]` (since 0.6.0 `hint-new <pkg>... [--no-dl]`,
+  no version, see the UI design): refuses when the hint exists. Builds
   the hint from the `.info` as mkhint does, without phantom deps (see the
   facts), then applies the version when given. No `.bak` (a stale
   one is removed); revert means delete.
diff --git a/docs/superpowers/specs/2026-10-20-sb-builder-ui-design.md b/docs/superpowers/specs/2026-10-20-sb-builder-ui-design.md
index 7c7b254..8a6844d 100644
--- a/docs/superpowers/specs/2026-10-20-sb-builder-ui-design.md
+++ b/docs/superpowers/specs/2026-10-20-sb-builder-ui-design.md
@@ -70,7 +70,7 @@ Disabled reasons (tooltips):
 - Delete hint: "none of the ticked packages has a hint".
 - Show build log: "select a result with a log".
 - Run it: "select a finished preview".
-- Kill: "no job running".
+- Kill: "select a running job".
 - Check upstream while running: "checking…".
 
 Update all, Publish, Pull overlay and Check shadowing are always enabled
@@ -120,7 +120,8 @@ dialog, Build these -> preview dialog, Run it. No tab switch.
 
 - Starting a job no longer switches to Jobs; the user stays on the tab.
 - While a job runs, the Jobs tab shows a running icon (`system-run`) and
-  accent-colored text (palette highlight).
+  reads "Jobs (running)": the tab style sheet's text color would override a
+  per-tab color.
 - When it ends, the icon becomes the end status (`✔` ok, `✘` failed,
   killed, lost) and stays until the Jobs tab is shown, then clears.
 - The status bar job button stays.