@quickchatai/quickreview 1.1.0 → 1.3.1

package/README.md

@@ -18,17 +18,27 @@ for one kind of problem and never see each other's output. It merges their
 findings so one root cause gets one comment, and an **adversarial validator
 re-derives every candidate from the code** before one review is posted.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-hero-dark.png">
+  <img src="docs/media/bench-hero.png" alt="AACR-Bench, 185 real PRs, 520 verified defects, QuickReview on GPT-6.1 Sol against six other reviewers, share found at each severity. High (90 defects): QuickReview 97%, next best Codex CLI 90%. Medium (145): QuickReview 93%, next best pi-review panel 82%. Low (285): QuickReview 84%, next best pi-review panel 52%.">
+</picture>
+
+On 185 real PRs with 520 defects each verified in the code, QuickReview on
+GPT-6.1 Sol finds **97% of the high-severity defects, 93% of the medium and
+84% of the low**; at each severity the best of the six other reviewers we ran
+finds 90%, 82% and 52%. On the same model it also finds more than the model
+maker's own reviewer at every severity: against Claude Code's `/code-review`
+on Claude Opus 5.5 and against Codex CLI on GPT-6.1 Sol. Its last changes were
+mined from its misses on 145 of the 185 PRs; on the 20 kept out, it finds 83%
+of all defects and the next best 72%. That recall costs more: about $2 and
+17.5 minutes per PR, where the other tools take $0.07–0.53 and 0.7–2.3
+minutes ([Benchmarks](#benchmarks)).
+
 <p align="center">
   <img src="docs/media/lenses.gif" width="800"
        alt="Animation: nine lens passes sweep the same diff in parallel, each marking the lines where it finds a problem; findings that share a root cause merge, eight candidates into six causes; the validator re-derives each from the code, keeps four and strikes two with a reason (below the bar; refuted); the four survivors become one posted review, three blockers and one question, marked REQUEST_CHANGES.">
 </p>
 
-On 185 real PRs with 520 defects each verified in the code, it finds
-**97% of the high-severity defects and 89% of all of them**; the strongest
-third-party configuration we measured finds 67%. That recall costs more:
-about $2 and 17 minutes per PR, where the other tools take $0.07–0.53 and
-0.7–2.3 minutes ([Benchmarks](#benchmarks)).
-
 Around the review sits a small, deterministic TypeScript daemon with no LLM
 in its decision path. It takes GitHub App webhooks, runs an authoritative
 reconcile poll, keeps one sticky [pi](https://github.com/earendil-works/pi)
@@ -70,22 +80,37 @@ The lens catalogue, with each lens's trigger and severity cap, is §3.3 of the
 
 Recall is the headline: a review that misses the defect has failed, whatever
 else it does. Precision, cost and time are shown beside it, because that is
-where QuickReview pays. Its results are the frozen build of 2026-10-04 on
-`gpt-6.1-sol`, shipped defaults, one review per PR. The third-party tools we
-ran used the best configuration we found for each, the OpenAI-based ones on
-the same model, under the same judge on the same PRs.
+where QuickReview pays. Unless a chart or table names another build or model,
+its results are the frozen build of 2026-10-04 on `gpt-6.1-sol`, shipped
+defaults, one review per PR. The third-party tools we ran used the best
+configuration we found for each (except Claude Code, which ran `/code-review`
+at its default effort and was not varied), the OpenAI-based ones on the same
+model, under the same judge on the same PRs.
+
+**AACR-Bench, verified defects.** AACR-Bench's own reference comments are
+mostly not real problems, so we built a key of 520 defects, each verified in
+the code and graded by its consequence: **high** would block a merge (a
+user-visible bug on a normal path, a crash, data loss, a security hole, a
+broken build), **medium** should be fixed before merge, **low** is real but
+fine as a follow-up. The chart at the top is this key. QuickReview misses 2.5
+of the 90 high-severity defects, 10.5 of the 145 medium and 46 of the 285 low
+(a partly found defect counts as half); the best other reviewer at each
+severity misses 9, 26 and 136.5. Over the panel and Codex CLI the
+high-severity lead holds under a paired bootstrap (+8.3 points [+1.9, +14.6]
+over the panel). The price: 6.9 comments per PR, 42% of them true but minor.
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-aacr-dark.png">
-  <img src="docs/media/bench-aacr.png" alt="AACR-Bench, 185 PRs, 520 verified defects. Share of high-severity defects found: QuickReview 97%, Codex CLI 90%, pi-review panel 89%, OpenCode 84%, Claude Code 81%, open-code-review 71%, PR-Agent 62%. Share of all defects found: QuickReview 89%, pi-review panel 67%, Claude Code 62%, open-code-review 57%, Codex CLI 55%, OpenCode 51%, PR-Agent 37%.">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-same-model-dark.png">
+  <img src="docs/media/bench-same-model.png" alt="AACR-Bench, the same base model in two reviewers, one judge, share found at high, medium and low severity. Claude Opus 5.5, 40 PRs: QuickReview 94%, 98%, 93%; Claude Code /code-review 75%, 71%, 45%. GPT-6.1 Sol, 185 PRs: QuickReview 97%, 93%, 84%; Codex CLI at high 90%, 70%, 37%. GPT-6 Sol, 185 PRs: QuickReview 96%, 86%, 80%; Codex CLI as shipped 78%, 61%, 31%.">
 </picture>
 
-**AACR-Bench, verified defects.** AACR-Bench's own reference comments are
-mostly not real problems, so we built a key of 520 defects, each verified in
-the code, and a judge for it. Over the panel and Codex CLI the lead holds
-under a paired bootstrap on high and on high + medium defects (+8.3 points
-[+1.9, +14.6] on high over the panel). The price: 6.9 comments per PR, 42%
-of them true but minor.
+**Same model, two reviewers.** With the model held fixed, QuickReview still
+finds more than the model maker's own reviewer on each of the three models
+where we ran both, at 11 to 20 times the cost ($3.24 against $0.16 per PR on
+Opus). This contrasts two tools, not a measured design effect: they also
+differ in budget and inputs, Claude Code ran `/code-review` at its default
+effort, the Opus and GPT-6 Sol rows are September builds of QuickReview, and
+the 40 Opus PRs are all PRs QuickReview was tuned on.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-martian-dark.png">
@@ -97,7 +122,7 @@ per PR and counts every other comment as a false positive. It extracts about
 12.8 issues per PR from QuickReview's reviews, so QuickReview has the highest
 recall and the lowest precision. We
 audited the goldens: of the 86 that describe a real defect the PR
-introduces, it finds 75 (87%), the most of any tool.
+introduces, it finds 75 (87%), the most of the seven reviewers judged alike.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-qodo-dark.png">
@@ -109,20 +134,57 @@ and 271 violations of rules written in the repo. QuickReview finds the most
 functional bugs of the thirteen tools (52.1%) and the second-most issues
 overall, at the lowest precision; it is fourth on F1.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/bench-elo-dark.png">
+  <img src="docs/media/bench-elo.png" alt="Pairwise Elo on the 20 Martian PRs where QuickReview on GPT-6.1 Sol or DeepSeek did worst, two judges pooled, with 95% intervals. Claude Code max, Opus 5.5 directing Sonnet 5.5 agents, 1666, QuickReview on Opus 5.5 1628, QuickReview on GPT-6.1 Sol 1566, Claude Code high on Opus 5.5 1518, QuickReview on Sonnet 5.5 1489, QuickReview on DeepSeek V4.1 Flash 1406, Claude Code high on Sonnet 5.5 1398, QuickReview on GLM-5.3 Flash 1329.">
+</picture>
+
+**Judged side by side.** A pairwise judge reads two reviews of the same PR
+blind and picks the better one. GPT-6.1 Sol and Claude Opus 5.5 both judged,
+and a Bradley-Terry fit over their 596 verdicts gives Elo; alone, the two
+judges pick the same winner only 56% of the time, which is why they are
+pooled. On the 20 Martian PRs where QuickReview on GPT-6.1 Sol or DeepSeek did
+worst, QuickReview on Opus 5.5 (six of its lenses on GPT-6 Luna) beat Claude
+Code's `/code-review` at high effort on Opus 5.5 in 29 of 40 verdicts, at more
+than ten times its cost (about $4 per PR). Only Claude Code's max mode (Opus
+5.5 directing Sonnet 5.5 agents, about $20 per PR) ranks higher, by a margin
+inside the intervals.
+
+**Other models.** QuickReview's models are configurable. On AACR-Bench
+it holds most of its recall on cheap open models, and it falls apart on a
+weak one:
+
+| QuickReview on | PRs | High (90) | Medium (145) | Low (285) | All (520) | $/PR | Judge |
+|---|---|---|---|---|---|---|---|
+| GPT-6.1 Sol (frozen build) | 185 | 87.5 (97%) | 134.5 (93%) | 239 (84%) | 461 (89%) | 2.06 | gpt-6-sol |
+| DeepSeek V4.1 Flash (mostly low effort) | 185 | 83 (92%) | 131 (90%) | 237.5 (83%) | 451.5 (87%) | 0.74 | gpt-6.1-sol |
+| GLM-5.3 Flash | 185 | 83 (92%) | 120.5 (83%) | 231.5 (81%) | 435 (84%) | 0.52 | gpt-6.1-sol |
+| GPT-6 Luna | 185 | 39 (43%) | 44 (30%) | 64 (22%) | 147 (28%) | 0.04 | gpt-6-sol |
+| Claude Opus 5.5 | 40 | 32/34 (94%) | 30.5/31 (98%) | 57/61 (93%) | 119.5/126 (95%) | 3.24 | gpt-6-sol |
+
+The best third-party reviewer at each severity finds 81 of 90 high (Codex
+CLI), 119 of 145 medium and 148.5 of 285 low (both the pi-review panel). The
+open-model rows ran a later build (mid-October, with cost changes made after
+the freeze) and a later judge; DeepSeek ran at low reasoning effort on 143 of
+its PRs, and GLM's review was missing a lens pass on 7. The GPT-6 Luna and
+Opus rows ran a September build; on the same 40 PRs as Opus, the frozen
+GPT-6.1 Sol build finds 33 of 34 high, 28 of 31 medium and 44 of 61 low. Read
+the table as directional.
+
 <details>
 <summary>The full tables</summary>
 
 **AACR-Bench** (185 PRs, 10 languages, 520 verified defects; a partly found defect counts ½)
 
-| Reviewer | High (90) | High + medium (235) | All (520) | Comments correct | $/PR | Median min/PR |
-|---|---|---|---|---|---|---|
-| **QuickReview** | **87.5 (97%)** | **222 (94.5%)** | **461 (89%)** | 92% | 2.06 | 17.5 |
-| pi-review panel (high) | 80 (89%) | 199 (85%) | 347.5 (67%) | 89% | 0.27 | 1.8 |
-| Claude Code (Opus 5.5) | 72.5 (81%) | 177.5 (76%) | 324.5 (62%) | 81% | 0.20 | 0.7 |
-| open-code-review (high) | 63.5 (71%) | 165.5 (70%) | 298.5 (57%) | 86% | 0.53 | 1.8 |
-| Codex CLI (high) | 81 (90%) | 182.5 (78%) | 287 (55%) | 93% | 0.14 | 2.1 |
-| OpenCode (+ PR text) | 76 (84%) | 175 (74%) | 263.5 (51%) | 93% | 0.17 | 2.3 |
-| PR-Agent | 55.5 (62%) | 125.5 (53%) | 194 (37%) | 76% | 0.07 | 1.9 |
+| Reviewer | High (90) | Medium (145) | Low (285) | All (520) | Comments correct | $/PR | Median min/PR |
+|---|---|---|---|---|---|---|---|
+| **QuickReview** | **87.5 (97%)** | **134.5 (93%)** | **239 (84%)** | **461 (89%)** | 92% | 2.06 | 17.5 |
+| pi-review panel (high) | 80 (89%) | 119 (82%) | 148.5 (52%) | 347.5 (67%) | 89% | 0.27 | 1.8 |
+| Claude Code (Opus 5.5) | 72.5 (81%) | 105 (72%) | 147 (52%) | 324.5 (62%) | 81% | 0.20 | 0.7 |
+| open-code-review (high) | 63.5 (71%) | 102 (70%) | 133 (47%) | 298.5 (57%) | 86% | 0.53 | 1.8 |
+| Codex CLI (high) | 81 (90%) | 101.5 (70%) | 104.5 (37%) | 287 (55%) | 93% | 0.14 | 2.1 |
+| OpenCode (+ PR text) | 76 (84%) | 99 (68%) | 88.5 (31%) | 263.5 (51%) | 93% | 0.17 | 2.3 |
+| PR-Agent | 55.5 (62%) | 70 (48%) | 68.5 (24%) | 194 (37%) | 76% | 0.07 | 1.9 |
 
 **Martian** (50 PRs, Core; one `gpt-6.1-sol` judge for every row, the vendor rows re-judged from their published comments)
 
@@ -154,8 +216,8 @@ overall, at the lowest precision; it is fourth on F1.
 **Held-out PRs.** The last tuning round was mined from misses on part of
 each benchmark. On the PRs kept out of it, the frozen build finds 83% of
 AACR-Bench's defects (20 PRs), ties qodo-extended-v2 on Martian's real
-goldens (43 of 52, 30 PRs), and reaches 60.3% recall and F1 53.0 on Qodo
-(31 PRs), against 51.3 for qodo-exhaustive.
+goldens (43 of 52, 30 PRs), and on Qodo (31 PRs) reaches 60.3% recall and
+F1 53.0, level with qodo-exhaustive's 51.3.
 
 **Read more.** Two papers carry the method, every table and the threats to
 validity: [*Measuring whether a code review finds the real
@@ -223,9 +285,19 @@ Slack concierge, a local companion session, opt-in escalation notes, and the
 
 ## Quickstart
 
-You need **Docker** with Compose v2 and **a GitHub account that can create an
-App** on the repository to review. No personal access token is used. On
-Windows, run everything inside **WSL2**.
+You need **Docker** with Compose v2, a model login, and either `gh` signed in
+to your own GitHub account or **a GitHub account that can create an App** on
+the repository to review. On Windows, run everything inside **WSL2**.
+
+There is a second route that needs no App: `[github] auth = "user"` runs the
+reviewer on **your own GitHub account**. Use it on one box where `gh` is
+already signed in. It is polling-only, with no webhooks and no tunnel. Every
+review it posts is a COMMENT that states its verdict, because an automated
+verdict must never count as your approval and GitHub refuses either on your own
+PR. Your token reaches the daemon only as the 0600 file
+`<secrets dir>/github_token`, which `qcr github-token sync` refreshes from
+`gh`. It never comes from the environment or a command line. On the App route
+no personal access token is used.
 
 ```sh
 # once: install `qcr`, the host wrapper the image writes (docs/host-wrapper.md);
@@ -233,32 +305,38 @@ Windows, run everything inside **WSL2**.
 docker run --rm --user "$(id -u):$(id -g)" -v ~/.local/bin:/out \
   ghcr.io/quickchatai/quickreview:<version> install
 
-qcr onboard          # the whole setup, guided
+qcr                  # the home: sign in, connect GitHub, choose a repository
 ```
 
-`qcr onboard` is a pi agent that walks you through setup using named,
-deterministic tools whose results you see. It checks the machine, asks where
-the reviewer lives and which LLM route you use (a ChatGPT subscription or an
-OpenAI API key, [docs/llm-setup.md](docs/llm-setup.md)), **creates your
-GitHub App in one click** from a pinned manifest, wires the webhook ingress,
-mints the memory keys, brings the stack up, and then **watches a real review
-land in the dry-run record** on a PR you label. Only then does it offer to go
-live. It is resumable, and re-running it on a working install is a
-diagnostic. Every step: [docs/onboarding.md](docs/onboarding.md).
+A bare `qcr` opens the **home**: QuickReview's own pi, with the plugin loaded
+and a panel of your repository's open pull requests. On a first run the panel
+is a short setup checklist, and anything already set up is found and skipped:
+sign in to OpenAI with pi's device code (device-code login must be on in
+ChatGPT → Settings → Security), check that `gh` is signed in, and choose a
+repository from your recently pushed ones or paste any `owner/name` or URL.
+`alt+n` runs the next step. The home then lists the pull requests, "To review"
+and "Reviewed". `qcr tui` opens the admin TUI, and only it starts the
+companion. Through the Docker wrapper the home runs in a container of its own:
+its login is kept in the `qcr-login` volume, its config and sessions in the
+`qcr-state` volume, and its `gh` uses the token the wrapper finds on this
+machine (`GITHUB_TOKEN`, `GH_TOKEN` or `gh auth token`). The always-on daemon, a GitHub App, webhooks and a server over ssh
+are the setup wizard's steps: [docs/onboarding.md](docs/onboarding.md).
 
 ### Where the reviewer lives
 
-- **A server over ssh (recommended)**, because a reviewer that is asleep
-  reviews nothing. Setup rides the Ansible deploy
+- **This computer**, in Docker ([docker/README.md](docker/README.md)): the
+  pick when the machine is itself an always-on server, such as a cloud VM;
+  on a laptop it reviews only while the machine is awake.
+- **A server over ssh**, recommended when your own computer sleeps. Setup
+  rides the Ansible deploy
   ([deploy/ansible/README.md](deploy/ansible/README.md)); it needs
   passwordless sudo there and `ansible-playbook` on your machine.
-- **This computer**, in Docker, reviewing while the machine is awake
-  ([docker/README.md](docker/README.md)).
 
-GitHub needs an HTTPS URL to deliver webhooks to: a Cloudflare quick tunnel,
-ngrok, your own named Cloudflare tunnel, or polling only, which exposes
-nothing but delays triggers by up to one poll interval and silences
-author-reply routing and the `[feedback]` loop. The trade-offs are in
+Polling is the default: the daemon checks GitHub every few minutes and
+exposes nothing, at the cost of trigger latency up to one poll interval and
+quiet author-reply routing and `[feedback]` loop. Webhooks need an HTTPS URL:
+a Cloudflare quick tunnel, ngrok or your own named Cloudflare tunnel, on the
+App route only. The trade-offs are in
 [docker/README.md](docker/README.md).
 
 `dry_run = true` stays on until you flip it, through the wizard's go-live
@@ -279,9 +357,10 @@ npm i -g @quickchatai/quickreview
 qcr login              # pi's own /login, for the review's models
 qcr review             # review this branch against its base, with no daemon
 qcr review 123         # review a pull request (or pass its URL)
-qcr pi                 # pi with the QuickReview plugin: /review /scan /selfimprove /qcr-setup
+qcr pi                 # pi with the plugin (/qcr-review /qcr-scan /qcr-setup) and /selfimprove
 qcr update             # update qcr with the package manager that installed it
-qcr                    # the admin TUI
+qcr                    # the home: pi on your own login, with your repo's pull requests
+qcr tui                # the admin TUI
 ```
 
 `qcr review` asks where the result goes (shown, saved as markdown and JSON,
@@ -337,8 +416,9 @@ never the same system ([MANIFESTO.md](MANIFESTO.md)).
 
 ## Appendix — setting up by hand
 
-`qcr onboard` composes these tools rather than replacing them; re-running it
-afterwards re-checks every step without rewriting what already holds.
+The setup wizard's steps ([docs/onboarding.md](docs/onboarding.md)) compose
+these tools rather than replacing them; re-running one afterwards re-checks it
+without rewriting what already holds.
 
 ```sh
 IMG=ghcr.io/quickchatai/quickreview:<version>
@@ -355,8 +435,8 @@ curl -s http://127.0.0.1:8787/health
 
 Then point your HTTPS ingress at the webhook port, install the App, create
 the trigger label and label a PR: `state/dryrun/` fills up. The memory keys
-are minted by the running server, so run `qcr onboard` for that step even if
-you did the rest by hand; declining memory is supported.
+are minted by the running server (the wizard's memory-keys steps, 60 and 72,
+in [docs/onboarding.md](docs/onboarding.md)); declining memory is supported.
 
 ## Star history
 

package/bin/qcr.js

@@ -3,7 +3,7 @@
 // name `qcr`, so the CLI module cannot recognise itself by its file name: this
 // file imports the bin's front door and calls it explicitly. The front door
 // (src/qcrbin.ts) runs the verbs an npm install needs without the state
-// database's native driver, opens the admin TUI on a bare `qcr`, and hands
+// database's native driver, opens the home on a bare `qcr`, and hands
 // every other verb to the app's `main` (src/cli.ts). The image's
 // `node /opt/qcr/dist/src/cli.js` is the app's entry, run directly.
 import { runBin } from "../dist/src/qcrbin.js";

package/config.example.toml

@@ -6,10 +6,11 @@
 # supply are marked "← FILL (n)" — grep for FILL. Flip dry_run to false only
 # as a deliberate cutover act, never as part of setup.
 #
-# YOU DO NOT HAVE TO FILL THIS BY HAND: `scripts/qcr onboard` interviews you
-# for the few values only you can answer, derives the rest, and patches this
-# file in place — every comment survives, and a re-run edits only what changed.
-# It never writes dry_run in either direction; going live is its own explicit
+# YOU DO NOT HAVE TO FILL THIS BY HAND: a bare `qcr` (the home) writes the
+# repository you choose and its defaults, and the setup wizard's steps
+# interview you for the rest, derive what they can, and patch this file in
+# place — every comment survives, and a re-run edits only what changed.
+# Neither writes dry_run in either direction; going live is its own explicit
 # step. See docs/onboarding.md.
 # ONE mutation class is exempt and executes for real even here: the App
 # re-pointing its OWN webhook URL (see [ingress] below) — it can never touch
@@ -27,8 +28,22 @@ timezone = "UTC"                             # ← FILL: your IANA timezone, e.g
 
 [github]
 repo = ""                                    # ← FILL (1): the repo to review, "owner/name"
-app_slug = ""                                # ← FILL (2): your GitHub App slug
-bot_login = ""                               # ← FILL (3): the App bot login, "<app_slug>[bot]"
+# Whose GitHub credential the daemon runs on:
+#   "app"  (the default; a missing key means "app") — a GitHub App: its
+#          installation token, webhooks, APPROVE / REQUEST_CHANGES reviews.
+#   "user" — your OWN GitHub account, no App. Polling only: [ingress] shape
+#          must be "polling" (config load refuses anything else), no webhooks,
+#          no webhook self-heal. Every review posts as a COMMENT whose body
+#          states the verdict (an automated verdict never counts as your
+#          approval, and GitHub refuses either on your own PR). The token is
+#          read from the FILE <secrets dir>/github_token (0600, the token
+#          alone), which `qcr github-token sync` writes from your `gh` login;
+#          never from the environment or a command line. app_slug may be "";
+#          bot_login is your own GitHub login. The App secrets (app_id,
+#          app.pem, webhook_secret) are not needed.
+#auth = "app"
+app_slug = ""                                # ← FILL (2): your GitHub App slug ("" under auth = "user")
+bot_login = ""                               # ← FILL (3): the App bot login, "<app_slug>[bot]" (your login under auth = "user")
 review_team = ""                            # ← FILL (4): "org/team" whose review request triggers
 # There is no reviewer knob here. The reviewer never hands a PR back: it always
 # decides on the merits and posts a verdict. If you want a named person told
@@ -39,7 +54,8 @@ in_progress_label = "AI review in progress"
 reviewed_label = "Automatic Review"
 improvement_label = "Bot improvement"
 issue_label = "bot-filed"
-# secrets dir: app_id, app.pem, webhook_secret, tunnel_token; optional openai_api_key (pi, API-key
+# secrets dir: app_id, app.pem, webhook_secret, tunnel_token (auth = "user": github_token instead
+# of the first three); optional openai_api_key (pi, API-key
 # route) and openai_embeddings_api_key (only with embedding_provider = "openai" in the openviking table)
 # "" (recommended) = the install's config home, $XDG_CONFIG_HOME/qcr/<install>/secrets (the old
 # ~/.config/quickreview-bot is never read — `qcr install migrate` moves it). A path here wins.
@@ -81,8 +97,12 @@ port = 8787                                  # loopback only; your HTTPS ingress
 # touches only the App's own configuration, never the reviewed repo. Off by
 # default: with the section absent (or shape = "none") no watcher ever starts —
 # a stable hostname (named tunnel, VM route) needs none of this.
+# shape = "polling" takes no webhooks at all: the daemon's /webhook route
+# refuses every delivery, no webhook_secret is read, and the reconcile poll
+# (poll_interval_s, below) is the only trigger. [github] auth = "user"
+# requires it.
 #[ingress]
-#shape = "tunnel-file"                       # "none" (default) | "tunnel-file"
+#shape = "tunnel-file"                       # "none" (default) | "tunnel-file" | "polling"
 #hostname_file = ""                          # "" ⇒ <root>/state/ingress/hostname
 #debounce_ms = 3000                          # settle time after a file change
 #sweep_interval_s = 300                      # polling backstop behind fs.watch
@@ -204,7 +224,9 @@ improvement_pr_deny_prefixes = ["migrations/", "infra/", "ansible/", ".github/wo
 [models]
 # default for every role; tiered pass models below
 # Provider prefix is `openai-codex/` — the ChatGPT-OAuth route's provider key
-# in pi's auth.json (direct `openai/` needs an API key we don't ship).
+# in pi's auth.json. Any OpenAI login serves it: when pi holds no
+# `openai-codex` login but an `openai` one (pi 1.4's Sign in with ChatGPT, or
+# an OpenAI API key), the same model runs on `openai` (docs/llm-setup.md).
 default = "openai-codex/gpt-6.1-sol"
 conversation = "openai-codex/gpt-6.1-sol"
 # Passes always run at sol-high — single variant, not raisable (already top).
@@ -261,7 +283,11 @@ small_diff_lines = 150
 #             memory forward follows this knob too — it reaches the daemon
 #             container's loopback memory engine with a plain `docker exec`
 #             (the forward script's --local mode) instead of the ssh hop.
-# Always explicit: an empty ssh_host does NOT mean local.
+# Onboarding writes this from the recorded topology. Until it has (ssh with an
+# EMPTY ssh_host), the TUI never runs `ssh ""`: on a compose project (the
+# checklist recorded the local topology, or the project .env pins
+# QCR_VERSION) it reads the local stack and says so once; otherwise every
+# surface says "ssh_host is empty — set it to the VM's ssh alias".
 target = "ssh"
 ssh_host = ""                                # ← FILL (7): ssh alias of the VM running the container
                                              #   (leave "" when target = "local" — it is unused)
@@ -270,10 +296,14 @@ memory_container = ""             # the container the memory forward relays into
                                   # (OpenViking is the daemon container's child). On a VM running
                                   # the memory sidecar (the openviking table's endpoint =
                                   # "remote") set "quickreview-memory"; flip it back with the endpoint.
-remote_state_dir = "/opt/quickreview/state"  # host path on ssh; inside the daemon container on local
+remote_state_dir = "/opt/quickreview/state"  # host path on ssh; inside the daemon container on local,
+                                  # where this default reads as the release image's /opt/qcr/state
+                                  # (the compose state volume; onboarding writes it for local)
 remote_sandbox_root = ""         # "" = read the container's qcr.layout label (release: /opt/qcr, legacy: /opt/quickreview/sandbox);
                                   # a value here wins and is never probed
-sudo_docker = true                # docker on the VM needs sudo (root-owned socket)
+sudo_docker = true                # docker on the VM needs sudo (root-owned socket). On local, onboarding
+                                  # writes false, and the TUI drops sudo by itself when this user can open
+                                  # the docker socket (a sudo prompt behind the TUI can only fail)
 poll_interval_s = 3
 stale_after_s = 90                # DATA STALE banner past this written_at age
                                   # (the daemon rewrites status.json every ~30s)
@@ -338,6 +368,19 @@ session_dir = "state/pi-sessions"
 # lens_cache_stagger_ms = 2500
 # lens_pass_deadline_min = 8
 
+[home]
+# The home: a bare `qcr` opens the app's own pinned pi, on your own pi login
+# ($PI_CODING_AGENT_DIR, default ~/.pi/agent), with a panel of the
+# repository's pull requests. Every key is optional.
+#   model — the chat's model, "provider/id". The panel counts only this
+#           model's provider as signed in: a login under another provider
+#           cannot run the chat.
+#   tools — "reviewer": the model may call the plugin's tools, the home's
+#           own home_* tools and pi's read tools (read, grep, find, ls), and
+#           no MCP server starts. "full": every tool pi has.
+model = "openai-codex/gpt-6.1-sol"
+tools = "reviewer"
+
 [memory]
 # Round seeding — how much memory rides each round prompt and how
 # long the daemon waits for it. Memory NEVER blocks or delays a round: past
@@ -594,7 +637,10 @@ local_embedder_threads = 1
 # (COMPANION_DEFAULTS) are the shipped configuration; uncomment to override.
 # enabled = true                  # `qcr tui` starts it unless --no-companion
 # container_name = "qcr-companion"
-# image = "qcr-companion:release" # the release image (docker/Dockerfile) in companion mode, built from the app root: qcr companion rebuild
+# image = "qcr-companion:release" # the release image (docker/Dockerfile) in companion mode, built from the app root: qcr companion rebuild.
+#                                  # Left unset on a compose box (the project .env pins QCR_VERSION), a first start runs the
+#                                  # already-pulled ghcr.io/quickchatai/quickreview:<QCR_VERSION> instead of building, unless a
+#                                  # local build exists; a ghcr.io/quickchatai/quickreview tag set here is pulled, never built over
 # pihome_volume = "companion-pihome"   # its OWN pi auth — never the VM's auth.json
 # session = "companion"           # tmux session inside the container
 # model = "openai-codex/gpt-6.1-sol:medium"
@@ -859,7 +905,7 @@ extra_vendored_segments = []   # extra third-party markers (case-insensitive)
 # whatever — the system BEHAVES exactly as a build without the feature.
 # (The placeholder that renders empty leaves a blank line in the prompt, like
 # the sibling notes beside it.)
-# `qcr onboard`'s escalation step writes this section.
+# The setup wizard's escalation step writes this section.
 #
 # The configuration cannot be half-done: `enabled = true` with no `targets`,
 # or a rule pointing at a login that is not a target, or a rule that declares

package/deploy/ansible/README.md

@@ -12,7 +12,7 @@ once (`deploy.sh provision`, this playbook), which installs a thin updater,
 `qcr-update`, and its run spec; every deploy after that is
 `deploy.sh release <version>`, which runs `ssh vm sudo qcr-update ...`.
 
-> **`qcr onboard` drives this route for you.** The wizard's
+> **The setup wizard's steps drive this route.** The wizard's
 > **topology** step offers it as one of two first-class answers — advertised as
 > the always-on recommendation, because a reviewer that is asleep reviews
 > nothing — then checks your ssh alias and agent *before* anything is built
@@ -40,7 +40,7 @@ having no built-in permission system.
 
 ## Prerequisites (once, manual)
 
-Items 2–4 are what `qcr onboard` fills in for you on this route; item 1 is
+Items 2–4 are what the setup wizard fills in for you on this route; item 1 is
 yours either way — the wizard never creates a machine.
 
 1. **A VM you can reach over ssh by an alias**, with passwordless sudo for your
@@ -198,14 +198,20 @@ when one names another root. `remote_state_dir` stays the host path.
 
 ### Pulling the release
 
-The images are private and are pulled BY the updater, on the VM, by digest. The VM pulls them with ONE credential: your own CLASSIC
-personal access token, scoped `read:packages` and nothing else, stored by
-`docker login` in root's docker config on the VM host (never in a container,
-env, argv or the secrets directory: the daemon holds only the App credential). Not the token `gh auth
-token` prints: that one carries the full scopes of your gh login.
-
-A deploy needs this login to exist before the first `release` (the pull is the
-updater's first step, and a lapsed login fails there with nothing changed).
+The images are public on ghcr.io and are pulled BY the updater, on the VM, by
+digest. A public pull needs no login, so a VM that pulls the release images
+needs no registry credential at all; `deploy.sh verify` and `release` then say
+`no ghcr login recorded` and nothing more.
+
+**A private mirror.** Images that are not public (`QC_RELEASE_IMAGE` and
+`QC_RELEASE_MEMORY_IMAGE` naming another package) need the VM logged in, with
+ONE credential: your own CLASSIC personal access token, scoped `read:packages`
+and nothing else, stored by `docker login` in root's docker config on the VM
+host (never in a container, env, argv or the secrets directory: the daemon
+holds only the App credential). Not the token `gh auth token` prints: that one
+carries the full scopes of your gh login. The login must exist before the
+first `release` from the mirror (the pull is the updater's first step, and a
+lapsed login fails there with nothing changed).
 
 Once per VM, and again when the token is renewed (it expires after one year):
 
@@ -227,7 +233,9 @@ idempotent, and the token is never an argument or an environment variable.
 
 A lapsed login fails the updater's pull before anything on the VM changes
 (`qcr-update` refuses at its `pull` step). `scripts/deploy.sh verify` and
-`release` warn 14 days before the recorded expiry. `ssh <vm> sudo docker logout ghcr.io` removes the login.
+`release` warn 14 days before the recorded expiry. `ssh <vm> sudo docker logout ghcr.io` removes the login;
+a VM back on the public images can drop it, and the recorded expiry with it
+(`<state home>/ghcr-token-expiry`), so the warning stops.
 
 ### The cutover (legacy image to release image)
 
@@ -307,7 +315,7 @@ ssh <vm> docker exec quickreview-sandbox tmux ls
 ssh <vm> curl -sS http://127.0.0.1:8787/health     # loopback-only by design
 ```
 
-That is the same layering `qcr onboard`'s verification step runs — containers,
+That is the same layering the setup wizard's verification step runs — containers,
 then the health endpoint, then GitHub's own webhook delivery log — and the
 order matters: a container that is not up cannot answer a health probe, and a
 daemon that is not answering cannot accept a delivery. While the tunnel is up

package/deploy/ansible/inventory.example.ini

@@ -1,7 +1,7 @@
 # Copy to inventory.ini and fill in — inventory.ini is gitignored:
 # it carries YOUR real hostnames and stays local to the controller machine.
 #
-# `scripts/qcr onboard` writes inventory.ini for you on the server route, from
+# The setup wizard writes inventory.ini for you on the server route, from
 # answers you have already given (the ssh alias, the login user your ssh config
 # resolves, and whether the playbook should install cloudflared). This file
 # documents what it writes, and what to fill if you do it by hand.

package/deploy/collect-secrets.sh

@@ -7,7 +7,7 @@
 # Values are read with hidden input and NEVER printed back. Re-run any time —
 # existing files are kept unless you choose to replace them.
 #
-# `scripts/qcr onboard` writes app_id / app.pem / webhook_secret itself, from
+# The setup wizard writes app_id / app.pem / webhook_secret itself, from
 # the GitHub App manifest exchange, and mints the OpenViking keys — so on the
 # guided path you only reach for this script for the values it points you at
 # (the OpenAI key, a tunnel token, an ngrok authtoken, the hosted-embeddings

package/deploy/qcr-update.sh

@@ -535,7 +535,7 @@ fi
 # ---- 4. pull both images by digest, check them ----------------------------------------------------------
 
 step pull
-d pull "$DAEMON_REF" >/dev/null || die "could not pull $DAEMON_REF (is the VM logged in to ghcr.io? scripts/vm-ghcr-login.sh)"
+d pull "$DAEMON_REF" >/dev/null || die "could not pull $DAEMON_REF (the release images are public: check the VM reaches ghcr.io and the digest is published; a private mirror needs the VM logged in, scripts/vm-ghcr-login.sh)"
 d pull "$MEMORY_REF" >/dev/null || die "could not pull $MEMORY_REF"
 
 step check-images

package/dist/extensions/cli/home.js

@@ -0,0 +1,14 @@
+// The env shim for the home's extension: the one place the process's env
+// becomes its options (extensions/home.ts). A bare `qcr` loads it by path
+// (src/home/launch.ts), with the model and tool set it launched on in the env.
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { homeOptionsFromEnv } from "../../src/home/adapters.js";
+import { homeSetupFromEnv } from "../../src/home/setupadapters.js";
+import { createHome } from "../home.js";
+export default function activate(pi) {
+    void createHome({
+        ...homeOptionsFromEnv(process.env),
+        setup: homeSetupFromEnv(process.env, VERSION),
+    })(pi);
+}
+//# sourceMappingURL=home.js.map

package/dist/extensions/cli/home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home.js","sourceRoot":"","sources":["../../../extensions/cli/home.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,+EAA+E;AAC/E,OAAO,EAAE,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAgB;IAC/C,KAAK,UAAU,CAAC;QACd,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC;QAClC,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC;KAC9C,CAAC,CAAC,EAAE,CAAC,CAAC;AACT,CAAC"}

package/dist/extensions/cli/login-route.js

@@ -0,0 +1,5 @@
+import { createLoginRoute, loginRouteConfigFromEnv } from "../login-route.js";
+export default function activate(pi) {
+    void createLoginRoute(loginRouteConfigFromEnv(process.env))(pi);
+}
+//# sourceMappingURL=login-route.js.map

package/dist/extensions/cli/login-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-route.js","sourceRoot":"","sources":["../../../extensions/cli/login-route.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE9E,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAgB;IAC/C,KAAK,gBAAgB,CAAC,uBAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/extensions/cli/selfimprove.js

@@ -0,0 +1,18 @@
+// The env shim for the app's /selfimprove (extensions/selfimprove.ts): the
+// one place the process's env, home and standard output become its config.
+// `qcr pi` loads this file beside the plugin.
+import { homedir } from "node:os";
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { nodeRunner } from "@quickchatai/pi-quickreview/src/plugin/runner.js";
+import { createSelfImprove } from "../selfimprove.js";
+export default function activate(pi) {
+    const env = process.env;
+    createSelfImprove({
+        env,
+        home: (env["HOME"] ?? "").trim() || homedir(),
+        runner: nodeRunner(env),
+        print: (text) => void process.stdout.write(text.endsWith("\n") ? text : `${text}\n`),
+        piVersion: VERSION,
+    })(pi);
+}
+//# sourceMappingURL=selfimprove.js.map

package/dist/extensions/cli/selfimprove.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfimprove.js","sourceRoot":"","sources":["../../../extensions/cli/selfimprove.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,8CAA8C;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,kDAAkD,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAgB;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,iBAAiB,CAAC;QAChB,GAAG;QACH,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,OAAO,EAAE;QAC7C,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC;QACvB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;QACpF,SAAS,EAAE,OAAO;KACnB,CAAC,CAAC,EAAE,CAAC,CAAC;AACT,CAAC"}