pi-bro 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.29.0] - 2026-11-05
+
+### Highlights
+
+- The default Bro completion menu shows eight capability-level actions while preserving all explicit command routes.
+- `/bro config` now offers Global (default, Preferences and on-demand Doctor) and Features navigation.
+- Feature pages reuse the existing model pickers and save logic; Elevate, Grill Me and Remember Me display inherited BTW settings without new overrides.
+
 ## [0.28.0] - 2026-11-05
 
 ### Highlights

package/docs/reference/commands.md

@@ -18,6 +18,10 @@ Pressing **R** simplifies the captured source again in the mode shown, and
 new source: `/bro text`, `/bro file`, `/bro url`, and `/bro show`. Giving `/bro` a URL, path, or
 text directly captures a new source the same way.
 
+## Default command suggestions
+
+Typing `/bro ` displays eight task-level suggestions: `simplify`, `show`, `btw`, `guided-review`, `elevate`, `grill-me`, `remember-me`, and `config`. Every other documented command remains callable and discoverable by typing its prefix (e.g., `/bro doc`).
+
 ## Commands
 
 | Command | Description |
@@ -33,7 +37,7 @@ text directly captures a new source the same way.
 | `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
 | `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](settings.md#preferences). |
-| `/bro config` | Open settings for the shared backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor/review) overrides. |
+| `/bro config` | Open Global (defaults, preferences and Doctor) or Features (per-feature overrides, BTW inheritance and Advisor steering). |
 | `/bro guided-review <PR number or URL>` | Automatically explain and assess a captured PR in local Pi, with source evidence and optional private questions. Opening the same PR restores its saved review. |
 | `/bro guided-review` | List saved reviews; `resume` is an alias. |
 | `/bro remember-me [thought]` | Start a private memory-writing conversation, browse and expand memories, and approve saves explicitly. [Guide](../remember-me.md). |

package/docs/reference/settings.md

@@ -4,9 +4,7 @@
 
 ## Settings
 
-Use `/bro config` to review or change the shared default backend/model/effort
-and any per-capability (explain/show/btw/advisor/review) overrides, the explanation
-mode, and the default show turn count. Changes save immediately. Esc inside a
+Use `/bro config` for the layered Global and Features menu. Its editable pages retain the existing backend/model/effort pickers, save checks and per-capability overrides. Changes save immediately. Esc inside a
 picker cancels that pick; Esc on the settings screen closes it, keeping
 whatever was already saved. If the terminal becomes too small, config blocks
 hidden actions; Esc closes config even if a picker was open, after pending saves
