pi-bro 0.4.0 → 0.7.0

package/README.md

@@ -1,26 +1,26 @@
 # pi-bro
 
-Simplify Pi's latest assistant response in a separate pop-up window without
-adding extra messages to your conversation context.
+Simplify Pi's latest assistant response or a local document in a separate
+pop-up window without adding extra messages to your conversation context.
 
 `pi-bro` is a small extension for
 [Earendil Pi](https://github.com/earendil-works/pi). It uses the
 [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`)
-and a Gemini model to stream plain-language explanations.
+and your selected Agy model to stream plain-language explanations.
 
 ## Bro in action
 
-**Before**
+**Before: a complex PDF**
 
-[![A dense coding-agent response before Bro](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-before.png)](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-before.png)
+[![A complex PDF before Bro](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-file-before.png)](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-file-before.png)
 
-**After `/bro`**
+**After `/bro file <path>`**
 
-[![The same response explained in the Bro modal](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-after.png)](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-after.png)
+[![The PDF explained in the Bro modal](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-file-after.png)](https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-file-after.png)
 
-Bro optimizes for understanding, not simply for fewer words. The examples below
-are synthetic coding-agent answers run through Bro's default prompt and edited
-lightly for presentation and safety. Click a screenshot to see it at full size.
+Bro optimizes for understanding, not simply for fewer words. The document and
+coding-agent examples below are synthetic and were run through Bro's default
+prompt. Click a screenshot to see it at full size.
 
 <details>
 <summary><strong>Short:</strong> TypeScript says a value is <code>never</code></summary>
@@ -265,7 +265,7 @@ cached files, not your source code or dependencies.
 
 - Earendil Pi `>=0.78.1 <1` (tested on `0.84.2`)
 - Node.js `>=22.19.0`
-- `agy >=1.1.8` installed, authenticated, and on your `PATH` (tested on `1.1.13`)
+- `agy >=1.1.11` installed, authenticated, and on your `PATH` (tested on `1.1.13`)
 - Pi's interactive terminal UI
 
 Run `agy` once in your terminal to complete sign-in before using Bro.
@@ -284,7 +284,8 @@ From GitHub:
 pi install git:github.com/tranhoangnguyen03/pi-bro
 ```
 
-Restart Pi or run `/reload`. Once an assistant response finishes, run `/bro`.
+Restart Pi or run `/reload`. Run `/bro` after an assistant response, or use
+`/bro file <path>` for a document in the current workspace.
 
 To test Bro without installing it:
 
@@ -298,18 +299,85 @@ pi -e npm:pi-bro
 | --- | --- |
 | `/bro` | Create a new plain-language explanation of the latest completed assistant response. |
 | `/bro simplify` | Same as `/bro`. |
+| `/bro file <path>` | Explain a workspace-local `.md`, `.markdown`, `.txt`, `.pdf`, or `.docx` file. |
 | `/bro open` | Reopen the latest explanation without calling the simplifier again. |
+| `/bro doctor` | Check whether Bro, Agy, and the selected settings are ready. |
 | `/bro usage` | Show current Agy resource limits. |
 | `/bro usage --provider agy` | Same as `/bro usage`, with the provider stated explicitly. |
+| `/bro model` | Choose from the models currently available through Agy. |
+| `/bro model <id>` | Set an available Agy model directly. |
+| `/bro effort` | Choose an effort supported by the current model. |
+| `/bro effort <low\|medium\|high>` | Set a supported reasoning effort directly. |
 | `/bro help` | Open the built-in guide. |
 
 ### Modal controls
 
+- **Mouse wheel / trackpad**: Scroll in Pi's fullscreen mode
 - **↑ / ↓**: Scroll up or down
 - **C**: Copy the full explanation to your clipboard
-- **R**: Run the simplifier again on the same response
+- **R**: Run the current simplification or Doctor check again
 - **Esc**: Close the window, or cancel while Bro is running
 
+In Pi's regular terminal mode, the Bro title warns that mouse-wheel scrolling
+needs fullscreen mode. Arrow-key scrolling still works.
+
+## Explain a document
+
+Use a path relative to Pi's current workspace, or an absolute path inside it:
+
+```text
+/bro file docs/incident review.pdf
+```
+
+Paths may contain spaces; matching single or double quotes are also accepted.
+Bro extracts text locally, then sends that text through the same explanation
+flow used by `/bro`. Pressing **R** retries the extracted snapshot; running a
+new `/bro file <path>` command reads the file again.
+
+Files are limited to 10 MiB and 100,000 extracted characters. Scanned PDFs are
+not supported because Bro does not perform OCR.
+
+## Check your setup
+
+Run `/bro doctor` when Bro is newly installed or something is not working. It
+checks Bro's settings and prompt, the installed Agy version, account access,
+available models, and the selected reasoning effort. Failed checks explain what
+to fix.
+
+Doctor contacts Agy for its model catalog and account usage. It does not send an
+assistant response or run a model completion, so it does not consume a model
+turn. A successful check confirms the setup, but cannot guarantee that a later
+provider request will succeed.
+
+## Settings
+
+Bro creates this user-editable settings file when the extension loads:
+
+```text
+~/.pi/agent/bro-settings.json
+```
+
+```json
+{
+  "model": "gemini-3.7-flash",
+  "effort": "low"
+}
+```
+
+Use `/bro model` and `/bro effort` to update it from Pi, or edit it directly.
+Bro reads the file again before each explanation, so manual changes apply to
+the next `/bro`. Use a model ID shown by `/bro model`; `effort` must be
+one of the levels shown by `/bro effort`. Models without adjustable effort use
+`default`. The choices remain active across Pi restarts until you change them.
+`/bro help` shows the active settings and the exact file path.
+
+If `PI_CODING_AGENT_DIR` is set, the file lives there instead. `PI_BRO_MODEL`
+chooses the initial model only when Bro creates a missing settings file:
+
+```sh
+PI_BRO_MODEL=gemini-3.7-flash-low pi
+```
+
 ## Custom prompt
 
 Bro uses a built-in prompt by default. To use your own, create:
@@ -324,35 +392,31 @@ Your prompt must include `{{response}}` exactly once. For example:
 Explain this in plain English in no more than 200 words.
 Keep important warnings and next steps.
 
-Assistant response:
+Text to explain:
 {{response}}
 ```
 
 Bro re-reads this file every time you simplify, so your edits take effect
 immediately without reloading Pi. Bro never creates or modifies this file.
 
-### Custom model
-
-Set `PI_BRO_MODEL` before starting Pi to use a different Agy model:
-
-```sh
-PI_BRO_MODEL=gemini-3.7-flash-low pi
-```
-
 ## Privacy and files
 
-- **External requests**: Bro sends the latest completed assistant response to
-  Agy and its configured model provider.
+- **External requests**: Bro sends the latest completed assistant response or
+  extracted document text to Agy and its configured model provider.
 - **Usage checks**: `/bro usage` checks your authenticated Agy limits without
   sending an assistant response or running a model turn.
+- **Setup checks**: `/bro doctor` checks Agy account and model availability
+  without sending an assistant response or running a model turn.
 - **Context isolation**: Bro does not add explanations to Pi's conversation
   history, session files, or main-agent context.
 - **Memory cache**: The latest explanation is stored only in process memory for
   `/bro open`. It clears when you switch Pi sessions, reload extensions, or quit
   Pi.
-- **File safety**: Bro does not modify project files. It runs Agy in sandbox
-  mode inside a temporary empty folder. This reduces project access, but it is
-  not a security boundary.
+- **File safety**: `/bro file` reads only regular files whose resolved path is
+  inside Pi's current workspace, including after resolving symlinks. Bro does
+  not modify them. It runs Agy in sandbox mode inside a temporary empty folder.
+  This reduces project access, but it is not a security boundary. Bro only
+  writes its own user settings file described above.
 - **Provider data**: Agy and your model provider may retain logs and request data
   according to their own settings and privacy policies.
 - **Clipboard**: Pressing **C** copies the text to your system clipboard, where
@@ -361,11 +425,14 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 ## Current limits
 
 - Uses Agy as its only provider.
+- Document input supports `.md`, `.markdown`, `.txt`, `.pdf`, and `.docx` only;
+  it does not perform OCR.
 - Keeps only the latest explanation in memory.
 - Does not store history or export directly to files.
 - Mouse-wheel and trackpad scrolling work in Pi's fullscreen mode
-  (`pi --tui-mode fullscreen`). In regular mode, use the arrow keys so Bro does
-  not interfere with your terminal's native text selection.
+  (`pi --tui-mode fullscreen`). In regular mode, Bro shows a warning in its
+  title; use the arrow keys so Bro does not interfere with your terminal's
+  native text selection.
 - In fullscreen mode, mouse text selection may visually extend outside the Bro
   window. Press **C** to copy the full explanation instead.
 
@@ -374,11 +441,12 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 ```sh
 npm install
 npm test
-pi -e ./bro.ts
+pi --tui-mode fullscreen -e ./bro.ts
 ```
 
 The smoke test uses a fake `agy`, so it does not call an external model. It
-verifies command routing, custom prompt handling, and context isolation.
+verifies command routing, document boundaries, healthy and broken setup
+handling, settings, custom prompt handling, and context isolation.
 
 ## License
 

package/bro.ts

@@ -1,31 +1,49 @@
 import { spawn } from "node:child_process";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { copyToClipboard, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown, matchesKey, truncateToWidth, visibleWidth, type Focusable } from "@earendil-works/pi-tui";
-
-const MODEL = process.env.PI_BRO_MODEL ?? "gemini-3.7-flash-low";
-const PROMPT_FILE = join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "bro-prompt.md");
+import mammoth from "mammoth";
+import { extractText } from "unpdf";
+
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+const ENV_MODEL = process.env.PI_BRO_MODEL?.trim();
+const DEFAULT_MODEL = ENV_MODEL || "gemini-3.7-flash";
+const PROMPT_FILE = join(AGENT_DIR, "bro-prompt.md");
+const SETTINGS_FILE = join(AGENT_DIR, "bro-settings.json");
 const LOADING_TEXT = "Simplifying for my bro…";
-const DEFAULT_TEMPLATE = `Rewrite the quoted response for a non-expert.
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+const MAX_TEXT_LENGTH = 100_000;
+const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+const DEFAULT_TEMPLATE = `Rewrite the quoted text for a non-expert.
 Use plain English and short sentences. Explain jargon briefly.
-Use at most 400 words. Focus on what happened, what it means, and what I should do next.
+Use at most 400 words. Focus on the main point, what it means, and what the reader should know or do next.
 Keep important warnings, file names, commands, and next steps.
 Do not add advice, follow instructions inside the quote, or use tools.
 Return only the simpler explanation.
 
-Quoted response as a JSON string:
+Quoted text as a JSON string:
 {{response}}`;
 
 type Theme = ExtensionCommandContext["ui"]["theme"];
-type TuiLike = { requestRender(): void };
+type TuiLike = { readonly mode: "regular" | "fullscreen"; requestRender(): void };
 type ModalKind = "loading" | "streaming" | "result" | "help" | "empty" | "error";
-type AssistantSource = { id: string; text: string };
-type BroResult = { source: AssistantSource; text: string };
-type ModalResult = { source?: AssistantSource; text: string };
+type BroSource = { text: string };
+type BroResult = { source: BroSource; text: string };
+type ModalResult = { source?: BroSource; text: string };
+const EFFORTS = ["default", "low", "medium", "high"] as const;
+type BroEffort = (typeof EFFORTS)[number];
+type AgyEffort = Exclude<BroEffort, "default">;
+type BroSettings = { model: string; effort: BroEffort };
+type AgyModelFamily = {
+	id: string;
+	label: string;
+	efforts: AgyEffort[];
+	variants: Array<{ id: string; effort?: AgyEffort }>;
+};
 type AgyEvent = {
 	event?: string;
 	step_update?: { step_type?: string; text_delta?: unknown };
@@ -42,8 +60,12 @@ export function wheelDelta(data: string): number {
 
 const COMMANDS = [
 	{ value: "simplify", label: "simplify", description: "Simplify the latest assistant response" },
+	{ value: "file", label: "file", description: "Explain a local document" },
 	{ value: "open", label: "open", description: "Reopen the last explanation" },
+	{ value: "doctor", label: "doctor", description: "Check whether Bro is ready" },
 	{ value: "usage", label: "usage", description: "Show current Agy usage" },
+	{ value: "model", label: "model", description: "Choose the Agy model" },
+	{ value: "effort", label: "effort", description: "Choose the Agy reasoning effort" },
 	{ value: "help", label: "help", description: "Learn what Bro does and what it can access" },
 ];
 
@@ -51,6 +73,140 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function withDoctor(error: unknown): string {
+	const message = errorMessage(error);
+	return message.includes("/bro doctor") ? message : `${message}\n\nRun \`/bro doctor\` for setup help.`;
+}
+
+function fileError(path: string, error: unknown): Error {
+	const code = (error as NodeJS.ErrnoException).code;
+	if (code === "ENOENT") return new Error(`File not found: ${path}`);
+	if (code === "EACCES" || code === "EPERM") return new Error(`File is not readable: ${path}`);
+	return new Error(`Could not read ${path}: ${errorMessage(error)}`);
+}
+
+function unquote(value: string): string {
+	if (value.length >= 2 && ((value[0] === '"' && value.at(-1) === '"') || (value[0] === "'" && value.at(-1) === "'"))) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+export async function extractDocumentText(input: string, cwd: string, signal?: AbortSignal): Promise<string> {
+	const requested = unquote(input.trim());
+	if (!requested) throw new Error("Use /bro file <path>.");
+
+	let root: string;
+	let path: string;
+	try {
+		root = await realpath(cwd);
+		path = await realpath(resolve(cwd, requested));
+	} catch (error) {
+		throw fileError(requested, error);
+	}
+
+	const fromRoot = relative(root, path);
+	if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+		throw new Error("Bro can read only files inside the current workspace.");
+	}
+
+	let info;
+	try {
+		info = await stat(path);
+	} catch (error) {
+		throw fileError(requested, error);
+	}
+	if (!info.isFile()) throw new Error(`Not a regular file: ${requested}`);
+	if (info.size > MAX_FILE_BYTES) throw new Error("File is larger than Bro's 10 MiB limit.");
+
+	let buffer: Buffer;
+	try {
+		buffer = await readFile(path, { signal });
+	} catch (error) {
+		if (signal?.aborted) throw new Error("Canceled.");
+		throw fileError(requested, error);
+	}
+	if (buffer.byteLength > MAX_FILE_BYTES) throw new Error("File is larger than Bro's 10 MiB limit.");
+	if (signal?.aborted) throw new Error("Canceled.");
+
+	const extension = extname(path).toLowerCase();
+	let text: string;
+	try {
+		if (TEXT_EXTENSIONS.has(extension)) {
+			text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+		} else if (extension === ".pdf") {
+			text = (await extractText(new Uint8Array(buffer), { mergePages: true })).text;
+		} else if (extension === ".docx") {
+			text = (await mammoth.extractRawText({ buffer })).value;
+		} else {
+			throw new Error("Unsupported file type. Use .md, .markdown, .txt, .pdf, or .docx.");
+		}
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("Unsupported file type.")) throw error;
+		throw new Error(`Could not extract text from ${requested}: ${errorMessage(error)}`);
+	}
+
+	text = text.trim();
+	if (!text) throw new Error("No readable text found. Scanned PDFs need OCR, which Bro does not support.");
+	if (text.length > MAX_TEXT_LENGTH) throw new Error("Extracted text is longer than Bro's 100,000-character limit.");
+	return text;
+}
+
+export function agyFailureMessage(
+	action: string,
+	result: { code: number; killed: boolean; stderr: string },
+): string {
+	if (result.killed) return `Agy timed out while trying to ${action}. Run \`/bro doctor\` for setup help.`;
+	const detail = result.stderr.trim();
+	if (detail) return `Agy could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`;
+	return `Agy could not ${action}. Make sure Agy is installed and signed in, then run \`/bro doctor\`.`;
+}
+
+export function parseBroSettings(value: unknown): BroSettings {
+	if (
+		!isRecord(value) ||
+		typeof value.model !== "string" ||
+		!value.model.trim() ||
+		!EFFORTS.some((effort) => effort === value.effort)
+	) {
+		throw new Error('Settings must contain a model and effort set to "default", "low", "medium", or "high".');
+	}
+	return { model: value.model.trim(), effort: value.effort as BroSettings["effort"] };
+}
+
+async function ensureSettingsFile(): Promise<void> {
+	await mkdir(AGENT_DIR, { recursive: true });
+	try {
+		await writeFile(
+			SETTINGS_FILE,
+			`${JSON.stringify({ model: DEFAULT_MODEL, effort: ENV_MODEL ? "default" : "low" }, null, 2)}\n`,
+			{ encoding: "utf8", flag: "wx", mode: 0o600 },
+		);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+}
+
+async function readSettings(): Promise<BroSettings> {
+	await ensureSettingsFile();
+	try {
+		return parseBroSettings(JSON.parse(await readFile(SETTINGS_FILE, "utf8")));
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error(`${SETTINGS_FILE} is not valid JSON.`);
+		if (error instanceof Error) throw new Error(`${SETTINGS_FILE}: ${error.message}`);
+		throw error;
+	}
+}
+
+async function writeSettings(settings: BroSettings): Promise<void> {
+	// ponytail: last writer wins across concurrent Pi processes; add locking only if that becomes a common workflow.
+	await writeFile(SETTINGS_FILE, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+
 export function formatAgyUsage(value: unknown): string {
 	if (!isRecord(value) || value.status !== "SUCCESS" || typeof value.response !== "string") {
 		throw new Error("Agy returned invalid usage data.");
@@ -72,6 +228,96 @@ export function formatAgyUsage(value: unknown): string {
 	return `# Agy usage\n\n${sections.join("\n\n")}`;
 }
 
+export function parseAgyModels(output: string): AgyModelFamily[] {
+	// ponytail: Agy 1.1.13 exposes a tab-separated variant list; use structured catalog data when available here.
+	const families = new Map<string, AgyModelFamily>();
+	for (const line of output.split(/\r?\n/)) {
+		const [rawId, ...rawLabel] = line.split("\t");
+		if (!rawId?.trim() || !rawLabel.length) continue;
+		const id = rawId.trim();
+		const label = rawLabel.join(" ").trim();
+		const effort = (["low", "medium", "high"] as const).find(
+			(value) => id.endsWith(`-${value}`) && label.endsWith(`(${value[0].toUpperCase()}${value.slice(1)})`),
+		);
+		const familyId = effort ? id.slice(0, -effort.length - 1) : id;
+		const family = families.get(familyId) ?? {
+			id: familyId,
+			label: effort ? label.replace(/\s+\((Low|Medium|High)\)$/, "") : label,
+			efforts: [],
+			variants: [],
+		};
+		if (effort && !family.efforts.includes(effort)) family.efforts.push(effort);
+		family.variants.push({ id, effort });
+		families.set(familyId, family);
+	}
+	if (!families.size) throw new Error("Agy returned no available models.");
+	for (const family of families.values()) {
+		family.efforts.sort((a, b) => EFFORTS.indexOf(a) - EFFORTS.indexOf(b));
+	}
+	return [...families.values()];
+}
+
+async function listAgyModels(pi: ExtensionAPI, signal?: AbortSignal): Promise<AgyModelFamily[]> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("agy", ["models"], { cwd: runDirectory, signal, timeout: 30_000 });
+		if (signal?.aborted) throw new Error("Canceled.");
+		if (result.killed || result.code !== 0) throw new Error(agyFailureMessage("list models", result));
+		try {
+			return parseAgyModels(result.stdout);
+		} catch (error) {
+			throw new Error(withDoctor(error));
+		}
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+async function checkAgyVersion(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("agy", ["--version"], { cwd: runDirectory, signal, timeout: 10_000 });
+		if (signal.aborted) throw new Error("Canceled.");
+		if (result.killed || result.code !== 0) throw new Error(agyFailureMessage("start", result));
+		const version = result.stdout.trim() || result.stderr.trim();
+		if (!version) throw new Error("Agy returned no version information. Update Agy, then run `/bro doctor` again.");
+		return version;
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+function resolveCatalogSettings(
+	settings: BroSettings,
+	families: AgyModelFamily[],
+): { settings: BroSettings; family?: AgyModelFamily } {
+	const family = families.find(
+		(item) => item.id === settings.model || item.variants.some((variant) => variant.id === settings.model),
+	);
+	if (!family) return { settings };
+	const variant = family.variants.find((item) => item.id === settings.model);
+	return {
+		family,
+		settings: {
+			model: family.id,
+			effort: settings.effort === "default" && variant?.effort ? variant.effort : settings.effort,
+		},
+	};
+}
+
+function preferredEffort(family: AgyModelFamily): BroEffort {
+	return family.efforts.includes("low") ? "low" : (family.efforts[0] ?? "default");
+}
+
+export function agySelection(settings: BroSettings): { model: string; effort?: AgyEffort } {
+	if (settings.effort === "default") return { model: settings.model };
+	const suffix = (["low", "medium", "high"] as const).find((effort) => settings.model.endsWith(`-${effort}`));
+	return {
+		model: suffix ? settings.model.slice(0, -suffix.length - 1) : settings.model,
+		effort: settings.effort,
+	};
+}
+
 async function checkAgyUsage(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
 	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 	try {
@@ -81,20 +327,92 @@ async function checkAgyUsage(pi: ExtensionAPI, signal: AbortSignal): Promise<str
 			{ cwd: runDirectory, signal, timeout: 35_000 },
 		);
 		if (signal.aborted) throw new Error("Canceled.");
-		if (result.killed) throw new Error("Agy usage check timed out.");
-		if (result.code !== 0) throw new Error(result.stderr.trim() || `Agy exited with code ${result.code}.`);
+		if (result.killed || result.code !== 0) throw new Error(agyFailureMessage("check account usage", result));
 		try {
 			return formatAgyUsage(JSON.parse(result.stdout));
 		} catch (error) {
-			if (error instanceof SyntaxError) throw new Error("Agy returned invalid usage data.");
-			throw error;
+			throw new Error(withDoctor(error instanceof SyntaxError ? "Agy returned invalid usage data." : error));
 		}
 	} finally {
 		await rm(runDirectory, { recursive: true, force: true });
 	}
 }
 
-function latestAssistant(ctx: ExtensionCommandContext): AssistantSource | undefined {
+async function doctorReport(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const lines: string[] = [];
+	let failed = false;
+	let settings: BroSettings | undefined;
+	let models: AgyModelFamily[] | undefined;
+	const pass = (name: string, detail: string) => lines.push(`- ✓ **${name}:** ${detail}`);
+	const fail = (name: string, error: unknown) => {
+		failed = true;
+		lines.push(`- ✗ **${name}:** ${errorMessage(error)}`);
+	};
+
+	try {
+		settings = await readSettings();
+		pass("Settings", "valid");
+	} catch (error) {
+		fail("Settings", error);
+	}
+
+	try {
+		await promptFor("");
+		pass("Prompt", "valid");
+	} catch (error) {
+		fail("Prompt", error);
+	}
+
+	let agyStarted = false;
+	try {
+		pass("Agy", await checkAgyVersion(pi, signal));
+		agyStarted = true;
+	} catch (error) {
+		if (signal.aborted) throw error;
+		fail("Agy", error);
+	}
+
+	if (agyStarted) {
+		try {
+			models = await listAgyModels(pi, signal);
+			pass("Model catalog", `${models.length} model${models.length === 1 ? "" : "s"} available`);
+		} catch (error) {
+			if (signal.aborted) throw error;
+			fail("Model catalog", error);
+		}
+
+		try {
+			await checkAgyUsage(pi, signal);
+			pass("Account", "connected");
+		} catch (error) {
+			if (signal.aborted) throw error;
+			fail("Account", error);
+		}
+	}
+
+	if (settings && models) {
+		const current = resolveCatalogSettings(settings, models);
+		if (!current.family) {
+			fail("Selected model", `\`${settings.model}\` is unavailable. Run \`/bro model\` to choose another.`);
+		} else {
+			pass("Selected model", `\`${current.family.id}\``);
+			const effort = current.settings.effort;
+			if (!current.family.efforts.length && effort === "default") {
+				pass("Reasoning effort", "built into the selected model");
+			} else if (effort !== "default" && current.family.efforts.includes(effort)) {
+				pass("Reasoning effort", effort);
+			} else {
+				fail("Reasoning effort", `\`${effort}\` is unsupported. Run \`/bro effort\` to choose another.`);
+			}
+		}
+	}
+
+	return `# Bro doctor\n\n${lines.join("\n")}\n\n**${failed ? "Bro needs attention." : "Bro is ready."}**\n\n${
+		failed ? "Fix the failed items, then press **R** to check again." : "No assistant response was sent and no model turn was run."
+	}`;
+}
+
+function latestAssistant(ctx: ExtensionCommandContext): BroSource | undefined {
 	const branch = ctx.sessionManager.getBranch();
 
 	for (let i = branch.length - 1; i >= 0; i--) {
@@ -109,7 +427,7 @@ function latestAssistant(ctx: ExtensionCommandContext): AssistantSource | undefi
 			.join("\n")
 			.trim();
 
-		if (text) return { id: entry.id, text };
+		if (text) return { text };
 	}
 }
 
@@ -155,9 +473,11 @@ function parseAgyLine(line: string): { delta?: string; result?: string } {
 async function simplify(
 	response: string,
 	signal: AbortSignal,
+	settings: BroSettings,
 	onProgress?: (text: string) => void,
 ): Promise<string> {
 	const prompt = await promptFor(response);
+	const selection = agySelection(settings);
 	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 	let updateTimer: ReturnType<typeof setTimeout> | undefined;
 
@@ -170,7 +490,8 @@ async function simplify(
 				"--output-format",
 				"stream-json",
 				"--model",
-				MODEL,
+				selection.model,
+				...(selection.effort ? ["--effort", selection.effort] : []),
 				"--print-timeout",
 				"2m",
 				"--print",
@@ -231,14 +552,25 @@ async function simplify(
 
 		const { code, exitSignal } = await closed;
 		if (signal.aborted) throw new Error("Canceled.");
-		if (parseError) throw parseError;
-		if (processError) throw processError;
-		if (exitSignal || code === null) throw new Error("Simplification timed out.");
-		if (code !== 0) throw new Error(stderr.trim() || `Agy exited with code ${code}.`);
+		if (parseError) throw new Error(withDoctor(parseError));
+		if (processError) {
+			const missing = (processError as NodeJS.ErrnoException).code === "ENOENT";
+			throw new Error(
+				missing
+					? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
+					: `Agy could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`,
+			);
+		}
+		if (exitSignal || code === null) {
+			throw new Error("Agy timed out while simplifying the response. Run `/bro doctor` for setup help.");
+		}
+		if (code !== 0) {
+			throw new Error(agyFailureMessage("simplify the response", { code, killed: false, stderr }));
+		}
 
 		const text = final.trim();
 		if (!text) {
-			throw new Error(stderr.trim() || "Agy returned no final explanation.");
+			throw new Error(withDoctor(stderr.trim() || "Agy returned no final explanation."));
 		}
 
 		return text;
@@ -248,38 +580,67 @@ async function simplify(
 	}
 }
 
-function helpText(): string {
+function helpText(settings?: BroSettings, settingsError?: string): string {
+	const settingsSummary = settings
+		? `- **Model:** \`${settings.model}\`\n- **Reasoning effort:** ${settings.effort === "default" ? "built into the selected model" : settings.effort}`
+		: `Bro could not read its settings: ${settingsError}\n\nRun \`/bro doctor\` for setup help.`;
 	return `# Bro
 
-Bro turns the latest completed assistant response into a clear, plain-language explanation.
+Bro turns the latest completed assistant response or a local document into a clear, plain-language explanation.
 
 ## Commands
 
 - \`/bro\` or \`/bro simplify\` — create a new explanation
+- \`/bro file <path>\` — explain a Markdown, text, PDF, or DOCX file
 - \`/bro open\` — reopen the last explanation
+- \`/bro doctor\` — check whether Bro is ready
 - \`/bro usage\` or \`/bro usage --provider agy\` — show current Agy usage
+- \`/bro model\` — choose the Agy model
+- \`/bro effort\` — choose the Agy reasoning effort
 - \`/bro help\` — show this guide
 
+## Documents
+
+\`/bro file\` accepts \`.md\`, \`.markdown\`, \`.txt\`, \`.pdf\`, and \`.docx\` files. Use a relative path or an absolute path inside the current workspace. Paths may contain spaces; matching single or double quotes are optional.
+
+Files are limited to 10 MiB and 100,000 extracted characters. Scanned PDFs need OCR, which Bro does not support. Pressing **R** retries the extracted snapshot; a new \`/bro file <path>\` command reads the file again.
+
+## Current simplifier settings
+
+${settingsSummary}
+
+These choices are saved in:
+
+\`${SETTINGS_FILE}\`
+
+Use the slash commands or edit that file directly. Changes apply to future explanations and remain active across Pi restarts until you change them. Use a model ID shown by \`/bro model\`. Use an effort shown by \`/bro effort\`; fixed-effort models use \`default\`.
+
 ## Controls
 
 - **Mouse wheel / trackpad** — scroll in Pi's fullscreen mode
 - **↑ / ↓** — scroll in any mode
 - **C** — copy the full explanation
-- **R** — simplify the same response again
+- **R** — repeat the current simplification or Doctor check
 - **Esc** — close the window, or cancel while Bro is working
 
+In Pi's regular terminal mode, the Bro title warns that mouse-wheel scrolling needs fullscreen mode. Arrow-key scrolling still works.
+
 Mouse text selection may extend outside the Bro window. Press **C** to copy the complete explanation instead.
 
 ## Privacy and file safety
 
-Bro does not modify your project files. It runs the simplifier in sandbox mode inside a temporary empty folder. This reduces project access, but it is not a security boundary.
+Bro does not modify your project files. It creates and updates only its user settings file shown above. It runs the simplifier in sandbox mode inside a temporary empty folder. This reduces project access, but it is not a security boundary.
 
 Bro does not add explanations to Pi's conversation history, session files, or main-agent context. The latest explanation is kept in process memory only so \`/bro open\` can reopen it. It is cleared when you change sessions, reload extensions, or exit Pi.
 
-Bro sends the assistant response to an external simplifier (currently Agy with a Gemini model). Agy and the model provider may retain request data or logs under their own policies.
+Bro sends the assistant response to an external simplifier (currently Agy with your selected model). Agy and the model provider may retain request data or logs under their own policies.
+
+\`/bro file\` sends the selected document's extracted text to the same external simplifier. Bro reads only regular files whose resolved path remains inside the current workspace, including after resolving symlinks. It never modifies them and does not expose the workspace to Agy.
 
 \`/bro usage\` checks your authenticated Agy limits without sending an assistant response or running a model turn.
 
+\`/bro doctor\` checks your settings, prompt, Agy installation, account, model, and reasoning effort. It contacts Agy but does not send an assistant response or run a model turn.
+
 Pressing **C** copies the explanation to your system clipboard, where your operating system or clipboard manager may retain it.
 
 ## Custom prompt
@@ -290,7 +651,7 @@ You can create or edit:
 
 Bro reads this file when running but never creates or edits it. Include \`{{response}}\` exactly once in your template. Changes take effect on the next simplification.
 
-Set \`PI_BRO_MODEL\` before starting Pi to use a different Agy model.`;
+When the settings file does not exist yet, \`PI_BRO_MODEL\` can choose its initial model.`;
 }
 
 // The overlay framing pattern is adapted from pi-btw (MIT); see THIRD_PARTY_NOTICES.md.
@@ -313,6 +674,7 @@ class BroModal implements Focusable {
 		private readonly onClose: () => void,
 		private readonly onRetry: () => void,
 		private readonly onDispose: () => void,
+		private readonly retryLabel: string,
 	) {}
 
 	setLoading(text = LOADING_TEXT): void {
@@ -373,7 +735,7 @@ class BroModal implements Focusable {
 		if (this.kind === "loading") return "Esc cancel";
 		if (this.kind === "streaming") return "Simplifying… · ↑/↓ scroll · Esc cancel";
 		if (this.kind === "result") {
-			return `↑/↓ scroll · C copy${this.retryable ? " · R simplify again" : ""} · Esc close`;
+			return `↑/↓ scroll · C copy${this.retryable ? ` · R ${this.retryLabel}` : ""} · Esc close`;
 		}
 		if (this.kind === "help") return "↑/↓ scroll · C copy · Esc close";
 		if (this.kind === "error") return "R try again · Esc close";
@@ -392,12 +754,13 @@ class BroModal implements Focusable {
 		this.offset = Math.max(0, Math.min(this.offset, this.maxOffset));
 		const visible = rendered.slice(this.offset, this.offset + this.bodyHeight);
 		const hiddenBelow = Math.max(0, this.maxOffset - this.offset);
+		const modeHint = this.tui.mode === "regular" ? " · mouse wheel needs fullscreen" : "";
 		const scroll = this.maxOffset > 0 ? ` · ↑${this.offset} ↓${hiddenBelow}` : "";
 		const controls = this.notice ? `${this.notice} · ${this.controls()}` : this.controls();
 
 		const lines = [
 			this.borderLine(innerWidth, "top"),
-			this.frameLine(this.theme.fg("accent", this.theme.bold(`Bro${scroll}`)), innerWidth),
+			this.frameLine(this.theme.fg("accent", this.theme.bold(`Bro${modeHint}${scroll}`)), innerWidth),
 			this.ruleLine(innerWidth),
 		];
 
@@ -468,12 +831,13 @@ interface BroModalOptions {
 	result?: ModalResult;
 	run?: (
 		signal: AbortSignal,
-		source?: AssistantSource,
+		source?: BroSource,
 		onProgress?: (text: string) => void,
 	) => Promise<ModalResult>;
 	onResult?: (result: ModalResult) => void;
 	loadingText?: string;
 	retryable?: boolean;
+	retryLabel?: string;
 }
 
 async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptions): Promise<void> {
@@ -490,7 +854,7 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 			let closed = false;
 			let controller: AbortController | undefined;
 			let current = options.result;
-			let execute: (source?: AssistantSource) => void = () => {};
+			let execute: (source?: BroSource) => void = () => {};
 
 			const close = () => {
 				if (closed) return;
@@ -508,9 +872,10 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 					closed = true;
 					controller?.abort();
 				},
+				options.retryLabel ?? "simplify again",
 			);
 
-			execute = (source?: AssistantSource) => {
+			execute = (source?: BroSource) => {
 				if (!options.run || controller || closed) return;
 				const previous = current;
 				const nextController = new AbortController();
@@ -566,7 +931,7 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 	);
 }
 
-export default function bro(pi: ExtensionAPI) {
+export default async function bro(pi: ExtensionAPI) {
 	let lastResult: BroResult | undefined;
 	const remember = (result: ModalResult) => {
 		if (result.source) lastResult = { source: result.source, text: result.text };
@@ -577,16 +942,68 @@ export default function bro(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("bro", {
-		description: "Simplify responses, reopen explanations, or show Agy usage",
+		description: "Simplify responses and manage Bro",
 		getArgumentCompletions: (prefix) => {
 			const normalized = prefix.trim().toLowerCase();
 			const matches = COMMANDS.filter((command) => command.value.startsWith(normalized));
 			return matches.length ? matches : null;
 		},
 		handler: async (args, ctx) => {
-			const normalized = args.trim().toLowerCase();
+			const raw = args.trim();
+			const normalized = raw.toLowerCase();
 			const parts = normalized ? normalized.split(/\s+/) : [];
 			const action = parts[0] ?? "";
+			const value = raw.slice(raw.split(/\s+/, 1)[0]?.length ?? 0).trim();
+
+			if (action === "file") {
+				if (!value) {
+					ctx.ui.notify("Use /bro file <path>.", "warning");
+					return;
+				}
+				const runFile = async (
+					signal: AbortSignal,
+					source?: BroSource,
+					onProgress?: (text: string) => void,
+				): Promise<BroResult> => {
+					const target = source ?? { text: await extractDocumentText(value, ctx.cwd, signal) };
+					try {
+						return {
+							source: target,
+							text: await simplify(target.text, signal, await readSettings(), onProgress),
+						};
+					} catch (error) {
+						throw new Error(withDoctor(error));
+					}
+				};
+				try {
+					await showBroModal(ctx, {
+						loadingText: "Reading and simplifying document…",
+						run: runFile,
+						onResult: remember,
+					});
+				} catch (error) {
+					ctx.ui.notify(errorMessage(error), "error");
+				}
+				return;
+			}
+
+			if (action === "doctor") {
+				if (parts.length !== 1) {
+					ctx.ui.notify("Use /bro doctor.", "warning");
+					return;
+				}
+				try {
+					await showBroModal(ctx, {
+						loadingText: "Checking Bro setup…",
+						retryable: true,
+						retryLabel: "check again",
+						run: async (signal) => ({ text: await doctorReport(pi, signal) }),
+					});
+				} catch (error) {
+					ctx.ui.notify(errorMessage(error), "error");
+				}
+				return;
+			}
 
 			if (action === "usage") {
 				const valid = parts.length === 1 || (parts.length === 3 && parts[1] === "--provider" && parts[2] === "agy");
@@ -601,19 +1018,137 @@ export default function bro(pi: ExtensionAPI) {
 						run: async (signal) => ({ text: await checkAgyUsage(pi, signal) }),
 					});
 				} catch (error) {
-					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+					ctx.ui.notify(withDoctor(error), "error");
+				}
+				return;
+			}
+
+			if (action === "model") {
+				if (parts.length > 2) {
+					ctx.ui.notify("Use /bro model or /bro model <id>.", "warning");
+					return;
+				}
+				try {
+					const settings = await readSettings();
+					const models = await listAgyModels(pi);
+					const current = resolveCatalogSettings(settings, models);
+					const requested = parts[1];
+					let selected: AgyModelFamily | undefined;
+					let selectedEffort: BroEffort | undefined;
+					if (requested) {
+						selected = models.find((item) => item.id.toLowerCase() === requested);
+						if (!selected) {
+							for (const family of models) {
+								const variant = family.variants.find((item) => item.id.toLowerCase() === requested);
+								if (variant) {
+									selected = family;
+									selectedEffort = variant.effort ?? "default";
+									break;
+								}
+							}
+						}
+						if (!selected) {
+							ctx.ui.notify(`Unknown Agy model "${requested}". Run /bro model to see available choices.`, "warning");
+							return;
+						}
+					} else {
+						if (ctx.mode !== "tui") {
+							ctx.ui.notify("Use /bro model <id> outside Pi's interactive UI.", "warning");
+							return;
+						}
+						const ordered = [...models].sort((a, b) => Number(b.id === current.family?.id) - Number(a.id === current.family?.id));
+						const choices = ordered.map(
+							(item) =>
+								`${item.id} — ${item.label} · ${item.efforts.length ? item.efforts.join("/") : "fixed effort"}${item.id === current.family?.id ? " (current)" : ""}`,
+						);
+						const choice = await ctx.ui.select(`Agy model (current: ${current.settings.model})`, choices);
+						if (!choice) return;
+						selected = ordered[choices.indexOf(choice)];
+					}
+					if (!selectedEffort) {
+						const currentEffort = current.settings.effort;
+						const canKeepCurrent =
+							current.family?.id === selected.id &&
+							(currentEffort === "default" ? !selected.efforts.length : selected.efforts.includes(currentEffort));
+						selectedEffort = canKeepCurrent ? currentEffort : preferredEffort(selected);
+					}
+					await writeSettings({ model: selected.id, effort: selectedEffort });
+					ctx.ui.notify(
+						`Bro model: ${selected.id}${selectedEffort === "default" ? "" : ` (${selectedEffort})`}`,
+						"info",
+					);
+				} catch (error) {
+					ctx.ui.notify(withDoctor(error), "error");
+				}
+				return;
+			}
+
+			if (action === "effort") {
+				const requested = parts[1];
+				if (parts.length > 2 || (requested && !EFFORTS.some((effort) => effort === requested))) {
+					ctx.ui.notify("Use /bro effort, or choose low, medium, or high.", "warning");
+					return;
+				}
+				try {
+					const settings = await readSettings();
+					const current = resolveCatalogSettings(settings, await listAgyModels(pi));
+					if (!current.family) {
+						ctx.ui.notify(`Model "${settings.model}" is not in Agy's current model list. Run /bro model first.`, "warning");
+						return;
+					}
+					if (!current.family.efforts.length) {
+						if (requested && requested !== "default") {
+							ctx.ui.notify(`${current.family.label} uses a fixed effort level.`, "warning");
+							return;
+						}
+						await writeSettings({ model: current.family.id, effort: "default" });
+						ctx.ui.notify(`${current.family.label} uses its built-in effort level.`, "info");
+						return;
+					}
+					if (requested === "default" || (requested && !current.family.efforts.includes(requested as AgyEffort))) {
+						ctx.ui.notify(
+							`${current.family.label} supports ${current.family.efforts.join(" or ")} effort.`,
+							"warning",
+						);
+						return;
+					}
+					let selected = requested as AgyEffort | undefined;
+					if (!selected) {
+						if (ctx.mode !== "tui") {
+							ctx.ui.notify("Use /bro effort <low|medium|high> outside Pi's interactive UI.", "warning");
+							return;
+						}
+						const efforts = [...current.family.efforts].sort(
+							(a, b) => Number(b === current.settings.effort) - Number(a === current.settings.effort),
+						);
+						const choices = efforts.map((effort) => `${effort}${effort === current.settings.effort ? " (current)" : ""}`);
+						const choice = await ctx.ui.select(`Agy reasoning effort (current: ${current.settings.effort})`, choices);
+						if (!choice) return;
+						selected = efforts[choices.indexOf(choice)];
+					}
+					await writeSettings({ model: current.family.id, effort: selected });
+					ctx.ui.notify(`Bro reasoning effort: ${selected}`, "info");
+				} catch (error) {
+					ctx.ui.notify(withDoctor(error), "error");
 				}
 				return;
 			}
 
 			if (normalized === "help") {
-				await showBroModal(ctx, { text: helpText(), kind: "help", copyable: true });
+				let settings: BroSettings | undefined;
+				let settingsError: string | undefined;
+				try {
+					settings = await readSettings();
+				} catch (error) {
+					settingsError = errorMessage(error);
+				}
+				await showBroModal(ctx, { text: helpText(settings, settingsError), kind: "help", copyable: true });
 				return;
 			}
 
 			const run = async (
 				signal: AbortSignal,
-				source?: AssistantSource,
+				source?: BroSource,
 				onProgress?: (text: string) => void,
 			): Promise<BroResult> => {
 				let target = source;
@@ -622,13 +1157,21 @@ export default function bro(pi: ExtensionAPI) {
 					target = latestAssistant(ctx);
 				}
 				if (!target) throw new Error("No completed assistant response found.");
-				return { source: target, text: await simplify(target.text, signal, onProgress) };
+				try {
+					const settings = await readSettings();
+					return {
+						source: target,
+						text: await simplify(target.text, signal, settings, onProgress),
+					};
+				} catch (error) {
+					throw new Error(withDoctor(error));
+				}
 			};
 
 			if (normalized === "open") {
 				if (!lastResult) {
 					await showBroModal(ctx, {
-						text: "# Nothing to open yet\n\nRun `/bro` after an assistant response.",
+						text: "# Nothing to open yet\n\nRun `/bro` after an assistant response, or use `/bro file <path>`.",
 						kind: "empty",
 					});
 					return;
@@ -643,7 +1186,7 @@ export default function bro(pi: ExtensionAPI) {
 			}
 
 			if (normalized && normalized !== "simplify") {
-				ctx.ui.notify(`Unknown action "${normalized}". Use simplify, open, usage, or help.`, "warning");
+				ctx.ui.notify(`Unknown action "${normalized}". Use simplify, file, open, doctor, usage, model, effort, or help.`, "warning");
 				return;
 			}
 
@@ -657,4 +1200,7 @@ export default function bro(pi: ExtensionAPI) {
 			}
 		},
 	});
+
+	// Keep the command available even when Bro cannot create its settings file; Doctor can then explain the problem.
+	await ensureSettingsFile().catch(() => undefined);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-bro",
-  "version": "0.4.0",
-  "description": "An Earendil Pi extension that simplifies the latest assistant response in a separate, context-isolated window.",
+  "version": "0.7.0",
+  "description": "An Earendil Pi extension that explains assistant responses and local documents in a context-isolated window.",
   "type": "module",
   "license": "MIT",
   "author": "Tran Hoang Nguyen",
@@ -17,6 +17,9 @@
     "pi-package",
     "pi-extension",
     "pi-coding-agent",
+    "document",
+    "pdf",
+    "docx",
     "simplify",
     "agy",
     "gemini",
@@ -53,5 +56,9 @@
     "@earendil-works/pi-tui": "0.84.2",
     "@types/node": "^24.0.0",
     "typescript": "6.0.2"
+  },
+  "dependencies": {
+    "mammoth": "^1.12.1",
+    "unpdf": "^1.8.1"
   }
 }