pi-bro 0.24.0 → 0.25.0

package/docs/reference/settings.md

@@ -0,0 +1,108 @@
+# Set up models and preferences
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## Settings
+
+Use `/bro config` to review or change the shared default backend/model/effort
+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. If the terminal becomes too small, config blocks
+hidden actions; Esc closes config even if a picker was open, after pending saves
+finish. A failed save cancels that close and shows its error inline; if the error
+alone makes config too small, any other key clears it so you can try again. `/bro mode` changes the mode directly (**M** in an explanation
+tries another mode without saving it), and `/bro help` shows the active settings
+and file path.
+
+Elevate inherits the **BTW** backend/model/effort selection. There is no separate Elevate setting in this release. See the [Elevate guide](../elevate.md).
+
+Settings live in this user-editable file, created when the extension loads
+(under `$PI_CODING_AGENT_DIR` instead when that is set):
+
+```text
+~/.pi/agent/bro-settings.json
+```
+
+```json
+{
+  "version": 2,
+  "default": { "backend": "agy", "model": "gemini-3.7-flash", "effort": "low" },
+  "mode": "balanced",
+  "showTurns": 1,
+  "overrides": {
+    "explain": { "backend": "claude", "model": "sonnet", "effort": "medium" },
+    "advisor": { "backend": "grok", "model": "grok-4.7", "effort": "high" }
+  }
+}
+```
+
+Bro reads the file again before each request, so manual edits apply next time.
+
+- Each selection is one atomic backend/model/effort choice. An override pins
+  its own complete selection and ignores the shared default, even when it
+  happens to match it; select **Default** in `/bro config` to inherit again.
+  Omitted overrides inherit `default`.
+- `effort` must be one the backend offers (`default` omits it and lets the
+  model decide). Agy selections are normalized against Agy's installed model
+  catalog. Claude, Grok, Codex, and Muse accept seeded or custom model IDs; a model/effort
+  combination the account does not support fails with the backend's own error
+  instead of silently falling back.
+- `mode` is `brief`, `balanced` (the default), or `faithful`. `showTurns` is
+  the default number of turns `/bro show` draws (default 1); `/bro show
+  <n-turns>` overrides it for one run.
+- `PI_BRO_MODEL` picks the initial Agy model only when Bro creates a missing
+  settings file, for example `PI_BRO_MODEL=gemini-3.7-flash-low pi`.
+- Older flat settings files (root `model`/`effort`) still load and mean Agy.
+
+## Preferences
+
+Tell Bro about yourself and how you like answers. Bro adds what you write to
+every explain, `/bro show`, `/bro btw`, `/bro elevate`, 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.
+
+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
+## 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.
+```
+
+You can also edit the file directly (under `$PI_CODING_AGENT_DIR` instead when
+that is set):
+
+```text
+~/.pi/agent/bro-preferences.md
+```
+
+- **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.

package/docs/reference/troubleshooting.md

@@ -0,0 +1,55 @@
+# Diagnostics and troubleshooting
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## Check your setup
+
+Run `/bro doctor` when Bro is newly installed or something is not working. It
+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.
+
+- **Agy**: installed version, model catalog, and account access.
+- **Claude Code**: installed version and configured authentication.
+- **Grok**: installed version only; authentication and connectivity are not
+  verified.
+- **Codex**: installed version and configured authentication.
+- **Muse**: installed version only; authentication and connectivity are not
+  verified.
+
+Doctor never sends source text or runs a model completion. A successful check
+confirms the setup but cannot guarantee that a later provider request will
+succeed.
+
+## Troubleshooting and current limits
+
+If an explanation fails, run `/bro doctor` first. If a webpage cannot be
+extracted, copy its content into a supported text file or save it as a PDF and
+use `/bro file`. If a PDF contains only scanned images, run OCR with another
+tool before giving it to Bro.
+
+- An unsupported model, effort, or missing backend fails with that backend's
+  diagnostic; Bro never falls back to another backend.
+- Document input supports `.md`, `.markdown`, `.txt`, `.pdf`, and `.docx` only;
+  it does not perform OCR.
+- Webpage input supports one public HTML page, up to 5 MiB downloaded and
+  100,000 extracted characters. JavaScript-only, authenticated, paywalled,
+  blocked, paginated, and media-first pages are not supported.
+- Direct webpage fetching does not currently use `HTTP_PROXY`, `HTTPS_PROXY`,
+  or other proxy environment variables.
+- `/bro elevate` is pre-execution only. It does not validate expert claims, run source research or keep a persistent thread. Invalid discovery JSON can be retried with the [Retry] button; if it recurs, choose another BTW backend/model in `/bro config`. See [Elevate](../elevate.md).
+- `/bro btw` threads are memory-only and do not survive reloads or restarts.
+- The Agy advisor requires Agy CLI `>=1.1.15`.
+- Show captures only the conversation text of what already happened in the
+  current session — the last few turns' user and assistant messages, with
+  tool calls, tool results, reasoning, and images always omitted; its shapes
+  reflect what was reported in the conversation, not independent verification.
+- Diagrams open in your default browser; pressing **O** on a remote or
+  headless session with no display reports the failure instead of opening
+  anything.
+- 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](../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;
+  press **C** to copy the full explanation instead.