@@ -15,6 +13,39 @@ alone makes config too small, any other key clears it so you can try again. `/br
 tries another mode without saving it), and `/bro help` shows the active settings
 and file path.
 
+### Config navigation
+
+```text
+/bro config
+├── Global
+│   ├── Default backend, model and effort
+│   ├── Preferences (opens the existing shared editor)
+│   └── Doctor (runs only when selected)
+└── Features
+    ├── Simplify — Explain override and default brief/balanced/faithful mode
+    ├── Show — Show override and default turn count
+    ├── BTW — backend/model/effort override
+    ├── Guided Review — Review override
+    ├── Advisor — override and persistent steering editor
+    ├── Elevate — inherits BTW (informational)
+    ├── Grill Me — inherits BTW (informational)
+    └── Remember Me — inherits BTW (informational)
+```
+
+The BTW page shows what the selected backend can do in conversation-only mode,
+and reminds users that `/mode` **inside BTW** switches to full workspace access.
+Guided Review shows its selected backend's real inspection limits: strict file
+tools on some backends, sandboxed shell on others, and Agy's ability to write
+within the captured checkout. These are explanations of existing behavior,
+not a new permission switch or an extra compatibility restriction. See
+[backend access and retention](data-and-permissions.md#backends-access-and-retention).
+
+Enter drills down. Esc backs out or closes at root; editors use their existing
+save/cancel behavior. Opening Config does **not** run Doctor, touch a model, or
+modify settings. Current selected models and overrides remain visible in the
+existing editing pages. The old `/bro doctor`, `/bro preferences` and
+`/bro advisor-steer` shortcuts remain callable.
+
 Elevate inherits the **BTW** backend/model/effort selection. There is no separate Elevate setting in this release. See the [Elevate guide](../elevate.md).
 
 Settings live in this user-editable file, created when the extension loads

package/docs/user-guide.md

@@ -167,3 +167,7 @@ See [Troubleshooting and current limits](reference/troubleshooting.md#troublesho
 ## Simplify modal
 
 `/bro` opens Simplify and explains the latest completed assistant reply. `/bro simplify` returns to the most recent Simplify screen without another model request. Inside, `/simplify`, `/text <text>`, `/file <path>` and `/url <url>` produce one explanation at a time; `/copy` copies the answer, `/clear` clears it, and `/help` shows controls. Press **M** with an empty composer to change the explanation mode and rerun; **R** retries. The saved default mode remains unchanged. The current screen is kept only within the Pi session. Old `/bro text|file|url|open` forms remain callable for compatibility.
+
+## Bro command discovery and Config navigation
+
+The default `/bro ` completion menu highlights eight tasks: `simplify`, `show`, `btw`, `guided-review`, `elevate`, `grill-me`, `remember-me`, `config`. Existing explicit commands, including `/bro doctor`, `/bro preferences`, `/bro advisor-steer`, `/bro file`, `/bro url`, `/bro text`, `/bro open` and `/bro help`, remain valid and discoverable by prefix. `/bro config` starts with **Global** (default, Preferences editor, Doctor on demand) and **Features** (five configurable capabilities and three workflows inheriting BTW). Esc goes back; existing save behavior is unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.",
   "type": "module",
   "license": "MIT",
@@ -65,6 +65,8 @@
     "src/settings.ts",
     "src/sources.ts",
     "src/config-ui.ts",
+    "src/config-navigation-ui.ts",
+    "src/config-navigation.ts",
     "src/ui-capabilities.ts",
     "src/modal-kit.ts",
     "src/backend.ts",
@@ -95,7 +97,7 @@
   "scripts": {
     "docs:check": "node scripts/check-docs.mjs && node --test test/docs-quality.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/elevate-docs.test.mjs test/elevate.test.ts test/simplify.test.ts test/simplify-modal.test.mjs test/grill.test.ts test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
+    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/elevate-docs.test.mjs test/elevate.test.ts test/simplify.test.ts test/simplify-modal.test.mjs test/grill.test.ts test/config-navigation.test.ts test/config-navigation-modal.test.mjs test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",

package/src/bro.ts

@@ -83,12 +83,17 @@ const COMMANDS = [
 	{ value: "elevate", label: "elevate", description: "Discover missing expert considerations, then improve a request" },
 	{ value: "remember-me", label: "remember-me", description: "Help write and review personal memories; agents can unfold them on demand" },
 	{ value: "grill-me", label: "grill-me", description: "A private, one-question-at-a-time decision interview" },
-	{ value: "config", label: "config", description: "Configure shared defaults and per-capability model/effort overrides" },
+	{ value: "config", label: "config", description: "Global defaults, diagnostics and feature settings" },
 	{ value: "advisor", label: "advisor", description: "Check whether the executor's advisor tool is available right now" },
 	{ value: "advisor-steer", label: "advisor-steer", description: "View, edit, save, or clear the advisor's persistent steering brief" },
 	{ value: "help", label: "help", description: "Learn what Bro does and what it can access" },
 ];
 const KNOWN_ACTIONS = new Set(COMMANDS.map((command) => command.value));
+/** Only capability-level commands appear by default; all existing commands remain discoverable by prefix. */
+export const FEATURED_BRO_COMMANDS = [
+  "simplify","show","btw","guided-review","elevate","grill-me","remember-me","config",
+] as const;
+const FEATURED_COMMANDS = new Set<string>(FEATURED_BRO_COMMANDS);
 
 export default async function bro(pi: ExtensionAPI) {
 	let lastResult: ModalResult | undefined;
@@ -119,7 +124,8 @@ export default async function bro(pi: ExtensionAPI) {
 		description: "Explain text, documents, and webpages; draw session turns; open a side conversation; configure Bro and the executor's advisor tool",
 		getArgumentCompletions: (prefix) => {
 			const normalized = prefix.trim().toLowerCase();
-			const matches = COMMANDS.filter((command) => command.value.startsWith(normalized));
+			const matches = COMMANDS.filter((command) =>
+        normalized ? command.value.startsWith(normalized) : FEATURED_COMMANDS.has(command.value));
 			return matches.length ? matches : null;
 		},
 		handler: async (args, ctx) => {

package/src/config-navigation-ui.ts

@@ -0,0 +1,110 @@
+/** Compact navigation over existing settings/editors; no separate configuration state. */
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import { SelectList, matchesKey, wrapTextWithAnsi, type SelectItem, type Component } from "@earendil-works/pi-tui";
+import { delegateMouse, modalHeight, renderFrame, type Theme, type TuiLike, type Area } from "./modal-kit.ts";
+import type { BroMouseEvent } from "./ui-capabilities.ts";
+import type { BroSettings } from "./settings.ts";
+import {
+  CONFIG_ROOT, CONFIG_GLOBAL, CONFIG_FEATURES,
+  inheritedConfigDescription,
+  type ConfigNavAction, type ConfigNavState, type ConfigNavScreen,
+} from "./config-navigation.ts";
+
+type MenuItem = {value:string;label:string};
+const rowsFor=(screen:ConfigNavScreen):readonly MenuItem[]=>{
+  if(screen==="root")return CONFIG_ROOT;
+  if(screen==="global")return CONFIG_GLOBAL;
+  if(screen==="features")return CONFIG_FEATURES;
+  if(screen==="advisor")return [
+    {value:"advisor-settings",label:"Backend, model and effort"},
+    {value:"advisor-steer",label:"Persistent advisor steering brief"},
+  ];
+  return [{value:"btw-settings",label:"Open BTW's inherited backend settings"}];
+};
+
+export function createConfigNavigationModal(
+  state:ConfigNavState,
+  settings:BroSettings,
+): (tui:TuiLike,theme:Theme,keys:unknown,done:(result:ConfigNavAction)=>void)=>Component {
+  return (tui,theme,_keys,done)=>{
+    let closed=false;
+    let list:SelectList;
+    let listArea:Area={top:0,left:0,width:0,height:0};
+    const finish=(result:ConfigNavAction)=>{if(closed)return;closed=true;done(result);};
+    const go=(screen:ConfigNavScreen)=>{
+      state.screen=screen;
+      const items=rowsFor(screen) as SelectItem[];
+      list=new SelectList(items,Math.min(items.length,Math.max(1,modalHeight(tui)-10)),getSelectListTheme());
+      list.onSelect=item=>choose(item.value);
+      list.onCancel=back;
+      tui.requestRender();
+    };
+    const back=()=>{
+      if(state.screen==="root")return finish({kind:"close"});
+      if(state.screen==="global"||state.screen==="features"){go("root");return;}
+      go("features");
+    };
+    const choose=(value:string)=>{
+      if(state.screen==="root"){go(value==="global"?"global":"features");return;}
+      if(state.screen==="global"){
+        if(value==="defaults")return finish({kind:"settings",page:"defaults"});
+        if(value==="preferences")return finish({kind:"preferences"});
+        if(value==="doctor")return finish({kind:"doctor"});
+      }
+      if(state.screen==="features"){
+        if(value==="advisor"){go("advisor");return;}
+        if(value==="elevate"||value==="grill-me"||value==="remember-me"){
+          state.inherited=value;go("inherited");return;
+        }
+        if(value==="explain"||value==="show"||value==="btw"||value==="review")return finish({kind:"settings",page:value});
+      }
+      if(state.screen==="advisor"){
+        if(value==="advisor-steer")return finish({kind:"advisor-steer"});
+        if(value==="advisor-settings")return finish({kind:"settings",page:"advisor"});
+      }
+      if(state.screen==="inherited"&&value==="btw-settings"){
+        state.screen="features";return finish({kind:"settings",page:"btw"});
+      }
+    };
+    go(state.screen);
+    const title=()=>{
+      const s=state.screen;
+      return s==="root"?"Bro · config":
+        s==="global"?"Bro · config / Global":
+        s==="features"?"Bro · config / Features":
+        s==="advisor"?"Bro · config / Features / Advisor":
+        "Bro · config / Features / "+(state.inherited??"Inherited");
+    };
+    const subtitle=()=>{
+      if(state.screen==="root")return "Choose Global or Features. Enter drill down · Esc close.";
+      if(state.screen==="global")return "Defaults are shared. Doctor runs only when selected.";
+      if(state.screen==="features")return "Feature model overrides are optional; inherited features use BTW.";
+      if(state.screen==="advisor")return "Steering keeps its own file; changing models does not change steering.";
+      if(state.inherited)return inheritedConfigDescription(settings,state.inherited);
+      return "Inherits BTW";
+    };
+    return {
+      render:(width:number)=>{
+        const h=modalHeight(tui),w=Math.max(1,width-2),lines=list.render(w);
+        // Derive mouse hit area from the same subtitle lines we render, including long
+        // inherited-backend descriptions and narrow-terminal layouts.
+        const subtitleLines=wrapTextWithAnsi(theme.fg("dim",subtitle()),w).slice(0,Math.max(0,h-5-lines.length));
+        listArea={top:3+subtitleLines.length,left:1,width:w,height:Math.max(0,Math.min(lines.length,h-5-subtitleLines.length))};
+        return renderFrame(theme,width,h,{
+          header:()=>theme.fg("accent",theme.bold(title())),
+          body:()=>[...subtitleLines,...lines],
+          hints:"↑/↓ select · Enter open · Esc back",
+          fill:false,
+          minBody:Math.max(1,lines.length),
+        });
+      },
+      invalidate:()=>list.invalidate(),
+      handleMouse:(event:BroMouseEvent)=>delegateMouse(list,event,listArea),
+      handleInput:(data:string)=>{
+        if(matchesKey(data,"escape")){back();return;}
+        list.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  };
+}

package/src/config-navigation.ts

@@ -0,0 +1,74 @@
+/** Navigation taxonomy only. Existing config storage remains in settings.ts. */
+import type { BroSettings, Capability } from "./settings.ts";
+import { capabilityBackend, capabilityOverride, capabilityPair } from "./settings.ts";
+import { reviewBackendNotice } from "./backend.ts";
+
+export type ConfigSettingsPage = "defaults" | Capability;
+export type ConfigNavScreen = "root" | "global" | "features" | "advisor" | "inherited";
+export type ConfigNavState = { screen: ConfigNavScreen; inherited?: "elevate"|"grill-me"|"remember-me" };
+export type ConfigNavAction =
+  | {kind:"settings";page:ConfigSettingsPage}
+  | {kind:"preferences"|"doctor"|"advisor-steer"|"close"};
+
+export const CONFIG_ROOT = [
+  {value:"global",label:"Global — shared defaults, preferences and Doctor"},
+  {value:"features",label:"Features — specific settings and inherited behavior"},
+] as const;
+export const CONFIG_GLOBAL = [
+  {value:"defaults",label:"Default backend, model and effort"},
+  {value:"preferences",label:"Preferences — shared response style"},
+  {value:"doctor",label:"Doctor — run setup and model diagnostics"},
+] as const;
+export const CONFIG_FEATURES = [
+  {value:"explain",label:"Simplify — Explain override and default mode"},
+  {value:"show",label:"Show — backend override and default turn count"},
+  {value:"btw",label:"BTW — backend override; conversation/full access"},
+  {value:"review",label:"Guided Review — override and inspection limits"},
+  {value:"advisor",label:"Advisor — backend override and steering"},
+  {value:"elevate",label:"Elevate — inherits BTW"},
+  {value:"grill-me",label:"Grill Me — inherits BTW"},
+  {value:"remember-me",label:"Remember Me — inherits BTW"},
+] as const;
+
+export function effectiveConfigLabel(settings:BroSettings, capability:Capability):string {
+  const p=capabilityPair(settings,capability);
+  const source=capabilityOverride(settings,capability)?"override":"global default";
+  return (capabilityBackend(settings,capability))+" / "+p.model+" / "+p.effort+" ("+source+")";
+}
+
+export function inheritedConfigDescription(settings:BroSettings, feature:"elevate"|"grill-me"|"remember-me"):string {
+  const purpose=feature==="elevate"?"Improve a request":feature==="grill-me"?"Private decision interview":"Personal memory writing";
+  return purpose+". This workflow inherits BTW's configured backend, model and effort: "+
+    effectiveConfigLabel(settings,"btw")+
+    ". No separate override exists. Use Features > BTW to change the inherited selection.";
+}
+
+
+/**
+ * Show the selected backend's actual access boundary at the point of configuration.
+ * Informational only: does not alter backend invocation, tools or permissions.
+ * Matched to the existing backend adapter flags and reference/data-and-permissions.md.
+ */
+export function configFeatureAccessNote(settings: BroSettings, feature: "btw" | "review"): string {
+  const backend = capabilityBackend(settings,feature);
+  if(feature==="btw") {
+    const notes: Record<typeof backend,string> = {
+      agy:"Agy's conversation-only path uses a temporary directory and sandboxed shell; the sandbox is not a no-write guarantee.",
+      claude:"Claude disables tools in conversation-only mode.",
+      grok:"Grok's conversation-only limit is prompt guidance only: its sandbox stays off and permissions are bypassed.",
+      codex:"Codex allows workspace reads and sandboxed commands under its read-only sandbox; it is not tool-free.",
+      muse:"Muse disables shell, write and approvals in conversation-only mode, but other tools can remain available.",
+      pi:"Pi's conversation-only session has no tools, extensions or context files.",
+    };
+    return "BTW: /mode in the BTW modal toggles conversation-only and full workspace access; full mode bypasses backend permission checks. "+notes[backend];
+  }
+  const existing=reviewBackendNotice(backend);
+  if(existing)return existing;
+  const strict: Record<"claude"|"muse"|"pi",string>={
+    claude:"Claude uses Read/Grep/Glob file-inspection tools only in the captured checkout; no shell.",
+    muse:"Muse disables shell, writes and web access in the captured checkout; reads remain available.",
+    pi:"Pi permits only read/grep/find/ls in the captured checkout; no shell or workspace writes.",
+  };
+  return "Guided Review: "+strict[backend as keyof typeof strict]+
+    " PR content remains untrusted evidence; backend restrictions do not prove the review's conclusions.";
+}

package/src/config-ui.ts

@@ -6,6 +6,7 @@ import {
 	SelectList,
 	SettingsList,
 	matchesKey,
+	wrapTextWithAnsi,
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
@@ -31,6 +32,7 @@ import {
 	withCapabilityOverride,
 } from "./settings.ts";
 import { BRO_MODES, parseBroMode } from "./prompt.ts";
+import { type ConfigSettingsPage, effectiveConfigLabel, configFeatureAccessNote } from "./config-navigation.ts";
 import { delegateMouse, formatNotice, modalHeight, renderFrame, type Area, type Theme, type TuiLike } from "./modal-kit.ts";
 import type { BroMouseEvent } from "./ui-capabilities.ts";
 import { errorMessage } from "./util.ts";
@@ -64,6 +66,7 @@ export function createConfigModal(
 	families: AgyModelFamily[],
 	persistSettings: (settings: BroSettings) => Promise<void>,
 	piModels: PiModelChoice[] = [],
+	page: ConfigSettingsPage | "all" = "all",
 ): (tui: TuiLike, theme: Theme, keybindings: unknown, done: (value?: void) => void) => Component & { dispose?(): void } {
 	return (tui, theme, _keybindings, done) => {
 		// Size the host list once, then stop interaction if a later resize cannot show the whole
@@ -294,13 +297,15 @@ export function createConfigModal(
 		}
 		refresh();
 
-		const items: SettingItem[] = [
-			modelItem,
-			effortItem,
-			modeItem,
-			showTurnsItem,
-			...CAPABILITIES.flatMap((capability) => [capabilityItems[capability].model, capabilityItems[capability].effort]),
-		];
+		// The existing pickers and save queue remain unchanged. Pages differ only in rows.
+		const items: SettingItem[] = page === "all"
+			? [modelItem, effortItem, modeItem, showTurnsItem, ...CAPABILITIES.flatMap((capability) => [capabilityItems[capability].model, capabilityItems[capability].effort])]
+			: page === "defaults"
+				? [modelItem, effortItem]
+				: [capabilityItems[page].model, capabilityItems[page].effort,
+					...(page === "explain" ? [modeItem] : []),
+					...(page === "show" ? [showTurnsItem] : []),
+				];
 
 		let notice = "";
 		let interactive = true;
@@ -414,27 +419,32 @@ export function createConfigModal(
 				const height = modalHeight(tui);
 				const innerWidth = Math.max(1, width - 2);
 				const list = settingsList.render(innerWidth);
+				// An access boundary must be visible whenever BTW/Review permissions are editable.
+				// If the terminal cannot show it alongside the controls, refuse blind edits.
+				const accessNote = page === "btw" || page === "review"
+					? wrapTextWithAnsi(theme.fg("warning", configFeatureAccessNote(settings, page)), innerWidth)
+					: [];
 				// renderFrame shrinks a notice to one line before taking minBody rows.
-				interactive = list.length <= Math.max(0, height - 5 - (notice ? 1 : 0));
+				interactive = list.length + accessNote.length <= Math.max(0, height - 5 - (notice ? 1 : 0));
 				return renderFrame(theme, width, height, {
 					header: () => theme.fg(
 						interactive ? "accent" : "warning",
-						theme.bold(interactive ? "Bro · config" : "Bro · config · enlarge terminal"),
+						theme.bold(interactive ? "Bro · config · " + (page === "all" ? "All" : page === "defaults" ? "Global defaults" : CAPABILITY_LABELS[page]) : "Bro · config · enlarge terminal"),
 					),
 					body: (rows) => {
 						if (!interactive) return [theme.fg("warning", "Enlarge the terminal to configure settings safely.")];
 						// The subtitle gives way before SettingsList's selection, scroll state and key hints.
-						const subtitle = rows > list.length
-							? [truncateToWidth(theme.fg("dim", "Shared defaults, with optional overrides per capability"), innerWidth)]
+						const subtitle = rows > list.length + accessNote.length
+							? [truncateToWidth(theme.fg("dim", page === "all" ? "Shared defaults, with optional overrides per capability" : page === "defaults" ? "Shared default selection" : "Effective: " + effectiveConfigLabel(settings, page)), innerWidth)]
 							: [];
-						// Clicks only reach list rows that were actually drawn.
-						listArea = { top: 3 + subtitle.length, left: 1, width: innerWidth, height: Math.min(list.length, rows - subtitle.length) };
-						return [...subtitle, ...list];
+						// Access notes always remain above the editable list, including after backend changes.
+						listArea = { top: 3 + subtitle.length + accessNote.length, left: 1, width: innerWidth, height: Math.min(list.length, rows - subtitle.length - accessNote.length) };
+						return [...subtitle, ...accessNote, ...list];
 					},
 					notice,
 					hints: interactive ? undefined : "Esc close",
 					fill: false,
-					minBody: interactive ? list.length : 1,
+					minBody: interactive ? list.length + accessNote.length : 1,
 				});
 			},
 			invalidate: () => settingsList.invalidate(),

package/src/doctor.ts

@@ -18,6 +18,9 @@ import {
 } from "./advisor.ts";
 import { agyFailureMessage, bridgePiRuntimeForCatalog, piEffectiveEffort, reviewBackendNotice, splitPiModel } from "./backend.ts";
 import { createConfigModal } from "./config-ui.ts";
+import { createConfigNavigationModal } from "./config-navigation-ui.ts";
+import { type ConfigNavAction, type ConfigNavState } from "./config-navigation.ts";
+import { showBroModal, showPreferencesModal, showAdvisorSteerModal } from "./explain-modal.ts";
 import { openBroOverlay } from "./modal-kit.ts";
 import {
 	type AgyEffort,
@@ -642,36 +645,60 @@ export async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContex
 	}`;
 }
 
