salemsayed · salemsayed · Aug 10, 2026 · Aug 10, 2026
diff --git a/README.md b/README.md
@@ -2,13 +2,14 @@
 
 > A persistent, independent reviewer for bb coding threads.
 
+[![CI](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml/badge.svg)](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![bb ≥ 0.35](https://img.shields.io/badge/bb-%E2%89%A5%200.35-8b5cf6.svg)](#install)
+
 <p align="center">
   <img src="./docs/media/advisor-hero.svg" alt="Advisor — an independent reviewer on every coding thread" width="100%" />
 </p>
 
-[![CI](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml/badge.svg)](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-
 Advisor pairs every coding thread with a second model that reviews the work —
 before the agent finishes its answer, and again after the turn completes. The
 reviewer runs in its own hidden thread with its own context, remembers what it
@@ -25,19 +26,9 @@ that cannot run reports as *unavailable*, never as approval.
 | --- | --- |
 | ![Advisor panel showing an open finding with evidence and decision controls](./docs/media/panel.png) | ![Advisor history showing independently re-checked findings](./docs/media/history.png) |
 
-<details>
-<summary><strong>Configuration</strong></summary>
-
-![Advisor settings, including optional auto-continue and per-machine reviewer selection](./docs/media/settings.png)
-
-</details>
-
-<details>
-<summary><strong>Reviewer evidence</strong></summary>
-
-![Advisor's expanded reviewer output with a stable finding key and supporting evidence](./docs/media/reviewer-work.png)
-
-</details>
+<sub>The finding on the left is real: while this release was being prepared,
+Advisor reviewed the repository and flagged a stale screenshot in this very
+README. It was recaptured — the screenshot above is the replacement.</sub>
 
 ## Why
 
@@ -84,12 +75,96 @@ whole bounded queue into that turn — delivering one finding never silently
 consumes its siblings. Advice older than 24 hours is retired rather than
 injected stale.
 
+## Install
+
+Requires bb ≥ 0.35.
+
+From GitHub:
+
+```sh
+bb plugin install git:https://github.com/salemsayed/bb-plugin-advisor.git@main
+```
+
+From a local checkout:
+
+```sh
+bb plugin install . --yes
+```
+
+## Configure
+
+All settings live in **Settings → Extensions → Advisor**.
+
+![Advisor settings, including optional auto-continue and per-machine reviewer selection](./docs/media/settings.png)
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| Enable advisor | on | Requires an independent review before an agent completes substantial work. |
+| Review completed turns | on | Post-turn review; late findings carry into the next turn. |
+| Auto-continue on late findings | **off** | See below. |
+| Fallback advisor reasoning | inherit | Used only when a machine follows the primary model. |
+| Minimum severity | nit | Findings below the threshold are not delivered to the agent. |
+| Watchdog file | `WATCHDOG.md` | Workspace-relative reviewer policy file. |
+| Review timeout | 2 minutes | 30 seconds to 10 minutes. Exceeding it reports unavailable, never a pass. |
+| Transcript budget | 60,000 characters | 20,000 to 120,000. |
+
+### Reviewer model, per machine
+
+The model section loads the live provider/model catalog independently from
+every connected bb machine. Selections are stored by stable host id, not as
+one global model string. Each machine selection includes a reasoning level
+populated from that model's live supported-reasoning metadata; choosing
+"Model default" tracks the model's reported default.
+
+At review time the plugin routes discovery through the primary thread's
+environment and revalidates that machine's saved selection. A machine without
+a selection follows the primary thread's provider and model. A disconnected
+machine, a model that was removed, or a reasoning level the model no longer
+supports also falls back to the primary model. The picker only offers
+providers that can host a reviewer in one of the accepted permission modes,
+and it never accepts models from an unverified fallback catalog returned after
+a provider probe failure.
+
+Falling back to the primary model is checked, not assumed: if the primary
+thread's own provider cannot run a reviewer in any accepted mode and that
+machine has no advisor model configured, the review reports as unavailable
+instead of failing at spawn. A catalog that cannot be read is treated as
+inconclusive, so a transient outage does not disable reviews.
+
+### Auto-continue on late findings (off by default)
+
+When enabled, Advisor starts the **Fix in new turn** follow-up without a
+click: one corrective turn for a newly raised finding chain. It is idempotent
+per review round and can fire only once per finding chain, so a persistent
+finding cannot create an unattended review loop.
+
+### Project reviewer policy
+
+Place project-specific reviewer policy in `WATCHDOG.md` at the workspace root.
+The reviewer reads it before each review; the filename is configurable.
+
 ## The life of a finding
 
 The advisor assigns each finding a stable `key` naming the defect itself. A
 later round carrying the same key joins that finding's chain even when it is
-reworded or rated differently. Every finding carries its own lifecycle, shown
-in the thread panel:
+reworded or rated differently.
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    state "Re-raised" as Reraised
+    [*] --> Queued : advisor raises a finding
+    Queued --> Sent : tool result or next-turn injection
+    Sent --> Reraised : flagged again
+    Reraised --> Sent : held at strongest severity
+    Sent --> Closed : advisor re-checks and closes
+    Closed --> Reraised : same key returns
+    Sent --> Decided : user rules not an issue or won't fix
+    Closed --> [*]
+    Decided --> [*]
+```
+
+Every finding carries its own lifecycle, shown in the thread panel:
 
 - **Queued** — found, but its text has not reached the primary agent yet.
 - **Sent to the agent** — set at the two moments the finding is actually
@@ -126,6 +201,14 @@ Reviews are persisted in the plugin's SQLite database, keyed by primary thread
 and timeline sequence. Deleting a primary thread deletes its review history;
 archiving keeps it.
 
+<details>
+<summary><strong>Reviewer evidence</strong> — every finding links to the reviewer's own workings</summary>
+<br />
+
+![Advisor's expanded reviewer output with a stable finding key and supporting evidence](./docs/media/reviewer-work.png)
+
+</details>
+
 ## When a review cannot run
 
 When the advisor cannot run — the provider does not support the reviewer's
@@ -158,72 +241,6 @@ moves it to `accept-edits`. A mode the host accepted before is tried first, so
 the probe costs nothing on the common path. A transient outage therefore
 neither disables reviews nor silently widens them.
 
-## Install
-
-Requires bb ≥ 0.35.
-
-From GitHub:
-
-```sh
-bb plugin install git:https://github.com/salemsayed/bb-plugin-advisor.git@main
-```
-
-From a local checkout:
-
-```sh
-bb plugin install . --yes
-```
-
-## Configure
-
-All settings live in **Settings → Extensions → Advisor**.
-
-| Setting | Default | Notes |
-| --- | --- | --- |
-| Enable advisor | on | Requires an independent review before an agent completes substantial work. |
-| Review completed turns | on | Post-turn review; late findings carry into the next turn. |
-| Auto-continue on late findings | **off** | See below. |
-| Fallback advisor reasoning | inherit | Used only when a machine follows the primary model. |
-| Minimum severity | nit | Findings below the threshold are not delivered to the agent. |
-| Watchdog file | `WATCHDOG.md` | Workspace-relative reviewer policy file. |
-| Review timeout | 2 minutes | 30 seconds to 10 minutes. Exceeding it reports unavailable, never a pass. |
-| Transcript budget | 60,000 characters | 20,000 to 120,000. |
-
-### Reviewer model, per machine
-
-The model section loads the live provider/model catalog independently from
-every connected bb machine. Selections are stored by stable host id, not as
-one global model string. Each machine selection includes a reasoning level
-populated from that model's live supported-reasoning metadata; choosing
-"Model default" tracks the model's reported default.
-
-At review time the plugin routes discovery through the primary thread's
-environment and revalidates that machine's saved selection. A machine without
-a selection follows the primary thread's provider and model. A disconnected
-machine, a model that was removed, or a reasoning level the model no longer
-supports also falls back to the primary model. The picker only offers
-providers that can host a reviewer in one of the accepted permission modes,
-and it never accepts models from an unverified fallback catalog returned after
-a provider probe failure.
-
-Falling back to the primary model is checked, not assumed: if the primary
-thread's own provider cannot run a reviewer in any accepted mode and that
-machine has no advisor model configured, the review reports as unavailable
-instead of failing at spawn. A catalog that cannot be read is treated as
-inconclusive, so a transient outage does not disable reviews.
-
-### Auto-continue on late findings (off by default)
-
-When enabled, Advisor starts the **Fix in new turn** follow-up without a
-click: one corrective turn for a newly raised finding chain. It is idempotent
-per review round and can fire only once per finding chain, so a persistent
-finding cannot create an unattended review loop.
-
-### Project reviewer policy
-
-Place project-specific reviewer policy in `WATCHDOG.md` at the workspace root.
-The reviewer reads it before each review; the filename is configurable.
-
 ## Inspect
 
 ```sh
@@ -234,10 +251,11 @@ bb plugin logs advisor -f
 
 ## Security and trust
 
-Like every bb plugin, Advisor is full-trust code: its server runs inside your
-bb server, not in a sandbox, with access to the plugin SDK, its own database,
-and thread orchestration. Read the source before installing — this repository
-is small on purpose.
+> [!IMPORTANT]
+> Like every bb plugin, Advisor is full-trust code: its server runs inside
+> your bb server, not in a sandbox, with access to the plugin SDK, its own
+> database, and thread orchestration. Read the source before installing —
+> this repository is small on purpose.
 
 The reviewer itself is constrained by the negotiated permission mode, with one
 caveat: bb only gained a first-class `readonly` mode recently, so on an older
@@ -249,6 +267,8 @@ capabilities must still be assessed by that provider.
 
 ## Development
 
+Requires Node 22.
+
 ```sh
 npm ci
 npm run verify   # typecheck + tests + build

diff --git a/docs/media/history.png b/docs/media/history.png
diff --git a/docs/media/panel.png b/docs/media/panel.png
diff --git a/docs/media/reviewer-work.png b/docs/media/reviewer-work.png
diff --git a/docs/media/settings.png b/docs/media/settings.png