diff --git a/README.md b/README.md
index 8923de2..fb3c933 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,14 @@
> A persistent, independent reviewer for bb coding threads.
+[](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml)
+[](./LICENSE)
+[](#install)
+
-[](https://github.com/salemsayed/bb-plugin-advisor/actions/workflows/ci.yml)
-[](./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.
| --- | --- |
|  |  |
-
-Configuration
-
-
-
-
-
-
-Reviewer evidence
-
-
-
-
+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.
## 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**.
+
+
+
+| 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.
+
+Reviewer evidence — every finding links to the reviewer's own workings
+
+
+
+
+
+
## 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
index 39c9fa6..a2e0477 100644
Binary files a/docs/media/history.png and b/docs/media/history.png differ
diff --git a/docs/media/panel.png b/docs/media/panel.png
index ba1041d..0b71b0b 100644
Binary files a/docs/media/panel.png and b/docs/media/panel.png differ
diff --git a/docs/media/reviewer-work.png b/docs/media/reviewer-work.png
index a9973f1..b969066 100644
Binary files a/docs/media/reviewer-work.png and b/docs/media/reviewer-work.png differ
diff --git a/docs/media/settings.png b/docs/media/settings.png
index 8057d0e..5577798 100644
Binary files a/docs/media/settings.png and b/docs/media/settings.png differ