# pi-bro user guide

Find help by goal at the [docs home](README.md).

- [Getting started](getting-started.md) — install and a first working example.
- [Command reference](reference/commands.md) — complete commands and controls.
- [Model settings and preferences](reference/settings.md).
- [Backend access, privacy and retention](reference/data-and-permissions.md).
- [Troubleshooting](reference/troubleshooting.md).

The sections below retain previous guide anchors so existing links and bookmarks still lead to the right task page. Detailed instructions have moved, not been removed.

## What Bro can explain

See [What Bro can explain](reference/commands.md#what-bro-can-explain).

## Commands

See [Commands](reference/commands.md#commands).

## Explanation modes

See [Explanation modes](features/explain.md#explanation-modes).

### Modal controls

See [Explanation modes](features/explain.md#explanation-modes).

## Guided Review

See [Guided Review](guided-review.md#guided-review).

## Bro Elevate — improve a task before sending it

See [Elevate: Discover → Select → Upgrade](elevate.md). Elevate does not execute a task or send it to the main agent. It helps find gaps, lets you approve suggestions, then offers a revised request. In the terminal, insertion can replace your unchanged original draft; see the [editor-safety rules](elevate.md#what-happens-to-the-original-editor-draft).

## Bro btw (side conversation)

See [Bro btw (side conversation)](features/btw.md#bro-btw-side-conversation).

## Bro advisor

See [Bro advisor](features/advisor.md#bro-advisor).

## Bro show

See [Bro show](features/show.md#bro-show).

### A slow session-create, traced

See [Bro show](features/show.md#bro-show).

### The shape of code before it exists

See [Bro show](features/show.md#bro-show).

### A layout that collapses at narrow widths

See [Bro show](features/show.md#bro-show).

## Bro in action

See [Bro in action](examples.md#bro-in-action).

### Assistant response

See [Bro in action](examples.md#bro-in-action).

### Local document

See [Bro in action](examples.md#bro-in-action).

### Before

See [the first example's walkthrough](examples.md#bro-in-action).

### After `/bro`

#### What happened

See [What happened](examples.md#what-happened).

#### What it means

See [What it means](examples.md#what-it-means).

#### What you should do next

See [What you should do next](examples.md#what-you-should-do-next).

### Before

See [the second example](examples.md#bro-in-action).

### After `/bro`

#### What happened

See [What happened](examples.md#what-happened-1).

#### What it means

See [What it means](examples.md#what-it-means-1).

#### What you should do next

See [What you should do next](examples.md#what-you-should-do-next-1).

### Before

See [the third example](examples.md#bro-in-action).

### After `/bro`

#### What happened

See [What happened](examples.md#what-happened-2).

#### What it means

See [What it means](examples.md#what-it-means-2).

#### What you should do next

See [What you should do next](examples.md#what-you-should-do-next-2).

## Explain pasted text

See [Explain pasted text](features/explain.md#explain-pasted-text).

## Explain a document

See [Explain a document](features/explain.md#explain-a-document).

## Explain a webpage

See [Explain a webpage](features/explain.md#explain-a-webpage).

## Check your setup

See [Check your setup](reference/troubleshooting.md#check-your-setup).

## Settings

See [Settings](reference/settings.md#settings).

## Backends: access and retention

See [Backends: access and retention](reference/data-and-permissions.md#backends-access-and-retention).

### Configuration precedence

See [Backends: access and retention](reference/data-and-permissions.md#backends-access-and-retention).

## Preferences

See [Preferences](reference/settings.md#preferences).

## Privacy and safety

See [Privacy and safety](reference/data-and-permissions.md#privacy-and-safety).

## Troubleshooting and current limits

See [Troubleshooting and current limits](reference/troubleshooting.md#troubleshooting-and-current-limits).

## Simplify modal

`/bro` opens Simplify and explains the latest completed assistant reply. `/bro simplify` returns to the most recent Simplify screen without another model request. Inside, `/simplify`, `/text <text>`, `/file <path>` and `/url <url>` produce one explanation at a time; `/copy` copies the answer, `/clear` clears it, and `/help` shows controls. Press **M** with an empty composer to change the explanation mode and rerun; **R** retries. The saved default mode remains unchanged. The current screen is kept only within the Pi session. Old `/bro text|file|url|open` forms remain callable for compatibility.

## Bro command discovery and Config navigation

The default `/bro ` completion menu highlights eight tasks: `simplify`, `show`, `btw`, `guided-review`, `elevate`, `grill-me`, `remember-me`, `config`. Existing explicit commands, including `/bro doctor`, `/bro preferences`, `/bro advisor-steer`, `/bro file`, `/bro url`, `/bro text`, `/bro open` and `/bro help`, remain valid and discoverable by prefix. `/bro config` starts with **Global** (default, Preferences editor, Doctor on demand) and **Features** (five configurable capabilities and three workflows inheriting BTW). Esc goes back; existing save behavior is unchanged.