pi-better-model-select 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.5
+
+### Added
+
+- Include the subtle-highlight Better Model Select icon in the npm package and display it at the top of the README.
+- Set the Pi package gallery preview image to the packaged icon.
+- Preserve the original icon design sheet in docs/design as a repository-only reference.
+
+## 0.3.4
+
+### Fixed
+
+- Streamline Ctrl+O into a BMS navigation menu with Models, Add model, Defaults, and Options. Keep Ctrl+A visible on model search and add Ctrl+E for model effort.
+- Share the startup-default form between Ctrl+D and Defaults, with explicit Apply now. Separate model capabilities from preferred effort and group agent roles under Defaults.
+- Separate packaged user documentation in docs/public from internal development and menu-design documents in docs/internal.
+- Save Ctrl+D effort choices per model without changing the global fallback or other model preferences. Configure fallback effort in BMS Defaults instead, in user or trusted-project scope.
+- Replace status text with separate DEFAULT and CURRENT checkmark columns.
+- Show an EFFORT column for every search result before loading, using saved preferences or the session fallback. Non-reasoning models show off.
+- Apply saved model effort preferences immediately when loading through BMS, without relying on Pi's cached settings or requiring a reload. Trusted project preferences still take priority.
+- Update the smoke test for the save notification's settings path.
+
 ## 0.3.3
 
 ### Fixed

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://cdn.jsdelivr.net/npm/pi-better-model-select@latest/icon.svg" alt="Better Model Select icon" width="96" height="96">
+
 # pi-better-model-select
 
 A searchable model picker for [Pi](https://pi.dev). Switch models, edit model definitions, and save default models and thinking effort. Models you pick most often appear first.
@@ -12,9 +14,9 @@ Run `/bms`, type to filter by name, model ID, or provider, then press Enter to s
 
 ## Compact TUI
 
-![BMS model search, forms, defaults, and result placement](https://cdn.jsdelivr.net/npm/pi-better-model-select@0.3.1/docs/demo/showcase.gif)
+![BMS model search, forms, defaults, and result placement](https://cdn.jsdelivr.net/npm/pi-better-model-select@latest/docs/demo/showcase.gif)
 
-The picker uses aligned model, provider, context, usage, and status columns. Type in the search field in Pi's editor area. Results appear below search by default, matching Pi command completion. Choose **Options → Result placement → Above prompt** for bottom-up results with the best match nearest the search line.
+The picker uses aligned model, provider, effort, context, usage, default, and current columns. Type in the search field in Pi's editor area. Results appear below search by default, matching Pi command completion. Choose **Options → Result placement → Above prompt** for bottom-up results with the best match nearest the search line.
 
 Add and edit use one form. Review the fields, press Enter to change a value, then choose **Save configuration** or press Ctrl+S to save. Text and numeric fields currently open a Pi input dialog; choices use the compact table. Esc goes back; unsaved changes require a discard confirmation. Options also stay in a draft until saved.
 
@@ -33,26 +35,28 @@ Inside `/bms`:
 | --- | --- |
 | ↑ / ↓ | Move through models |
 | Enter | Use the selected model for this session |
-| Ctrl+D | Choose effort, save as the Pi default, and use it now |
+| Ctrl+D | Open startup-default form for the highlighted model |
+| Ctrl+E | Edit the highlighted model's effort preference |
 | Ctrl+G | Open the defaults menu |
 | Ctrl+A / Ctrl+U / Ctrl+X | Add / update / delete a model |
-| Ctrl+O | Open actions, including options and defaults |
+| Ctrl+O | Open BMS menu: Models, Add model, Defaults, Options |
 | Ctrl+R | Reset usage ranking |
 | Esc | Close |
 
-The status column identifies the active model and saved default. Only Enter selections count toward usage ranking. Returning from a submenu preserves your search and selection. Plain menus always browse top-to-bottom; only searchable result lists reverse in above-prompt mode. Esc goes back one level, including back to Actions when that is where you entered a submenu.
+The DEFAULT and CURRENT columns use checkmarks to identify the saved startup default and active session model. The row highlight shows the model you are browsing. The EFFORT column shows the effort each model will use when loaded, using its saved preference or the current session level as a fallback. Non-reasoning models show `off`. Pi may clamp unsupported effort levels. Only Enter selections count toward usage ranking. Returning from a submenu preserves your search and selection. Plain menus always browse top-to-bottom; only searchable result lists reverse in above-prompt mode. Esc goes back one level, including back to the BMS menu when that is where you entered a submenu.
 
 ## Default models and effort
 
 Save a model and thinking effort for Pi, a subagent fallback, or an individual agent role.
 
-- Use Ctrl+D in `/bms` for the main Pi default.
+- Use Ctrl+D in `/bms` to set the main Pi default and save effort for that model only. Other models' preferences and the global fallback stay unchanged.
+- Configure the user-wide fallback effort in `/bms-defaults` → Pi fallback effort. Per-model preferences take priority.
 - Use `/bms-defaults` for all defaults. The menu starts in user scope; select the scope row to switch to a trusted project's settings.
 - Agent model and effort overrides are independent. You can inherit the parent model while choosing a different effort.
 
 Removing an override restores the agent's own definition and fallback rules. Effort `off` is explicit, not inheritance. The menu shows saved settings and their sources, not running-child state.
 
-Run `/reload` after changing agent defaults or per-model effort preferences. Existing children stay unchanged. Test Pi startup defaults in a fresh session, since resumed sessions restore their recorded model and effort.
+BMS applies saved per-model effort preferences when you load a model, without `/reload`. Run `/reload` after changing agent defaults or before using updated per-model preferences through Pi's own model picker. Existing children stay unchanged. Test Pi startup defaults in a fresh session, since resumed sessions restore their recorded model and effort.
 
 ### Optional pi-subagents integration
 
@@ -74,7 +78,7 @@ BMS uses provider-reported effort lists when available and Pi's capability restr
 off · minimal · low · medium · high · xhigh · max
 ```
 
-Add/update also lets you edit supported levels and set a per-model preferred effort. These hints do not change Pi's provider adapters. If Pi clamps an effort, BMS asks before saving the applied level. No paid model probes are made.
+Add/update edits supported effort levels. Ctrl+E edits a per-model preferred effort separately. These hints do not change Pi's provider adapters. If Pi clamps an effort, BMS asks before saving the applied level. No paid model probes are made.
 
 ## Where changes are saved
 
@@ -92,8 +96,8 @@ Provider filters hide entries only in `/bms`, not Pi's `/model` picker. Default-
 ## Further documentation
 
 - [Changelog](https://cdn.jsdelivr.net/npm/pi-better-model-select@latest/CHANGELOG.md): changes by version.
-- [Configuration reference](https://cdn.jsdelivr.net/npm/pi-better-model-select@0.3.2/docs/configuration.md): file paths, precedence, overlays, metadata, and integration limits.
-- [Development and testing](https://cdn.jsdelivr.net/npm/pi-better-model-select@0.3.2/docs/development.md): local loading, isolated tests, checks, and publishing.
+- [Configuration reference](https://cdn.jsdelivr.net/npm/pi-better-model-select@latest/docs/public/configuration.md): file paths, precedence, overlays, metadata, and integration limits.
+Development and navigation design documents live in `docs/internal/` in the source checkout and are not included in the npm package.
 
 ## License
 

package/docs/{configuration.md → public/configuration.md}

@@ -48,14 +48,14 @@ Default settings are independent of the model write mode.
 | Setting | Native Pi settings field |
 | --- | --- |
 | Pi model | `defaultProvider`, `defaultModel` |
-| Pi effort | `defaultThinkingLevel` |
+| Global fallback effort, configured in BMS Defaults | `defaultThinkingLevel` |
 | Per-model preferred effort | `modelThinkingLevels["provider/model"]` |
 | Subagent fallback | `subagents.defaultModel`, `subagents.defaultThinking` |
 | Role override | `subagents.agentOverrides.<name>.model` and `.thinking` |
 
 The defaults menu starts in user scope. Project scope requires a trusted project. Pi defaults use the working directory's `.pi/settings.json`. Agent defaults use the project root resolved by `pi-subagents`, which may differ in nested repositories. The menu shows the paths.
 
-Project settings and provider-specific role overrides may take precedence. BMS shows override sources and warns when a saved Pi default would be shadowed. Saving a Pi default removes the selected model's per-model effort preference in the same scope, so it cannot override the new default.
+Project settings and provider-specific role overrides may take precedence. BMS shows override sources and warns when a saved Pi default would be shadowed. Saving a Pi default sets the selected model's `modelThinkingLevels` preference in the chosen scope without changing `defaultThinkingLevel` or other models' preferences. Automatic removes only the selected model's preference. Configure fallback effort in BMS Defaults. The scope selector chooses user or trusted-project settings.
 
 For agent roles:
 

package/extensions/bms.ts

@@ -5,7 +5,7 @@
 // to the search box.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { defaultsFlow, piPreference, setMainDefault } from "./lib/defaults.ts";
+import { defaultsFlow, editPiDefault, editModelPreference, modelEffort, piPreference } from "./lib/defaults.ts";
 import { readSettings, settingsPath } from "./lib/defaults-store.ts";
 import { pickerDialog } from "./lib/picker-dialog.ts";
 import { confirmAction, editForm, tableSelect } from "./lib/tui.ts";
@@ -80,12 +80,12 @@ function syncLocalConfig(pi: ExtensionAPI, ctx: any): ModelsConfig | null {
 }
 
 /** Stage option changes until the user explicitly saves. */
-async function optionsFlow(ctx: any, config: ModelsConfig): Promise<void> {
+export async function optionsFlow(ctx: any, config: ModelsConfig): Promise<void> {
   const settings = loadSettings();
   const providers = Object.keys(config.providers ?? {}).sort();
   const writeLabel = () => settings.writeMode === "overlay" ? "BMS overlay (models.bms.json)" : "Pi config (models.json)";
   await editForm(ctx, {
-    title: "Models / Options",
+    title: "BMS / Options",
     fields: [
       { key: "placement", label: "Result placement", value: settings.resultPlacement === "above" ? "Above prompt" : "Below prompt",
         description: "The best match stays nearest the search line. Arrow keys follow the displayed direction.",
@@ -105,6 +105,10 @@ async function optionsFlow(ctx: any, config: ModelsConfig): Promise<void> {
           settings.writeMode = value as "overlay" | "direct";
           return writeLabel();
         } },
+      { key: "reset", label: "Reset usage ranking", value: "", edit: async () => {
+        if (await confirmAction(ctx, { title: "BMS / Options / Reset usage", lines: ["Clear all model usage counts? This takes effect immediately."], confirmLabel: "Reset usage" })) saveUsage({ version: 1, counts: {}, lastUsed: {} });
+        return;
+      } },
       { key: "providers", label: "Providers", value: `${providers.filter(p => !settings.disabledProviders.includes(p)).length} enabled`,
         description: "Choose a provider to toggle visibility. Esc returns to options; Ctrl+S saves the complete draft.",
         edit: async () => {
@@ -125,7 +129,7 @@ async function optionsFlow(ctx: any, config: ModelsConfig): Promise<void> {
   });
 }
 
-async function loadModel(
+export async function loadModel(
   pi: ExtensionAPI,
   ctx: any,
   provider: string,
@@ -147,9 +151,15 @@ async function loadModel(
     return;
   }
 
+  // Read before switching so malformed settings cannot leave a partial switch.
+  // Pi caches settings; BMS preference edits on disk must apply without /reload.
+  const user = readSettings(settingsPath(ctx.cwd, "user"));
+  const project = ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {};
+  const effort = modelEffort(user, project, `${provider}/${modelId}`) ?? pi.getThinkingLevel();
   // pi.setModel lives on the ExtensionAPI, not on the command context.
   const ok = await pi.setModel(model);
   if (ok) {
+    pi.setThinkingLevel(effort);
     // Counted here rather than in model_select so /bms picks are ranked but
     // session restores are not, which would otherwise inflate every startup.
     recordUsage(provider, modelId);
@@ -171,7 +181,8 @@ export default function (pi: ExtensionAPI) {
     try { await action(); } catch (error) { ctx.ui.notify(`BMS: ${error}`, "error"); }
   };
   const addModel = async (ctx: any) => addFlow(ctx, async (provider, modelId) => {
-    if (syncLocalConfig(pi, ctx)) await report(ctx, () => setMainDefault(pi, ctx, provider, modelId));
+    const config = syncLocalConfig(pi, ctx);
+    if (config) await report(ctx, () => editPiDefault(pi, ctx, config, "user", readSettings(settingsPath(ctx.cwd, "user")), ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {}, { provider, modelId }));
   });
   pi.registerCommand("bms-options", {
     description: "Configure BMS result placement, write mode, and provider visibility",
@@ -235,9 +246,13 @@ export default function (pi: ExtensionAPI) {
         }
 
         try {
-          const preference = piPreference(readSettings(settingsPath(ctx.cwd, "user")), ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {});
+          const user = readSettings(settingsPath(ctx.cwd, "user"));
+          const project = ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {};
+          const preference = piPreference(user, project);
           for (const row of rows) {
             row.current = ctx.model?.provider === row.provider && ctx.model?.id === row.modelId;
+            const model = ctx.modelRegistry.find(row.provider, row.modelId);
+            row.effort = (model?.reasoning ?? row.reasoning) ? modelEffort(user, project, `${row.provider}/${row.modelId}`) ?? pi.getThinkingLevel() : "off";
             row.default = preference.provider === row.provider && preference.model === row.modelId;
           }
         } catch (error) { ctx.ui.notify(`Cannot read defaults: ${error}`, "warning"); }
@@ -248,7 +263,10 @@ export default function (pi: ExtensionAPI) {
             await loadModel(pi, ctx, action.provider, action.modelId);
             return;
           case "set-default":
-            await report(ctx, () => setMainDefault(pi, ctx, action.provider, action.modelId));
+            await report(ctx, () => editPiDefault(pi, ctx, config, "user", readSettings(settingsPath(ctx.cwd, "user")), ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {}, action));
+            break;
+          case "effort":
+            await report(ctx, () => editModelPreference(pi, ctx, action.provider, action.modelId));
             break;
           case "defaults":
             await report(ctx, () => defaultsFlow(pi, ctx, config));

package/extensions/lib/defaults-store.ts

@@ -67,12 +67,12 @@ export function saveCapability(key: string, capability: Capability, path = metad
 export function setPiDefault(data: JsonObject, provider: string, model: string, effort: Effort | undefined): void {
   data.defaultProvider = provider;
   data.defaultModel = model;
-  if (effort === undefined) delete data.defaultThinkingLevel;
-  else data.defaultThinkingLevel = effort;
-  // A per-model startup preference would otherwise beat the newly chosen default.
-  if (data.modelThinkingLevels !== undefined) {
-    const levels = object(data.modelThinkingLevels);
-    delete levels[`${provider}/${model}`];
+  // Choosing one model must not change the fallback for every other model.
+  if (effort !== undefined) {
+    const levels = data.modelThinkingLevels === undefined ? data.modelThinkingLevels = {} : object(data.modelThinkingLevels);
+    levels[`${provider}/${model}`] = effort;
+  } else if (data.modelThinkingLevels !== undefined) {
+    delete object(data.modelThinkingLevels)[`${provider}/${model}`];
   }
 }
 export function setRoleField(data: JsonObject, role: string | undefined, field: "model" | "thinking", value: string | false | undefined): void {

package/extensions/lib/defaults.ts

@@ -1,5 +1,5 @@
 import { discoverRoles, type AgentRole } from "./agents.ts";
-import { capabilities, isEffort, patchSettings, readSettings, roleField, setPiDefault, setRoleField, settingsPath, type Effort, type JsonObject, type Scope } from "./defaults-store.ts";
+import { EFFORTS, capabilities, isEffort, patchSettings, readSettings, roleField, setPiDefault, setRoleField, settingsPath, type Effort, type JsonObject, type Scope } from "./defaults-store.ts";
 import { tableSelect, editForm, confirmAction } from "./tui.ts";
 import { rankModelsForDefaults } from "./defaults-models.ts";
 import type { ModelsConfig } from "./store.ts";
@@ -17,9 +17,13 @@ export function piPreference(user: JsonObject, project: JsonObject): { provider?
   const provider = project.defaultProvider ?? user.defaultProvider;
   const model = project.defaultModel ?? user.defaultModel;
   const key = `${provider}/${model}`;
-  const effort = project.modelThinkingLevels?.[key] ?? user.modelThinkingLevels?.[key] ?? project.defaultThinkingLevel ?? user.defaultThinkingLevel;
+  const effort = modelEffort(user, project, key);
   return { provider, model, effort, source: project.defaultModel !== undefined || project.defaultProvider !== undefined ? "Project" : "User / automatic" };
 }
+export function modelEffort(user: JsonObject, project: JsonObject, key: string): Effort | undefined {
+  const value = project.modelThinkingLevels?.[key] ?? user.modelThinkingLevels?.[key] ?? project.defaultThinkingLevel ?? user.defaultThinkingLevel;
+  return isEffort(value) ? value : undefined;
+}
 function trusted(pi: any, ctx: any): boolean {
   return typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : typeof pi.isProjectTrusted === "function" && pi.isProjectTrusted();
 }
@@ -34,14 +38,14 @@ function confirmDefault(ctx: any, title: string, message: string, confirmLabel:
 export async function setMainDefault(pi: any, ctx: any, provider: string, modelId: string, scope: Scope = "user"): Promise<void> {
   await applyMainDefault(pi, ctx, provider, modelId, scope);
 }
-async function applyMainDefault(pi: any, ctx: any, provider: string, modelId: string, scope: Scope, selectedEffort?: Effort | "automatic"): Promise<boolean> {
+async function applyMainDefault(pi: any, ctx: any, provider: string, modelId: string, scope: Scope, selectedEffort?: Effort | "automatic", applyNow = true): Promise<boolean> {
   if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
   await ctx.modelRegistry.refresh();
   const model = ctx.modelRegistry.find(provider, modelId);
   if (!model) throw new Error(`Model ${provider}/${modelId} is not in the active registry`);
   const user = readSettings(settingsPath(ctx.cwd, "user"));
   const project = projectSettings(pi, ctx, ctx.cwd);
-  const choice = selectedEffort ?? await chooseEffort(ctx, `${provider}/${modelId}`, model, piPreference(user, project).effort);
+  const choice = selectedEffort ?? await chooseEffort(ctx, `${provider}/${modelId}`, model, modelEffort(user, project, `${provider}/${modelId}`));
   if (choice === undefined) return false;
   const effort = choice === "automatic" ? undefined : choice;
   const preview = structuredClone(scope === "user" ? user : project);
@@ -58,6 +62,11 @@ async function applyMainDefault(pi: any, ctx: any, provider: string, modelId: st
   } else if (selectedEffort === undefined && !(await confirmDefault(ctx, "Save and use Pi default?", summary, "Save and use"))) return false;
   // Parse before changing session state. A malformed file must never be overwritten.
   readSettings(settingsPath(ctx.cwd, scope));
+  if (!applyNow) {
+    patchSettings(settingsPath(ctx.cwd, scope), data => setPiDefault(data, provider, modelId, effort));
+    ctx.ui.notify(`Saved ${scope} startup default. Current session unchanged.`, "info");
+    return true;
+  }
   const previousModel = ctx.model;
   const previousEffort = pi.getThinkingLevel();
   if (!(await pi.setModel(model))) {
@@ -95,21 +104,22 @@ async function assignModel(ctx: any, config: ModelsConfig, title: string): Promi
   const row = value === undefined ? undefined : rows[Number(value)];
   return row ? { provider: row.provider, modelId: row.modelId } : undefined;
 }
-async function editPiDefault(pi: any, ctx: any, config: ModelsConfig, scope: Scope, user: JsonObject, project: JsonObject): Promise<void> {
+export async function editPiDefault(pi: any, ctx: any, config: ModelsConfig, scope: Scope, user: JsonObject, project: JsonObject, initial?: { provider: string; modelId: string }): Promise<void> {
   const current = piPreference(user, project);
-  let provider = current.provider, modelId = current.model;
-  let effort: Effort | "automatic" = current.effort ?? "automatic";
+  let provider = initial?.provider ?? current.provider, modelId = initial?.modelId ?? current.model;
+  let effort: Effort | "automatic" = modelEffort(user, project, `${provider}/${modelId}`) ?? "automatic";
+  let applyNow = false;
   let reset = false;
   const path = settingsPath(ctx.cwd, scope);
   await editForm(ctx, {
-    title: "Pi session default",
-    hint: `Scope: ${scope}\n${path}\nSave switches the session after validating the model. Higher-priority settings still apply at startup.`,
+    title: "BMS / Defaults / Pi startup default",
+    hint: `Scope: ${scope}\n${path}\nSave sets the startup default. Apply now explicitly switches the session.`,
     fields: [
       { key: "model", label: "Model", value: `${provider ?? "auto"}/${modelId ?? "auto"}`, edit: async () => {
-        const action = await tableSelect(ctx, { title: "Pi default model", rows: [{ value: "choose", label: "Choose model" }, { value: "reset", label: "Remove scope defaults", description: "Remove this scope's default model and global effort. Keep other per-model preferences." }] });
+        const action = await tableSelect(ctx, { title: "Pi default model", rows: [{ value: "choose", label: "Choose model" }, { value: "reset", label: "Remove scope defaults", description: "Remove this scope's default model. Keep per-model preferences and global fallback effort." }] });
         if (action === undefined) return;
         if (action === "reset") {
-          if (!(await confirmAction(ctx, { title: "Reset Pi defaults?", lines: [`Scope: ${scope}`, path, "Remove defaultProvider, defaultModel and defaultThinkingLevel only. Session stays unchanged."], confirmLabel: "Reset scope defaults" }))) return;
+          if (!(await confirmAction(ctx, { title: "Reset Pi defaults?", lines: [`Scope: ${scope}`, path, "Remove defaultProvider and defaultModel only. Effort preferences and session stay unchanged."], confirmLabel: "Reset scope defaults" }))) return;
           reset = true; return "remove scope defaults";
         }
         const selected = await assignModel(ctx, config, "Choose Pi default model");
@@ -123,15 +133,74 @@ async function editPiDefault(pi: any, ctx: any, config: ModelsConfig, scope: Sco
         if (selected === undefined) return;
         effort = selected; return selected;
       } },
+      { key: "apply", label: "Apply now", value: "no", edit: async () => {
+        const value = await tableSelect(ctx, { title: "BMS / Defaults / Apply now", search: false, rows: ["no", "yes"].map(value => ({ value, label: value })) });
+        if (value === undefined) return;
+        applyNow = value === "yes"; return value;
+      } },
     ],
     onSave: async () => {
       if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
       if (reset) {
-        patchSettings(path, data => { delete data.defaultProvider; delete data.defaultModel; delete data.defaultThinkingLevel; });
+        patchSettings(path, data => { delete data.defaultProvider; delete data.defaultModel; });
         return true;
       }
       if (!provider || !modelId) { ctx.ui.notify("Choose a model first.", "warning"); return false; }
-      return applyMainDefault(pi, ctx, provider, modelId, scope, effort);
+      return applyMainDefault(pi, ctx, provider, modelId, scope, effort, applyNow);
+    },
+  });
+}
+export async function editModelPreference(pi: any, ctx: any, provider: string, modelId: string): Promise<void> {
+  let scope: Scope = "user";
+  const key = `${provider}/${modelId}`;
+  const initial = readSettings(settingsPath(ctx.cwd, scope)).modelThinkingLevels?.[key];
+  let effort: Effort | "automatic" = isEffort(initial) ? initial : "automatic";
+  await editForm(ctx, {
+    title: `BMS / Models / ${key} / Effort`,
+    hint: "Save changes only this model's preference, not the startup model or global fallback.",
+    fields: [
+      { key: "scope", label: "Scope", value: scope, edit: async () => {
+        if (!trusted(pi, ctx)) { ctx.ui.notify("Project preferences require trust.", "warning"); return; }
+        scope = scope === "user" ? "project" : "user"; return scope;
+      } },
+      { key: "effort", label: "Preferred effort", value: effort, edit: async () => {
+        const value = await chooseEffort(ctx, key, ctx.modelRegistry.find(provider, modelId), effort);
+        if (value === undefined) return;
+        effort = value; return value;
+      } },
+    ],
+    onSave: async () => {
+      if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
+      patchSettings(settingsPath(ctx.cwd, scope), data => {
+        const levels = data.modelThinkingLevels ??= {};
+        if (effort === "automatic") delete levels[key]; else levels[key] = effort;
+      });
+      return true;
+    },
+  });
+}
+export async function editFallbackEffort(pi: any, ctx: any, scope: Scope): Promise<void> {
+  if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
+  const path = settingsPath(ctx.cwd, scope);
+  const saved = readSettings(path).defaultThinkingLevel;
+  let fallback = isEffort(saved) ? saved : "automatic";
+  await editForm(ctx, {
+    title: "BMS / Defaults / Pi fallback effort",
+    hint: `Scope: ${scope}\n${path}\nUsed only when a model has no per-model preference. Automatic removes this scope's fallback.`,
+    fields: [{ key: "fallback", label: "Fallback effort", value: fallback, edit: async () => {
+      const value = await tableSelect(ctx, { title: "Pi fallback effort / Choose level", initialValue: fallback,
+        rows: ["automatic", ...EFFORTS].map(value => ({ value, label: value })) });
+      if (value === undefined) return;
+      fallback = value; return value;
+    } }],
+    onSave: async () => {
+      if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
+      patchSettings(path, data => {
+        if (isEffort(fallback)) data.defaultThinkingLevel = fallback;
+        else delete data.defaultThinkingLevel;
+      });
+      ctx.ui.notify(`Saved ${scope} fallback effort. Per-model preferences are unchanged.`, "info");
+      return true;
     },
   });
 }
