@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/@juicesharp/rpiv-ask-user-question/view/dialog-builder.ts

@@ -1,5 +1,6 @@
 import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Container, type Editor, Spacer } from "@earendil-works/pi-tui";
+import { DEFAULT_COLLAPSE_KEY, formatKeySpecForDisplay } from "../config.js";
 import type { QuestionnaireState } from "../state/state.js";
 import type { QuestionData } from "../tool/types.js";
 import type { PreviewPaneProps } from "./components/preview/preview-pane.js";
@@ -16,8 +17,21 @@ export const HINT_PART_TOGGLE = "Space to toggle";
 export const HINT_PART_NOTES = "n to add notes";
 export const HINT_PART_TAB = "Tab to switch questions";
 export const HINT_PART_CANCEL = "Esc to cancel";
-export const HINT_PART_COLLAPSE = "Ctrl+] to collapse";
-export const HINT_PART_EXPAND = "Ctrl+] to expand";
+/**
+ * Collapse/expand hint copy is templated on `KEY_PLACEHOLDER` because the
+ * shortcut is configurable (`collapseKey`) and `rpiv-i18n`'s `tr` has no
+ * interpolation — locale entries carry the same `{key}` placeholder and call
+ * sites `.replace()` it with `formatKeySpecForDisplay(collapseKey)` after
+ * lookup, so per-locale word order is preserved.
+ */
+export const KEY_PLACEHOLDER = "{key}";
+export const HINT_PART_COLLAPSE_TEMPLATE = `${KEY_PLACEHOLDER} to collapse`;
+export const HINT_PART_EXPAND_TEMPLATE = `${KEY_PLACEHOLDER} to expand`;
+/** Default-key (`Ctrl+]`) rendering of the collapse template, for tests and default-config assertions. */
+export const HINT_PART_COLLAPSE = HINT_PART_COLLAPSE_TEMPLATE.replace(
+	KEY_PLACEHOLDER,
+	formatKeySpecForDisplay(DEFAULT_COLLAPSE_KEY),
+);
 /**
  * `HINT_SINGLE` / `HINT_MULTI` are the resting core hint for NON-multiSelect
  * question tabs only: `buildHintText` drops `NOTES` while the notes editor is
@@ -33,8 +47,12 @@ export const HINT_SINGLE = [HINT_PART_ENTER, HINT_PART_NAV, HINT_PART_NOTES, HIN
 export const HINT_MULTI = [HINT_PART_ENTER, HINT_PART_NAV, HINT_PART_NOTES, HINT_PART_TAB, HINT_PART_CANCEL].join(
 	" · ",
 );
-/** Single-line footer shown by `QuestionnaireSession` when `state.collapsed === true`. Bypasses `buildHintText`. */
-export const COLLAPSED_HINT = [HINT_PART_EXPAND, HINT_PART_CANCEL].join(" · ");
+/**
+ * Template for the single-line footer shown by `QuestionnaireSession` when
+ * `state.collapsed === true`. Bypasses `buildHintText`; the session replaces
+ * `KEY_PLACEHOLDER` with the configured key's display form.
+ */
+export const COLLAPSED_HINT_TEMPLATE = [HINT_PART_EXPAND_TEMPLATE, HINT_PART_CANCEL].join(" · ");
 export const REVIEW_HEADING = "Review your answers";
 export const READY_PROMPT = "Ready to submit your answers?";
 export const INCOMPLETE_WARNING_PREFIX = "⚠ Answer remaining questions before submitting:";
