docs: onboarding uses .pr-review.json:enabled, not labels

README.md

@@ -3,7 +3,8 @@
 An AI pull-request reviewer for Gitea that posts **inline comments with suggested
 fixes**, not a wall of prose — and reports what each review cost.
 
-Label a PR `AI-REVIEW`. A webhook wakes a service that checks the repo out at the
+A webhook wakes for any PR on a repo whose default branch carries a
+`.pr-review.json` with `"enabled": true`. The service checks the repo out at the
 PR's head commit, reads the changed files *and the code around them*, runs the
 repo's own linters, and posts a review anchored to real lines.
 
@@ -40,14 +41,16 @@ built — see [`docs/plans/`](docs/plans/).
 
 What works today:
 
-- a central webhook service, so onboarding a repo is *add the bot + add the label*
+- a central webhook service, so onboarding a repo is *add the bot + commit
+  `.pr-review.json:enabled = true`*
 - whole-repo context: the reviewer reads callers and types, not just the hunk
 - inline comments with language-highlighted suggested fixes, anchored to
   post-change lines and validated in Python before posting
 - per-commit dedupe, and prior reviews fed back so a re-push synthesises rather
   than repeats
-- `.pr-review.json` for per-repo focus and house rules
-- optional token/cost reporting via an `AI-USAGE` label
+- `.pr-review.json` for per-repo focus and house rules (also the opt-in flag)
+- token-usage reporting on every review, measured from opencode `step_finish`
+  events
 - containment against hostile PR content (see [Security](#security))
 
 Not yet: status checks, fail-close, attention tiering enforced in code (it is
@@ -56,21 +59,22 @@ currently a skill the agent follows), multi-model routing.
 ## How a review runs
 
 ```
-PR labelled AI-REVIEW
+PR opened on repo with `.pr-review.json:enabled = true`
    │  Gitea webhook (HMAC-verified, body-capped, concurrency-bounded)
    ▼
 review_pr()
-   1. dedupe        already reviewed this exact sha? stop.
-   2. fetch diff    + .pr-review.json from the BASE branch
-   3. checkout      repo archive at head sha → temp workdir
-   4. sanitize      delete author-controlled agent-instruction files
-   5. brief         .pragent/brief.md, untrusted parts explicitly fenced
-   6. review        opencode agent: read code, run linters, emit findings JSON
-   7. anchor        validate every line against the diff's post-change lines
-   8. post          inline comments + summary, as pragent-bot
+   1. opt-in    .pr-review.json:enabled=true on base? if not, skip.
+   2. dedupe    already reviewed this exact sha? stop.
+   3. fetch     diff + .pr-review.json from the BASE branch
+   4. checkout  repo archive at head sha → temp workdir
+   5. sanitize  delete author-controlled agent-instruction files
+   6. brief     .pragent/brief.md, untrusted parts explicitly fenced
+   7. review    opencode agent: read code, run linters, emit findings JSON
+   8. anchor    validate every line against the diff's post-change lines
+   9. post      inline comments + summary, as pragent-bot
 ```
 
-Steps 1, 2, 7 and 8 are deterministic Python. The model's only job is step 6 —
+Steps 1, 3, 8 and 9 are deterministic Python. The model's only job is step 7 —
 producing correct findings. It never talks to Gitea, and a finding whose line
 does not validate becomes a summary bullet rather than a misplaced comment.
 
@@ -79,8 +83,8 @@ does not validate becomes a summary bullet rather than a misplaced comment.
 Onboarding a repo, once the service is running for that owner:
 
 1. add `pragent-bot` as a **Write** collaborator
-2. create the `AI-REVIEW` label
-3. label a PR
+2. commit `.pr-review.json: {"enabled": true}` to the repo's default branch
+3. open a PR
 
 Standing up the service itself — the webhook, the image, the Gitea SSRF
 allow-list, the per-owner webhook registration — is in
@@ -136,8 +140,9 @@ concurrency. Full threat model and residual risks: `pilot/README-webhook.md`.
 
 The pilot runs against a self-hosted model and bills nothing per token, but the
 token *work* is real. `pilot/cost_model.py` prices it against published API
-rates, calibrated against runs measured through the `AI-USAGE` label
-(`OBSERVED_RUNS` in that file — append to it, don't guess).
+rates, calibrated against runs measured through the usage telemetry
+(`OBSERVED_RUNS` in that file — append to it, don't guess). Tokens are summed
+from opencode `step_finish` events per review.
 
 Two measured reviews of a ~1100-line PR in this repo: 28 and 31 agent steps,
 ~2.1M input tokens each, **zero cache reads or writes**. The demo repo's PR, same