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

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

1 files changed, 21 insertions, 0 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: