pi-bro 0.5.0 → 0.7.0

package/README.md

@@ -1,7 +1,7 @@
 # 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
@@ -10,17 +10,17 @@ 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>
@@ -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,7 +299,9 @@ 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. |
@@ -312,12 +315,40 @@ pi -e npm:pi-bro
 - **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:
@@ -361,7 +392,7 @@ 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}}
 ```
 
@@ -370,19 +401,22 @@ immediately without reloading Pi. Bro never creates or modifies this file.
 
 ## 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. Bro only writes its own user settings file described
-  above.
+- **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
@@ -391,6 +425,8 @@ immediately without reloading Pi. Bro never creates or modifies this file.
 ## 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
@@ -409,8 +445,8 @@ 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, settings, 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,11 +1,13 @@
 import { spawn } from "node:child_process";
-import { mkdir, mkdtemp, readFile, rm, writeFile } 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";
+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();
@@ -13,22 +15,25 @@ 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 = { 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">;
@@ -55,7 +60,9 @@ 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" },
@@ -66,6 +73,99 @@ 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) ||
@@ -157,13 +257,31 @@ export function parseAgyModels(output: string): AgyModelFamily[] {
 	return [...families.values()];
 }
 
-async function listAgyModels(pi: ExtensionAPI): Promise<AgyModelFamily[]> {
+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", ["models"], { cwd: runDirectory, timeout: 30_000 });
-		if (result.killed) throw new Error("Agy model check timed out.");
-		if (result.code !== 0) throw new Error(result.stderr.trim() || `Agy exited with code ${result.code}.`);
-		return parseAgyModels(result.stdout);
+		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 });
 	}
@@ -209,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--) {
@@ -237,7 +427,7 @@ function latestAssistant(ctx: ExtensionCommandContext): AssistantSource | undefi
 			.join("\n")
 			.trim();
 
-		if (text) return { id: entry.id, text };
+		if (text) return { text };
 	}
 }
 
@@ -362,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;
@@ -379,24 +580,34 @@ async function simplify(
 	}
 }
 
-function helpText(settings: BroSettings): 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
 
-- **Model:** \`${settings.model}\`
-- **Reasoning effort:** ${settings.effort === "default" ? "built into the selected model" : settings.effort}
+${settingsSummary}
 
 These choices are saved in:
 
@@ -409,7 +620,7 @@ Use the slash commands or edit that file directly. Changes apply to future expla
 - **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.
@@ -424,8 +635,12 @@ Bro does not add explanations to Pi's conversation history, session files, or ma
 
 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
@@ -459,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 {
@@ -519,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";
@@ -615,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> {
@@ -637,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;
@@ -655,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();
@@ -714,7 +932,6 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 }
 
 export default async function bro(pi: ExtensionAPI) {
-	await ensureSettingsFile();
 	let lastResult: BroResult | undefined;
 	const remember = (result: ModalResult) => {
 		if (result.source) lastResult = { source: result.source, text: result.text };
@@ -732,9 +949,61 @@ export default async function bro(pi: ExtensionAPI) {
 			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");
@@ -749,7 +1018,7 @@ export default async 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;
 			}
@@ -809,7 +1078,7 @@ export default async function bro(pi: ExtensionAPI) {
 						"info",
 					);
 				} catch (error) {
-					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+					ctx.ui.notify(withDoctor(error), "error");
 				}
 				return;
 			}
@@ -860,23 +1129,26 @@ export default async function bro(pi: ExtensionAPI) {
 					await writeSettings({ model: current.family.id, effort: selected });
 					ctx.ui.notify(`Bro reasoning effort: ${selected}`, "info");
 				} catch (error) {
-					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+					ctx.ui.notify(withDoctor(error), "error");
 				}
 				return;
 			}
 
 			if (normalized === "help") {
+				let settings: BroSettings | undefined;
+				let settingsError: string | undefined;
 				try {
-					await showBroModal(ctx, { text: helpText(await readSettings()), kind: "help", copyable: true });
+					settings = await readSettings();
 				} catch (error) {
-					ctx.ui.notify(error instanceof Error ? error.message : String(error), "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;
@@ -885,17 +1157,21 @@ export default async function bro(pi: ExtensionAPI) {
 					target = latestAssistant(ctx);
 				}
 				if (!target) throw new Error("No completed assistant response found.");
-				const settings = await readSettings();
-				return {
-					source: target,
-					text: await simplify(target.text, signal, settings, 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;
@@ -910,7 +1186,7 @@ export default async function bro(pi: ExtensionAPI) {
 			}
 
 			if (normalized && normalized !== "simplify") {
-				ctx.ui.notify(`Unknown action "${normalized}". Use simplify, open, usage, model, effort, or help.`, "warning");
+				ctx.ui.notify(`Unknown action "${normalized}". Use simplify, file, open, doctor, usage, model, effort, or help.`, "warning");
 				return;
 			}
 
@@ -924,4 +1200,7 @@ export default async 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.5.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"
   }
 }