@@ -149,20 +218,17 @@ export async function defaultsFlow(pi: any, ctx: any, config: ModelsConfig): Pro
     const modelFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "model");
     const thinkingFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "thinking");
     const selected = await tableSelect(ctx, {
-      title: "BMS defaults",
+      title: "BMS / Defaults",
       search: false,
       state,
-      hint: `Scope: ${scope}. Saved settings, not running children. Agent changes require /reload.\nPi: ${settingsPath(ctx.cwd, scope)}\nAgents: ${settingsPath(discovery.projectRoot, scope)}`,
+      description: `Scope: ${scope}. Saved settings, not running children. Agent changes require /reload.\nPi: ${settingsPath(ctx.cwd, scope)}\nAgents: ${settingsPath(discovery.projectRoot, scope)}`,
       columns: [{ key: "target", label: "TARGET" }, { key: "model", label: "MODEL" }, { key: "effort", label: "EFFORT" }, { key: "source", label: "SOURCE" }],
       rows: [
         { value: "0", label: `Scope: ${scope}`, cells: { target: "Scope", model: scope, effort: "", source: "Select to change" } },
-        { value: "1", label: "Pi session", cells: { target: "Pi session", model: `${main.provider ?? "auto"}/${main.model ?? "auto"}`, effort: main.effort ?? "automatic", source: main.source } },
+        { value: "1", label: "Pi startup default", cells: { target: "Pi startup default", model: `${main.provider ?? "auto"}/${main.model ?? "auto"}`, effort: main.effort ?? "automatic", source: main.source } },
+        { value: "fallback", label: "Pi fallback effort", cells: { target: "Pi fallback effort", model: "Models without a preference", effort: project.defaultThinkingLevel ?? user.defaultThinkingLevel ?? "automatic", source: project.defaultThinkingLevel !== undefined ? "Project" : "User / automatic" } },
         { value: "2", label: "Subagent fallback", cells: { target: "Subagent fallback", model: display(modelFallback.value), effort: display(thinkingFallback.value), source: `${modelFallback.source}; ${thinkingFallback.source}` } },
-        ...roles.map((role, index) => {
-          const model = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "model");
-          const effort = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "thinking");
-          return { value: String(index + 3), label: role.name, cells: { target: role.name, model: display(model.value ?? role.model), effort: display(effort.value ?? role.thinking), source: role.runner ? "External runner" : `${model.source}; ${effort.source}` } };
-        }),
+        { value: "roles", label: "Agent roles…", cells: { target: "Agent roles…", model: `${roles.length} discovered`, effort: "", source: "Choose a role" } },
         ...(discovery.warning ? [{ value: "details", label: "Agent discovery details" }] : []),
         { value: "done", label: "Done" },
       ],
