@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/docs/PROVIDER_SETUP.md

@@ -0,0 +1,1737 @@
+# Provider Setup Guide
+
+This guide walks you through setting up AI providers for Build. Build supports multiple execution providers out of the box: Claude, Codex CLI, Cursor CLI, Copilot CLI, Gemini CLI, Grok, Kiro, Google Antigravity CLI, Pi CLI, and OpenCode. GLM/Z.AI models are available through OpenCode; OpenRouter is a catalog/pricing source, not an execution provider.
+
+> **Public-release validation status:** Claude and Codex are primary validated
+> providers. Grok, Cursor, and OpenCode are supported validated providers.
+> Antigravity and Pi are also supported validated; Gemini, Kiro, and Copilot
+> are experimental (Gemini is no longer being extended; see below). This is
+> separate from configured defaults:
+> `build config resolved --summary --json` reports the active execution and
+> judge defaults. Run `build provider list` and `build doctor --matrix` before
+> relying on a local provider.
+
+> **Execution modes:** All providers run locally through their CLI adapters. Variant mode `:cloud` and direct provider API transport are not executable product paths (see [ADR-023](https://github.com/ebrindley/build/blob/main/docs/adr/023-cli-only-provider-execution.md)). Historical telemetry may still contain Codex/Cursor cloud-shaped fields; those records stay readable but are not a signal to run cloud workflows.
+
+---
+
+## Model Selection and Namespaces
+
+Build enforces provider model purity: every provider only accepts its own canonical model identifiers; unknown or cross-provider names either omit the provider model override or raise a validation error, depending on the provider path. Use `build config resolved --summary --json` for active defaults, and keep the registry fresh with:
+
+```bash
+build provider refresh <id> --models
+```
+
+The release catalog is generated from Build's canonical provider YAML and is
+shipped with the package. Refresh writes a narrow, digest-bound model/pricing
+overlay; it does not rewrite release capabilities or executable configuration.
+Existing project `providers.yaml` files remain supported as policy overlays
+(for example enabled state, defaults, roles, mappings, and local limits), while
+their copied catalog inventory is ignored. New projects do not receive a
+provider-catalog snapshot.
+
+| Provider    | Default Source                   | Notes                                                                                                            |
+| ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Claude      | Primary validated               | Zero-flag model selection follows the installed Claude CLI; choose it explicitly during first-run setup or config |
+| Codex       | Primary validated               | Zero-flag model selection follows the installed Codex CLI; reasoning effort remains separately configurable      |
+| Grok        | Supported validated             | Use `--variant grok` for an explicit Grok run; not implied as the global default                    |
+| Cursor      | Supported validated             | `auto` is supported for Cursor-native routing; macOS Keychain access can block agent sandboxes                   |
+| OpenCode    | Supported validated             | Router CLI; use exact upstream model IDs such as `z-ai/glm-4.7`                                                  |
+| Antigravity | Supported validated             | Google `agy` CLI provider; authenticate with Google OAuth or `ANTIGRAVITY_API_KEY` where supported               |
+| Pi          | Supported validated             | Backend-agnostic host CLI; cost and capability depend on the configured backend; local OpenAI-compatible path not yet validated |
+| Gemini      | Experimental                    | No longer extended; opt-in only. Check vendor CLI availability and entitlements. CLI must be installed separately |
+| Copilot     | Experimental                    | Copilot CLI exposes its own supported model set                                                                  |
+| Kiro        | Experimental                    | Experimental native adapter; headless mode requires `KIRO_API_KEY`                                                |
+
+Use explicit provider IDs in configuration or CLI flags. Common provider IDs
+`claude`, `codex`, `grok`, `cursor`, `opencode`, and `gemini` cover most public
+release usage. Passing a generic GPT name to a provider that does not expose it
+now omits the model override or returns a validation error so you can correct
+the selection.
+
+For the shared installation and first-use sequence, follow
+[INSTALL.md: Set up a provider](../INSTALL.md#set-up-a-provider). First-run
+setup saves a provider selection, and an active profile takes precedence over
+project and user settings. Inspect `build config resolved --summary --json`
+before relying on zero-flag routing; the installation guide shows how to select
+a named profile explicitly. Deferred auth is a cold state, not proof of bad
+credentials: a real invocation establishes whether the selected CLI can run.
+
+For a read-only preview before installing or changing provider setup, the
+internal-tier `explain` command reads embedded config without initializing
+anything (it is intentionally absent from `build --help`):
+
+```bash
+build explain providers
+```
+
+### Fast model
+
+Anything that wants a fast model (`--variant <provider>:fast`, speed and cost
+optimization, flywheel verify stages, `roles.*.modelRole: fast`) uses one lookup, in this order: the active profile, then project,
+then user `defaults.providers.<id>.fastModel`, then the provider's fast slot in
+`providers.yaml`. Claude, Codex, Gemini and Cursor have a fast slot. A provider
+without one uses its default model. An executor on its fast model does not
+inherit `defaults.providers.<id>.reasoningEffort`; set `roles.executor.reasoningEffort`
+to choose one.
+
+```bash
+build config set defaults.providers.opencode.fastModel <model-id> --scope user
+```
+
+A `fastModel` the provider does not accept is rejected when you set it and
+reported with its config path at run time; Build never swaps in another model.
+
+### Claude model aliases (incl. Fable 5 and 5.1)
+
+Claude accepts the short aliases `opus`, `sonnet`, `haiku`, and `fable` (each floats to the latest of that family), version-pinned shorthands (`opus-5-5`, `opus-4-8`, `sonnet-4-6`, `fable-5`, `fable-5-1`), and full `claude-*` ids (`claude-opus-5-5`, `claude-opus-4-8`, `claude-fable-5`, `claude-fable-5-1`). Direct backend ids (Bedrock `*.anthropic.claude-*`, Vertex `claude-*@YYYYMMDD`) also pass through. A **specific** Claude version pin (family + major.minor, e.g. `sonnet-4-99`, `opus-4.99`, `fable-5-9`) that doesn't resolve now fails fast with a clear error instead of silently running the CLI default. Bare families and major-only aliases (`opus`, `sonnet-4`, `opus-99`, `fable`) float and are not errored, a full `claude-*` id is passed through to the CLI unchanged (direct-string support; a misspelled `claude-*` id surfaces at the CLI rather than at this guard), and non-Claude tokens (`gpt-*`, arbitrary strings) omit `--model` under provider purity.
+
+> **Fable 5 availability.** The `fable` / `fable-5` aliases and the full `claude-fable-5` id resolve on the Anthropic, Vertex, and AWS Bedrock backends (Bedrock → `global.anthropic.claude-fable-5`). Fable 5 may be **temporarily unavailable upstream** while external availability controls are in effect. During that state, a run targeting Fable surfaces a clear "temporarily unavailable" message; retry later or pick another model (`opus`, `sonnet`) in the meantime. **The Bedrock inference profile is wired ahead of availability but is unverified** and has not been invoked live while Fable is unavailable. When access returns, re-verify the profile live and add any regional profiles to the `claude-fable-5` entry in `.build-project/config/providers.yaml`. The `fable-5-1` shorthand and the full `claude-fable-5-1` id resolve the same way (Bedrock → `global.anthropic.claude-fable-5-1`); only the global profile is declared.
+
+## Quick Start with Mock Mode
+
+**For development and testing**, you can use mock mode to run Build without installing any providers.
+
+Outside test runners (`NODE_ENV=test` or `VITEST=true|1`), both flags are required. If only `BUILD_MOCK_PROVIDERS=1` is set, CLI startup scrubs it with a warning and real providers remain the default.
+
+```bash
+# Enable mock mode outside tests (both flags required)
+export BUILD_MOCK_PROVIDERS=1
+export BUILD_ALLOW_MOCK_PROVIDERS=1
+
+# Run with mock providers
+build run "test task" --variants=3
+
+# Disable mock mode
+unset BUILD_MOCK_PROVIDERS
+unset BUILD_ALLOW_MOCK_PROVIDERS
+```
+
+Mock mode simulates realistic execution times and occasional errors (10% failure rate) for testing variant competition logic. See [MOCK_ENV_VARS.md](https://github.com/ebrindley/build/blob/main/docs/MOCK_ENV_VARS.md).
+
+## Verify Your Environment (Health / Doctor)
+
+Build includes a built-in environment check:
+
+```bash
+# Alias:
+build doctor
+
+# Check configured providers only (default behavior)
+build doctor
+
+# Check all known providers explicitly
+build doctor --all
+
+# Support matrix: tier + CLI/auth/runtime health
+build doctor --matrix
+
+# Check a single provider
+build doctor --provider claude
+```
+
+`build provider list` is the first-user readiness check: it is read-only and
+reports whether at least one configured provider appears ready. After
+target-repo `build init`, run `build doctor` for the full checklist. The
+readiness subset (`doctor`, `doctor --provider <id>`, and `doctor --all`) is
+part of the dependable supported surface when used for setup verification.
+
+---
+
+## Setup Command
+
+Build provides a unified `build provider setup` command for managing providers.
+
+### Interactive Wizard
+
+Run the setup wizard to interactively select and install providers:
+
+```bash
+build provider setup
+```
+
+The wizard will:
+
+1. Show available providers with descriptions
+2. Let you select one or more providers
+3. Install each provider
+4. Configure provider options (when available)
+
+### First-Run Wizard
+
+`build provider setup --first-run` is re-runnable. When two or more providers are
+already ready, it asks which one is your default, then asks whether to save it for
+all repos, for this repo only, or just for this run. Pressing Enter at the provider
+choice keeps the current default. With one ready provider there is no default
+question. `--first-run --providers <id>[,<id>]` skips the wizard and saves the
+first ready listed provider as your user default; add `--non-interactive` to
+also skip the instructions-import question.
+
+### Non-Interactive Setup
+
+Install specific providers without interaction:
+
+```bash
+# Install single provider
+build provider setup --providers claude
+
+# Install multiple providers
+build provider setup --providers claude,gemini,opencode
+```
+
+### Check Mode
+
+Report provider readiness without making changes:
+
+```bash
+build provider list
+```
+
+Output shows:
+
+- `OK` — Installed, authenticated, and execute-ready
+- `Sandbox blocked (execute)` — CLI/auth may be present, but sandbox or policy prevents provider state access
+- `Warning:` — Installed but degraded or not authenticated
+- `Error` — Not installed (with install command)
+
+### First-Run Picker
+
+When you run `build run` or `build run competition` without a configured provider:
+
+**TTY Mode** (interactive terminal):
+
+- Shows provider picker automatically
+- Prompts to install selected provider
+- Retries your original command after setup
+
+**Non-Interactive Mode** (scripts, CI):
+
+- Prints error message
+- Shows deterministic setup commands
+- Exits with error code
+
+Example:
+
+```bash
+# First run without provider
+$ build run "test task"
+Warning: No runnable provider configured
+
+Setup required. Run one of these commands:
+  build provider setup                          # Interactive wizard
+  build provider setup --providers claude       # Install Claude
+  build provider setup --providers opencode     # Install OpenCode
+```
+
+### Safety Boundary
+
+Build categorizes installers by risk level:
+
+**Safe** (auto-install allowed):
+
+- npm global install
+- brew install
+- pipx install
+
+**Needs Confirmation** (requires approval):
+
+- curl | bash installers
+- Manual installation steps
+
+To allow risky installers (currently `cursor`, `grok`, `kiro`, `antigravity`, and `opencode`, which ship as
+`curl | bash`), set this env var. The gate applies to **both interactive and
+non-interactive** runs — without it, `build provider setup` will print the install
+command and exit without executing it:
+
+```bash
+export BUILD_ALLOW_CURL_BASH=1
+build provider setup --providers <provider>
+```
+
+---
+
+## Provider Installation
+
+> **Node version note:** The per-provider "Prerequisite: Node.js" lines below are
+> each external CLI's own minimum, not Build's. Build itself requires Node.js
+> 24.x or 26.x (see [INSTALL.md](../INSTALL.md#prerequisites)); a provider CLI may run on
+> an older Node, but Build still needs 24.x or 26.x to run.
+
+### Claude CLI
+
+**Status**: Supported local CLI provider
+
+#### Installation
+
+Prerequisite: Node.js 18+ (the Claude CLI's own minimum; Build itself requires Node 24.x or 26.x).
+
+```bash
+# Install Claude Code CLI
+npm install -g @anthropic-ai/claude-code
+
+# Verify installation
+claude --version
+```
+
+#### Authentication
+
+1. **CLI Login (preferred)**:
+
+   ```bash
+   claude auth login
+   # Browser/device flow; stores credentials in Claude CLI config
+   ```
+
+2. **Verify Setup**:
+   ```bash
+   # Run a simple Claude command and rely on its error output
+   claude --version
+   ```
+
+#### Configuration
+
+Build uses a dedicated config directory to avoid conflicts:
+
+```bash
+# Default location
+~/.build/config/providers/claude
+
+# Or set custom location
+export CLAUDE_CONFIG_DIR=~/.build/config/providers/claude
+```
+
+**Bedrock Configuration (AWS)**:
+
+Build defaults Claude to Anthropic. Bedrock mode is enabled when
+`BUILD_CLAUDE_BACKEND=bedrock` is set.
+AWS environment variables (`AWS_REGION`, `AWS_PROFILE`) alone do **not**
+activate Bedrock mode — explicit opt-in is still required.
+
+> **Migration**: Prefer `BUILD_CLAUDE_BACKEND=bedrock` in shell profiles and CI.
+> Build's backend resolver checks `BUILD_CLAUDE_BACKEND` first; `CLAUDE_CODE_USE_BEDROCK=1`
+> is still honored as a legacy fallback when the canonical variable is unset.
+
+When Bedrock is active, Build converts **explicit pins** to cross-region
+inference profiles automatically. A **family alias** is not converted: `opus`,
+`sonnet`, `haiku`, and `fable` reach the Claude CLI unchanged, and the CLI
+resolves the family against your account's entitlement and builds the profile ID
+itself. Build keeps no table of what a family currently means — one would go
+stale silently and downgrade runs.
+
+Redirect a family with the Claude CLI's own variables when you need a specific
+deployment:
+
+```bash
+export ANTHROPIC_DEFAULT_OPUS_MODEL=<model-or-deployment-id>
+export ANTHROPIC_DEFAULT_SONNET_MODEL=<model-or-deployment-id>
+export ANTHROPIC_DEFAULT_HAIKU_MODEL=<model-or-deployment-id>
+```
+
+**Default prefix: `global`**. The `global` inference pool draws capacity from
+all AWS regions, reducing single-region throttling. Use a regional prefix only
+when you need explicit data residency, latency affinity, or compliance controls.
+
+```bash
+# Canonical Build setting:
+export BUILD_CLAUDE_BACKEND=bedrock
+
+# Override to pin a specific region prefix (global|us|eu|jp|apac):
+export BUILD_BEDROCK_REGION_PREFIX=us
+```
+
+Build applies that prefix itself when it builds a profile ID for an explicit
+pin. For a family alias — where the CLI builds the ID — it passes the same value
+through as `ANTHROPIC_BEDROCK_REGION_PREFIX`, which the Claude CLI honours from
+2.1.224. On an older CLI the variable is ignored and the alias draws from the
+CLI's own default pool, so the configured prefix is only a preference there;
+`build doctor` reports this (see **Family-alias migration** below).
+
+Not every model has a profile under every prefix. For an explicit pin whose
+registry entry declares no profile under your prefix, Build uses that model's
+`global` profile instead, and AWS may serve a global request from any region.
+If you need data residency, check that the model's AWS Bedrock model card lists
+a profile for your geography before relying on the prefix.
+
+**Inference profile examples**:
+
+| Input                        | What goes on the wire                             | Built by |
+| ---------------------------- | ------------------------------------------------- | -------- |
+| `--model sonnet`             | `sonnet` (CLI resolves the family)                | Claude CLI |
+| `--model opus`               | `opus` (CLI resolves the family)                  | Claude CLI |
+| `--model sonnet-4-6`         | `global.anthropic.claude-sonnet-4-6`              | Build |
+| `--model claude-opus-4-8`    | `global.anthropic.claude-opus-4-8`                | Build |
+| `--model haiku-4-5`          | `global.anthropic.claude-haiku-4-5-20251001-v1:0` | Build |
+
+Bedrock model ID suffixes for explicit pins are maintained in
+`CLAUDE_BEDROCK_MODELS` in `src/core/providers/claude/config.ts` — do not
+construct inference profile strings manually.
+
+**Family-alias migration**: Build's Claude registry roles (`judge_primary`,
+`quality`, `reasoning`, `long_context`) point at the `opus` family rather than a
+pinned version, so which Opus runs now follows the installed Claude CLI and your
+account entitlement, not a Build table. Two consequences on an older CLI, both
+reported by `build doctor`: before 2.1.219 a family alias resolves to the
+previous flagship, and before 2.1.224 `ANTHROPIC_BEDROCK_REGION_PREFIX` is
+unavailable. Context-window selection follows the CLI for aliases too: Build
+appends a `[1m]` selector only to explicit pins, because it cannot know which
+model the CLI will pick — ask for it explicitly (`--model opus[1m]`) and the
+selector passes through. Pin a role to an explicit ID (or set
+`ANTHROPIC_DEFAULT_*_MODEL`) when you need a fixed version.
+
+Build also synthesizes `CLAUDE_CODE_USE_BEDROCK=1` for Claude subprocesses
+when the canonical `BUILD_CLAUDE_BACKEND=bedrock` setting is used, so the
+Claude CLI receives the backend signal it expects at the final subprocess
+boundary only.
+
+**Vertex Configuration (Google Cloud)**:
+
+Vertex mode is enabled when `BUILD_CLAUDE_BACKEND=vertex` is set.
+`CLAUDE_CODE_USE_VERTEX` is treated the same way as the Bedrock flag above:
+Build ignores it for routing and only synthesizes Claude-native backend flags
+when launching the final Claude subprocess.
+
+Build does **not** rewrite Claude model IDs in Vertex mode. Pass Claude-native
+model IDs through unchanged, including version-pinned IDs such as
+`claude-haiku-4-5@20251001` when needed.
+
+```bash
+# Canonical Build setting:
+export BUILD_CLAUDE_BACKEND=vertex
+
+# Required Vertex/Claude Code settings:
+export CLOUD_ML_REGION=us-central1
+export ANTHROPIC_VERTEX_PROJECT_ID=<your-project-id>
+
+# Standard Google Cloud auth:
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+
+# Optional project aliases supported by Claude Code:
+export GCLOUD_PROJECT=<your-project-id>
+# or:
+export GOOGLE_CLOUD_PROJECT=<your-project-id>
+```
+
+Vertex mode uses Google Cloud credentials, so Claude `/login` and `/logout`
+are not part of the setup flow.
+
+Build synthesizes `CLAUDE_CODE_USE_VERTEX=1` for Claude subprocesses when the
+canonical `BUILD_CLAUDE_BACKEND=vertex` setting is used.
+
+**Foundry Configuration (Microsoft Foundry)**:
+
+Foundry mode is enabled when `BUILD_CLAUDE_BACKEND=foundry` is set.
+`CLAUDE_CODE_USE_FOUNDRY` is treated the same way as the Bedrock and Vertex flags
+above: Build honors it as a legacy fallback when the canonical variable is unset,
+and synthesizes `CLAUDE_CODE_USE_FOUNDRY=1` for the final Claude subprocess.
+
+Build does **not** rewrite Claude model IDs in Foundry mode. Model names pass
+through unchanged and the Claude CLI resolves them against your deployments.
+
+```bash
+# Canonical Build setting:
+export BUILD_CLAUDE_BACKEND=foundry
+
+# Connection — set exactly one of these:
+export ANTHROPIC_FOUNDRY_RESOURCE=<your-foundry-resource-name>
+# or the full endpoint:
+export ANTHROPIC_FOUNDRY_BASE_URL=https://<resource>.services.ai.azure.com
+
+# Credential — the CLI takes the first available, in this order:
+export ANTHROPIC_FOUNDRY_AUTH_TOKEN=<bearer-token>
+export ANTHROPIC_FOUNDRY_API_KEY=<api-key>
+# ...or set neither and use the Azure default credential chain (e.g. `az login`).
+```
+
+Build's preflight requires the resource or the base URL, because neither is
+inferable from a credential. It does not check credentials or contact the
+service: Foundry auth is established by execution, and the Azure default
+credential chain sets no variable Build can observe.
+
+**Alias lag caveat**: Foundry aliases resolve to the CLI's own built-in Foundry
+defaults, which lag the Anthropic backend (`opus` currently means Opus 4.6
+there), and the CLI performs no startup availability check. Pin your deployment
+names explicitly:
+
+```bash
+export ANTHROPIC_DEFAULT_OPUS_MODEL=<your-opus-deployment-name>
+export ANTHROPIC_DEFAULT_SONNET_MODEL=<your-sonnet-deployment-name>
+export ANTHROPIC_DEFAULT_HAIKU_MODEL=<your-haiku-deployment-name>
+```
+
+**Manual checklist** (Build's Foundry support is verified at unit level only —
+no live Foundry deployment was available):
+
+```bash
+export BUILD_CLAUDE_BACKEND=foundry
+export ANTHROPIC_FOUNDRY_RESOURCE=<your-foundry-resource-name>
+build doctor
+build ask --to claude --model opus "reply OK"
+```
+
+Confirm the reported model is your Foundry deployment, not an Anthropic model ID.
+
+**Profile Setup**:
+
+Build uses "profiles" to organize work. The default profile is `default`. You can create custom profiles for different projects:
+
+```bash
+# Create a profile
+claude profile create my-project
+
+# Set active profile
+claude profile use my-project
+
+# List profiles
+claude profile list
+```
+
+#### Test Claude Provider
+
+```bash
+# Test execution
+build run "Create a hello world test" --engine=claude
+
+# Test variant competition
+build run "Implement login feature" --engine=claude --variants=3
+```
+
+---
+
+### Codex CLI
+
+**Status**: Supported, enterprise-focused
+
+#### Installation
+
+Prerequisite: Node.js 16+ (the Codex CLI's own minimum; Build itself requires Node 24.x or 26.x).
+
+```bash
+# Install Codex CLI
+npm install -g @openai/codex
+
+# Verify installation
+codex --version
+```
+
+#### Authentication
+
+**Default:** Codex CLI OAuth (ChatGPT / browser login). Build does not preflight auth before
+`run` or `run competition`; the CLI surfaces auth errors. `build doctor --provider codex` checks
+`auth.json` under `CODEX_HOME` (and `~/.codex` when unset), plus API keys when set.
+
+```bash
+codex login
+# or: build provider setup --providers codex
+```
+
+**API key mode (optional):** set `BUILD_CODEX_AUTH_MODE=api_key` and provide `CODEX_API_KEY`,
+the variable `codex exec` reads its API key from. Build also forwards `OPENAI_API_KEY` and
+`CODEX_TOKEN` and counts either as ready, but `codex exec` does not read them. In OAuth mode,
+Build strips API keys from the Codex subprocess environment so the CLI does not prefer a shell
+key over browser login.
+
+#### Configuration
+
+```bash
+# Default location
+~/.codex/
+
+# Or set custom location
+export CODEX_HOME=~/.codex
+```
+
+Codex execution is local only. `build run` and `build run competition` invoke `codex exec --json`
+inside the selected workspace or worktree; Build does not submit, poll, or apply Codex cloud tasks.
+
+#### Amazon Bedrock
+
+Codex CLI 0.154.0 ships two built-in Bedrock providers, selected by `model_provider` in
+`~/.codex/config.toml`: `amazon-bedrock` (the Mantle endpoint; ids `openai.<id>`) and
+`amazon-bedrock-runtime` (the Bedrock Runtime endpoint, which for a model such as GPT-6 Astra
+accepts only an inference profile, `global.openai.gpt-6-astra`). Build recognizes both, keeps the
+one your config names in force, and emits the matching id for a canonical pin such as
+`codex:gpt-6-astra`. Pin canonical ids only; `openai.*` and `global.openai.*` are rejected as pins.
+Reading `~/.aws` follows the provider your config names and needs no attestation.
+
+`BUILD_CODEX_BACKEND=bedrock` is an attestation, not a provider switch. It selects Bedrock routing
+when your config names no recognized provider, asserts `model_provider="amazon-bedrock"` in that
+case only, and lets readiness treat the run as a Bedrock run (no `auth.json` needed). It does not
+override a configured `amazon-bedrock-runtime` provider or its region. AWS environment credentials
+(`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) are forwarded to the Codex
+child whether or not it is set. Details and the measured evidence: `docs/reference/MODEL_ID_ROUTING.md` (not shipped in the npm package).
+
+#### Test Codex Provider
+
+```bash
+build run "Create a test suite" --engine=codex --variants=2
+```
+
+---
+
+### Cursor (CLI)
+
+**Status**: Supported, CLI-first
+
+#### Installation
+
+```bash
+# Install Cursor Agent
+curl https://cursor.com/install -fsS | bash
+
+# Verify installation
+cursor-agent --version
+```
+
+#### Authentication
+
+Build uses your Cursor account session. Authenticate via the Cursor Agent:
+
+```bash
+cursor-agent login
+```
+
+On a headless host (a CI runner, a container, a Cursor Cloud Agent VM), a
+`CURSOR_API_KEY` in the environment authenticates `cursor-agent` without a login
+session, and Build passes it to Cursor runs. `cursor-agent status` can still
+report "Not logged in" in that setup. Readiness reports the key as present but
+unverified until the first run, which is the real check.
+
+#### Cursor Cloud (Historical Only)
+
+Build does not run Cursor (or Codex) cloud agent workflows. Use local Cursor CLI execution via `cursor-agent login` and local variants such as `cursor:local`.
+
+Historical note (compatibility and recovery only):
+
+- Older runs may have used Cursor cloud transports (`api` REST agents or `github_pr` bot comments). Those shapes can still appear in telemetry, env dumps, or recovery notes.
+- Env vars such as `BUILD_CURSOR_CLOUD_TRANSPORT` and `CURSOR_CLOUD_TRANSPORT` may exist in older operator setups; they do not enable a Build `:cloud` execution path. `CURSOR_API_KEY` is not a cloud setting: it authenticates the local CLI (see Authentication above).
+- Use `cursor-agent login` or `CURSOR_API_KEY` for local CLI authentication. Do not treat cloud transport configuration as setup for new work.
+- For PR publication after local `run competition apply`, use ordinary GitHub auth (`gh auth login`) as documented in the competition and CLI guides — that is not Cursor cloud execution.
+
+#### Configuration
+
+```bash
+# Default: leave CURSOR_CONFIG_DIR unset. Build then finds the login that
+# `cursor-agent login` stores in ~/.cursor (or ~/.build/config/providers/cursor).
+# With XDG_CONFIG_HOME set, cursor-agent stores it in $XDG_CONFIG_HOME/cursor,
+# which Build does not check; set CURSOR_CONFIG_DIR to that directory instead.
+
+# Custom location: when set, Build checks only this directory for a login,
+# so log in again with it set
+export CURSOR_CONFIG_DIR=/path/to/cursor-config
+cursor-agent login
+
+# Override default model for Cursor
+export BUILD_CURSOR_MODEL='auto'
+
+# Make Cursor the default provider without flags
+export BUILD_DEFAULT_PROVIDER='cursor'
+```
+
+The Cursor provider uses the `cursor` ID for local CLI execution. Use the environment variables above or Build's resolved provider configuration; `build.config.ts` is not a loaded configuration source.
+
+#### Test Cursor Provider
+
+```bash
+build run "Write a hello world function" --engine=cursor
+
+build run "Refactor this component" --engine=cursor --variants=2
+
+# Test with file context (auto-detected in output)
+build run "Review @src/auth.ts" --engine=cursor
+```
+
+**Important**: The Cursor CLI provider reuses Cursor's own session handling. Ensure `cursor-agent` works from your shell and that any enterprise policies allow CLI access. Use `BUILD_CURSOR_MODEL` or the Cursor preference store to pin defaults.
+
+---
+
+### Gemini CLI
+
+**Status**: Experimental and no longer being extended; opt-in only. Check the vendor's current CLI availability and entitlements before relying on it. Prefer `antigravity`, the better-supported path.
+
+#### Installation
+
+Prerequisite: Node.js 20+ (the Gemini CLI's own minimum; Build itself requires Node 24.x or 26.x).
+
+```bash
+# Install Gemini CLI globally
+npm install -g @google/gemini-cli
+
+# Verify installation
+gemini --version
+```
+
+#### Authentication
+
+**The Gemini CLI provider does not handle authentication** - you must configure authentication yourself. The CLI supports both personal Google accounts and enterprise Vertex AI access.
+
+**Option 1: Personal Google Account (Recommended for individuals)**
+
+```bash
+# Set your API key from Google AI Studio
+export GOOGLE_API_KEY='your-api-key-here'
+
+# Alternative: Set GEMINI_API_KEY (also supported)
+export GEMINI_API_KEY='your-api-key-here'
+
+# Get an API key at: https://aistudio.google.com/app/apikey
+```
+
+**Option 2: Vertex AI Enterprise (Recommended for organizations)**
+
+```bash
+# Authenticate with Google Cloud
+gcloud auth application-default login
+
+# Set your project and location
+export GOOGLE_CLOUD_PROJECT='your-gcp-project-id'
+export GOOGLE_CLOUD_LOCATION='us-central1'  # or your preferred region
+
+# Alternative: Use service account
+export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account-key.json'
+```
+
+#### Configuration
+
+Build uses a dedicated config directory for Gemini:
+
+```bash
+# Default location
+~/.build/gemini/
+
+# Or set custom location
+export GEMINI_CONFIG_DIR=~/.build/gemini
+```
+
+**Environment Variables**:
+
+- `GOOGLE_API_KEY` - API key for personal Google account
+- `GEMINI_API_KEY` - Alternative API key variable
+- `GOOGLE_CLOUD_PROJECT` - GCP project ID for Vertex AI
+- `GOOGLE_CLOUD_LOCATION` - GCP region for Vertex AI
+- `GOOGLE_APPLICATION_CREDENTIALS` - Service account key path
+
+#### Test Gemini Provider
+
+```bash
+# Test with personal account
+build run "Create a hello world function" --engine=gemini
+
+# Test with specific model
+build run "Add error handling" --engine=gemini --model=gemini-2.5-pro
+```
+
+**Important**: This provider assumes `gemini` CLI is already installed and authenticated. Build simply executes the `gemini` command and lets the CLI handle all authentication and API communication. Choose the authentication method that matches your use case (personal vs enterprise).
+
+---
+
+### Copilot CLI
+
+**Status**: Experimental — available for exploration, outside the primary validated public-release matrix.
+
+#### Installation
+
+Prerequisite: Node.js 22+ (the Copilot CLI's own minimum; Build itself requires Node 24.x or 26.x).
+
+```bash
+# Install GitHub Copilot CLI (Node.js package)
+npm install -g @github/copilot
+
+# Verify installation
+copilot --help
+```
+
+If your npm config has `ignore-scripts=true`, use:
+
+```bash
+npm_config_ignore_scripts=false npm install -g @github/copilot
+```
+
+#### Authentication
+
+Copilot CLI reuses your GitHub identity. Launch `copilot` once (interactive or `copilot -p "Hello" --allow-all-tools`) to complete device authentication if prompted. No additional Build configuration is required.
+
+#### Configuration
+
+Build invokes the standalone `copilot` application. Default execution is agentic direct editing: Copilot applies workspace edits and Build detects changes via git. Configure via environment variables:
+
+| Variable                     | Purpose                                         | Default                                 |
+| ---------------------------- | ----------------------------------------------- | --------------------------------------- |
+| `BUILD_COPILOT_CLI_COMMAND` | Path to Copilot CLI binary                      | `copilot`                               |
+| `BUILD_COPILOT_WORKFLOW`    | Default workflow (`suggest`, `chat`, `explain`) | `suggest`                               |
+| `BUILD_TIMEOUT_COPILOT_MS`  | Provider timeout override in ms                 | `(unset; registry fallback 2700000)`    |
+
+Timeout resolution: explicit caller timeout, then `BUILD_TIMEOUT_COPILOT_MS` (when set), then global `BUILD_TIMEOUT_MS`, then registry/`providers.yaml` `timeout_ms` (registry provider timeout is `2700000` ms / 45 minutes). The env override itself is unset by default; do not treat `2700000` as the env var's default.
+
+> **Note:** Default output mode is agentic direct edit with git-detected changes (`--allow-all-tools` and partial dangerous-command denies). Full shell denial requires `BUILD_COPILOT_SHELL_ENABLED=0`. Unified-diff/`diff_output` mode is opt-in (`BUILD_COPILOT_OUTPUT_MODE=diff_output`).
+
+#### Usage Patterns
+
+```bash
+# Agentic direct edit (git-detected changes; experimental provider)
+build run "Harden password validation in @src/auth/password.ts" --provider=copilot
+
+# Ask Copilot to propose tests for a new feature
+build run "Write vitest cases for the new billing limits" \
+  --provider=copilot \
+  --workflow=chat \
+  --prompt "Focus on branch coverage and edge cases around plan downgrades."
+
+# Combine Copilot with other providers for orchestration
+build run competition "Modernize feature flag utilities" \
+  --variant copilot:local \
+  --variant claude:local \
+  --variant gemini:local
+```
+
+**Recommended prompt structure**:
+
+- Begin with the **goal** ("Improve caching invalidation").
+- Specify **target files** (`FILES:` block or inline `@src/cache/index.ts`).
+- Add **acceptance criteria** ("No new dependencies, keep existing API").
+- End with **validation hints** for follow-up review after git-detected edits.
+
+#### Environment Variables
+
+| Variable                     | Purpose                                         | Default                              |
+| ---------------------------- | ----------------------------------------------- | ------------------------------------ |
+| `BUILD_COPILOT_CLI_COMMAND` | Override Copilot CLI binary path                | `copilot`                            |
+| `BUILD_COPILOT_WORKFLOW`    | Default workflow (`suggest`, `chat`, `explain`) | `suggest`                            |
+| `BUILD_TIMEOUT_COPILOT_MS`  | Provider timeout override in milliseconds       | `(unset; registry fallback 2700000)` |
+| `COPILOT_TELEMETRY_OPTOUT`   | Disable GitHub Copilot telemetry (1=on)         | `0`                                  |
+
+#### Troubleshooting
+
+- **`Command not found: copilot`** — Ensure the CLI is installed and on your `PATH`, or set `BUILD_COPILOT_CLI_COMMAND`.
+- **Authentication required** — Launch `copilot` once and follow the device-login flow, or ensure your GitHub CLI session includes Copilot scopes.
+- **No git-detected changes / empty diff output** — Prefer the agentic default (workspace edits). For opt-in `diff_output`, provide FILE/FILES hints for multi-file edits.
+- **`No changes detected (git status clean)` / `posix_spawnp failed`** — Under Build’s macOS sandbox wrapper, Copilot’s internal bash/shell tool can fail (`posix_spawnp failed`). Copilot can still perform direct file read/edit operations; prefer workflows that only create/edit files in existing directories. If you specifically need Copilot to run shell commands, opt out of Build’s sandbox for Copilot with `export BUILD_SANDBOX_COPILOT_ENABLED=0` (or `export BUILD_SANDBOX_GITHUB_COPILOT_ENABLED=0`).
+
+---
+
+### Grok CLI
+
+**Status**: Supported via Grok Build CLI
+
+For first-user delivery, prefer the validated selector
+`--variant grok` and omit a Grok model pin. Build's registry
+default is `auto`, which omits `-m/--model` and lets the installed Grok CLI use
+its currently configured default. To choose a model explicitly for Build runs,
+set the normal provider-scoped user option:
+
+```bash
+build config set defaults.providers.grok.model grok-4.6 --scope user
+```
+
+Inspect the resolved executor input, source, native default, discovery status,
+and model-argument decision with:
+
+```bash
+build config resolved --role executor --provider grok --json
+```
+
+Set the value back to `auto` to follow the Grok CLI default again. Project-scoped
+configuration and an explicit CLI model selection continue to take precedence
+through Build's standard configuration resolution.
+
+#### Installation
+
+Install Grok Build with xAI's official installer:
+
+```bash
+curl -fsSL https://x.ai/cli/install.sh | bash
+```
+
+Because this runs a remote installer, Build will not execute it unless you explicitly opt in:
+
+```bash
+BUILD_ALLOW_CURL_BASH=1 build provider setup --providers grok
+```
+
+Then verify the CLI is on `PATH`:
+
+```bash
+grok --version
+```
+
+#### Authentication
+
+Grok authentication is owned by the `grok` CLI. Build does not read or manage
+Grok tokens.
+
+**Primary (local / interactive):** use the Grok CLI's cached OAuth / device
+login. Complete login once so the CLI stores auth under `~/.grok/`; later
+Build runs reuse that cache without re-prompting:
+
+```bash
+# Preferred local path: device / CLI login (cached OAuth)
+grok login --device-auth
+# or, if your installed Grok CLI uses the shorter form:
+grok login
+# First interactive launch also completes auth when no cache exists:
+grok
+```
+
+**Optional (CI / headless automation):** set the official xAI API key when you
+need non-interactive runs without a local CLI auth cache:
+
+```bash
+export XAI_API_KEY=your-key
+```
+
+`GROK_CODE_XAI_API_KEY` is a **deprecated** Build compatibility alias. It is
+still accepted for older Grok Build CLI / Build setups; prefer `XAI_API_KEY`
+for new headless configuration. Do not treat the alias as the primary key.
+
+#### Health and passive readiness
+
+`build doctor --provider grok` uses passive checks only. A configured
+`XAI_API_KEY`, the deprecated `GROK_CODE_XAI_API_KEY` alias, or an existing
+`~/.grok/auth.json` reports authentication as **unknown** (legacy boolean auth
+is `false`) until execution verifies the credential. Passive checks do not run
+`grok` because that could start browser auth. That unverified state does not
+block provider selection or `run`/`run competition`. Use
+`build doctor --probe --provider grok` for an explicit active readiness check.
+`run` and `run competition` establish auth on the requested execution.
+
+For headless `run`/`run competition` without a usable CLI auth cache, set `XAI_API_KEY`
+(optional path above). `BUILD_GROK_ALLOW_BROWSER_AUTH=1` is an **opt-in only**
+escape hatch when you deliberately accept that the requested Grok execution
+may open a browser; do not treat browser auth as automatically safe in
+headless or CI environments.
+
+`build run competition` and `build run` delegate authentication to the requested Grok
+CLI execution. A cached CLI login, `XAI_API_KEY`, or the deprecated
+`GROK_CODE_XAI_API_KEY` alias are common auth paths, but Build does not reject
+the run based on a preflight inspection of those paths. Set
+`BUILD_GROK_ALLOW_BROWSER_AUTH=1` only when an interactive browser flow is
+acceptable.
+
+#### Headless argv posture
+
+Headless Grok runs use `grok --prompt-file` with structured JSON stdout (streaming by default),
+validated against live headless preflight runs.
+
+**Default posture** (`src/core/providers/grok/execution/commands.ts`):
+
+| Flag | Value | Rationale |
+|------|-------|-----------|
+| `--prompt-file` | always | Avoid argv bloat; never use `-p`/`--single` for Build prompts |
+| `--output-format` | `streaming-json` | Follows the provider-streaming gate (`BUILD_PROVIDER_STREAMING`, default on since 2026-06-04); set `BUILD_PROVIDER_STREAMING=0` for the `json` posture (deterministic success/error envelopes); `BUILD_GROK_OUTPUT_FORMAT` overrides both |
+| `--no-alt-screen` | always | Headless determinism |
+| `--no-memory` | default on | Disable Grok memory unless `BUILD_GROK_MEMORY=1` |
+| `--rules` | `build` and `native+build` launches | Carries Build's instruction set for that run only, appended to Grok's system prompt. Judges, `native` mode, and asks with `inheritance.ask` unset get none. `--trust` is never passed: it adds the folder to `~/.grok/trusted_folders.toml` for good |
+| `-m` / `--model` | omitted when the resolved model is `auto` | Lets the installed Grok CLI use its configured default. Explicit project/user/CLI model selections are passed through as `-m <model>`. |
+| `--permission-mode` | *omitted for `default`* | Passing an approval-requiring mode (incl. the literal `default`, plus `acceptEdits`/`auto`) kills Grok's permission worker on the first tool call under headless OAuth (`Transport channel closed, when Auth(AuthorizationRequired)`; exit 0, empty `Cancelled` envelope) — validated on 0.2.16, `acceptEdits` reconfirmed dead on 0.2.73. Omitting uses the CLI's native default and survives. Explicit `bypassPermissions` also survives and is still emitted. `dontAsk` is version-gated for the locked native read-only posture on grok >= 0.2.93: `dontAsk` plus matching inspect/search allows is not sufficient on its own, because unmatched tools fall through to the user's own Grok configuration; the locked posture therefore also positively lists inspect tools (`Read`, `Grep`, `Bash`, `WebFetch`, `WebSearch`), disallows `Edit`/`Write`, and denies MCP tools. Official `--sandbox read-only` is omitted because it cannot nest under Build's outer seatbelt. Read-only runs (`readOnlyWorkingDir`/analysis intent, e.g. `build ask --to grok`) use that locked posture when the CLI is new enough; older/unknown CLIs fail before semantic read-only spawn rather than falling back to `--always-approve`. |
+| `--allow` | read-only runs under `dontAsk` | Grants specific tools under `dontAsk` (`Read`, `Grep`, `Bash`, `WebFetch`, `WebSearch` for consults; necessary but not sufficient alone for the locked read-only posture). Callers pass `allowRules`; `BUILD_GROK_ALLOW_RULES` (csv) overrides. |
+| `--always-approve` | default on (except `dontAsk`) | Required for headless edit-task execution; gated by an active policy boundary. Suppressed under `dontAsk` / locked read-only posture, which would otherwise defeat the allowlist. |
+| `--max-turns` | *not set* | Empirically verified (0.2.82, 2026-07-02): no low default turn cap exists — 40+ sequential turns and 12-minute commands complete without the flag; its only observed real-world effect was killing healthy runs when set too low. Opt in with `BUILD_GROK_MAX_TURNS` (explicit doctor probes do, to stay cheap); invalid values omit the flag rather than falling back |
+| `--no-auto-update` | always | xAI recommends this for scripts/CI/headless runs |
+| `--sandbox` | omitted | Grok's official `read-only` profile is itself `sandbox-exec` and cannot nest under Build's outer seatbelt (EPERM). Read-only and edit/mixed both use Build's policy/sandbox boundary for FS confinement. |
+| `--reasoning-effort` | set after capability validation | Emitted for explicit effort-capable models (for example `grok-4.6`) and when `auto` discovers such a model. `--effort` is never passed. Discovery failure does not invent capability. |
+
+**Auth:** Primary local path is CLI OAuth / device login (`~/.grok` cache). Provider-scoped keys (`XAI_API_KEY`, deprecated `GROK_CODE_XAI_API_KEY`) are optional via provider policy for CI/headless without a cache — not mandatory. Passive tri-state readiness remains `unknown` and legacy boolean auth is `false` when either a key or a valid `~/.grok/auth.json` is present, until an explicit active probe or a successful requested execution verifies headless use; that unverified state does not block selection or execution. Compete/run do not run a pre-execution edit/auth probe; authentication is established by the requested `grok --prompt-file` invocation, and errors from that run keep their normal classification. Explicit `build doctor --probe --provider grok` still runs an active headless edit probe (`buildGrokArgv` + `executeProviderCommand`, `--max-turns 8`, `--always-approve`, `BUILD_GROK_AUTH_PROBE_TIMEOUT_MS` defaulting to 45 seconds). Session resume: `ProviderRunOptions.resumeSessionId` emits `--resume <id>`. Parsed token usage propagates through shared orchestration telemetry when present (USD may stay unknown without pricing).
+
+**Overrides:** see the `BUILD_GROK_*` env vars in the Configuration subsection below.
+
+#### Configuration
+
+Build invokes `grok` in headless mode. Configure transport behavior via environment variables:
+
+| Variable                         | Purpose                                                                                                                                 | Default |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `BUILD_GROK_CLI_COMMAND`        | Override Grok CLI binary path                                                                                                           | `grok`  |
+| `BUILD_GROK_PERMISSION_MODE`    | Optional explicit mode (`dontAsk`, `bypassPermissions`). Default **omits** `--permission-mode` (CLI native default). `acceptEdits`/`auto` are rejected as unsafe headless. `dontAsk` requires allow rules and is only used for the locked native read-only posture when the CLI is >= 0.2.93 | omit flag / `default` |
+| `BUILD_GROK_ALLOW_RULES`        | Comma-separated `--allow` rules when permission mode is `dontAsk` (required for `dontAsk`)                                              | unset   |
+| `BUILD_GROK_AUTO_APPROVE`       | Set to `0` to omit `--always-approve` (suppressed automatically under `dontAsk`)                                                        | enabled |
+| `BUILD_GROK_ALWAYS_APPROVE`     | Legacy alias for `BUILD_GROK_AUTO_APPROVE`                                                                                              | enabled |
+| `BUILD_GROK_MAX_TURNS`          | Opt-in `--max-turns` cap. **Unset by default** (flag omitted). Invalid values also omit the flag — there is no fallback default such as 400 | unset (omit flag) |
+| `BUILD_GROK_OUTPUT_FORMAT`      | `plain`, `json`, or `streaming-json`. When unset, follows `BUILD_PROVIDER_STREAMING` (default on → `streaming-json`; set `BUILD_PROVIDER_STREAMING=0` for buffered `json`) | `streaming-json` (when streaming on) |
+| `BUILD_GROK_MEMORY`             | Set to `1` to allow Grok memory                                                                                                         | disabled (`--no-memory`) |
+| `BUILD_GROK_ALLOW_BROWSER_AUTH` | Set to `1` to allow requested Grok execution (or an explicit doctor probe) to start browser auth                                         | disabled |
+| `BUILD_SKIP_GROK`               | Skip Grok execution                                                                                                                     | unset   |
+
+**Headless permission notes:**
+
+- Omitting `--permission-mode` is intentional and **not** the same as passing `--permission-mode default`. Approval-worker modes (`default`, `acceptEdits`, `auto`) die under headless OAuth on tool use.
+- `acceptEdits` and `auto` are unsafe for headless automation; Build rejects them if set via `BUILD_GROK_PERMISSION_MODE`.
+- Read-only consults (`build ask --to grok`, analysis intent / `readOnlyWorkingDir`) use the locked native posture when the CLI is >= 0.2.93: `dontAsk` + inspect/search allows (`Read`, `Grep`, `Bash`, `WebFetch`, `WebSearch`) plus write tools disallowed and MCP tools denied. Official `--sandbox read-only` is omitted (cannot nest under Build's seatbelt). `dontAsk` + allow rules alone are not globally fail-closed. Older/unknown CLIs fail before semantic read-only spawn rather than falling back to `--always-approve`. Elevating `BUILD_GROK_PERMISSION_MODE` (e.g. `bypassPermissions`) cannot YOLO past the locked posture.
+- `--always-approve` (and explicit `bypassPermissions`) require an active Build policy/sandbox boundary. For edit intent, `BUILD_GROK_AUTO_APPROVE=0` fails closed before launch (no false success without a tool-approval path).
+- Session resume: when `ProviderRunOptions.resumeSessionId` is set, Build emits Grok CLI `--resume <id>`. Legacy env names alone do not resume a session.
+- Token usage: when Grok headless envelopes include parseable token counts, Build propagates them through orchestration telemetry. USD cost may remain unknown when pricing is unavailable.
+
+#### Usage Patterns
+
+Straightforward first run:
+
+```bash
+git checkout -b run/my-task
+build run "Update the target file and add focused tests" --provider grok
+```
+
+When you want judge scores or feedback, use judged competition instead (AI
+judging is the default), then apply the harvested result from a delivery branch:
+
+```bash
+git checkout -b run/my-graded-task
+build run competition "Update the target file and add focused tests" \
+  --variant grok
+git checkout -b fix/my-graded-task
+build run competition apply <competition-id>
+```
+
+Multi-provider comparison after local validation:
+
+```bash
+build run competition "Update the target file and add focused tests" \
+  --variant grok \
+  --variant codex
+```
+
+**Important**: Build defers Grok authentication to the Grok CLI. For local use,
+prefer cached CLI OAuth / device login (`grok login --device-auth`, `grok login`,
+or an initial `grok`). `XAI_API_KEY` is optional for CI/headless automation.
+`GROK_CODE_XAI_API_KEY` remains a deprecated compatibility alias (still accepted;
+prefer `XAI_API_KEY`). Key presence is configured but unverified until an active
+probe or requested execution succeeds. Build starts the requested `grok --prompt-file`
+execution without inspecting those auth paths first; the CLI's actual result is
+authoritative. Set `BUILD_GROK_ALLOW_BROWSER_AUTH=1` only when browser auth is
+acceptable. Explicit `grok-4.6` reasoning effort
+(`low`/`medium`/`high`/`xhigh`) is passed as `--reasoning-effort`. The `auto`
+model honors an explicit effort request only when native model discovery
+resolves to an effort-capable model; discovery failure does not invent
+capability, and `auto` still omits `-m`.
+
+---
+
+### Kiro CLI
+
+**Status**: Experimental native provider adapter
+
+#### Installation
+
+Install Kiro CLI with Kiro's official installer:
+
+```bash
+curl -fsSL https://cli.kiro.dev/install | bash
+```
+
+Because this runs a remote installer, Build will not execute it unless you explicitly opt in:
+
+```bash
+BUILD_ALLOW_CURL_BASH=1 build provider setup --providers kiro
+```
+
+Then verify the CLI is on `PATH`:
+
+```bash
+kiro-cli --version
+```
+
+#### Authentication
+
+Kiro headless automation requires an API key:
+
+```bash
+export KIRO_API_KEY=your-key
+kiro-cli whoami --format json
+```
+
+Interactive login is available with `kiro-cli login`, but automation should use `KIRO_API_KEY` so `kiro-cli chat --no-interactive` can run without browser prompts.
+
+#### Health and passive readiness
+
+`build doctor --provider kiro` checks that `kiro-cli` is installed and reports passive auth readiness from `KIRO_API_KEY`. Kiro's native auth probe uses `kiro-cli whoami --format json` for active provider auth checks without attempting browser login.
+
+#### Configuration
+
+Build invokes Kiro in headless mode with:
+
+```bash
+printf '%s' "<prompt>" | kiro-cli chat --no-interactive --trust-all-tools
+```
+
+The prompt is delivered on stdin. Passing it positionally makes Kiro interpret
+the text as a file path.
+
+Kiro models come from the static list configured in
+`.build-project/config/providers.yaml`; Build does not query the Kiro CLI for a model
+list. Kiro is experimental: default readiness and interactive setup omit it.
+Select it explicitly with `build provider setup --providers kiro`, show
+experimental readiness with `build provider list --include-experimental`, or
+include it in interactive setup with
+`build provider setup --include-experimental`.
+
+| Variable                  | Purpose                              | Default    |
+| ------------------------- | ------------------------------------ | ---------- |
+| `KIRO_API_KEY`            | Kiro API key for headless automation | (none)     |
+| `BUILD_KIRO_CLI_COMMAND` | Override Kiro CLI binary path        | `kiro-cli` |
+| `BUILD_SKIP_KIRO`        | Skip Kiro execution                  | unset      |
+
+#### Usage Patterns
+
+```bash
+build run "Review this change for correctness" --provider=kiro
+build run competition "Add focused tests" --variant kiro:local
+```
+
+**Important**: Kiro support should be validated end-to-end in an authenticated environment before using it for critical work. Current support is based on Kiro's documented headless command surface plus unit-level Build coverage.
+
+---
+
+### Google Antigravity CLI
+
+**Status**: Supported validated native CLI provider using Google's official `agy` CLI.
+
+#### Installation
+
+Install Antigravity CLI with Google's official installer:
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+```
+
+Because this runs a remote installer, Build will not execute it unless you explicitly opt in:
+
+```bash
+BUILD_ALLOW_CURL_BASH=1 build provider setup --providers antigravity
+```
+
+Then verify the CLI is on `PATH`:
+
+```bash
+agy --version
+```
+
+#### Authentication
+
+Antigravity CLI authenticates with Google OAuth on first run and stores credentials in the OS keyring. On local machines it may open a browser; on SSH/headless machines it should print a browser URL and code.
+
+```bash
+agy
+```
+
+Some headless environments may also support an API key:
+
+```bash
+export ANTIGRAVITY_API_KEY=your-key
+```
+
+`build doctor --provider antigravity` checks that `agy` is installed and reports passive auth readiness from `ANTIGRAVITY_API_KEY` when present. Native headless readiness currently requires `ANTIGRAVITY_API_KEY`; browser/OAuth state is CLI-owned and is not treated as a reliable non-interactive health signal.
+
+#### Configuration
+
+Build invokes Google's Antigravity CLI in print mode with:
+
+```bash
+agy --print-timeout 45m0s \
+  --output-format stream-json \
+  [--model <model-id>] \
+  --add-dir <working-dir> \
+  --log-file <run-log> \
+  --dangerously-skip-permissions \
+  --print "<prompt>"
+```
+
+`--print` is value-bearing: it consumes the next argv token as the prompt. Every
+other flag must precede it, with the prompt immediately after. Ordering
+`--print` before another flag makes `agy` treat that flag as the prompt text and
+answer a question about it instead of running the task -- it still exits 0, so
+the mistake reads as a successful run. `buildAntigravityArgv`
+(`src/core/providers/antigravity/execution/commands.ts`) enforces this ordering.
+
+The prompt starts with a one-line provider context note. Under `inheritance.automated` (or
+`inheritance.ask`) set to `build` or `native+build`, Build's instruction set takes its place; see
+Inheritance modes in the repository's `docs/INSTRUCTION_ARCHITECTURE.md`.
+
+This provider is `supported_validated` as the better-supported alternative to the
+experimental `gemini` provider. Validated 2026-08-27 against an authenticated `agy` 1.1.22: structured
+stream output reports the resolved model, input/output/thinking/cache-read tokens,
+duration, status, and conversation id. Single-file
+and multi-file edits land through the Build worktree path, a failing task exits
+non-zero with no changes, and a judged competition produced a correct diff.
+
+`build provider list` reports Antigravity auth as `unknown` rather than `yes`.
+That is expected: `agy` exposes no non-interactive auth-status probe, so the
+absence of a signal does not prove you are unauthenticated. Execution defers auth
+to the CLI and surfaces any real auth error at runtime. Google's official docs
+still emphasize the interactive TUI, so re-check the headless `--print` path after
+an `agy` upgrade. Build does not route Antigravity through OpenCode. Concrete
+model ids are passed through `agy --model`; unpinned runs retain the CLI default
+and record the model when the stream reports one, otherwise `cli-default`.
+
+| Variable                         | Purpose                                                                                    | Default |
+| -------------------------------- | ------------------------------------------------------------------------------------------ | ------- |
+| `ANTIGRAVITY_API_KEY`            | Optional Antigravity API key for headless environments when supported by the installed CLI | (none)  |
+| `BUILD_ANTIGRAVITY_CLI_COMMAND` | Override Antigravity CLI binary path                                                       | `agy`   |
+| `BUILD_SKIP_ANTIGRAVITY`        | Skip Antigravity execution                                                                 | unset   |
+
+#### Usage Patterns
+
+```bash
+build run "Review this change for correctness" --provider=antigravity
+build run competition "Add focused tests" --variant antigravity:local
+```
+
+Aliases accepted by Build include `agy`, `anti-gravity`, and `antigravity-cli`.
+
+---
+
+### Upstream Models via OpenCode
+
+**Status**: Available through the OpenCode provider, not as standalone Build execution providers.
+
+Configure the upstream provider in OpenCode, then use the exact model ID reported by `opencode models`:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+opencode auth login
+opencode models
+
+build run "Analyze this code" --engine=opencode --model=<provider/model>
+build run competition "Implement feature" --variant opencode:<provider/model>
+```
+
+Build passes the model selection to OpenCode. Provider endpoints, credentials, and model declarations belong in OpenCode configuration rather than Build configuration.
+
+---
+
+### OpenRouter (Pricing Source Only)
+
+**Status**: Not available as an execution provider
+
+**Note**: OpenRouter is used internally by Build as a pricing data source for model cost calculations. It is not available for task execution. Use a native execution provider (Claude, Cursor, Codex, Gemini, Copilot, Grok, or OpenCode) instead.
+
+---
+
+### OpenCode
+
+**Status**: Supported (experimental)
+
+**Overview**: OpenCode is an AI assistant by Anomaly that provides code generation and assistance capabilities.
+
+#### Installation
+
+```bash
+# Quick setup
+BUILD_ALLOW_CURL_BASH=1 build provider setup --providers opencode
+
+# Or install manually on Linux/macOS/WSL
+curl -fsSL https://opencode.ai/install | bash
+
+# npm and Homebrew are also supported
+npm install -g opencode-ai
+brew install anomalyco/tap/opencode
+```
+
+#### Authentication
+
+OpenCode manages its provider configuration and credentials. Interactive setups can use:
+
+```bash
+opencode auth login
+```
+
+For headless setups, use the configuration and environment-variable mechanisms documented by OpenCode. Build does not interpret an upstream provider's credentials or treat their presence as proof that execution will authenticate.
+
+#### Discovery (CLI-first)
+
+Build obtains provider and model discovery observations from the OpenCode CLI; it does not parse credential files:
+
+- **Credential-store entries**: `opencode auth list` — reports what OpenCode has recorded, not whether a future execution will authenticate.
+- **Model inventory**: `opencode models` — advisory model IDs for `opencode run --model <id>`. OpenCode 1.x also takes `opencode models <provider>` and `--refresh`; OpenCode 2 takes neither, so Build filters the full list by `provider/` prefix. A missing or empty inventory does not replace an execution attempt.
+
+- **Health/diagnostics**: `build doctor --provider opencode` reports:
+  - Whether the OpenCode CLI is installed
+  - Credential-store entries reported by `opencode auth list`
+  - Advisory models reported by `opencode models`
+  - Optional metadata enrichment from models.dev (best-effort, cached 24h)
+
+- **Offline behavior**: If the network is unavailable, Build still succeeds; models.dev enrichment is skipped and cached data is reused when present.
+- **Refresh**: On OpenCode 1.x, use `opencode models --refresh` only when explicitly requested; Build does not auto-refresh on every run.
+
+Optional enrichment: Build may fetch the [models.dev](https://models.dev) catalog (pricing, context, capabilities) with a 24h TTL cache. Models.dev is metadata only and is never treated as authoritative for what you can run locally. Enrichment is best-effort and does not block startup or fail the command when offline.
+
+**Health check:**
+
+```bash
+build doctor --provider opencode
+```
+
+Shows: CLI installed, entries from `opencode auth list`, and advisory models from `opencode models`. Authentication is established by a requested execution, not this diagnostic. No secrets are printed in logs or telemetry.
+
+#### Plugins
+
+OpenCode supports plugins for extended functionality. Plugins are optional for basic provider use.
+
+Build does not use OpenCode plugins as the Antigravity integration path. Use the standalone Google Antigravity CLI provider (`--provider antigravity`) for Antigravity work.
+
+#### Test OpenCode Provider
+
+```bash
+# Test with default model
+build run "Create a hello world test" --variant opencode
+
+# Test in competition
+build run competition "Implement feature" \
+  --variant opencode \
+  --variant claude
+```
+
+#### Headless invocation posture
+
+Headless OpenCode runs use `opencode run` with prompt-file delivery when the CLI supports `--file`. The invocation shape is `--file <prompt.md> -- "Read the attached prompt file and complete the task exactly as specified."`; older CLIs without `--file` fall back to a positional prompt.
+
+On OpenCode 2, `run`, `models` and `auth list` get `--standalone`, so each call uses a private server instead of OpenCode's shared background service, which runs tools outside Build's sandbox. `run` also gets `--auto`, because OpenCode 2 ignores `OPENCODE_PERMISSION`, and reasoning effort goes as `--model <provider/model>#<variant>`. When `opencode --version` reports 2.x and a command's help cannot be read, Build still passes `--standalone`, and `--auto` for `run`; when `run --help` lists no `--standalone`, the run is refused before launch.
+
+Known failure modes to preserve in tests and diagnostics:
+
+- Positional prompt transport can be misread by OpenCode as file/path-like task text; prefer prompt-file delivery.
+- Headless runs can remain process-active while making no output or file progress; keep OpenCode idle defaults stricter than the hard timeout.
+- OpenCode may emit little or no useful stdout on timeout; preserve redacted argv plus stdout/stderr tails on provider results.
+- OpenCode config, data, state, and cache homes must stay isolated per run unless explicitly overridden.
+- The per-run config folder is seeded from the user's `opencode.json`, `opencode.jsonc` and `config.json`; the per-run data folder gets `auth.json` only, which OpenCode 1 reads. OpenCode 2 keeps credentials in its database (`opencode.db`), and a new database does not import `auth.json` (observed on 2.1.4). Sign-ins stored in the user's database, including OpenCode Console OAuth, therefore do not reach an OpenCode 2 run; it gets credentials from environment variables and the seeded configuration. For OpenCode Console and Go models, set `OPENCODE_API_KEY` to a Console API key with Go access.
+
+#### Configuration
+
+OpenCode reads project configuration from `opencode.json` or `opencode.jsonc`. Keep the schema declaration so editors and OpenCode validate against the upstream contract, and use OpenCode's `{env:VARIABLE_NAME}` substitution instead of committing credential values. OpenCode substitutes an unset variable with an empty string, so the resulting execution—not the placeholder's presence—establishes whether configuration is usable:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "{env:OPENCODE_MODEL}"
+}
+```
+
+Provider declarations, endpoints, model IDs, and credential variable names are upstream-specific; follow [OpenCode's configuration documentation](https://opencode.ai/docs/config/) for those fields.
+
+Build scopes the environment passed to provider children. When an OpenCode configuration references an otherwise unrecognized variable, add its name to the parent process's comma-separated allowlist, for example `BUILD_CHILD_ENV_ALLOWLIST=PROVIDER_API_KEY`. This only permits the variable to reach OpenCode. It does not configure the provider, validate the value, prove authentication, or make inventory output authoritative. Never put the credential value itself in `BUILD_CHILD_ENV_ALLOWLIST`.
+
+#### CLI binary
+
+Build runs the first `opencode` on `PATH`. To run a specific binary, set `BUILD_OPENCODE_CLI_COMMAND`, or set it for every project in your user registry overlay, `~/.build/config/providers.yaml`:
+
+```yaml
+providers:
+  opencode:
+    cli:
+      command: /opt/homebrew/bin/opencode
+```
+
+Point Build at the real OpenCode binary when the `opencode` on `PATH` is a wrapper or launcher. Build runs OpenCode inside its sandbox, which allows writes only to the run's workspace, temporary folders, caches, and Build's runtime state, so a launcher that first writes elsewhere (its own log file, for example) exits before OpenCode starts. The run then fails with reason `sandbox_path_denied` and names the refused path. Readiness and `build doctor` do not run the CLI inside the sandbox, so they can report OpenCode ready in this case.
+
+---
+
+### Pi CLI
+
+**Status**: Supported validated native provider adapter. Validated 2026-07-26 against `pi` 0.82.1 with a cloud Anthropic backend, exercised through `build run` and `build run competition` with incremental streaming. The local OpenAI-compatible (self-hosted) path is **not yet validated**.
+
+Pi is unlike Build's other providers: it is a backend-agnostic **host**, not a vendor. One Pi install can front cloud APIs (Anthropic, OpenAI, Google, and ~30 others) or a local OpenAI-compatible endpoint such as Ollama. Cost, speed, and reasoning quality are therefore properties of whichever backend you configure, not of `pi` itself — which is why Build's capability ratings for Pi are deliberately conservative.
+
+#### Installation
+
+```bash
+npm install -g @earendil-works/pi-coding-agent
+pi --version
+```
+
+#### Authentication
+
+Pi owns its own credential store at `~/.pi/agent/auth.json` (written `0600`). Configure a backend either through Pi or through a backend environment variable:
+
+```bash
+# Option A: a backend env var Build will pass through
+export ANTHROPIC_API_KEY=your-key
+
+# Option B: a local OpenAI-compatible endpoint (no real credential needed)
+# declare it in ~/.pi/agent/models.json; Pi still wants a placeholder
+# apiKey value, e.g. "ollama"
+```
+
+Build passes through `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and `GOOGLE_API_KEY`. An operator-named key such as `MY_COMPANY_API_KEY` is **not** carried into the child environment in v1.
+
+#### Health and passive readiness
+
+`build doctor --provider pi` checks that `pi` is installed and reports passive auth readiness. Readiness reports `unknown` rather than `no` when no backend env var is set, because an absent env var does not prove you are unauthenticated: Pi may hold a stored credential, or your backend may be a local endpoint that needs none. `unknown` keeps Pi attempt-eligible; a real auth failure surfaces from the CLI at execution time.
+
+#### Configuration
+
+Build invokes Pi non-interactively with:
+
+```bash
+pi --print --mode json --no-approve --no-session [--model <backend/model>] [--thinking <level>] [--tools <names>] "<prompt>"
+```
+
+Three details are load-bearing:
+
+- **`--provider` is never emitted.** Pi's `--provider` names its *inner* inference backend (its default is `google`), not the Build provider. Build passes a qualified `backend/model` id through `--model` instead, so Pi resolves the backend from the id and your configuration is never overridden. Bare model ids resolve against Pi's own default backend, so prefer qualified ids.
+- **`--no-approve`, never `--approve`.** Pi's `--approve` grants *project trust*, which loads project-local extensions — that is, executable code from the repository being worked on. Unattended runs must not opt in.
+- **Global Pi resources still load.** `--no-approve` does not disable user-level extensions or settings. The generated macOS profile keeps `extensions/`, `npm/`, `git/`, `settings.json`, `trust.json` and `models.json` readable but write-protected beneath the active agent directory, including `PI_CODING_AGENT_DIR`. Directory removal and rename are denied for that root and its ancestors; first-run directory creation, runtime data and sibling locks remain writable.
+- **Prepare global packages outside confined runs.** Install or update configured packages before starting Build; a missing or mismatched npm/git package cannot be installed into the protected store during startup. Settings/model maintenance and legacy settings migrations also belong outside the generated sandbox.
+- **Auth and helpers remain writable.** `auth.json` supports initialization and OAuth refresh, and `bin/` supports Pi's downloaded helpers. Auth values can contain executable credential commands, and helper binaries run through Pi's PATH. Those are residual persistence surfaces: the selected authority denies do not close them. A later direct Pi launch uses that later process's privileges.
+- **Tool names must be Pi's own.** The built-ins are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. Pi silently *filters* unrecognized `--tools` names rather than erroring, so a Claude-style name like `read_file` would yield an agent with zero tools that still reports success. Build drops unknown names and warns instead of passing them on. Critically, omitting `--tools` is **not** the same as granting nothing: Pi falls back to `read,bash,edit,write`. So when a caller requests an allowlist and none of the names survive filtering, Build emits `--no-tools` to fail closed rather than silently widening the request into write and shell access. A read-only run is restricted to `read,grep,find,ls` (`bash` is excluded because it can write via shell redirection).
+
+`--thinking` accepts `off|minimal|low|medium|high|xhigh|max`, a superset of Build's five effort levels, so every level maps natively and exactly. Whether the configured backend honors it is a backend property.
+
+Pi is a supported provider: default readiness and interactive setup include it, and no `--include-experimental` opt-in is needed. Passive auth readiness reports `unknown` rather than `no`, because Pi keeps credentials in its own `~/.pi/agent/auth.json` and a local endpoint may need no credential at all — so an absent env var does not prove you are unauthenticated. Backend auth failures surface at execution time and are classified for retry.
+
+| Variable                | Purpose                                       | Default |
+| ----------------------- | --------------------------------------------- | ------- |
+| `ANTHROPIC_API_KEY`     | Backend credential (when using Anthropic)     | (none)  |
+| `OPENAI_API_KEY`        | Backend credential (when using OpenAI)        | (none)  |
+| `BUILD_PI_CLI_COMMAND` | Override Pi CLI binary path                   | `pi`    |
+| `BUILD_SKIP_PI`        | Skip Pi execution                             | unset   |
+
+#### Usage Patterns
+
+```bash
+build run "Add a focused test for the parser" --provider pi
+build run "Fix the failing case" --provider pi --model anthropic/claude-haiku-4-5
+```
+
+#### Known behavior
+
+- **Exit codes are not a success signal in JSON mode.** Pi maps a failed turn to a non-zero exit only under `--mode text`; under `--mode json` it exits `0` even on an auth failure or an unresolvable model. Build derives success from the event stream (`stopReason`, `errorMessage`, and whether any text or file change was produced), so a failed run is reported as a failure rather than as an empty success.
+- **Pi blocks on an open stdin pipe.** Even in `--print` mode with the prompt in argv, Pi waits for stdin EOF before emitting anything: an open pipe produces zero bytes and never exits, while the identical spawn with stdin closed completes in about a second. Build spawns Pi with stdin ignored. This is also what makes an interactive `pi ... > file` appear to write nothing.
+- **Session resume is unsupported.** `--session <id>` calls an interactive "Fork this session?" confirmation even in non-interactive mode, which deadlocks on stdin. Build passes `--no-session`.
+- **Usage is snapshotted per model call, not per event.** Within one call Pi repeats the same running total on every event, so summing all events would multiply the totals. But a tool-using turn makes several billed calls (a verified two-call run reported 1482/143 then 1705/136), so taking only the last snapshot would undercount. Build accrues at each assistant `message_end` and skips the duplicate `turn_end`.
+
+---
+
+## Authentication Semantics
+
+Build has four distinct authentication contexts. Understanding which applies prevents confusion between "setup readiness" and "runtime guarantees."
+
+### 1. Setup and Readiness Checks
+
+`build provider list` reports provider installation and authentication status as a **one-time advisory check**. It does not gate execution. Output shows `OK` (installed + authenticated), `Warning:` (installed, not authenticated), or `Error` (not installed).
+
+### 2. Routing and Selection Heuristics
+
+When selecting providers, routing (`routing-planner.ts`) and auto-orchestration (`auto-orchestrator.ts`) call `isAuthenticated()` as a heuristic. If auth is not pre-verified, the provider is still eligible — the routing rationale notes "auth not pre-verified; runtime will defer to the provider CLI."
+
+### 3. Explicit Preflight (Flywheel and Dry-Run)
+
+Flywheel preflight (`flywheel-preflight.ts`) runs a dedicated `checkProviderAuth()` for workflow stages. Dry-run validation (`dry-run-validator.ts`) checks auth but explicitly labels it as advisory: "Authentication is advisory here; runtime will defer to the CLI."
+
+### 4. Runtime Execution
+
+Provider execution **defers authentication to the underlying provider CLI**. Provider modules do not check authentication before running. Auth errors surface at execution time from the provider CLI with actionable guidance. This is intentional — it avoids hanging auth probes in headless/subprocess environments.
+
+**Judge preflight** follows the same pattern: `checkJudgeCliAvailability()` resolves the
+selected judge provider and verifies that provider's CLI installation only, deliberately
+skipping auth status checks. Auth errors from the judge provider surface at execution time.
+
+---
+
+## Dependency Matrix
+
+Quick reference for what you need to install:
+
+| Provider            | Primary CLI             | Secondary CLI | Status                                       |
+| ------------------- | ----------------------- | ------------- | -------------------------------------------- |
+| **Claude**          | `claude` (Anthropic)    | -             | Primary validated                            |
+| **Codex**           | `codex` (OpenAI)        | -             | Primary validated                            |
+| **Grok**            | `grok` (xAI)            | -             | Supported validated                          |
+| **Cursor**          | `cursor-agent` (Cursor) | -             | Supported validated                          |
+| **OpenCode**        | `opencode` (Anomaly)    | -             | Supported validated                          |
+| **Gemini**          | `gemini` (Google)       | -             | Experimental (no longer extended)            |
+| **Copilot**         | `copilot`               | -             | Experimental                                 |
+| **Kiro**            | `kiro-cli`              | -             | Experimental headless CLI provider           |
+| **Pi**              | `pi`                    | -             | Supported validated; backend-agnostic host CLI |
+| **Antigravity**     | `agy` (Google)          | -             | Supported validated Google Antigravity CLI provider |
+| **GLM/Z.AI models** | `opencode` (Anomaly)    | -             | Available through OpenCode model selection   |
+
+**Note**: GLM/Z.AI models use OpenCode CLI with built-in Z.ai authentication. Select them with `--engine=opencode --model=<glm model id>`.
+
+---
+
+## Environment Variables Reference
+
+| Variable                         | Purpose                                                                                    | Default                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------- |
+| `BUILD_MOCK_PROVIDERS`          | Request mock mode (1=on, 0=off); outside tests also requires `BUILD_ALLOW_MOCK_PROVIDERS=1` or startup scrubs it | `0`                      |
+| `BUILD_ALLOW_MOCK_PROVIDERS`    | Explicit opt-in for mock mode outside test runners (`1` required with `BUILD_MOCK_PROVIDERS=1`) | `0`                            |
+| `CLAUDE_CONFIG_DIR`              | Claude config directory                                                                    | `~/.build/config/providers/claude` |
+| `BUILD_CLAUDE_BACKEND`          | Claude backend selector (`anthropic`\|`bedrock`\|`vertex`)                                 | `anthropic`                         |
+| `BUILD_BEDROCK_REGION_PREFIX`   | Bedrock inference profile prefix (`global`\|`us`\|`eu`\|`jp`\|`apac`)                      | `global`                            |
+| `CODEX_HOME`                     | Codex config directory                                                                     | `~/.codex`                          |
+| `BUILD_CODEX_AUTH_MODE`         | `api_key` passes API keys to Codex CLI; otherwise OAuth (default)                          | OAuth                               |
+| `BUILD_CODEX_BACKEND`           | Codex backend attestation (`openai` or `bedrock`); unset follows the Codex config. `bedrock` selects Bedrock routing when the config names no recognized provider (`amazon-bedrock` or `amazon-bedrock-runtime`), asserts `amazon-bedrock` in that case, and marks readiness as a Bedrock run. AWS environment credentials are forwarded to Codex regardless. | (auto) |
+| `BUILD_TIMEOUT_CODEX_MS`        | Codex subprocess timeout in milliseconds                                                   | `2700000`                           |
+| `OPENAI_API_KEY`                 | Forwarded under `BUILD_CODEX_AUTH_MODE=api_key` and counts as ready, but `codex exec` does not read it | (none)                              |
+| `CODEX_API_KEY`                  | API key `codex exec` reads when `BUILD_CODEX_AUTH_MODE=api_key`                           | (none)                              |
+| `CODEX_TOKEN`                    | Legacy token; counts as ready under `api_key`, but `codex exec` does not read it           | (none)                              |
+| `BUILD_CODEX_ISOLATE_HOME`      | Isolate Codex session/history per worktree (`0` disables)                                  | `1`                                 |
+| `CURSOR_CONFIG_DIR`              | Cursor config directory. When set, Build checks only this directory for a login, so run `cursor-agent login` with it set | (unset; `~/.cursor` when logged in there, else `~/.build/config/providers/cursor`; with `XDG_CONFIG_HOME` set, set it to `$XDG_CONFIG_HOME/cursor`) |
+| `CURSOR_API_KEY`                 | Authenticates the local Cursor CLI without a login session (headless hosts); also used for model discovery | (none)                 |
+| `BUILD_CURSOR_CLOUD_TRANSPORT`  | Historical Cursor cloud transport selector (`api` or `github_pr`); not a product path      | (none)                              |
+| `CURSOR_CLOUD_TRANSPORT`         | Historical alternative for Cursor cloud transport selection                                | (none)                              |
+| `GEMINI_CONFIG_DIR`              | Gemini config directory                                                                    | `~/.build/gemini`                  |
+| `ANTHROPIC_API_KEY`              | Optional legacy Claude API key (CLI login recommended; Build defaults to CLI auth)        | (none)                              |
+| `GOOGLE_API_KEY`                 | Gemini API key (personal account)                                                          | (none)                              |
+| `GEMINI_API_KEY`                 | Alternative Gemini API key                                                                 | (none)                              |
+| `OPENAI_API_KEY`                 | OpenAI API key (used by some providers/agents)                                             | (none)                              |
+| `OPENROUTER_API_KEY`             | OpenRouter API key (pricing + optional provider key)                                       | (none)                              |
+| `BUILD_SKIP_OPENCODE`           | Skip OpenCode execution (dry-run mode, 1=on)                                               | `0`                                 |
+| `BUILD_OPENCODE_CLI_COMMAND`    | Path to OpenCode CLI binary                                                                | `opencode`                          |
+| `GOOGLE_CLOUD_PROJECT`           | GCP project ID (Vertex AI)                                                                 | (none)                              |
+| `GCLOUD_PROJECT`                 | Alternate GCP project ID (Vertex AI)                                                       | (none)                              |
+| `CLOUD_ML_REGION`                | Vertex AI region for Claude Code                                                           | (none)                              |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Service account key path (Vertex AI)                                                       | (none)                              |
+| `BUILD_CURSOR_CLI_COMMAND`      | Path to Cursor Agent binary (preferred). Legacy `CURSOR_CLI_COMMAND` is still honored.     | `cursor-agent`                      |
+| `CURSOR_CLI_TIMEOUT`             | Cursor run timeout in milliseconds, clamped to 2-120 minutes; outranks `BUILD_TIMEOUT_MS`, while `BUILD_TIMEOUT_CURSOR_MS` outranks it | `(unset; registry fallback 2700000)` |
+| `BUILD_CURSOR_MODEL`            | Default Cursor model for local CLI                                                         | `auto`                              |
+| `BUILD_DEFAULT_PROVIDER`        | Global default provider without flags                                                      | (none)                              |
+| `BUILD_COPILOT_CLI_COMMAND`     | Path to GitHub Copilot CLI binary                                                          | `copilot`                           |
+| `BUILD_COPILOT_WORKFLOW`        | Default Copilot workflow (`suggest`, `chat`, `explain`)                                    | `suggest`                           |
+| `BUILD_TIMEOUT_COPILOT_MS`      | Copilot provider timeout override in milliseconds                                          | `(unset; registry fallback 2700000)` |
+| `COPILOT_TELEMETRY_OPTOUT`       | Disable GitHub Copilot telemetry (1=on)                                                    | `0`                                 |
+| `KIRO_API_KEY`                   | Kiro API key for headless automation                                                       | (none)                              |
+| `BUILD_KIRO_CLI_COMMAND`        | Path to Kiro CLI binary                                                                    | `kiro-cli`                          |
+| `BUILD_SKIP_KIRO`               | Skip Kiro execution                                                                        | unset                               |
+| `BUILD_PI_CLI_COMMAND`          | Path to Pi CLI binary                                                                      | `pi`                                |
+| `BUILD_SKIP_PI`                 | Skip Pi execution                                                                          | unset                               |
+| `ANTIGRAVITY_API_KEY`            | Optional Antigravity API key for headless environments when supported by the installed CLI | (none)                              |
+| `BUILD_ANTIGRAVITY_CLI_COMMAND` | Path to Google Antigravity CLI binary                                                      | `agy`                               |
+| `BUILD_SKIP_ANTIGRAVITY`        | Skip Antigravity execution                                                                 | unset                               |
+| `BUILD_DEBUG`                   | Enable debug logging for all providers                                                     | `0`                                 |
+| `BUILD_VERBOSE`                 | Enable verbose output for all providers                                                    | `0`                                 |
+| `BUILD_PLAIN_LOGS`              | Disable ANSI colors in logs                                                                | `0`                                 |
+
+---
+
+## Troubleshooting
+
+### Claude Issues
+
+**Problem**: `'claude' is not available on this system`
+
+**Solution**:
+
+```bash
+# Verify Claude CLI is installed
+which claude
+
+# If not found, install it
+npm install -g @anthropic-ai/claude-code
+
+# Add to PATH if needed
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+**Problem**: `Authentication failed`
+
+**Solution**:
+
+```bash
+# Re-authenticate
+claude auth logout
+claude auth login
+```
+
+**Problem**: `Rate limit exceeded`
+
+**Solution**: Wait 60 seconds or upgrade your Anthropic plan for higher limits.
+
+---
+
+### Codex Issues
+
+**Problem**: `Command not found: codex`
+
+**Solution**:
+
+```bash
+# Install Codex CLI
+npm install -g @openai/codex
+
+# Verify installation
+codex --version
+```
+
+**Problem**: `Authentication required`
+
+**Solution**:
+
+```bash
+# Re-authenticate
+codex login
+```
+
+---
+
+### Cursor Issues
+
+**Problem**: `ConnectError: [invalid_argument]`
+
+**Solution**: This often occurs in plan mode. Disable plan mode or try a different model (`--model auto` falls back to your Cursor preference).
+
+**Problem**: `Command not found: cursor-agent`
+
+**Solution**: Install Cursor Agent (see [Cursor (CLI)](#cursor-cli) → Installation), then verify with `cursor-agent --version`.
+
+**Problem**: `Not authenticated`
+
+**Solution**: Build reuses your Cursor login. Authenticate with `cursor-agent login` (see [Cursor (CLI)](#cursor-cli) → Authentication).
+
+**Problem**: `Command timed out after 30000ms`
+
+**Solution**: Increase timeout in config or environment:
+
+```bash
+export CURSOR_CLI_TIMEOUT=3600000  # 60 minutes; clamped to 2-120 minutes
+```
+
+**Problem**: `Invalid model: xyz`
+
+**Solution**: Use supported models (`auto`, `gpt-4o`, `gpt-4o-mini`, etc.) or set `BUILD_CURSOR_MODEL` to a known value.
+
+---
+
+### Gemini Issues
+
+**Problem**: `'gemini' is not available on this system`
+
+**Solution**:
+
+```bash
+# Verify Gemini CLI is installed
+which gemini
+
+# If not found, install it
+npm install -g @google/gemini-cli
+
+# Add to PATH if needed
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+**Problem**: `Authentication failed` or `API key not found`
+
+**Solution**: Set up proper authentication:
+
+```bash
+# For personal Google account
+export GOOGLE_API_KEY='your-api-key-here'
+
+# For Vertex AI enterprise
+gcloud auth application-default login
+export GOOGLE_CLOUD_PROJECT='your-project-id'
+export GOOGLE_CLOUD_LOCATION='us-central1'
+```
+
+**Problem**: `Permission denied` or `Insufficient permissions`
+
+**Solution**: Ensure proper permissions:
+
+```bash
+# For Vertex AI, check service account has AI Platform User role
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="serviceAccount:your-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
+  --role="roles/aiplatform.user"
+```
+
+**Problem**: `Rate limit exceeded`
+
+**Solution**: Wait or upgrade quotas. Personal accounts have different limits than enterprise Vertex AI accounts.
+
+---
+
+### OpenCode Model Issues
+
+**Problem**: `Command not found: opencode`
+
+**Solution**:
+
+```bash
+# Install OpenCode CLI
+curl -fsSL https://opencode.ai/install | bash
+# or:
+npm install -g opencode-ai
+
+# Verify installation
+opencode --version
+```
+
+**Problem**: An OpenCode execution reports an authentication failure
+
+**Solution**: Repair the affected upstream provider through OpenCode, then retry the execution:
+
+```bash
+opencode auth login
+```
+
+For a headless provider configured through environment substitution, confirm the referenced variable reaches OpenCode. If Build would otherwise filter that variable, name it in `BUILD_CHILD_ENV_ALLOWLIST`; this propagation setting does not validate the credential.
+
+**Problem**: A model-family name passed as `--engine` is rejected
+
+**Solution**: Use OpenCode as the execution provider and pass an exact model ID from `opencode models`:
+
+```bash
+build run "Analyze this code" --engine=opencode --model=<provider/model>
+```
+
+---
+
+## Provider Comparison
+
+Setup effort and context window only. Build does not rank providers on output
+quality, speed, price, or support tier: per-model prices live in the sourced
+pricing catalog, and the rest would be an unsourced claim about someone else's
+product.
+
+| Feature                | Claude              | Codex                | Cursor           | Gemini          | Copilot                   | OpenCode              |
+| ---------------------- | ------------------- | -------------------- | ---------------- | --------------- | ------------------------- | --------------------- |
+| **Context Window**     | 200K+ tokens        | 128K+ tokens         | Provider-routed  | 1M tokens       | Provider-routed           | Upstream-dependent    |
+| **Setup Complexity**   | Medium              | High                 | High             | Low             | Low                       | Medium                |
+| **Dependencies**       | Single CLI          | Single CLI           | Single CLI       | Single CLI      | Single CLI                | Single CLI            |
+
+**Notes**:
+
+- GLM/Z.AI models are selected through OpenCode, for example `--engine=opencode --model=z-ai/glm-4.7`.
+
+---
+
+## Next Steps
+
+Once providers are set up:
+
+1. **Test Execution**:
+
+   ```bash
+   build run "Create a hello world test" --engine=claude
+   ```
+
+2. **Run Variant Competition**:
+
+   ```bash
+   build run "Implement feature X" --variants=3
+   ```
+
+3. **View Telemetry**:
+
+   ```bash
+   build telemetry leaderboard
+   build telemetry trends
+   ```
+
+4. **Review Results**:
+   - Check the resolved telemetry directory for SQLite databases (`db/variants.db`, `invocations.db`) and monthly JSONL under `logs/<YYYY-MM>/`. Default: `~/.build/data/telemetry/`. `build doctor --verbose` prints the resolved path. Per-run state is under `~/.build/data/projects/<project-id>/telemetry/state/`.
+
+---
+
+## Support
+
+- **Documentation**: `docs/CLI_REFERENCE.md`, `docs/TROUBLESHOOTING.md`, [ARCHITECTURE.md](https://github.com/ebrindley/build/blob/main/ARCHITECTURE.md)
+- **Issues**: https://github.com/ebrindley/build/issues
+
+---
+
+**Last Updated**: 2026-07-25
+
+**Major Changes:**
+
+- Documented local-only execution for all providers (ADR-021)
+- Cursor/Codex cloud setup reframed as historical compatibility only
+- Legacy provider API transport selections are rejected with migration guidance; historical API configuration remains readable but does not enable execution
+- Ordinary PR publication and judge-winner semantics unchanged