+/** Global/Features navigation over the existing settings modal and editor contracts. */
 export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
 	if (!hasBroCustomUi(ctx)) {
 		ctx.ui.notify("Use /bro config in Pi's interactive UI.", "warning");
 		return;
 	}
-	let settings: BroSettings;
-	try {
-		settings = await readSettings();
-	} catch (error) {
-		ctx.ui.notify(withDoctor(error), "error");
-		return;
-	}
-	// Keep configuration repair accessible even when the Agy catalog is unavailable.
-	let families: AgyModelFamily[];
-	try {
-		families = await listAgyModels(pi);
-	} catch {
-		families = [];
-		ctx.ui.notify("Agy model catalog unavailable — showing other backend settings without Agy choices.", "warning");
-	}
-	// The Pi catalog is loaded independently so /bro config still works when Agy is offline.
-	let piModels: PiModelChoice[] = [];
-	try {
-		const catalog = await listPiModels(ctx);
-		piModels = catalog.models;
-		// A configured scope that resolves to nothing leaves the Pi model list empty; say why instead of
-		// showing a silently empty picker.
-		for (const diagnostic of catalog.diagnostics) ctx.ui.notify(`Pi scoped models: ${diagnostic}`, "warning");
-	} catch (error) {
-		ctx.ui.notify(`Pi model catalog unavailable — Pi choices will be empty. ${errorMessage(error)}`, "warning");
+	const navigation: ConfigNavState = {screen:"root"};
+	for (;;) {
+		// Even invalid settings must not prevent access to Doctor. The placeholder is navigation-only:
+		// every editable page re-reads the actual settings and refuses to edit on failure.
+		let current: BroSettings;
+		try { current = await readSettings(); }
+		catch (error) {
+			ctx.ui.notify("Settings unavailable: "+errorMessage(error)+". Global > Doctor can diagnose.", "warning");
+			current = { backend:"agy",model:"(unavailable)",effort:"default",mode:"balanced",showTurns:1,overrides:{} };
+		}
+		const selected = await openBroOverlay<ConfigNavAction>(
+			ctx, createConfigNavigationModal(navigation,current), {mouse:true}
+		);
+		if (!selected || selected.kind === "close") return;
+		if (selected.kind === "preferences") {
+			await showPreferencesModal(ctx);
+			continue;
+		}
+		if (selected.kind === "advisor-steer") {
+			await showAdvisorSteerModal(ctx,pi);
+			continue;
+		}
+		if (selected.kind === "doctor") {
+			await showBroModal(ctx,{
+				loadingText:"Checking Bro setup…",
+				retryable:true,
+				retryLabel:"check again",
+				run:async(signal)=>({text:await doctorReport(pi,ctx,signal)}),
+			});
+			continue;
+		}
+		if (selected.kind !== "settings") continue;
+		// Catalog discovery is needed only when an editable settings page is opened, not on
+		// every navigation or diagnostic visit. Keep independent Agy/Pi failure handling.
+		let settings:BroSettings;
+		try { settings = await readSettings(); }
+		catch (error) { ctx.ui.notify(withDoctor(error),"error"); continue; }
+		let families:AgyModelFamily[]=[];
+		try { families=await listAgyModels(pi); }
+		catch { ctx.ui.notify("Agy catalog unavailable — other backends remain configurable.","warning"); }
+		let piModels:PiModelChoice[]=[];
+		try {
+			const catalog=await listPiModels(ctx);
+			piModels=catalog.models;
+			for(const diagnostic of catalog.diagnostics) ctx.ui.notify("Pi scoped models: "+diagnostic,"warning");
+		} catch(error) { ctx.ui.notify("Pi catalog unavailable: "+errorMessage(error),"warning"); }
+		await openBroOverlay<void>(
+			ctx,createConfigModal(settings,families,writeSettings,piModels,selected.page),{mouse:true}
+		);
 	}
-	await openBroOverlay<void>(ctx, createConfigModal(settings, families, writeSettings, piModels));
 }

package/src/explain-modal.ts

@@ -425,7 +425,7 @@ Quick reference. Full user guide: https://github.com/tranhoangnguyen03/pi-bro/bl
 ## Configure and check
 
 - \`/bro preferences\` — tell Bro about yourself and how you like answers; added to explain, show, btw, Elevate and Guided Review prompts, never the advisor (**Ctrl+S** save, **Ctrl+K** delete, **Ctrl+C** copy, **Esc** close)
-- \`/bro config\` — shared default and per-capability (explain/show/btw/advisor/review) backend, model, and effort; explain mode; show turns. Two steps: choose the backend (Agy, Claude, Grok, Codex, Muse, Pi), then its model; Esc steps back without saving. Changes save immediately. If the terminal is too small, Esc closes config after pending saves finish; a failed save keeps it open.
+- \`/bro config\` — Global (shared defaults, preferences, Doctor) and Features (Simplify, Show, BTW, Review, Advisor and BTW-inherited workflows). The same model pickers, safe saves and error handling remain; Esc backs out.
 - \`/bro mode [brief|balanced|faithful]\` — view or choose the explanation mode
 - \`/bro doctor\` — check settings, preferences, and every selected backend without running a model turn