@@ -67,6 +85,13 @@ export interface DialogConfig {
 	getCurrentBodyHeight: (width: number) => number;
 	/** Terminal height getter. Mirrors `getTerminalWidth` — reads `tui.terminal.rows` at render time. */
 	getTerminalRows: () => number;
+	/**
+	 * Resolved collapse/expand key spec (`resolveCollapseKey` output: `"ctrl+]"`,
+	 * `"alt+o"`, or `"off"`). Construction-time config, NOT canonical state —
+	 * `QuestionnaireRuntime.collapseKey` must never reach view setProps consumers.
+	 * The footer hint interpolates it, and drops the collapse part when `"off"`.
+	 */
+	collapseKey: string;
 }
 
 /**
@@ -95,6 +120,7 @@ export class DialogView implements StatefulView<DialogProps> {
 			notesInput: config.notesInput,
 			isMulti: config.isMulti,
 			getCurrentBodyHeight: config.getCurrentBodyHeight,
+			collapseKey: config.collapseKey,
 		});
 		this.submitStrategy = config.isMulti
 			? new SubmitTabStrategy({

package/node_modules/@juicesharp/rpiv-ask-user-question/view/tab-content-strategy.ts

@@ -1,5 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Container, type Editor, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF, formatKeySpecForDisplay } from "../config.js";
 import { t } from "../state/i18n-bridge.js";
 import { formatAnswerScalar } from "../tool/format-answer.js";
 import type { QuestionData } from "../tool/types.js";
@@ -8,7 +9,7 @@ import {
 	type DialogState,
 	HINT_PART_CANCEL,
 	HINT_PART_CLEAR,
-	HINT_PART_COLLAPSE,
+	HINT_PART_COLLAPSE_TEMPLATE,
 	HINT_PART_ENTER,
 	HINT_PART_NAV,
 	HINT_PART_NEW_LINE,
@@ -16,6 +17,7 @@ import {
 	HINT_PART_TAB,
 	HINT_PART_TOGGLE,
 	INCOMPLETE_WARNING_PREFIX,
+	KEY_PLACEHOLDER,
 	READY_PROMPT,
 	REVIEW_HEADING,
 } from "./dialog-builder.js";
@@ -86,6 +88,8 @@ export interface QuestionTabStrategyConfig {
 	notesInput: Editor;
 	isMulti: boolean;
 	getCurrentBodyHeight: (width: number) => number;
+	/** Resolved collapse key spec (`"ctrl+]"`, `"alt+o"`, or `"off"`). Drives the footer's collapse hint. */
+	collapseKey: string;
 }
 
 export class QuestionTabStrategy implements TabContentStrategy {
@@ -137,7 +141,10 @@ export class QuestionTabStrategy implements TabContentStrategy {
 		// drops the trailing parts (collapse hint first, then cancel) with `…`.
 		return [
 			new Spacer(1),
-			new OneLineClippedText(this.config.theme.fg("dim", buildHintText(question, this.config.isMulti, state)), 1),
+			new OneLineClippedText(
+				this.config.theme.fg("dim", buildHintText(question, this.config.isMulti, state, this.config.collapseKey)),
+				1,
+			),
 		];
 	}
 
@@ -228,21 +235,35 @@ export class SubmitTabStrategy implements TabContentStrategy {
 
 /**
  * Build the controls hint line. Order:
- *   Enter · ↑/↓ [· Space toggle] [· n notes] [· Tab switch] · Esc · Ctrl+] collapse
+ *   Enter · ↑/↓ [· Space toggle] [· n notes] [· Tab switch] · Esc [· <key> collapse]
  *   [· Shift+Enter newline] [· Ctrl+U clear]
  *
  * `NOTES` is part of the resting (notes-closed) core — it drops while the notes
  * editor or custom-answer input has the keyboard. Ctrl+G is Pi's global external-
  * editor shortcut and needs no local hint; the context-specific clear shortcut is
  * appended at the far right while input mode is active.
+ *
+ * The collapse part interpolates the configured `collapseKey` (display-cased)
+ * and is omitted entirely when the shortcut is `"off"` — `routeKey` and the raw
+ * terminal listener both refuse to collapse in that case, so advertising a key
+ * would be a lie.
  */
-export function buildHintText(question: QuestionData | undefined, isMulti: boolean, state: DialogState): string {
+export function buildHintText(
+	question: QuestionData | undefined,
+	isMulti: boolean,
+	state: DialogState,
+	collapseKey: string,
+): string {
 	const parts: string[] = [t("hint.enter", HINT_PART_ENTER), t("hint.navigate", HINT_PART_NAV)];
 	if (question?.multiSelect === true) parts.push(t("hint.toggle", HINT_PART_TOGGLE));
 	if (question && !state.notesVisible && !state.inputMode) parts.push(t("hint.notes", HINT_PART_NOTES));
 	if (isMulti) parts.push(t("hint.tab", HINT_PART_TAB));
 	parts.push(t("hint.cancel", HINT_PART_CANCEL));
-	parts.push(t("hint.collapse", HINT_PART_COLLAPSE));
+	if (collapseKey !== COLLAPSE_KEY_OFF) {
+		parts.push(
+			t("hint.collapse", HINT_PART_COLLAPSE_TEMPLATE).replace(KEY_PLACEHOLDER, formatKeySpecForDisplay(collapseKey)),
+		);
+	}
 	if (state.notesVisible || state.inputMode) parts.push(t("hint.newline", HINT_PART_NEW_LINE));
 	if (state.inputMode) parts.push(t("hint.clear", HINT_PART_CLEAR));
 	return parts.join(" · ");

package/node_modules/@narumitw/pi-btw/README.md

@@ -1,26 +1,19 @@
-# 💬 pi-btw — Side Questions for the Pi Coding Agent
+# 💬 pi-btw — Ask Side Questions Without Derailing the Main Task
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-btw)](https://www.npmjs.com/package/@narumitw/pi-btw) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-btw` is a native [Pi coding agent](https://pi.dev) extension that adds `/btw`, a side-question command for quick clarifications that should not interrupt or pollute the main agent conversation.
+Ask temporary questions in a separate side thread while the main Pi conversation and coding task stay focused.
 
-Use it when you want to ask a temporary question, inspect context, or get a short explanation while keeping the primary coding task focused.
+Bring back only the answer or context you explicitly choose.
 
 ## ✨ Features
 
-- Adds a `/btw` menu for starting or resuming an in-memory side thread or changing pi-btw settings.
-- Keeps `/btw <question>` as a direct fast path that always starts a fresh side thread.
-- Answers side questions in a dedicated, scrollable full-screen UI.
-- Keeps mouse-drag copying stable while the main agent continues running in the background.
-- Supports follow-up questions in the same ephemeral side thread.
-- Resumes any non-empty side thread retained by the current Pi session, listed by its first question.
-- Queues Pi-style `Steering` questions while an answer is running and processes them one at a time.
-- Optionally brings the latest answer, a question-to-end suffix, an exact line range, or the entire side thread into the main editor.
-- Uses the current session branch as context.
-- Uses Pi's current model or an independent model selected in `pi-btw.json`.
-- Uses a pi-btw thinking level that can be changed with Pi's configured thinking shortcut and remembered for next time.
-- Does not append the side question or answer to the main conversation.
-- Works as an independently installable npm Pi extension package.
+- Starts a fresh side thread immediately with `/btw <question>` or opens the manager with `/btw`.
+- Uses any persisted main-session branch as context without switching that branch.
+- Supports scrollable answers, follow-up questions, queued steering, and resumable in-memory threads.
+- Keeps side questions and answers out of the main conversation by default.
+- Brings back only the latest answer, a selected range, a question suffix, or the complete side thread when requested.
+- Uses Pi's current model and thinking level or independent saved choices.
 
 ## 📦 Install
 
@@ -34,13 +27,21 @@ Try without installing permanently:
 pi -e npm:@narumitw/pi-btw
 ```
 
-Try this package locally from the repository root:
+Build and try this package locally from the repository root:
 
 ```bash
+npm --workspace @narumitw/pi-btw run build
 pi -e ./packages/pi-btw
 ```
 
-## 🚀 Usage
+The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
+
+## 🚀 Quick start
+
+Run `/btw <question>` to start a side thread immediately, or run `/btw` to choose context and settings first.
+Side-thread questions and answers remain separate from the main conversation unless you explicitly bring selected context back.
+
+## 💬 Commands
 
 Open the pi-btw menu or provide the first question immediately:
 
@@ -59,79 +60,83 @@ Examples:
 ```
 
 Running `/btw` alone opens a menu with **Start side thread** selected first.
+**Start from main thread tree…** opens Pi's native session tree and uses the root-to-selected-entry path, including the selected entry, as the new side thread's context.
+Selecting context does not navigate, fork, append to, or switch the main conversation, and it preserves the main editor draft.
+The selector is a snapshot of entries persisted when it opens, while the resulting side thread keeps an immutable context snapshot even if the main conversation later changes.
+Press `Escape` to return to the `/btw` menu or `Ctrl+C` to close the flow.
+The native tree controls remain available: copying reports success or failure, and an explicit `Shift+L` label edit persists through Pi as the only main-session mutation available from this selector.
 When the current Pi session has non-empty side threads in memory, **Resume side thread** opens a bounded searchable choice list.
 Search matches the displayed first question and question count while returning the thread's raw in-memory ID.
-**Settings** changes the starting thinking level and whether shortcut changes are remembered.
+**Settings** changes the starting thinking level and whether shortcut changes for fixed levels are remembered.
 Each Resume row keeps the first question as its fixed title, shows its question count, and the list is ordered by the newest recorded answer or visible error.
 Opening and closing a thread without a new result does not reorder it.
 `/btw <question>` bypasses this menu and always starts a fresh side thread.
 Its answer opens above the side-thread editor.
 The side thread uses a dedicated full-screen terminal view.
-The main agent continues running in the background, but its screen rendering stays suspended until
-`/btw` closes, so new main-thread output cannot move a mouse selection inside the side thread.
-Drag the primary mouse button across side-thread text to select and copy it through Pi's terminal
-clipboard support. Returning from `/btw` redraws the main view with everything produced while it
-was hidden. A compact `btw · side thread` header stays fixed above the content so the ephemeral
-workspace remains recognizable while scrolling. Messages use Pi's normal
-user and assistant presentation without numbered turns or role labels. Type each question and press
-`Enter`; no follow-up shortcut is required.
-Previous side questions and answers remain available to the model and visible for that
-invocation. The side-thread header shows its current thinking level. Press Pi's configured
-`app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle the levels
-supported by the side-thread model; every later question uses the displayed level until it is
-changed again. By default, each shortcut change is also written to `pi-btw.json` for the next
-invocation. Turn **Remember thinking level changes** off in Settings to keep changes local to the
-current side thread. Neither path changes the main session's thinking level.
-While a response is running, the transcript and composer remain visible above an `Answering…`
-status.
-Type another question and press `Enter` to queue it as `Steering`; queued questions are shown in
-submission order and answered one at a time after the active response completes.
+The main agent continues running in the background, but its screen rendering stays suspended until `/btw` closes, so new main-thread output cannot move a mouse selection inside the side thread.
+Drag the primary mouse button across side-thread text to request a copy through Pi's host clipboard helper.
+The view reports `Copied!` when Pi accepts the copy and `Copy failed` when Pi reports failure; actual clipboard availability still depends on operating-system and terminal support.
+Returning from `/btw` redraws the main view with everything produced while it was hidden.
+A compact `btw · side thread` header stays fixed above the content so the ephemeral workspace remains recognizable while scrolling.
+Messages use Pi's normal user and assistant presentation without numbered turns or role labels.
+Type each question and press `Enter`; no follow-up shortcut is required.
+Press `Ctrl+Shift+F` to search completed or answering transcript content.
+Press `Enter` or `Ctrl+G` for the next match, `Shift+Enter` or `Ctrl+Shift+G` for the previous match, and `Escape` to close search.
+Search uses Pi's active theme, keeps the composer available after closing the search overlay, and does not include fixed header or footer chrome.
+Previous side questions and answers remain available to the model and visible for that invocation.
+The side-thread header shows its current thinking level.
+Press Pi's configured `app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle the levels supported by the side-thread model; every later question uses the displayed level until it is changed again.
+When a fixed thinking level is selected, each shortcut change is also written to `pi-btw.json` for the next invocation by default.
+Turn **Remember thinking level changes** off in Settings to keep fixed-level changes local to the current side thread.
+When **Same as main thread** is selected, shortcut changes are always local to the current side thread.
+Neither path changes the main session's thinking level.
+While a response is running, the transcript and composer remain visible above an `Answering…` status.
+Type another question and press `Enter` to queue it as `Steering`; queued questions are shown in submission order and answered one at a time after the active response completes.
 A queued question uses the side thread's thinking level when its turn begins.
 A failed active response is shown in the transcript and does not discard later steering questions.
-The footer shows `PgUp`/`PgDn` only when history can scroll; press `Ctrl+C` to cancel the active
-response and discard the ephemeral side-thread draft and steering queue. Completed questions,
-answers, and visible errors remain available through Resume until the current extension instance
-ends. Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
-
-After at least one successful answer, press `Ctrl+R` to bring selected context to the main
-editor. The scope menu shows the size of the latest question and answer and the entire side
-thread before you choose. Bring the latest question and answer, everything from a chosen
-question onward, an exact text range, or the entire side thread. Question-suffix, exact-range,
-and entire-thread choices preview the exact editable context block before the side thread closes;
-`Escape` returns and `Ctrl+C` closes without bringing anything to main.
+Use the mouse wheel or trackpad to scroll transcript history like Pi's main thread.
+Keyboard `PgUp`/`PgDn` history navigation remains available and appears in the footer only when the transcript can scroll.
+Press `Ctrl+C` to cancel the active response and discard the ephemeral side-thread draft and steering queue.
+Completed questions, answers, and visible errors remain available through Resume until the current extension instance ends.
+Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
+
+After at least one successful answer, press `Ctrl+R` to bring selected context to the main editor.
+The scope menu shows the size of the latest question and answer and the entire side thread before you choose.
+Bring the latest question and answer, everything from a chosen question onward, an exact text range, or the entire side thread.
+Question-suffix, exact-range, and entire-thread choices preview the exact editable context block before the side thread closes.
+Pressing `Escape` returns, while `Ctrl+C` closes without bringing anything to main.
 
 The text-range selector supports both fast line selection and editor-style character selection.
-It reports whether anything is selected plus the selected line, message, and approximate token
-counts. Press `Space` to select the current raw source line, then use `Up`/`Down` to extend by
-whole lines; press `Space` again to clear it. Alternatively, use the arrow keys to move the cursor
-and `Shift`+arrow keys to extend a character-level selection. Starting a Shift selection replaces
-any active line selection. Selected lines include a visible `●` marker in addition to highlighting.
-Pi's configured keys control vertical navigation, bringing, and going back (`Up`/`Down`, `Enter`,
-and `Escape` by default), and the selector displays the active keys. Selection follows raw source
-text rather than terminal-wrapped visual rows.
-
-Bringing context to main closes the side thread and loads a deterministic, editable context block
-into Pi's main editor. It never sends the draft automatically. If the main editor already has a
-draft, append is the recommended default. Replace is labeled as destructive and requires a second
-confirmation; Cancel returns to the side thread without changing either draft. Concurrent editor
-updates made while these menus are open are preserved. A success message reports whether context
-was loaded, appended, or replaced and its approximate size.
-Without an explicit bring-to-main action, closing `/btw` never adds the side thread to the main
-conversation. Non-empty threads remain only in memory for Resume within the current Pi session.
-`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard every retained
-thread. Unsent drafts, steering queues, interrupted answers, and model credentials are never retained.
-
-## ⚙️ Model and thinking level
-
-By default, `/btw` uses the current session model. To use an independent model for side
-questions, create:
+It reports whether anything is selected plus the selected line, message, and approximate token counts.
+Press `Space` to select the current raw source line, then use `Up`/`Down` to extend by whole lines; press `Space` again to clear it.
+Alternatively, use the arrow keys to move the cursor and `Shift`+arrow keys to extend a character-level selection.
+Starting a Shift selection replaces any active line selection.
+Selected lines include a visible `●` marker in addition to highlighting.
+Pi's configured keys control vertical navigation, bringing, and going back (`Up`/`Down`, `Enter`, and `Escape` by default), and the selector displays the active keys.
+Selection follows raw source text rather than terminal-wrapped visual rows.
+
+Bringing context to main closes the side thread and loads a deterministic, editable context block into Pi's main editor.
+It never sends the draft automatically.
+If the main editor already has a draft, append is the recommended default.
+Replace is labeled as destructive and requires a second confirmation; Cancel returns to the side thread without changing either draft.
+Concurrent editor updates made while these menus are open are preserved.
+A success message reports whether context was loaded, appended, or replaced and its approximate size.
+Without an explicit bring-to-main action, closing `/btw` never adds the side thread to the main conversation.
+Non-empty threads remain only in memory for Resume within the current Pi session.
+`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard every retained thread.
+Unsent drafts, steering queues, interrupted answers, and model credentials are never retained.
+
+## ⚙️ Settings
+
+By default, `/btw` uses the current session model.
+To use an independent model for side questions, create:
 
 ```text
 $PI_CODING_AGENT_DIR/pi-btw.json
 ```
 
-The normal location is `~/.pi/agent/pi-btw.json`. `PI_CODING_AGENT_DIR` is an existing Pi
-setting; pi-btw does not add any environment variables.
+The normal location is `~/.pi/agent/pi-btw.json`.
+`PI_CODING_AGENT_DIR` is an existing Pi setting; pi-btw does not add any environment variables.
 
 ```json
 {
@@ -141,46 +146,54 @@ setting; pi-btw does not add any environment variables.
 }
 ```
 
-The `model` value uses `provider/model-id` format. Only the first `/` is the separator, so
-model IDs may contain additional slashes, such as `openrouter/anthropic/claude-sonnet`.
-The configured model must exist in Pi's model registry and have usable credentials. If it
-cannot be found or authenticated, pi-btw warns and falls back to the current session model.
-If neither model is available, `/btw` reports an error and stops. This selection affects only
-`/btw`; it does not change the main session model.
-
-Pi calls its reasoning setting the **thinking level**. `thinkingLevel` sets pi-btw's starting
-level; accepted values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. When the
-field is absent for backward compatibility, the next invocation starts from the current session
-level. The initial value and shortcut cycle are clamped to the selected side model's capabilities
-using Pi's model rules. Pi-btw does not read, write, or change the main session's
-`defaultThinkingLevel`.
-
-`rememberThinkingLevelChanges` controls only persistence and defaults to `true` when omitted. A
-side-thread shortcut always changes that side thread immediately. When remembering is on, the
-concrete level is written for the next invocation; when off, `pi-btw.json` stays unchanged. If a
-shortcut write fails, the local change remains active and pi-btw warns that it was not remembered.
+The `model` value uses `provider/model-id` format.
+Only the first `/` is the separator, so model IDs may contain additional slashes, such as `openrouter/anthropic/claude-sonnet`.
+The configured model must exist in Pi's model registry and have usable credentials.
+If it cannot be found or authenticated, pi-btw warns and falls back to the current session model.
+If neither model is available, `/btw` reports an error and stops.
+This selection affects only `/btw`; it does not change the main session model.
+
+Pi calls its reasoning setting the **thinking level**.
+In Settings, choose **Same as main thread** to start each new side thread from the main thread's current thinking level.
+This is stored by omitting `thinkingLevel` from `pi-btw.json`.
+
+Set `thinkingLevel` only when you want a fixed pi-btw starting level.
+Accepted fixed values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
+The initial value and shortcut cycle are clamped to the selected side model's capabilities using Pi's model rules.
+Resumed side threads keep their own local thinking level instead of re-syncing with the main thread.
+Pi-btw does not read, write, or change the main session's `defaultThinkingLevel`.
+
+`rememberThinkingLevelChanges` controls only persistence for fixed thinking levels and defaults to `true` when omitted.
+A side-thread shortcut always changes that side thread immediately.
+When a fixed thinking level is selected and remembering is on, the concrete level is written for the next invocation; when off, `pi-btw.json` stays unchanged.
+When **Same as main thread** is selected, shortcut changes stay local even when remembering is on.
+If a shortcut write fails, the local change remains active and pi-btw warns that it was not remembered.
 A failed Settings-screen save instead restores the previous displayed value.
 
-A missing settings file is a side-effect-free read: pi-btw creates it only after a Settings change
-or a remembered shortcut change. Saves are ordered within the Pi process and published atomically
-with a same-directory temporary file and rename. They preserve `model` and unknown fields; malformed
-or invalid files block saves and remain unchanged. Settings must be valid UTF-8 and no larger than
-64 KiB, so unexpectedly large or invalidly encoded files are rejected without being rewritten.
-Separate Pi processes and external editors are outside this in-process ordering boundary. The file
-is read for each `/btw` invocation, so edits apply without `/reload`.
+A missing settings file is a side-effect-free read: pi-btw creates it only after a Settings change or a remembered shortcut change.
+Saves are ordered within the Pi process and published atomically with a same-directory temporary file and rename.
+They preserve `model` and unknown fields; malformed or invalid files block saves and remain unchanged.
+Settings must be valid UTF-8 and no larger than 64 KiB, so unexpectedly large or invalidly encoded files are rejected without being rewritten.
+Separate Pi processes and external editors are outside this in-process ordering boundary.
+The file is read for each `/btw` invocation, so edits apply without `/reload`.
 
 ## 🧠 Why use pi-btw?
 
-Normal assistant messages become part of the main Pi conversation and can distract the coding agent from the task. `pi-btw` creates a lightweight side channel for context-aware questions, making it useful for pair programming, debugging, code review, and repository exploration.
+Normal assistant messages become part of the main Pi conversation and can distract the coding agent from the task.
+`pi-btw` creates a lightweight side channel for context-aware questions, making it useful for pair programming, debugging, code review, and repository exploration.
 
 ## 🗂️ Package layout
 
 ```txt
 packages/pi-btw/
+├── dist/                  # Generated TypeScript runtime loaded by Jiti
+├── scripts/
+│   └── build-runtime.mjs  # Deterministic runtime builder and boundary validator
 ├── src/
 │   ├── index.ts
 │   ├── btw.ts
 │   ├── bring-to-main.ts
+│   ├── main-tree-picker.ts
 │   ├── menu.ts
 │   ├── settings.ts
 │   ├── side-thread.ts
@@ -197,15 +210,18 @@ The package exposes its Pi extension through `package.json`:
 ```json
 {
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": ["./dist/index.ts"]
   }
 }
 ```
 
+The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
+
 ## 🔎 Keywords
 
 Pi extension, Pi coding agent, AI coding agent, side question command, agent chat workflow, TypeScript Pi package, npm Pi extension.
 
 ## 📄 License
 
-MIT. See [`LICENSE`](./LICENSE).
+MIT.
+See [`LICENSE`](./LICENSE).