pi-bro 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.22.0] - 2026-10-11
+
+### Fixed
+
+- Persist settings with atomic replacement and mode 0o600 (#84):
+  - Replace direct `writeFile` with atomic sibling write (`.tmp`) and `rename` to prevent settings corruption on failure, crash, or disk full (`ENOSPC`).
+  - Flush writes before replacement (`flush: true`) and clean up temporary files on failure.
+  - Enforce `mode: 0o600` on replaced settings files so permissions are never loosened.
+  - Resolve symlinks via lstat and realpath before replacement to preserve dotfile-managed configuration symlinks, and reject if an existing symlink target cannot be resolved.
+  - Align on-disk state with modal rollback behavior in `/bro config`.
+
+### Added
+
+- Guided Review (#104): open a PR by URL/number in local Pi to automatically get an explanation and quality assessment, captured Git evidence, findings with fix/check suggestions, diffs and optional private questions. Acquisition uses authenticated `gh` outside the active working tree. Findings remain model proposals, not approval or applied changes.
+- Automatic local remembering of questions/drafts/reading position; reopening the same PR restores the captured revision without a model call. Bare `/bro guided-review` lists saved reviews; `resume` remains an alias. Close saves automatically; Stop and close cancels first. Copy finding copies to the system clipboard without submission.
+- Confirmed same-revision regeneration replaces one current guide and preserves original private context; failed/cancelled generation retains it and save errors offer recovery. There is no guide-version UI or prototype-format migration. Review has its own backend override.
+- Bounded live checks demonstrated an unchanged-caller defect and successful regeneration; manual UX accepted. This is not a general accuracy guarantee, live five-backend matrix or complete #104 scope. Notes, examination tracking, branch/update review and feedback delivery are not implemented.
+
+- Durable advisor steering across sessions in `~/.pi/agent/bro-advisor.md` (#97):
+  - Ingest standing priorities from `bro-advisor.md` alongside session steering (`/bro advisor-steer`).
+  - Labeled prompt composition in `buildAdvisorPrompt`: standing priorities appear under `### Standing priorities (durable across sessions)` and session priorities under `### Session priorities (this session only)`.
+  - Session-specific priorities take precedence over standing defaults where they conflict.
+  - Fail-closed validation rejects files > 64 KB and > 4,000 characters before spawning any backend process.
+  - Doctor reports both `Advisor steering (session)` and `Advisor steering (durable)`.
+  - Tool result context line and details track `steeringSources: { durable, session }` while preserving backwards-compatible `steeringIncluded` boolean.
+  - Retries use a frozen prompt snapshot built prior to `runAdvisorWithRetries`.
+  - Clearing session steering leaves durable steering intact.
+
+### Changed
+
+- Doctor treats an unsupported optional review backend as an informational override hint, not a broken installation; healthy Agy/Grok/Codex defaults still report ready.
+- Review is file-only on Claude/Muse: no shell, write or web tools; Agy/Grok/Codex review calls fail closed without switching backend. Other features retain their access behavior.
+- Capture uses depth-1 head/merge-base trees instead of full history; fetch gets a ten-minute bound while evidence stays offline. Interrupted-capture recovery remains.
+- Removed prototype record migrations after one-time backup/normalization of development records; split validation and formatted review modules/tests to the repository tab style.
+
+- Guided Review UX consistency pass: origin-preserving Back, focused-action Enter, topic-filtered findings, pane-aware paging, visible focus/overflow, selected-item previews and compact full-width 36×18 layout. Discussion follows conversation/composer/actions order; save errors have shared retry controls and failed questions have draft-safe explicit edit/resend. Request errors are separate from model answers, streaming follows again at the bottom, and acquisition/resume/close messages give clearer orientation. Current review behavior, controls, access/storage and recovery are documented in the user guide; developer/testing guidance records its implementation rules and verification limits. Review itself has no publication action.
+- Remove dead declarations and stale backend naming (#90):
+  - Enable native TypeScript unused checks (`noUnusedLocals`, `noUnusedParameters`) in `tsconfig.json`.
+  - Remove verified unused declarations across `bro.ts`, `backend.test.ts`, `benchmark/run.ts`, `codex.test.ts`, and `release.test.ts`.
+  - Drop pass-through re-exports from `bro.ts` (`agyFailureMessage`, `agySelection`, `advisorFlagErrorHint`, `parseBtwAgyLine`); tests and consumers import them directly from `backend.ts`.
+  - Rename multi-backend facilities with obsolete Agy prefixes: `runAgyText` -> `runBackendText` in `bro.ts` and `killAgyGroup` -> `killProcessGroup` in `backend.ts`.
+  - Modernize outdated single-backend and pre-extraction comments.
+- Separate Bro responsibilities and unify settings and backend-selection policy (#83):
+  - Extract `settings.ts` (schema, typed `EXTERNAL_BACKENDS` metadata, selection policy, pure transitions, and file persistence).
+  - Extract `sources.ts` (self-contained document text extraction and public web scraping with SSRF protection).
+  - Extract `config-ui.ts` (`/bro config` modal, setting items, and async save serialization).
+  - Extract `util.ts` (shared leaf utility helpers).
+  - Unify legacy flat and v2 settings parsing into one converged validation pipeline in `settings.ts`, eliminating duplicate validation branches.
+  - Initialize clean version 2 settings on fresh installations in `ensureSettingsFile()`.
+  - Share pure state transitions (`applyModelChange`, `applyEffortChange`) across default and capability override rows.
+  - Fix Agy variant model reselection bug where resolved effort from suffixed variants was lost.
+  - Consolidate CLI version probes in `/bro doctor` into a single `checkCliVersion` helper.
+
+## [0.21.0] - 2026-10-04
+
+### Added
+
+- `bro-preferences.md`: tell Bro about yourself and how you like answers. Bro adds it, JSON-quoted and labelled, to every explain, `/bro show`, and `/bro btw` prompt alongside its own instructions; the advisor never receives it. Preferences can change wording, tone, technical depth, and the answer language (code, commands, paths, names, and numbers stay verbatim). In Show they change only wording and language. Per-run choices (the mode, **M**, a Show steering query, a BTW question) win over them, and Bro's source rules, Show's hard rules, and BTW access mode always apply. Blank or missing preferences leave every prompt byte-identical to 0.20.0 (#94).
+- `/bro preferences` edits the file (**Ctrl+S** save, **Ctrl+K** delete, **Ctrl+C** copy, **Esc** close). Without a file it opens with unsaved starter text that restates the old built-in audience and brief wording. Saves are checked against the 4,000-character limit, and an oversize file still opens so it can be trimmed (#94).
+- The modal header shows `· prefs` when preferences shaped an explanation, drawing, or BTW turn; `/bro open` keeps the result's tag (#94).
+
+### Changed
+
+- Modes, **M**, and the source guard now always apply; nothing disables them (#94).
+- Preferences over 4,000 characters stop explain, Show, and BTW with an actionable error before any backend call instead of being truncated. `/bro doctor` replaces its Prompt check with a Preferences check, and `/bro help` shows the preferences status (#94).
+- When preferences change mid-thread, the next BTW turn starts a fresh native session reseeded with the quoted thread, on every backend, so old preferences don't linger in the backend's history (#94).
+
+### Removed
+
+- **Breaking:** `bro-prompt.md` is no longer read. It was a full replacement template for the explain prompt that disabled modes, **M**, and the source guard and did not affect Show or BTW. Bro does not migrate, rename, or delete it. Move what you want to keep into `/bro preferences`, and use `/bro mode brief` for the original ELI-simpleton instruction (#94).
+
 ## [0.20.0] - 2026-10-04
 
 ### Added

package/README.md

@@ -1,14 +1,11 @@
 # pi-bro
 
-Turn a dense AI reply, pasted text, local document, or public webpage into a
-plain-language explanation — or open a separate side conversation with
-`/bro btw` — without adding anything to your main agent's context.
+Turn a dense AI reply, pasted text, document or webpage into a plain-language explanation. Ask side questions with `/bro btw`, or understand and assess a PR with `/bro guided-review`. These windows do not add their discussions to your main agent's context.
 
 `pi-bro` is an extension for [Earendil Pi](https://github.com/earendil-works/pi).
 Experimental [PiG 0.3.0 compatibility](docs/pig-compatibility.md) uses the same npm package and requires Node.js. See the compatibility notes for verified coverage and the PiG RPC tool-exclusion limitation.
 It opens explanations in a separate modal and runs them through a CLI backend
-you already have installed and signed in to. Explain, show, BTW, and the
-advisor all work across five backends:
+you already have installed and signed in to. Explain, show, BTW and advisor use five backend adapters. Guided Review generation/questions require Claude or Muse file-only inspection (live verification varies by feature):
 
 - [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`) — the default for new settings
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
@@ -72,9 +69,12 @@ text directly captures a new source the same way.
 | `/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, prompt, and each selected backend, with the effective backend/model/effort per feature. |
+| `/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 config` | Open an interactive settings screen for the shared default backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor) overrides. |
+| `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](#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 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. |
@@ -91,7 +91,8 @@ Giving `/bro` the input directly works the same way:
 ## Explanation modes
 
 Bro treats the source as data, rejects embedded instructions, preserves its
-language, and avoids adding facts, advice, or conclusions in every mode. Choose
+language (unless your [preferences](#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:
 
@@ -112,19 +113,58 @@ next mode without saving it:
 - **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. Not offered while a custom prompt is active
+  ahead
 - **O**: Open the HTML 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; `/bro open` keeps the original labels and mode.
+explanation mode, and `prefs` when your [preferences](#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.
 
 
+## Guided Review
+
+**Open a PR → read and investigate → leave when satisfied.** Bro automatically
+prepares an explanation and quality assessment with captured code, ranked
+findings and suggested fixes/checks. Asking private questions is optional.
+Nothing is automatically applied or posted to GitHub.
+
+```text
+/bro guided-review https://github.com/OWNER/REPO/pull/123
+```
+
+Local Pi interactive mode, Git, authenticated `gh`, and Claude or Muse configured for review
+are required. A new review makes a model call using that backend's account.
+Opening the same PR restores its saved review without another model call.
+Bare `/bro guided-review` lists saved reviews (`resume` is an alias).
+
+Contents holds Overview, topics, Findings, Coverage, Changed files and Your
+questions. Enter opens an item or focuses contextual actions; Enter on a
+highlighted action activates it. Tab changes focus. Esc goes back, then closes
+from Contents. Your work is saved automatically; **Close** leaves normally,
+and **Stop and close** cancels active work before saving and leaving.
+
+Optional conveniences:
+- **Copy finding** copies its text to the system clipboard; nothing is submitted.
+- **Regenerate guide** makes a confirmed model call about the **same captured
+  revision**. Success replaces the guide while retaining original private
+  discussion context; failure keeps it. It does not fetch later commits.
+
+Reopening also keeps the captured revision, even after the author pushes.
+Findings are model suggestions, not approval; citations show real locations,
+not proof of the conclusion. Review uses Claude or Muse file-only inspection: shell, writes and web tools are disabled. Agy/Grok/Codex review requests fail clearly; choose a review override in `/bro config`. Saved reviews remain readable with any selection. Repository text can still mislead the model; tool restrictions are not proof of its conclusions.
+Use `pi --tui-mode fullscreen` for pane-local wheel scrolling.
+
+See the [Guided Review guide](docs/guided-review.md) for controls, calls and
+costs, source freshness, access/privacy, local storage, recovery and current
+scope. Notes, examination tracking, branch/update review and feedback delivery
+are not implemented.
+
 ## Bro btw (side conversation)
 
 `/bro btw` opens a separate multi-turn conversation in a modal, so you can ask
@@ -198,18 +238,21 @@ presence, and backend compatibility (for Agy, a minimum CLI version with an
   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**: `/bro advisor-steer` opens an editor for one persistent
-  steering brief — e.g. "quick prototype; keep A and B careful, everything
-  else minimal" — that the advisor always reads. **Ctrl+S** saves and keeps
-  the editor open; **Enter** or **Shift+Enter** inserts a newline; **Ctrl+K**
-  clears both the saved brief and draft while staying open; **Ctrl+C** copies
-  the entire current draft, including unsaved edits; and **Esc** closes without
-  saving unsaved edits. The brief is **never added to Pi's conversation or
-  sent to the main model** — the advisor is the only thing that reads it.
-- **Persistence**: the steering brief persists with the Pi session (not
-  globally, not per project) as custom extension data in the session file and
-  is restored on resume or reload. Forking a session inherits it; edits made
-  after the fork are independent of the original branch.
+- **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
@@ -241,7 +284,9 @@ 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 and `bro-prompt.md` do not affect it.
+draw prompt; the explanation modes do not affect it. Your
+[preferences](#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
@@ -693,7 +738,7 @@ it as a PDF, then use `/bro file <path>`.
 ## Check your setup
 
 Run `/bro doctor` when Bro is newly installed or something is not working. It
-checks Bro's settings and prompt, then probes only the backends some feature
+checks Bro's settings and preferences, then probes only the backends some feature
 actually selects, and reports the effective backend/model/effort for each
 feature. Failed checks explain what to fix.
 
@@ -712,7 +757,7 @@ succeed.
 ## Settings
 
 Use `/bro config` to review or change the shared default backend/model/effort
-and any per-capability (explain/show/btw/advisor) overrides, the explanation
+and any per-capability (explain/show/btw/advisor/review) overrides, the explanation
 mode, and the default show turn count. Changes save immediately. Esc inside a
 picker cancels that pick; Esc on the settings screen closes it, keeping
 whatever was already saved. A failed save (for example, a read-only file) is
@@ -765,13 +810,13 @@ credentials, and does not copy credentials or rewrite backend configuration.
 Each backend and your model provider may retain sessions, logs, and request
 data under their own settings and policies.
 
-| | Explain / show | BTW conversation-only | BTW full permission | Advisor |
-| --- | --- | --- | --- | --- |
-| **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed |
-| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) |
+| | Explain / show | BTW conversation-only | BTW full permission | Advisor | Guided Review |
+| --- | --- | --- | --- | --- | --- |
+| **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Unavailable; choose Claude/Muse |
+| **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Restricted Read/Grep/Glob only; confined checkout, no persistence |
+| **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Unavailable; choose Claude/Muse |
+| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed | Unavailable; command execution is not allowed for review |
+| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) | Captured checkout; writes/shell/web disabled, no session log |
 
 - Grok always runs with its sandbox off and permissions bypassed; its tools,
   hooks, skills, plugins, and MCP may remain available. "Answer only from the
@@ -800,7 +845,7 @@ data under their own settings and policies.
 ### Configuration precedence
 
 When resolving backend, model, and reasoning effort:
-1. **Per-capability override**: `overrides.<capability>` (`explain`, `show`, `btw`, or `advisor`) pins that capability's complete selection.
+1. **Per-capability override**: `overrides.<capability>` (`explain`, `show`, `btw`, `advisor`, or `review`) pins that capability's complete selection.
 2. **Shared default**: otherwise the capability inherits `default` (root `model`/`effort` in older flat files).
 3. **Agy catalog normalization**: for Agy selections, Bro maps suffixed variant IDs and handles fixed-effort models.
 4. **Initial file creation only**: `PI_BRO_MODEL` has no effect once the settings file exists.
@@ -809,41 +854,66 @@ When resolving turn count for `/bro show`:
 1. **Command argument**: an explicit count like `/bro show 3` or `/bro show 1 query` overrides for that run.
 2. **Saved setting**: `showTurns` (defaults to 1).
 
-When resolving the explanation prompt (`explain` capability only):
-1. **Custom prompt**: a valid `~/.pi/agent/bro-prompt.md` (or `$PI_CODING_AGENT_DIR/bro-prompt.md`) completely overrides all built-in modes.
-2. **Saved mode**: `mode` in `bro-settings.json` (defaults to `balanced`).
-3. `bro-prompt.md` applies only to `/bro`, `/bro text`, `/bro file`, and `/bro url`; it does not affect `/bro show`, `/bro btw`, or `bro_advisor`.
+When shaping an answer, each part has one owner:
 
-## Custom prompt
+| Part | Decided by |
+| --- | --- |
+| Bro's source rules: quoted source treated as data, no added facts, Show's traceability rules, BTW access mode | Built in; nothing overrides them |
+| How much of the source an explanation keeps | The mode: **M** for one explanation, otherwise the saved `mode` |
+| What a Show drawing focuses on | The steering query |
+| Who the answer is for: wording, tone, depth, and answer language | Your [preferences](#preferences), otherwise Bro's built-in defaults |
 
-Bro uses a built-in prompt by default. To use your own, create:
+## Preferences
 
-```text
-~/.pi/agent/bro-prompt.md
-```
+Tell Bro about yourself and how you like answers. Bro adds what you write to
+every explain, `/bro show`, `/bro btw`, and Guided Review prompt as a labelled section,
+alongside its own instructions. It never replaces them: modes, **M**, and the
+source rules keep working. The advisor never receives your preferences; use
+`/bro advisor-steer` for it.
 
-Your prompt must include `{{response}}` exactly once. For example:
+Run `/bro preferences` to edit them: **Ctrl+S** saves, **Ctrl+K** deletes the
+file, **Ctrl+C** copies, and **Esc** closes without saving. The first time,
+the editor opens with this starter text, which is not saved until you press
+**Ctrl+S**:
 
 ```md
-Explain this in plain English in no more than 200 words.
-Keep important warnings and next steps.
-
-Text to explain:
-{{response}}
+## About me
+I'm an overworked white-collar worker, and so are my colleagues. By the end of a
+hard day our brains are fried and we can only handle simple language, no matter
+how sharp we are at our best.
+
+## How I like answers
+- Explain it like I'm a simpleton: plain, everyday words.
+- Go easy on analogies. No forced ones.
 ```
 
-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.
-Existing valid custom prompts continue working unchanged.
+You can also edit the file directly (under `$PI_CODING_AGENT_DIR` instead when
+that is set):
+
+```text
+~/.pi/agent/bro-preferences.md
+```
 
-A valid custom prompt fully overrides all built-in mode instructions.
-`/bro show` is separate: it always uses its own built-in draw prompt and
-ignores `bro-prompt.md`. `/bro
-mode` still changes the saved mode, but that mode remains inactive while
-`bro-prompt.md` exists. Remove or rename `bro-prompt.md` to use the saved
-built-in mode again. If the custom prompt is invalid—for example, it has no
-`{{response}}` placeholder or has more than one—Bro blocks the explanation;
-run `/bro doctor` for the exact problem.
+- **Free-form**: no placeholder or structure is required. Bro re-reads the
+  file on every request, so edits apply next time. A missing or empty file
+  means no preferences, and Bro's prompts are then exactly the built-in ones.
+- **What preferences can change**: wording, tone, technical depth, length in
+  BTW, and the answer language. If you name a language, code, commands, paths,
+  names, and numbers still stay exactly as written. In `/bro show`,
+  preferences only change wording and language. Guided Review also receives preferences for explanation/answer wording; they do not override its evidence or review rules. A per-run choice (the mode,
+  **M**, a Show steering query, or what a BTW/review question asks for) wins over a
+  standing preference.
+- **Limit**: 4,000 characters, because the text goes with every request. A
+  longer file stops explain, Show, BTW, and Guided Review with an error until you trim it;
+  Bro never cuts it silently. `/bro doctor` reports the problem, and the
+  editor still opens the file so you can fix it.
+- **BTW threads**: when your preferences change, the next side question starts
+  a fresh backend session that is caught up on the thread, so old preferences
+  don't linger.
+
+`bro-prompt.md`, the full prompt template from earlier versions, is no longer
+read. Move what you want to keep into `/bro preferences`, and choose
+`/bro mode brief` for the original ELI-simpleton instruction.
 
 
 ## Privacy and safety
@@ -856,6 +926,10 @@ run `/bro doctor` for the exact problem.
   seeded main-session conversation text (plus earlier turns when a native
   session is reseeded) to the selected backend. In full permission mode the
   side agent can additionally read and edit the workspace.
+- **Guided Review requests**: PR identity/description, captured diff, relevant private discussion and preferences go to the selected backend, which can inspect captured files using Claude/Muse read-only tools. Main-session context is not attached. Review shell/write/web tools are disabled; Claude file tools are confined with `--restricted`, Muse uses workspace-scoped inspection. Prompt injection can still corrupt conclusions or reveal captured content to the provider; this is not a general confidentiality guarantee. See [Guided Review access and storage](docs/guided-review.md#access-privacy-and-storage).
+- **Preferences**: `bro-preferences.md` is sent with every explain, Show,
+  BTW, and Guided Review request to the selected backend. It is never sent to the advisor or
+  to Pi's main model.
 - **Advisor requests**: `bro_advisor` sends the executor agent's system
   instructions, active tool list (excluding `bro_advisor`), ordered
   conversation history including tool calls and tool results (unlike Show,
@@ -871,10 +945,12 @@ run `/bro doctor` for the exact problem.
   steering brief to Pi's conversation history or main-agent context. BTW text
   reaches the main editor only through `/insert` or `/insert-all`, and advisor
   results appear as normal tool results in the executor's transcript.
+- **Saved reviews**: Guided Review records, questions, drafts and captured Git source persist under the host's `getAgentDir()/bro-reviews/`. No automatic cleanup or sync is provided; see [storage and removal](docs/guided-review.md#access-privacy-and-storage).
 - **Memory**: the latest explanation (for `/bro open`) and the BTW thread live
   only in process memory and clear when you switch Pi sessions, reload
   extensions, or quit Pi. Backend-native sessions can persist independently.
-  The advisor steering brief is stored as session-scoped extension data
+  Standing advisor priorities are stored in `~/.pi/agent/bro-advisor.md`, and
+  the session steering brief is stored as session-scoped extension data
   (`bro-advisor-steering`) in the session file.
 - **File safety**: `/bro file` reads only regular files whose resolved path is
   inside Pi's current workspace, including after resolving symlinks. Bro's
@@ -892,7 +968,7 @@ run `/bro doctor` for the exact problem.
   Bro writes it to `/tmp/pi-bro-<uid>/bro-show-<hash>.html` with a restrictive
   Content-Security-Policy, and opens it in your browser only when you press
   **O**. **C** copies the full reply, including the HTML.
-- **Clipboard**: **C**, `/copy`, and `/copy-all` copy text to your system
+- **Clipboard**: **C**, `/copy`, `/copy-all`, and Guided Review's Copy finding copy text to your system
   clipboard, where your operating system or clipboard manager may retain it.
 
 ## Troubleshooting and current limits
@@ -920,8 +996,8 @@ tool before giving it to Bro.
 - HTML diagrams open in your default browser; pressing **O** on a remote or
   headless session with no display reports the failure instead of opening
   anything.
-- Keeps only the latest explanation in memory and does not store history or
-  export directly to files.
+- Explain keeps only the latest result in memory and does not export directly to files. Guided Review separately persists review records and captured source.
+- Guided Review is local-Pi interactive only, keeps its captured revision on reopen, and does not publish, review a branch or fetch later PR changes. See [review recovery and limits](docs/guided-review.md#if-something-goes-wrong).
 - Bro temporarily captures mouse input while its modal is open so mouse-wheel
   and trackpad scrolling work in regular and fullscreen modes. Native mouse
   selection may be unavailable or visually extend outside the Bro window;
@@ -935,7 +1011,7 @@ npm test
 pi --tui-mode fullscreen -e ./bro.ts
 ```
 
-`npm test` uses fake `agy`, `claude`, and `grok` executables and never calls an
+`npm test` uses fake `agy`, `claude`, `grok`, `codex`, and `muse` executables and never calls an
 external model. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the code
 map and invariants, [docs/TESTING.md](docs/TESTING.md) for the manual
 end-to-end checklist, and [docs/README.md](docs/README.md) for the docs index.