feat(catalog): provider-level auto-review model selection

docs-site/src/content/docs/guides/providers.md

@@ -999,6 +999,57 @@ dashboard or `custom` in `ocx init` and enter the base URL. See the
 [Configuration reference](/reference/configuration/) for every provider field
 (`headers`, `noReasoningModels`, `noVisionModels`, `models`, …).
 
+## Approval reviewer per provider
+
+Codex asks a second model to review approval requests, and takes that reviewer from
+`auto_review_model_override` on the catalog row of the current turn's model. The root
+`auto_review_model` in `$CODEX_HOME/config.toml` applies one reviewer to every row. To give a
+routed provider its own — usually cheaper — reviewer, set the selector on that provider row in
+`~/.opencodex/config.json`:
+
+```json
+{
+  "providers": {
+    "blsc": {
+      "autoReviewModel": "opencode-go/deepseek-v4-flash",
+      "autoReviewModelOverrides": { "kimi-k3": "gpt-5.6-terra" }
+    }
+  }
+}
+```
+
+`autoReviewModel` covers every routed row of the provider. `autoReviewModelOverrides` targets a
+single upstream model id and wins over it. A value is either a bare model id of that same provider
+or a public catalog slug such as `opencode-go/deepseek-v4-flash`, and a provider stamp wins over the
+root selector on its own rows while the root selector stays the fallback elsewhere.
+
+An override key may be written as the upstream model id or as the provider's published alias, and an
+id that contains a slash may be written raw or in its encoded catalog form — the
+[configuration reference](/reference/configuration/providers/#auto-review-approval-model-selection)
+lists those field-level rules.
+
+A bare value resolves against the provider's own rows first and then against a bare catalog row,
+which is how a native model such as `gpt-5.6-terra` is named; a value that matches neither is left
+unresolved, and a bare value that lands outside the provider prints a note naming the row that
+supplies the reviewer. Giving the full slug avoids the question entirely when the reviewer is
+another provider's routed model.
+
+Selectors are resolved against the final catalog on the next sync, each one on its own, and each
+fails closed by itself: an unresolved `autoReviewModel` prints a diagnostic and stamps no
+provider-wide rows, an unresolved `autoReviewModelOverrides` entry prints a diagnostic and stamps
+nothing for that model, and whatever does resolve is still applied. Rows without a provider stamp
+keep the root selector, or upstream behavior when that is unset.
+
+Removing a provider selector falls back field by field: clearing `autoReviewModel` drops
+provider-wide stamps from rows that have no per-model override, clearing an `autoReviewModelOverrides`
+entry drops that model's stamp so it takes the provider-wide selector when one is configured, and
+clearing both drops every provider stamp. Removing the root selector never clears provider stamps.
+
+These fields are configuration/API only — `PATCH /api/providers?name=<provider>` accepts them and
+the dashboard provider editor does not render inputs for them yet. The canonical `openai` provider
+rejects them. Field-by-field rules live in the
+[provider configuration reference](/reference/configuration/providers/#auto-review-approval-model-selection).
+
 ## Rate limits in the providers overview
 
 The **Rate limits** section of the Providers overview shows live utilization

docs-site/src/content/docs/reference/configuration/providers.md

@@ -260,6 +260,52 @@ use `null` to clear a scalar or the whole map. A map entry set to `null` or `""`
 entry while preserving other entries. Malformed writes are rejected before saving. A malformed
 optional pin in a hand-edited file is ignored on load without discarding the rest of the config.
 
+### Auto-review (approval) model selection
+
+Codex reads `auto_review_model_override` from the catalog row of the current turn's model to
+choose the model that reviews approval requests. The root `auto_review_model` setting in
+`$CODEX_HOME/config.toml` applies one reviewer to every catalog row; the provider-scoped fields
+below override it per provider. The [provider guide](/guides/providers/#approval-reviewer-per-provider)
+has the operator workflow and a worked example.
+
+`autoReviewModel` is the provider-wide reviewer target. A value can be a bare model id of that same
+provider (the catalog row is normalized to the `provider/model` slug) or a full public catalog
+slug such as `opencode-go/deepseek-v4-flash`. A bare value resolves against that provider's rows
+first and then against a bare catalog row, which is how a native model such as `gpt-5.6-terra` is
+named, and a bare value that lands outside the provider prints a note naming the row that actually
+supplies the reviewer; a value that matches neither is left unresolved. `autoReviewModelOverrides`
+keys are exact upstream model ids of that provider, or the provider's published alias for one
+(`modelAliases`); either spelling names the same routed row, whose slug carries the upstream id. An
+entry wins over the provider-wide value for its model. A provider
+stamp wins over the root selector on its own routed rows, and the root selector remains the
+fallback for native rows and routed rows without a provider stamp.
+Removing a provider selector falls back field by field: clearing `autoReviewModel` drops
+provider-wide stamps from rows that have no per-model override, clearing an `autoReviewModelOverrides`
+entry drops that model's stamp so it takes the provider-wide selector when one is configured, and
+clearing both drops every provider stamp. Removing the root selector never clears provider stamps.
+Model ids that contain a slash may be written raw or in their encoded catalog form; both
+spellings resolve to the same routed row.
+Selectors are resolved against the final catalog on each sync, independently of one another, and
+each fails closed on its own: an unresolved `autoReviewModel` emits a diagnostic and stamps no
+provider-wide rows, an unresolved `autoReviewModelOverrides` entry emits a diagnostic and stamps
+nothing for that model, and any selector that does resolve is still applied. Rows without a provider
+stamp keep the root selector, or normal upstream auto-review behavior when that is unset. The
+canonical `openai` provider does not accept these fields.
+
+Removing the root selector clears root stamps from every row, including native rows stamped by
+earlier releases that predate OpenCodex's provenance marker. That cleanup recognizes a legacy
+stamp by its shape — one value across the whole catalog that a routed row also carries — so a
+genuine per-row value matching that shape is cleared with it, and a catalog that has since
+diverged from that shape needs one manual sync. Provider stamps are never touched by root removal.
+
+`PATCH /api/providers?name=<provider>` accepts both fields. Use `null` to clear the scalar or
+the whole map; use a map entry of `null` or `""` to remove that model while preserving other
+entries. Unrelated provider saves preserve previously configured values.
+
+These two fields are reachable today from `config.json` and the provider management API only:
+the Dashboard provider editor does not render inputs for them yet, so a browser-only workflow
+cannot change them after the fact.
+
 ### Discovered model display names
 
 Use `modelDisplayNames` when a provider returns machine friendly ids but the Codex model picker
@@ -328,6 +374,7 @@ projection, and merge precedence, so only a selector present in the catalog prod
 that sync can become an override. Native upstream values are preserved when the setting is
 cleared or unresolved. The persisted catalog field is read by Codex for the current turn's
 model, which is why a valid configured selector is copied to each applicable entry.
+Provider-scoped selectors (above) are applied before this root fallback and win on routed rows.
 
 ### FastWire B1 capability migration