@@ -174,6 +240,17 @@ export async function defaultsFlow(pi: any, ctx: any, config: ModelsConfig): Pro
       scope = scope === "user" ? "project" : "user";
     } else if (index === 1) {
       await editPiDefault(pi, ctx, config, scope, user, project);
+    } else if (selected === "fallback") {
+      await editFallbackEffort(pi, ctx, scope);
+    } else if (selected === "roles") {
+      const roleState = {};
+      for (;;) {
+        const value = await tableSelect(ctx, { title: "BMS / Defaults / Agent roles", search: true, state: roleState,
+          rows: roles.map(role => ({ value: role.name, label: role.name, description: role.runner ? "External runner" : role.model ?? "inherit" })) });
+        const role = roles.find(role => role.name === value);
+        if (!role) break;
+        await editRole(pi, ctx, config, scope, discovery.projectRoot, role, readSettings(settingsPath(discovery.projectRoot, "user")), projectSettings(pi, ctx, discovery.projectRoot));
+      }
     } else if (selected === "details") {
       ctx.ui.notify(discovery.warning!, "warning");
     } else {
@@ -195,7 +272,7 @@ async function editRole(pi: any, ctx: any, config: ModelsConfig, scope: Scope, r
   let effort: string | false | undefined = role ? entry?.thinking : local.subagents?.defaultThinking;
   let modelChanged = false, effortChanged = false;
   await editForm(ctx, {
-    title: `${title} defaults`,
+    title: `BMS / Defaults / ${title}`,
     hint: `Scope: ${scope}\n${path}\nProvider-specific and project overrides still take precedence. Removing effort restores agent-defined/fallback behavior, not parent inheritance.`,
     fields: [
       { key: "model", label: "Model", value: model ?? "remove override", edit: async () => {

package/extensions/lib/effort-editor.ts

@@ -10,7 +10,7 @@ export function modelEffortDraft(ctx: FlowCtx, key: string, reasoning: boolean,
   const previous = readSettings(settingsPath(ctx.cwd ?? process.cwd(), "user")).modelThinkingLevels?.[key];
   return { capability: { levels: [...levels], source }, preferred: isEffort(previous) ? previous : undefined };
 }
-export async function editModelEfforts(ctx: FlowCtx, key: string, reasoning: boolean, reported?: Effort[], initial?: EffortDraft): Promise<EffortDraft | undefined> {
+export async function editModelEfforts(ctx: FlowCtx, key: string, reasoning: boolean, reported?: Effort[], initial?: EffortDraft, capabilitiesOnly = false): Promise<EffortDraft | undefined> {
   const draft = structuredClone(initial ?? modelEffortDraft(ctx, key, reasoning, reported));
   if (!reasoning) draft.capability = { levels: ["off"], source: "pi" };
   const saved = await editForm(ctx, {
@@ -26,12 +26,12 @@ export async function editModelEfforts(ctx: FlowCtx, key: string, reasoning: boo
         draft.capability = { levels, source: "manual" };
         return levels.join(", ");
       } },
-      { key: "preferred", label: "Preferred effort", value: draft.preferred ?? "automatic", description: "Automatic removes the user per-model preference, not agent role defaults.", edit: async () => {
+      ...(!capabilitiesOnly ? [{ key: "preferred", label: "Preferred effort", value: draft.preferred ?? "automatic", description: "Automatic removes the user per-model preference, not agent role defaults.", edit: async () => {
         const selected = await tableSelect(ctx, { title: `Preferred effort for ${key}`, initialValue: draft.preferred ?? "automatic", rows: ["automatic", ...draft.capability.levels].map(value => ({ value, label: value })) });
         if (selected === undefined) return;
         draft.preferred = isEffort(selected) ? selected : undefined;
         return selected;
-      } },
+      } }] : []),
     ],
     onSave: async () => {
       if (draft.preferred && !draft.capability.levels.includes(draft.preferred)) { ctx.ui.notify("Preferred effort must be available. Choose another effort or automatic.", "warning"); return false; }

package/extensions/lib/flows.ts

@@ -62,7 +62,7 @@ async function modelForm(ctx: FlowCtx, provider: string, initial: ModelEntry, me
         const reasoning = value === "yes";
         // Do not change the visible field if its dependent effort draft is cancelled.
         const initialEfforts = reasoning === Boolean(draft.reasoning) ? efforts : modelEffortDraft(ctx, key, reasoning, meta.effortLevels);
-        const next = await editModelEfforts(ctx, key, reasoning, meta.effortLevels, initialEfforts);
+        const next = await editModelEfforts(ctx, key, reasoning, meta.effortLevels, initialEfforts, true);
         if (!next) return;
         draft.reasoning = reasoning; efforts = next; effortsChanged = true; changes.add("reasoning"); return value;
       }),
@@ -71,8 +71,8 @@ async function modelForm(ctx: FlowCtx, provider: string, initial: ModelEntry, me
         if (value === undefined) return;
         draft.input = value.split("+"); changes.add("input"); return value;
       }),
-      field("efforts", "Available / preferred efforts", effortLabel(efforts), async () => {
-        const next = await editModelEfforts(ctx, key, Boolean(draft.reasoning), meta.effortLevels, efforts);
+      field("efforts", "Supported effort levels", effortLabel(efforts), async () => {
+        const next = await editModelEfforts(ctx, key, Boolean(draft.reasoning), meta.effortLevels, efforts, true);
         if (!next) return;
         efforts = next; effortsChanged = true; return effortLabel(efforts);
       }),
@@ -96,7 +96,7 @@ async function modelForm(ctx: FlowCtx, provider: string, initial: ModelEntry, me
     },
   });
 }
-function effortLabel(draft: EffortDraft): string { return `${draft.capability.levels.join(", ")}; preferred ${draft.preferred ?? "automatic"}`; }
+function effortLabel(draft: EffortDraft): string { return draft.capability.levels.join(", "); }
 
 export async function addFlow(ctx: FlowCtx, onAdded?: (provider: string, modelId: string) => Promise<void>): Promise<void> {
   const config = loadConfig(ctx);

package/extensions/lib/picker.ts

@@ -8,6 +8,7 @@ import { loadUsage, usageKey, type ModelsConfig } from "./store.ts";
 export type PickerAction =
   | { kind: "load"; provider: string; modelId: string }
   | { kind: "set-default"; provider: string; modelId: string }
+  | { kind: "effort"; provider: string; modelId: string }
   | { kind: "defaults" }
   | { kind: "add" }
   | { kind: "update"; provider?: string; modelId?: string }
@@ -26,6 +27,7 @@ export interface RankedModel {
   reasoning: boolean;
   current?: boolean;
   default?: boolean;
+  effort?: string;
 }
 
 /**
@@ -103,7 +105,7 @@ export function selectListTheme(theme: any): SelectListTheme {
 }
 
 // Keep the default shortcut ahead of secondary actions so narrow terminals show it.
-const HINT = "↑↓ move · enter load · ctrl+d set default · ctrl+o actions · esc close";
+const HINT = "enter load · ctrl+d default · ctrl+a add · ctrl+o menu · esc close";
 
 export interface PickerOptions {
   placement?: Placement;
@@ -112,9 +114,11 @@ export interface PickerOptions {
 }
 
 const MODEL_COLUMNS: TableColumn[] = [
-  { key: "model", label: "MODEL" }, { key: "provider", label: "PROVIDER", width: 14 },
-  { key: "context", label: "CONTEXT", width: 7 }, { key: "uses", label: "USES", width: 5 },
-  { key: "status", label: "STATUS", width: 17 },
+  { key: "model", label: "MODEL" }, { key: "provider", label: "PROVIDER", width: 10 },
+  { key: "effort", label: "EFFORT", width: 7 },
+  { key: "context", label: "CONTEXT", width: 7 }, { key: "uses", label: "USES", width: 4 },
+  { key: "default", label: "DEFAULT", width: 7 },
+  { key: "current", label: "CURRENT", width: 7 },
 ];
 
 export class ModelPicker implements Focusable {
@@ -147,8 +151,8 @@ export class ModelPicker implements Focusable {
       rows: rows.map(row => ({ value: toSelectItem(row).value, label: row.label,
         // IDs remain searchable but are not repeated under the display name.
         description: row.modelId,
-        cells: { model: row.label, provider: row.provider, context: formatContext(row.contextWindow),
-          uses: String(row.count), status: [row.current ? "current" : "", row.default ? "default" : ""].filter(Boolean).join(" · ") },
+        cells: { model: row.label, provider: row.provider, effort: row.effort ?? "auto", context: formatContext(row.contextWindow),
+          uses: String(row.count), default: row.default ? "   ✓" : "", current: row.current ? "   ✓" : "" },
       })), placement: options.placement,
       hint: assignment ? "↑↓ move · enter assign · esc back" : HINT,
     }, theme, () => { this.saveState(); changed(); }, value => {
@@ -166,30 +170,29 @@ export class ModelPicker implements Focusable {
   private action(kind: PickerAction["kind"]): void {
     this.saveState();
     const row = this.currentRow();
-    if (kind === "load" || kind === "set-default") {
+    if (kind === "load" || kind === "set-default" || kind === "effort") {
       if (row) this.done({ kind, provider: row.provider, modelId: row.modelId });
     } else if (kind === "update" || kind === "delete") {
       this.done({ kind, provider: row?.provider, modelId: row?.modelId });
     } else this.done({ kind });
   }
   private openMenu(): void {
-    const row = this.currentRow();
-    const actions: { value: PickerAction["kind"]; label: string }[] = [
-      ...(row ? [{ value: "load" as const, label: "Load selected model" },
-        { value: "set-default" as const, label: "Set selected model as default" }] : []),
-      { value: "add", label: "Add model" }, { value: "update", label: "Update model" },
-      { value: "delete", label: "Delete model" }, { value: "defaults", label: "Model and agent defaults" },
-      { value: "options", label: "Options" }, { value: "reset", label: "Reset usage ranking" },
+    const actions = [
+      { value: "models", label: "Models" },
+      { value: "add", label: "Add model…" },
+      { value: "defaults", label: "Defaults" },
+      { value: "options", label: "Options" },
+      { value: "back", label: "Back" },
     ];
-    this.menu = new TableSelect({ title: "Models / Actions", rows: actions, search: false, initialValue: this.options.state?.menuValue,
+    this.menu = new TableSelect({ title: "BMS",  rows: actions, search: false, placement: this.options.placement, initialValue: this.options.state?.menuValue,
       hint: "↑↓ move · enter choose · esc back" }, this.theme, this.changed, value => {
       if (this.options.state) {
-        if (value === undefined) delete this.options.state.menuValue;
+        if (value === undefined || value === "models" || value === "back") delete this.options.state.menuValue;
         else this.options.state.menuValue = value;
       }
       this.menu = undefined;
       this.focused = this._focused;
-      if (value !== undefined) this.action(value as PickerAction["kind"]);
+      if (value !== undefined && value !== "models" && value !== "back") this.action(value as PickerAction["kind"]);
       this.changed();
     });
     this.focused = this._focused;
@@ -199,7 +202,7 @@ export class ModelPicker implements Focusable {
     if (this.menu) { this.menu.handleInput(data); return; }
     const shortcuts: [string, PickerAction["kind"]][] = [
       ["ctrl+a", "add"], ["ctrl+u", "update"], ["ctrl+x", "delete"], ["ctrl+d", "set-default"],
-      ["ctrl+g", "defaults"], ["ctrl+r", "reset"],
+      ["ctrl+g", "defaults"], ["ctrl+e", "effort"], ["ctrl+r", "reset"],
     ];
     if (matchesKey(data, "ctrl+o")) { if (!this.assignment) this.openMenu(); return; }
     for (const [key, kind] of shortcuts) {
@@ -207,6 +210,8 @@ export class ModelPicker implements Focusable {
     }
     this.table.handleInput(data);
   }
-  render(width: number): string[] { return (this.menu ?? this.table).render(width); }
+  render(width: number): string[] {
+    return (this.menu ?? this.table).render(width);
+  }
   invalidate(): void { this.table.invalidate(); this.menu?.invalidate(); }
 }

package/extensions/lib/tui.ts

@@ -23,6 +23,7 @@ export interface TableSelectOptions {
   columns?: TableColumn[];
   rows: TableRow[];
   hint?: string;
+  description?: string;
   search?: boolean;
   placement?: Placement;
   initialValue?: string;
@@ -155,16 +156,17 @@ export class TableSelect implements Component, Focusable {
   render(width: number): string[] {
     width = Math.max(1, width);
     const border = color(this.theme, "borderAccent", "─".repeat(width));
-    const prompt = this.options.search === false ? [] : [border, ...this.input.render(width), border];
+    const prompt = [border, ...(this.options.search === false ? [color(this.theme, "dim", "↑↓ navigate · Enter choose")] : this.input.render(width)), border];
     const results = this.tableLines(width);
     const count = this.filtered.length === this.options.rows.length
       ? `${this.filtered.length} results` : `${this.filtered.length} of ${this.options.rows.length} results`;
     const summary = color(this.theme, "dim", truncateToWidth(count, width, ""));
     const shortcuts = shortcutLine(this.theme, this.options.hint ?? "↑↓ move · enter select · esc back", width);
+    const details = (this.options.description ?? "").split("\n").filter(Boolean).map(line => color(this.theme, "dim", truncateToWidth(line, width, "…")));
     return [color(this.theme, "accent", truncateToWidth(singleLine(this.options.title), width, "…")),
-      ...(this.options.placement === "above" && prompt.length
-        ? [shortcuts, summary, ...results, ...prompt]
-        : [...prompt, ...results, summary, shortcuts])];
+      ...(this.options.placement === "above"
+        ? [shortcuts, ...details, summary, ...results, ...prompt]
+        : [...prompt, ...results, summary, ...details, shortcuts])];
   }
   invalidate(): void { this.input.invalidate(); }
 }
@@ -183,7 +185,7 @@ export interface ConfirmActionOptions { title: string; lines: string[]; confirmL
 export class ConfirmAction extends TableSelect {
   private lines: string[];
   constructor(options: ConfirmActionOptions, theme: any, changed: () => void, done: (confirmed: boolean) => void) {
-    super({ title: options.title, search: false,
+    super({ title: options.title, search: false, placement: resultPlacement(),
       rows: [{ value: "cancel", label: "Cancel" }, { value: "confirm", label: options.confirmLabel }],
     }, theme, changed, value => done(value === "confirm"));
     this.lines = options.lines;
@@ -203,7 +205,7 @@ export interface FormField {
   edit: () => Promise<string | undefined>;
 }
 export interface EditFormOptions {
-  title: string; fields: FormField[]; onSave: () => Promise<boolean | void>; hint?: string;
+  title: string; fields: FormField[]; onSave: () => Promise<boolean | void>; hint?: string; placement?: Placement;
 }
 
 /** Field callbacks edit the caller's draft. Only onSave may persist it. */
@@ -280,12 +282,21 @@ export class Form implements Component {
         return index + start === this.selected && typeof this.theme?.bg === "function"
           ? this.theme.bg("selectedBg", color(this.theme, "accent", text)) : text;
       });
-    return [color(this.theme, "accent", this.options.title + (this.dirty ? " *" : "")),
-      color(this.theme, "muted", `  ${fitCell("FIELD", labelWidth)}  VALUE`), ...rows,
-      ...(this.fields[this.selected]?.description ? [color(this.theme, "dim", this.fields[this.selected]!.description!)] : []),
+    // Reserve help, feedback, and visible-row slots so selection never moves the prompt.
+    const rowCount = Math.min(6, formRows.length);
+    while (rows.length < rowCount) rows.push("");
+    const help = this.fields.some(field => field.description)
+      ? [color(this.theme, "dim", this.fields[this.selected]?.description ?? "")] : [];
+    const context = [...help,
       ...(this.options.hint ? this.options.hint.split("\n").map(line => color(this.theme, "dim", line)) : []),
-      ...(this.busy || this.error ? [this.busy ? "Working…" : color(this.theme, "error", this.error)] : []),
-      shortcutLine(this.theme, this.discard ? "↑↓ move · enter choose · esc back" : "↑↓ move · enter choose · ctrl+s save · esc back", width)]
+      this.busy ? "Working…" : this.error ? color(this.theme, "error", this.error) : ""];
+    const content = [color(this.theme, "muted", `  ${fitCell("FIELD", labelWidth)}  VALUE`), ...rows];
+    const shortcuts = shortcutLine(this.theme, this.discard ? "↑↓ move · enter choose · esc back" : "↑↓ move · enter choose · ctrl+s save · esc back", width);
+    const border = color(this.theme, "borderAccent", "─".repeat(Math.max(1, width)));
+    const prompt = [border, color(this.theme, "dim", "Enter edit · Ctrl+S save"), border];
+    return [color(this.theme, "accent", this.options.title + (this.dirty ? " *" : "")),
+      ...((this.options.placement ?? resultPlacement()) === "above"
+        ? [shortcuts, ...context, ...content, ...prompt] : [...prompt, ...content, ...context, shortcuts])]
       .map(line => truncateToWidth(line, Math.max(1, width), "…"));
   }
   invalidate(): void {}

package/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96" role="img" aria-labelledby="title desc">
+  <title id="title">Better Model Select</title>
+  <desc id="desc">A dark rounded tile with an orange outlined selected row and chevron above amber and blue model rows.</desc>
+  <rect width="96" height="96" rx="20" fill="#1F1F1F"/>
+  <rect x="11" y="19" width="74" height="24" rx="6" fill="#FF6B3D" fill-opacity="0.2" stroke="#FF6B3D" stroke-width="2"/>
+  <rect x="20" y="25" width="42" height="12" rx="3" fill="#FF6B3D"/>
+  <path d="M71 26L77 31L71 36" fill="none" stroke="#FF6B3D" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="20" y="52" width="40" height="11" rx="3" fill="#FFB13D"/>
+  <rect x="20" y="70" width="24" height="11" rx="3" fill="#5BA7FF"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-model-select",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "Searchable, usage-ranked model picker for Pi with model management, default model and thinking effort selection, and per-role subagent defaults.",
   "keywords": [
@@ -25,13 +25,14 @@
     "extensions/",
     "!extensions/**/*.test.ts",
     "README.md",
+    "icon.svg",
     "CHANGELOG.md",
-    "docs/configuration.md",
-    "docs/development.md",
+    "docs/public/configuration.md",
     "docs/demo/showcase.gif",
     "LICENSE"
   ],
   "pi": {
+    "image": "https://cdn.jsdelivr.net/npm/pi-better-model-select@latest/icon.svg",
     "extensions": [
       "./extensions/bms.ts"
     ]

package/docs/development.md

@@ -1,104 +0,0 @@
-# Development and testing
-
-Run these commands from the repository checkout:
-
-```bash
-npm ci
-npm run gate
-npm run test:smoke  # optional: installed Pi, Python 3 and a POSIX PTY required
-pi --no-extensions -e ./extensions/bms.ts  # temporary load; no install or publish
-```
-
-## Temporary local testing
-
-Use a fresh terminal in this checkout. The command above disables installed
-extensions to avoid loading two copies of BMS. It still uses your real Pi settings,
-so default changes persist. For an isolated test, use a scratch agent directory
-and project directory instead:
-
-```bash
-REPO="$PWD"
-SANDBOX="$(mktemp -d -t bms-local)"
-mkdir -p "$SANDBOX/agent" "$SANDBOX/project/.pi"
-printf '{}\n' > "$SANDBOX/project/.pi/settings.json"
-# Optional: copy your model definitions. Review literal credentials in this file.
-cp "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/models.json" "$SANDBOX/agent/models.json"
-cd "$SANDBOX/project"
-PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions -e "$REPO/extensions/bms.ts"
-```
-
-Provider API-key environment variables remain available. The isolated directory
-has no login credentials; use `/login` there if needed. Do not commit credentials
-or scratch settings. To test agent roles, load your installed pi-subagents entry
-explicitly with another `-e` and make the package resolvable in the scratch agent's
-`npm/node_modules`, or use your real agent directory with backups. For the standard
-Pi npm install layout with pi-subagents 0.82.1, before launching:
-
-```bash
-REAL_AGENT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
-ln -s "$REAL_AGENT/npm" "$SANDBOX/agent/npm"
-PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions \
-  -e "$REPO/extensions/bms.ts" -e "$REAL_AGENT/npm/node_modules/pi-subagents/bundle/index.js"
-```
-
-This symlinks installed package code, not your settings or auth files. Do not run
-package installation/update commands in this sandbox, since they would modify the
-shared package directory.
-
-The automated `npm run test:smoke` uses an unreachable dummy endpoint and
-throwaway settings. It checks command registration, the real TUI default-save
-flow, the defaults shortcut, and restoration in a fresh Pi process. No model
-prompts are sent. The regular test suite uses mocked provider metadata and UI.
-
-Manual checks:
-
-1. `/bms`: filter and use Enter. Only the current session should change.
-2. Reopen `/bms`, press Ctrl+D, choose effort and confirm. Check both markers,
-   the footer effort, and the scratch `agent/settings.json`.
-3. Cancel the effort dialog and confirmation. Neither should change defaults.
-4. `/bms-defaults`: select a Pi model, then select the same model again to change
-   only its default effort. Test user and trusted-project scope.
-5. Configure a subagent fallback and a role model/effort. Confirm the parent
-   session stays unchanged. Test explicit model inheritance and removal of each
-   override, then `/reload` and inspect `/subagents-models reviewer`.
-6. Add/update a model. Check provider-reported effort lists, the unverified Pi
-   fallback, manual levels, and the preferred effort. Try removing a level that
-   a directly pinned default uses; BMS should block the conflicting edit.
-7. Exit and start a fresh Pi session with the same scratch paths. Confirm startup
-   model and effort. Do not use `--continue`, `--resume`, or CLI model/effort overrides.
-8. Test a narrow terminal and verify the list, wrapped hints, and search still work.
-
-Quit Pi before deleting the sandbox with `rm -rf "$SANDBOX"`, then return to the
-checkout with `cd "$REPO"`. The test commands do not publish or install BMS.
-
-## Publishing
-
-Publish from `main` after the feature PR is reviewed and merged. Do not publish from the unmerged feature branch.
-
-For the current `0.2.0` release:
-
-```bash
-git switch main
-git pull --ff-only origin main
-npm ci
-npm run gate
-npm run test:smoke
-npm pack --dry-run
-```
-
-Check that the working tree is clean, both package manifests say `0.2.0`, and the package contains `README.md`, `docs/configuration.md`, and `docs/development.md`. Tests and the internal PR draft must not be included. The README links point to `main`, so merge the documentation before publishing.
-
-Then publish to the public npm registry:
-
-```bash
-make publish
-```
-
-For later releases, update both manifests with `npm version <version> --no-git-tag-version`, and include that change in a reviewed PR before publishing.
-
-The target runs the full package gate, checks npm authentication, opens npm's
-browser login when needed, skips the upload if that exact version already
-exists, publishes the public package, and waits for npm to expose the
-new version. npm can take several minutes to process a package. If verification
-times out, rerun `make verify-publish`; do not publish the same version again.
-