pi-bro 0.28.0 → 0.30.0

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"||value==="architecture"){
+          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,75 @@
+/** 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"|"architecture" };
+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"},
+  {value:"architecture",label:"Architecture Docs — 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"|"architecture"):string {
+  const purpose=feature==="architecture"?"Repository architecture documentation":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

@@ -393,6 +393,10 @@ Quick reference. Full user guide: https://github.com/tranhoangnguyen03/pi-bro/bl
 - Inside Simplify: \`/simplify\`, \`/text <text>\`, \`/file <path>\`, \`/url <url>\`, \`/copy\`, \`/clear\`, \`/help\`. **M** changes the mode and re-explains; **R** retries. One source at a time, no chat thread.\n- \`/bro open\` — legacy last-result view (retained for compatibility)
 - \`/bro show [n-turns] [query]\` — draw recent turns' conversation text as shapes; an optional query steers the focus
 
+## Architecture documentation
+
+- \`/bro architecture [focus]\` — inspect this project and create or refresh \`docs/architecture/\` (Markdown, diagrams and a self-contained HTML map). Inherits the BTW model selection. See docs/features/architecture.md.
+
 ## Guided Review
 
 - \`/bro guided-review <PR number or URL>\` — automatically explain and assess a PR with captured code and optional private questions (local Pi interactive only; Git and authenticated gh required).
@@ -425,7 +429,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