pi-bro 0.23.1 → 0.25.0

package/docs/features/advisor.md

@@ -0,0 +1,70 @@
+# Agent second opinions (Advisor)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Bro advisor
+
+`bro_advisor` is a tool the **executor agent** — not you — can voluntarily
+call mid-task for a second opinion. Unlike `/bro btw`, which is a side
+conversation for you, `bro_advisor` is a tool for the model you're working
+with; it shows up as a normal tool call/result in the transcript, not a
+modal. It is registered like any other tool when the extension loads and has
+no on/off switch of its own — whether the executor can actually call it
+depends entirely on this host's own tool restrictions.
+
+`/bro advisor` is a quick notice of whether `bro_advisor` is available right
+now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`.
+`/bro doctor` has the full diagnostic: whether this host exposes and
+activates `bro_advisor`, its resolved backend/model/effort, steering
+presence, and backend compatibility (for Agy, a minimum CLI version with an
+`agy update` action when it is too old).
+
+- **Automatic context, no prep needed**: the executor does not need to assemble
+  a summary. Bro captures a harness-neutral snapshot — the executor's system
+  instructions, its active tools, and the conversation so far including tool
+  calls and results — and sends it, along with an optional `question` the
+  executor may pass, to a **fresh, standalone process of the selected
+  backend** for every consultation. Nothing is resumed or reused across calls,
+  including retries.
+- **Instructed to investigate, not implement**: the advisor process has real
+  tool access in the workspace with permissions auto-approved — there is no
+  enforced read-only isolation. It is instructed to verify claims itself and
+  return advice, leaving edits to the executor, but that boundary is a
+  behavioral prompt instruction rather than an enforced sandbox constraint, so
+  treat its findings as advice to verify, not a guaranteed hands-off review.
+- **Steering**: The advisor reads standing priorities from `~/.pi/agent/bro-advisor.md`
+  and session-specific priorities from `/bro advisor-steer`.
+  `/bro advisor-steer` opens an editor for one session steering brief — e.g. "quick
+  prototype; keep A and B careful, everything else minimal". Session steering takes
+  precedence over durable standing defaults where they conflict.
+  **Ctrl+S** saves and keeps the editor open; **Enter** or **Shift+Enter** inserts
+  a newline; **Ctrl+K** clears both the saved session brief and draft while staying open;
+  **Ctrl+C** copies the entire current draft, including unsaved edits; and **Esc**
+  closes without saving unsaved edits. Neither steering source is **ever added to Pi's
+  conversation or sent to the main model** — the advisor is the only thing that reads them.
+- **Persistence**: standing defaults persist across all sessions in `~/.pi/agent/bro-advisor.md`.
+  The session steering brief persists with the Pi session as custom extension data in the
+  session file (`bro-advisor-steering`) and is restored on resume or reload. Forking a
+  session inherits session steering; edits made after the fork are independent of the
+  original branch. Clearing session steering leaves durable steering intact.
+- **Retries**: on an invocation failure (not a completed answer — "I need
+  more evidence" is a normal result, not a failure), Bro retries with the
+  identical snapshot, steering, and question: once after 5 seconds, once more
+  after 10 seconds, then returns the backend's own diagnostic — including a
+  context-length error, verbatim — as the failure. Host-imposed deadlines and
+  cancellation are terminal: neither starts another attempt or a backoff wait.
+  The advisor CLI is asked to stop at 10 minutes; Bro's host deadline is 610
+  seconds plus bounded process cleanup. A CLI-reported error before that host
+  deadline remains an invocation failure and can be retried.
+  Cancelling the tool call skips any pending retry wait.
+- **Progress and provenance**: while an attempt is running, Bro shows the last
+  thing the advisor actually reported — a tool name or a user-facing response
+  line, never hidden reasoning — and how long ago it arrived, e.g. `last
+  reported: Read src/app.ts (2s ago)`, or "awaiting first activity" before
+  anything arrives. Expanding a running consultation shows up to the last 4
+  reported activity lines; each retry starts the trail over. The returned
+  answer starts with backend, model, effort, attempt count, duration,
+  workspace, steering presence, snapshot size, and known omission/compaction
+  notes; the advisor's complete answer follows unchanged.
+- **Model/effort**: resolved the same way as explain/show/btw, through
+  `/bro config` (shared default or per-capability override).

package/docs/features/btw.md

@@ -0,0 +1,51 @@
+# Side questions (BTW)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Bro btw (side conversation)
+
+`/bro btw` opens a separate multi-turn conversation in a modal, so you can ask
+a quick side question while the main agent keeps working. It runs through the
+selected backend and never adds anything to Pi's conversation unless you
+explicitly insert it into the editor. Bro writes for a tired reader: the point
+first, in plain words, at a length that fits the question, in the language you
+asked in.
+
+- `/bro btw <question>` asks immediately; `/bro btw` opens an empty thread.
+  Reopening keeps the thread and its mode.
+- **Two modes, toggled with `/mode`**: a new thread starts
+  **conversation-only**; type `/mode` in the modal to switch to **full
+  permission** (read and edit the workspace, run commands) and again to switch
+  back. The conversation is kept across switches. How conversation-only is
+  enforced depends on the backend — see
+  [Backends: access and retention](../reference/data-and-permissions.md#backends-access-and-retention).
+  **Conversation-only does not mean a hard sandbox on every backend:** Grok
+  relies on an instruction; Codex and Muse can retain some read, shell, or
+  network abilities under their own restricted settings. Do not send secrets
+  on the assumption that the model cannot access anything else.
+- Every new or cleared thread is seeded with up to the last 8 turns of
+  main-session user/assistant conversation text (40,000 characters max, with a
+  truncation notice). Later turns continue the backend's native session; in
+  full permission mode the side agent can also read the repo itself.
+- **In the modal**: type a question and press Enter (empty Enter re-asks the
+  last question). Composer actions trigger only on these exact commands:
+  - `/mode`: toggles conversation-only / full permission, keeping the thread
+  - `/copy`: copies the latest answer to the system clipboard
+  - `/copy-all`: copies the full thread to the system clipboard
+  - `/insert`: inserts the latest answer into the main editor without submitting
+  - `/insert-all`: inserts the full thread into the main editor without submitting
+  - `/retry`: re-asks the last question (empty Enter does the same)
+  - `/clear`: resets the thread
+
+  `/insert` and `/insert-all` never replace an existing main-editor draft:
+  edit or clear it first. Any other text, including other slash-prefixed input
+  such as `/send`, is sent as a question. Esc closes the modal and stops a
+  running turn; the thread is kept. The view follows the newest text while you
+  are at the bottom; scroll up to read earlier turns. The header shows the model and reasoning effort the latest
+  turn used (`default` when the model's own effort applies) and the current
+  mode.
+- A turn is capped at 2 minutes in conversation-only mode and 10 minutes in
+  full permission mode.
+- Bro's thread lives in memory only — it clears when you switch Pi sessions,
+  reload extensions, or quit Pi. Changing the BTW backend starts a fresh
+  thread; native session IDs never cross backends.

package/docs/features/explain.md

@@ -0,0 +1,92 @@
+# Explain text, files and webpages
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Explanation modes
+
+Bro treats quoted source as data and asks the model to ignore embedded
+instructions found in it. This is a prompt instruction, not an enforced security
+boundary. Bro preserves the source's language (unless your [preferences](../reference/settings.md#preferences) name another), and avoids
+adding facts, advice, or conclusions in every mode. Choose
+a persistent mode with `/bro mode`, or press **M** in an explanation to try the
+next mode without saving it:
+
+- **`brief`**: Uses the original audience-led ELI-simpleton prompt with no fixed
+  word target.
+- **`balanced`**: The default. Keeps important details, conditions, warnings,
+  context, code, and formatting while trimming fluff and repetition.
+- **`faithful`**: Simplifies the language while preserving every claim,
+  qualification, warning, number, command, code block, and formatting choice.
+
+### Modal controls
+
+- **Mouse wheel / trackpad**: Scroll in regular or fullscreen mode
+- **↑ / ↓**: Scroll in any mode
+- **PgUp / PgDn**: Scroll a page at a time (also in btw)
+- **C**: Copy the complete explanation
+- **R**: Simplify the captured source again in the mode shown, or run the
+  current Doctor check again
+- **M**: Re-simplify the captured source in the next mode (brief → balanced →
+  faithful → brief). It applies to this explanation only and does not change
+  the mode saved by `/bro mode`; pressing it again while Bro is working skips
+  ahead
+- **O**: Open the diagram (an HTML layout or a rendered sequence diagram) when a show reply contains one
+- **Esc**: Close the modal, or cancel while Bro is working
+
+The modal header shows the model and reasoning effort the explanation or
+drawing used (`default` when the model's own effort applies), followed by the
+explanation mode, and `prefs` when your [preferences](../reference/settings.md#preferences) shaped the
+result; `/bro open` keeps the original labels, mode, and tag.
+
+Bro temporarily captures mouse input while its modal is open. Native mouse
+selection may be unavailable or visually extend outside the modal depending on
+your terminal mode; press **C** to copy the complete explanation reliably.
+
+## Explain pasted text
+
+Paste text directly after the command:
+
+```text
+/bro text OAuth refresh tokens are rotated after every successful use.
+```
+
+Bro explains the pasted text instead of the latest assistant reply. With no text
+after `/bro text`, it falls back to the latest completed reply. Press **R**
+to simplify the same captured text again.
+
+## 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.
+
+## Explain a webpage
+
+Pass one public HTTP or HTTPS page:
+
+```text
+/bro url https://example.com/complicated-article
+```
+
+Bro fetches the page, extracts its main readable text locally, and sends only
+that text through the existing explanation flow. The completed modal shows the
+final website and page title. Pressing **R** retries the captured page without
+fetching again; running a new `/bro url <url>` command fetches a fresh copy.
+
+The first version is intentionally limited to one public, text-based page. It
+does not use browser cookies, sign in, run page JavaScript, bypass paywalls or
+bot protection, load complete discussion threads, follow pagination, or
+understand images and video. Pages that depend on those features may fail.
+
+If Bro cannot read a page, copy its content into a `.txt` or `.md` file, or save
+it as a PDF, then use `/bro file <path>`.

package/docs/features/show.md

@@ -0,0 +1,154 @@
+# Visualize a session (Show)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Bro show
+
+Where the explanation modes rewrite dense prose in simpler words, `/bro show`
+changes the form: it draws what you and the assistant said in the last few
+session turns as a shape instead of paragraphs. Capture keeps only user and
+assistant conversation text, including every intermediate assistant message in
+a turn — tool calls, tool results, reasoning, and images never leave the
+session. It runs the same backend-specific model call and shows the result
+in the same modal, never touching your conversation. `/bro show` uses its own
+draw prompt; the explanation modes do not affect it. Your
+[preferences](../reference/settings.md#preferences) can change only its wording and language, never
+which shapes it draws or its rules.
+
+Because the draw model only ever sees conversation text, its shapes reflect
+what was *reported* in the conversation — what the assistant said it did or
+found — not an independent check against the actual code or system state.
+
+Shapes are terminal-first: pseudocode, call trees, file trees, component
+trees, diffs, and types and signatures. Bro picks the shape from what
+happened in the session; there is no flag to request a specific one. When the source has no code structure
+to draw, Bro falls back to a plain outline instead of forcing a diagram. A
+reply that ends in one self-contained HTML block — layout, a state comparison,
+anything where position itself carries meaning — is written to a file and
+opened with **O**.
+
+When the turns describe messages passing among three or more participants in
+a set order (for example browser → API → database), a reply can instead end in
+one Mermaid `sequenceDiagram`. The modal keeps its source visible with
+`[Diagram saved — press O to render]`; **O** opens a page that draws it with
+the Mermaid copy bundled in Bro. Any other Mermaid stays plain text.
+
+Pressing **R** redraws the same captured turns; running `/bro show` again
+captures the latest turns afresh. `/bro show <n-turns>` overrides the default turn
+count for a single run.
+
+Add a query to steer what the shapes focus on, either after a turn count or on
+its own: `/bro show what changed in the auth flow`, or `/bro show 3 what
+changed in the auth flow`. The query is used as a lens on the captured turns,
+not as additional evidence, and its casing is preserved as typed. Pressing
+**R** retries with the same turn count and query.
+
+Any leading whitespace-delimited word that looks like a number is treated as the
+requested turn count: for example, `/bro show 3 what changed` captures 3 turns
+and steers on "what changed", while `/bro show 404 handler` parses "404" as the
+turn count and "handler" as the steering query. To steer on a phrase that starts
+with digits while choosing a turn count, specify the turn count explicitly
+first: `/bro show 1 404 handler` captures 1 turn and steers on "404 handler".
+If the first word is not a number, the whole input is treated as the steering
+query using the saved `showTurns` default.
+
+### A slow session-create, traced
+
+The agent followed a two-second delay from the handler down to the worker.
+`/bro show` drew the chain:
+
+```text
+handleCreateSession(req)
+├── validateRequest(req)
+├── SessionStore.insert(req.body)
+└── publish('session.created')
+    └── AgentWorker.run(sessionId)
+        ├── loadContext(sessionId)
+        ├── callModel(context)
+        └── persistResult(sessionId, result)
+```
+
+### The shape of code before it exists
+
+A design discussion agreed on the data model ahead of implementation. `/bro
+show` kept just the shape:
+
+```typescript
+interface Item { id: ItemId; parentId: ItemId | null }
+interface Cursor { position: ItemId; direction: 'up' | 'down' }
+function resolveTarget(items: Item[], cursor: Cursor): ItemId | null
+```
+
+### A layout that collapses at narrow widths
+
+Text can't show a before/after layout change at a glance, so Bro ends with one
+self-contained HTML block and **O** opens it (the terminal first shows
+`[HTML diagram saved — press O to open]`):
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-show-layout.png">
+    <img alt="A before/after dashboard grid" src="https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-show-layout.png" width="720">
+  </a>
+</p>
+
+<details>
+<summary><strong>More shapes</strong></summary>
+
+**Diff** — what changed in the save handler:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+**File layout** — where everything lives, for a refactor:
+
+```text
+src/
+├── commands/           # user intents
+│   ├── registry.ts
+│   └── show-me.ts
+├── sessions/           # state and lifecycle
+│   ├── events.ts
+│   ├── store.ts
+│   └── worker.ts
+├── transport/          # API
+│   ├── client.ts
+│   └── stream.ts
+└── config.ts           # root config
+```
+
+**Component tree** — what the session page renders:
+
+```text
+SessionPage (apps/example/src/routes/session.tsx)
+├── [hook] useSessionEvents
+├── SessionToolbar (packages/ui)
+│   └── RunSkillButton
+└── SessionTimeline (packages/ui)
+    └── SkillResultCard
+```
+
+**Pseudocode** — how scroll capture and restore work:
+
+```text
+capture(blocks, targetRect, scrollRect) -> Snapshot:
+  target = focusedBlock ?? firstBlockIntersectingViewportTop(blocks)
+  anchor = wholeBlockAnchor(blocks, target)
+  offset = targetRect.top - scrollRect.top
+  return { anchor, offset, scrollTop, revision + 1 }
+
+restore(snapshot, blocks) -> number:
+  placement = resolveAnchor(blocks, snapshot.anchor)
+  if placement: return scrollRect.top + targetRect.top - snapshot.offset
+  return snapshot.scrollTop
+```
+
+</details>
+
+Prose in, outline out: a purely conversational session with no code to draw
+degrades to a plain outline of the discussion — never a forced diagram.

package/docs/getting-started.md

@@ -0,0 +1,47 @@
+# Getting started with Pi-bro
+
+Pi-bro helps you understand agent replies, ask side questions, and review work without filling your main Pi conversation.
+
+## 1. Install
+
+You need **Pi**, Node.js 22.19.0 or later, and one supported backend CLI already installed and signed in (Agy, Claude, Grok, Codex, or Muse). See [requirements](../README.md#requirements).
+
+```sh
+pi install npm:pi-bro
+```
+
+Restart Pi (or run `/reload`). Then run:
+
+```text
+/bro doctor
+```
+
+**Expected:** A diagnostic view shows your selected backend, model, and any setup problems. This check does not prove that a live provider request will succeed. If it fails, [check your setup](reference/troubleshooting.md#check-your-setup).
+
+## 2. Get your first result
+
+Copy this complete command into Pi:
+
+```text
+/bro text A request limit means a service allows only a certain number of calls in a given time.
+```
+
+**Expected:** A Bro window opens and explains the sentence in simpler words. The exact answer depends on the backend. Use the arrow keys to scroll, **C** to copy, or **Esc** to close. Bro doesn't insert this result into your main agent's context.
+
+This step makes a **real model call**, which may use your backend account's quota or incur charges.
+
+## 3. Try the next useful command
+
+| I want to… | Command |
+| --- | --- |
+| Understand the last agent answer | `/bro` (after the main agent has replied) |
+| Ask a side question | `/bro btw What is a race condition?` |
+| Visualize what we discussed | `/bro show` (after at least one user turn) |
+| Explain a file in my workspace | `/bro file docs/my-report.md` (**replace with an existing path**) |
+| Explain an actual public webpage | `/bro url https://your-public-page.example` (**replace with a real URL**) |
+
+See the [docs home](README.md) for detailed workflows.
+
+## Data and access before you use Bro at work
+
+Bro sends your selected text and some context to the backend CLI and model provider you configure. BTW and the advisor have different access rules; some modes can read or change local files. Read [What leaves your machine](../README.md#what-leaves-your-machine) and the [backend access matrix](reference/data-and-permissions.md#backends-access-and-retention) before using private data. A model prompt saying 'do not access' is not a security boundary.

package/docs/guided-review.md

@@ -6,7 +6,7 @@ The normal journey is: **open a PR → read and investigate → leave when satis
 
 ## Open a review
 
-Requirements: local Pi interactive mode, Git, authenticated GitHub CLI (`gh`), and Claude or Muse configured for review. Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup but does not prove GitHub access or model connectivity.
+Requirements: local Pi interactive mode, Git, authenticated GitHub CLI (`gh`), and a configured review backend (Claude or Muse is recommended for untrusted PRs). Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup and shows an advisory when the review backend uses a shell-capable sandbox, without proving GitHub access or model connectivity.
 
 ```text
 /bro guided-review https://github.com/OWNER/REPO/pull/123
@@ -20,12 +20,6 @@ A URL works even when your current workspace belongs to a different repository.
 
 A **new** review captures the PR's base/head commits outside your working tree and automatically makes one model request. Subsequent questions each make another request. Calls use your selected backend CLI's account and billing—not Pi's model account. Bro does not automatically retry a failed generation or switch backends.
 
-For fullscreen mouse scrolling, start Pi with:
-
-```sh
-pi --tui-mode fullscreen
-```
-
 Opening the **same PR again** restores its saved review without another model call. Bare `/bro guided-review` lists saved reviews; `/bro guided-review resume` remains an alias for that list.
 
 **Reopening keeps the captured code.** It does not fetch a new comparison when the author pushes commits. Opening by URL/number checks current metadata and reports newer source, but continues the saved capture. The saved-review picker does not check freshness. Reviewing newer revisions is not implemented.
@@ -63,7 +57,7 @@ The generation header shows observable application stages and elapsed time—not
 | Close | Save automatically and leave |
 | Stop and close | Stop active work, await cancellation, save partial work, then leave |
 
-In fullscreen mode, the wheel scrolls the pane under the pointer without moving its list selection or keyboard focus. Reading an active answer pauses following; deliberately returning to the bottom resumes it. In regular terminal mode, the wheel belongs to terminal scrollback.
+The wheel scrolls the pane under the pointer without moving its list selection or keyboard focus, in regular and fullscreen mode. Reading an active answer pauses following; deliberately returning to the bottom resumes it. In regular terminal mode, Bro captures the mouse while the review is open (as its other windows do), so terminal scrollback and mouse text selection return when you close it; use the copy actions meanwhile.
 
 ## Ask privately, if needed
 
@@ -89,13 +83,15 @@ Use Overview → Regenerate guide only when you want a fresh explanation/assessm
 
 ## Access, privacy and storage
 
-Review uses **file-only inspection**, not full-access execution. Claude runs with `--restricted`, Read/Grep/Glob only, `dontAsk`, safe mode and no MCP; Muse disables write, shell and web tools, foreign personal context and native session logs, without trusting repository rules. No model-run project tests, commands, Git or network tools are available. Unsupported/older CLI flags fail visibly; there is no full-access fallback.
+Review never runs with full-access or bypass flags. **Claude and Muse provide strict file-only inspection** and are recommended for untrusted PRs: Claude runs with `--restricted`, Read/Grep/Glob only, `dontAsk`, safe mode and no MCP; Muse disables write, shell and web tools, foreign personal context and native session logs, without trusting repository rules. No model-run project tests, commands, Git or network tools are available on Claude or Muse.
+
+**Codex, Grok and Agy run with shell available inside their own sandbox**, and each sandbox is different: Codex and Grok apply a read-only sandbox (`codex exec --sandbox read-only --ephemeral`, `grok --sandbox read-only --permission-mode dontAsk`), while Agy's `--sandbox` only restricts terminal commands and still lets them write inside the project. All three inspect the captured checkout with a 10-minute review deadline, and **none is shell-free**. When one of these backends is selected for review, Bro shows an advisory during acquisition, in the live review workspace, and in `/bro doctor` (as a non-fatal informational note). Set the **review** override to Claude or Muse in `/bro config` for untrusted PRs; saved reviews remain readable with any backend. Unsupported/older CLI flags fail visibly; there is no bypass fallback.
 
-Agy, Grok and Codex are not available for review generation/questions: supported controls do not establish equivalent shell-free inspection (Codex read-only sandbox still executes commands). Set the **review** override to Claude or Muse in `/bro config`; shared defaults and other features are unchanged. Saved reviews remain readable without a supported model backend. Doctor shows the review override requirement as information; it does not make an otherwise healthy installation fail.
+Captured evidence is read from pinned Git blobs, so a shell-capable backend that writes inside the checkout cannot alter the code shown as evidence — but it can still change what it later reads, so treat very large changes with suspicion when using Agy.
 
 These controls reduce malicious-code execution/write risk, but repository content can still manipulate the model's conclusions. Captured content, questions and answers go to the provider; do not use review as a secrets boundary or approval certificate. CLI enforcement and managed host policies remain the backend's responsibility.
 
-PR identity/description, diff, relevant saved discussion and your Bro preferences are sent to the selected backend. It can read the captured source. Main-session conversation is not automatically attached. Each request reconstructs context; review does not resume BTW/native sessions. Claude/Muse disable native session persistence where their CLIs support it; backend/provider retention policies still apply.
+PR identity/description, diff, relevant saved discussion and your Bro preferences are sent to the selected backend. It can inspect the captured source. Main-session conversation is not automatically attached. Each request reconstructs context; review does not resume BTW/native sessions. Claude, Muse and Codex disable native session persistence where their CLIs support it; backend/provider retention policies still apply.
 
 Records, private text and captured source remain under:
 
@@ -112,7 +108,7 @@ One open writer per review is supported within a Pi process. Concurrent editing
 | Problem | What to do |
 | --- | --- |
 | GitHub unavailable when reopening | Use bare `/bro guided-review` to choose a saved review; the picker does not fetch |
-| Unsupported review backend | Choose Claude or Muse for review in `/bro config`; no automatic switching |
+| Sandboxed shell review backend (Codex, Grok, Agy) | Advisory shown; choose Claude or Muse in `/bro config` for strict file-only inspection on untrusted PRs |
 | Git/gh authentication or fetch error | Read the acquisition error; check Git/`gh auth status`; retry explicitly |
 | Invalid/failed preparation | Changed files remain available; use Prepare guide to retry when ready for another call |
 | Failed regeneration | Current guide is kept; retry only if you want another call |

package/docs/pig-compatibility.md

@@ -22,6 +22,7 @@ Bro follows the host's `getAgentDir()`: normally `~/.pi/agent` on Pi and `~/.pig
 
 - **PiG 0.3.0 RPC does not enforce `--exclude-tools`.** Excluded tools may remain active and reach provider requests. This is not a sandbox boundary. Use an explicit `--tools` allowlist instead; do not rely on `/bro doctor` to prove exclusion. Bro does not mask this defect by falsely reporting an active tool as unavailable.
 - The smoke suite retains Pi's strict exclusion assertion. The PiG lane has an explicit version-specific expected failure; a changed result fails the lane so the exception must be reviewed/removed.
+- Elevate is not yet qualified end-to-end on PiG. Interactive behavior, keyboard shortcut delivery and guarded editor insertion must be checked on PiG before claiming support.
 - Guided Review currently targets local Pi interactive mode. Its capture/reading/question/regeneration journey is not qualified on PiG or RPC/Desktop; existing Bro PiG checks do not establish review support. See [current review scope](guided-review.md#not-available-yet).
 - Mouse-wheel forwarding is not qualified; use keyboard scrolling.
 - Remote/SSH OSC 52 clipboard forwarding is not qualified. Local clipboard behavior depends on the host and installed platform utilities.

package/docs/reference/commands.md

@@ -0,0 +1,50 @@
+# Command reference
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## What Bro can explain
+
+| Source | Command | What Bro does |
+| --- | --- | --- |
+| Latest assistant reply | `/bro` | Explains the latest completed reply without adding the result to the conversation. |
+| Pasted text | `/bro text <text>` | Explains text supplied directly in the command. |
+| Local document | `/bro file <path>` | Extracts text from a workspace-local Markdown, text, PDF, or DOCX file. |
+| Public webpage | `/bro url <url>` | Fetches one public HTML page and extracts its main readable content. |
+| Recent session turns | `/bro show` | Draws the last turns' conversation text as shapes instead of prose (tool calls, tool results, reasoning, and images are omitted). |
+| Any of the above, auto-detected | `/bro <input>` | Routes a lone URL to the webpage reader, an existing workspace file with a supported extension to the document reader, and anything else to pasted text. |
+
+Pressing **R** simplifies the captured source again in the mode shown, and
+**M** re-simplifies it in the next mode. These commands capture a
+new source: `/bro text`, `/bro file`, `/bro url`, and `/bro show`. Giving `/bro` a URL, path, or
+text directly captures a new source the same way.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/bro`, `/bro simplify`, or `/bro text` | Explain the latest completed assistant response. |
+| `/bro text <text>` | Explain pasted text. |
+| `/bro <input>` | Explain it directly: a lone URL runs the webpage reader, an existing workspace file with a supported extension runs the document reader, and anything else is pasted text. A quoted path with spaces is routed too when the file exists. |
+| `/bro file <path>` | Explain a workspace-local `.md`, `.markdown`, `.txt`, `.pdf`, or `.docx` file. |
+| `/bro url <url>` | Explain one public, text-based webpage. |
+| `/bro open` | Reopen the latest explanation without calling the simplifier again. |
+| `/bro show [n-turns] [query]` | Draw recent session turns (default last 1) as shapes instead of prose, from user and assistant conversation text only — tool calls, tool results, reasoning, and images are omitted. An optional query steers what the shapes focus on, with or without a leading turn count. |
+| `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
+| `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
+| `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](settings.md#preferences). |
+| `/bro config` | Open settings for the shared backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor/review) overrides. |
+| `/bro guided-review <PR number or URL>` | Automatically explain and assess a captured PR in local Pi, with source evidence and optional private questions. Opening the same PR restores its saved review. |
+| `/bro guided-review` | List saved reviews; `resume` is an alias. |
+| `/bro elevate [request]` | Improve an assignment before execution. Discover up to five gaps, choose useful findings, and insert a revised request without submitting it. **Ctrl+Shift+E** can use your unsent draft. See [Elevate](../elevate.md). |
+| `/bro btw [question]` | Open a side conversation in a modal, seeded with recent main-session context. Starts conversation-only; type `/mode` inside to toggle full permission (read and edit the workspace) without losing the thread. |
+| `/bro advisor` | Quick notice of whether the executor's `bro_advisor` tool is available right now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`. |
+| `/bro advisor-steer` | View, edit, save, or clear the one persistent steering brief the advisor always sees. |
+| `/bro help` | Open the built-in quick reference. |
+
+Giving `/bro` the input directly works the same way:
+
+```text
+/bro https://example.com/article
+/bro docs/report.pdf
+/bro any other text is explained as pasted text
+```