@poetic-ai/poetic 1.42.0

package/docs/PROVIDER_SETUP.md

@@ -0,0 +1,1570 @@
+# Provider Setup Guide
+
+This guide walks you through setting up AI providers for Poetic. Poetic 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 because its CLI is sunsetting; see below). This is
+> separate from configured defaults:
+> `poetic config resolved --summary --json` reports the active execution and
+> judge defaults. Run `poetic provider list` and `poetic doctor --matrix` before
+> relying on a local provider.
+
+> **Execution modes:** All providers run locally. Variant mode `:cloud` is not an executable product path (see [ADR-021](https://github.com/ebrindley/Poetic/blob/main/docs/adr/021-local-only-execution.md)). Provider API transport for local CLI/API runs remains supported. 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
+
+Poetic 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 `poetic config resolved --summary --json` for active defaults, and keep the registry fresh with:
+
+```bash
+poetic provider refresh <id> --models
+```
+
+The release catalog is generated from Poetic'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:conservative` 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 (sunsetting)       | CLI retired for free/Pro/Ultra tiers 2026-06-18; opt-in only. Keep fan-out worker counts conservative; 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.
+
+The common provider IDs `claude`, `codex`, `cursor`, and `gemini` are stable
+shorthands for the corresponding local CLI providers in examples and
+configuration.
+
+First-run provider setup saves the selected provider under
+`defaults.provider`. If no provider has been selected, registry order is only a
+bootstrap fallback; run `poetic provider setup --first-run` or set
+`defaults.provider` before relying on zero-flag execution.
+
+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 `poetic --help`):
+
+```bash
+poetic explain providers
+```
+
+### Claude model aliases (incl. Fable 5)
+
+Claude accepts the short aliases `opus`, `sonnet`, `haiku`, and `fable` (each floats to the latest of that family), version-pinned shorthands (`opus-4-8`, `sonnet-4-6`, `fable-5`), and full `claude-*` ids (`claude-opus-4-8`, `claude-fable-5`). 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-1`) 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** — it follows the standard Anthropic-on-Bedrock naming and the AWS model card but, unlike the other Claude models, has not been live-verified (Fable cannot be invoked while unavailable). When access returns, re-verify the profile live and add any regional profiles to the `claude-fable-5` entry in `.poetic/config/providers.yaml`. (Mythos 5 is Project-Glasswing-only and is not a wired Poetic alias; a full `claude-mythos-5` id passes through like any `claude-*` string, and the same temporary-availability messaging applies.)
+
+## Quick Start with Mock Mode
+
+**For development and testing**, you can use mock mode to run Poetic without installing any providers.
+
+Outside test runners (`NODE_ENV=test` or `VITEST=true|1`), both flags are required. If only `POETIC_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 POETIC_MOCK_PROVIDERS=1
+export POETIC_ALLOW_MOCK_PROVIDERS=1
+
+# Run with mock providers
+poetic run "test task" --variants=3
+
+# Disable mock mode
+unset POETIC_MOCK_PROVIDERS
+unset POETIC_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/Poetic/blob/main/docs/MOCK_ENV_VARS.md).
+
+## Verify Your Environment (Health / Doctor)
+
+Poetic includes a built-in environment check:
+
+```bash
+# Alias:
+poetic doctor
+
+# Check configured providers only (default behavior)
+poetic doctor
+
+# Check all known providers explicitly
+poetic doctor --all
+
+# Support matrix: tier + CLI/auth/runtime health
+poetic doctor --matrix
+
+# Check a single provider
+poetic doctor --provider claude
+```
+
+`poetic 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 `poetic init`, run `poetic 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
+
+Poetic provides a unified `poetic provider setup` command for managing providers and plugins.
+
+### Interactive Wizard
+
+Run the setup wizard to interactively select and install providers:
+
+```bash
+poetic provider setup
+```
+
+The wizard will:
+
+1. Show available providers with descriptions
+2. Let you select one or more providers
+3. Install each provider
+4. Offer available plugins for each provider
+5. Configure provider options (when available)
+
+### Non-Interactive Setup
+
+Install specific providers without interaction:
+
+```bash
+# Install single provider
+poetic provider setup --providers claude
+
+# Install multiple providers
+poetic provider setup --providers claude,gemini,opencode
+
+# Install with plugins (optional; not required for GLM)
+poetic provider setup --providers opencode --plugins opencode:<plugin-id>
+```
+
+### Check Mode
+
+Report provider readiness without making changes:
+
+```bash
+poetic 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 `poetic run` or `poetic compete` 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
+$ poetic run "test task"
+Warning: No runnable provider configured
+
+Setup required. Run one of these commands:
+  poetic provider setup                          # Interactive wizard
+  poetic provider setup --providers claude       # Install Claude
+  poetic provider setup --providers opencode     # Install OpenCode
+```
+
+### Safety Boundary
+
+Poetic 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, `poetic provider setup` will print the install
+command and exit without executing it:
+
+```bash
+export POETIC_ALLOW_CURL_BASH=1
+poetic 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 Poetic's. Poetic itself requires Node.js
+> 24.x (see [INSTALL.md](../INSTALL.md#prerequisites)); a provider CLI may run on
+> an older Node, but Poetic still needs 24.x to run.
+
+### Claude CLI
+
+**Status**: Supported local CLI provider
+
+#### Installation
+
+Prerequisite: Node.js 18+ (the Claude CLI's own minimum; Poetic itself requires Node 24.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
+
+Poetic uses a dedicated config directory to avoid conflicts:
+
+```bash
+# Default location
+~/.poetic/config/providers/claude
+
+# Or set custom location
+export CLAUDE_CONFIG_DIR=~/.poetic/config/providers/claude
+```
+
+**Bedrock Configuration (AWS)**:
+
+Poetic defaults Claude to Anthropic. Bedrock mode is enabled when
+`POETIC_CLAUDE_BACKEND=bedrock` is set.
+AWS environment variables (`AWS_REGION`, `AWS_PROFILE`) alone do **not**
+activate Bedrock mode — explicit opt-in is still required.
+
+`CLAUDE_CODE_USE_BEDROCK` is a Claude Code CLI variable, not a Poetic routing
+input. Poetic ignores ambient Claude-native backend flags when selecting its own
+backend so a parent Claude Code session cannot silently reroute execution.
+
+> **Migration**: Prefer `POETIC_CLAUDE_BACKEND=bedrock` in shell profiles and CI.
+> Poetic's backend resolver checks `POETIC_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, Poetic converts model names to cross-region inference
+profiles automatically. All model inputs (`sonnet`, `sonnet-4-6`,
+`claude-sonnet-4-6`, etc.) resolve to inference profile IDs with the correct
+Bedrock model suffix.
+
+**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 Poetic setting:
+export POETIC_CLAUDE_BACKEND=bedrock
+
+# Override to pin a specific region prefix (global|us|eu|jp|apac):
+export POETIC_BEDROCK_REGION_PREFIX=us
+```
+
+**Inference profile examples** (generated by Poetic, not user-managed):
+
+| Input                | Bedrock inference profile                         |
+| -------------------- | ------------------------------------------------- |
+| `--model sonnet`     | `global.anthropic.claude-sonnet-4-6`              |
+| `--model sonnet-4-6` | `global.anthropic.claude-sonnet-4-6`              |
+| `--model opus`       | `global.anthropic.claude-opus-4-8`                |
+| `--model haiku`      | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
+
+Bedrock model ID suffixes are maintained in `CLAUDE_BEDROCK_MODELS` in
+`src/core/providers/claude/config.ts` — do not construct inference profile
+strings manually.
+
+Poetic also synthesizes `CLAUDE_CODE_USE_BEDROCK=1` for Claude subprocesses
+when the canonical `POETIC_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 `POETIC_CLAUDE_BACKEND=vertex` is set.
+`CLAUDE_CODE_USE_VERTEX` is treated the same way as the Bedrock flag above:
+Poetic ignores it for routing and only synthesizes Claude-native backend flags
+when launching the final Claude subprocess.
+
+Poetic 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 Poetic setting:
+export POETIC_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.
+
+Poetic synthesizes `CLAUDE_CODE_USE_VERTEX=1` for Claude subprocesses when the
+canonical `POETIC_CLAUDE_BACKEND=vertex` setting is used.
+
+**Profile Setup**:
+
+Poetic 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
+poetic run "Create a hello world test" --engine=claude
+
+# Test variant competition
+poetic 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; Poetic itself requires Node 24.x).
+
+```bash
+# Install Codex CLI
+npm install -g @openai/codex
+
+# Verify installation
+codex --version
+```
+
+#### Authentication
+
+**Default:** Codex CLI OAuth (ChatGPT / browser login). Poetic does not preflight auth before
+`run` or `compete`; the CLI surfaces auth errors. `poetic doctor --provider codex` checks
+`auth.json` under `CODEX_HOME` (and `~/.codex` when unset), plus API keys when set.
+
+```bash
+codex login
+# or: poetic provider setup --providers codex
+```
+
+**API key mode (optional):** set `POETIC_CODEX_AUTH_MODE=api_key` and provide `OPENAI_API_KEY`
+(or legacy `CODEX_API_KEY` / `CODEX_TOKEN`). In OAuth mode, Poetic 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. `poetic run` and `poetic compete` invoke `codex exec --json`
+inside the selected workspace or worktree; Poetic does not submit, poll, or apply Codex cloud tasks.
+
+#### Test Codex Provider
+
+```bash
+poetic 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
+
+Poetic uses your Cursor account session. Authenticate via the Cursor Agent:
+
+```bash
+cursor-agent login
+```
+
+#### Cursor Cloud (Historical Only)
+
+Poetic does not run Cursor (or Codex) cloud agent workflows. Use local Cursor CLI execution via `cursor-agent login` and local variants such as `cursor:conservative`.
+
+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 `CURSOR_API_KEY`, `POETIC_CURSOR_CLOUD_TRANSPORT`, and `CURSOR_CLOUD_TRANSPORT` may exist in older operator setups; they do not enable a Poetic `:cloud` execution path.
+- Prefer `cursor-agent login` for local CLI authentication. Do not treat cloud transport configuration as setup for new work.
+- For PR publication after local compete/apply, use ordinary GitHub auth (`gh auth login`) as documented in the compete and CLI guides — that is not Cursor cloud execution.
+
+#### Configuration
+
+```bash
+# Default location
+~/.poetic/cursor/
+
+# Or set custom location
+export CURSOR_CONFIG_DIR=~/.poetic/cursor
+
+# Override default model for Cursor
+export POETIC_CURSOR_MODEL='auto'
+
+# Make Cursor the default provider without flags
+export POETIC_DEFAULT_PROVIDER='cursor'
+```
+
+The Cursor provider uses the `cursor` ID for local CLI execution. Use the environment variables above or Poetic's resolved provider configuration; `poetic.config.ts` is not a loaded configuration source.
+
+#### Test Cursor Provider
+
+```bash
+poetic run "Write a hello world function" --engine=cursor
+
+poetic run "Refactor this component" --engine=cursor --variants=2
+
+# Fan-out local execution
+poetic run "Generate fixtures" --engine=cursor --fan-out 3
+
+# Test with file context (auto-detected in output)
+poetic 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 `POETIC_CURSOR_MODEL` or the Cursor preference store to pin defaults.
+
+---
+
+### Gemini CLI
+
+**Status**: Experimental (sunsetting). Google retired Gemini CLI for free, AI Pro, and Ultra tiers on 2026-06-18; usable only with enterprise Code Assist or paid API keys. Prefer `antigravity`.
+
+#### Installation
+
+Prerequisite: Node.js 20+ (the Gemini CLI's own minimum; Poetic itself requires Node 24.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
+
+Poetic uses a dedicated config directory for Gemini:
+
+```bash
+# Default location
+~/.poetic/gemini/
+
+# Or set custom location
+export GEMINI_CONFIG_DIR=~/.poetic/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
+poetic run "Create a hello world function" --engine=gemini
+
+# Test with specific model
+poetic run "Add error handling" --engine=gemini --model=gemini-2.5-pro
+
+# Test fan-out execution
+poetic run "Generate test suite" --engine=gemini --fan-out 3
+```
+
+**Important**: This provider assumes `gemini` CLI is already installed and authenticated. Poetic 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; Poetic itself requires Node 24.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 Poetic configuration is required.
+
+#### Configuration
+
+Poetic invokes the standalone `copilot` application. Default execution is agentic direct editing: Copilot applies workspace edits and Poetic detects changes via git. Configure via environment variables:
+
+| Variable                     | Purpose                                         | Default                                 |
+| ---------------------------- | ----------------------------------------------- | --------------------------------------- |
+| `POETIC_COPILOT_CLI_COMMAND` | Path to Copilot CLI binary                      | `copilot`                               |
+| `POETIC_COPILOT_WORKFLOW`    | Default workflow (`suggest`, `chat`, `explain`) | `suggest`                               |
+| `POETIC_TIMEOUT_COPILOT_MS`  | Provider timeout override in ms                 | `(unset; registry fallback 2700000)`    |
+
+Timeout resolution: explicit caller timeout, then `POETIC_TIMEOUT_COPILOT_MS` (when set), then global `POETIC_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 `POETIC_COPILOT_SHELL_ENABLED=0`. Unified-diff/`diff_output` mode is opt-in (`POETIC_COPILOT_OUTPUT_MODE=diff_output`).
+
+#### Usage Patterns
+
+```bash
+# Agentic direct edit (git-detected changes; experimental provider)
+poetic run "Harden password validation in @src/auth/password.ts" --provider=copilot
+
+# Ask Copilot to propose tests for a new feature
+poetic 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
+poetic compete "Modernize feature flag utilities" \
+  --variant copilot:innovative:local \
+  --variant claude:conservative:local \
+  --variant gemini:hybrid: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                              |
+| ---------------------------- | ----------------------------------------------- | ------------------------------------ |
+| `POETIC_COPILOT_CLI_COMMAND` | Override Copilot CLI binary path                | `copilot`                            |
+| `POETIC_COPILOT_WORKFLOW`    | Default workflow (`suggest`, `chat`, `explain`) | `suggest`                            |
+| `POETIC_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 `POETIC_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 Poetic’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 Poetic’s sandbox for Copilot with `export POETIC_SANDBOX_COPILOT_ENABLED=0` (or `export POETIC_SANDBOX_GITHUB_COPILOT_ENABLED=0`).
+
+---
+
+### Grok CLI
+
+**Status**: Supported via Grok Build CLI
+
+For first-user delivery, prefer the validated selector
+`--variant grok:conservative` and omit a Grok model pin. Poetic'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 Poetic runs,
+set the normal provider-scoped user option:
+
+```bash
+poetic 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
+poetic 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 Poetic'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, Poetic will not execute it unless you explicitly opt in:
+
+```bash
+POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers grok
+```
+
+Then verify the CLI is on `PATH`:
+
+```bash
+grok --version
+```
+
+#### Authentication
+
+Grok authentication is owned by the `grok` CLI. Poetic 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
+Poetic 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** Poetic compatibility alias. It is
+still accepted for older Grok Build CLI / Poetic setups; prefer `XAI_API_KEY`
+for new headless configuration. Do not treat the alias as the primary key.
+
+#### Health and passive readiness
+
+`poetic 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 compete/run. Use
+`poetic doctor --probe --provider grok` for an explicit active readiness check.
+Compete/run establish auth on the requested execution.
+
+For headless compete/run without a usable CLI auth cache, set `XAI_API_KEY`
+(optional path above). `POETIC_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.
+
+`poetic compete` and `poetic 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 Poetic does not reject
+the run based on a preflight inspection of those paths. Set
+`POETIC_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 in
+`.poetic/planning/grok-preflight/findings.md`.
+
+**Default posture** (`src/core/providers/grok/execution/commands.ts`):
+
+| Flag | Value | Rationale |
+|------|-------|-----------|
+| `--prompt-file` | always | Avoid argv bloat; never use `-p`/`--single` for Poetic prompts |
+| `--output-format` | `streaming-json` | Follows the provider-streaming gate (`POETIC_PROVIDER_STREAMING`, default on since 2026-06-04); set `POETIC_PROVIDER_STREAMING=0` for the `json` posture (deterministic success/error envelopes); `POETIC_GROK_OUTPUT_FORMAT` overrides both |
+| `--no-alt-screen` | always | Headless determinism |
+| `--no-memory` | default on | Disable Grok memory unless `POETIC_GROK_MEMORY=1` |
+| `-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` + matching inspect/search allows are necessary but not globally fail-closed alone; the locked posture 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 Poetic's outer seatbelt. Read-only runs (`readOnlyWorkingDir`/analysis intent, e.g. `poetic 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`. See `.poetic/planning/grok-preflight/transport-death.md`. |
+| `--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`; `POETIC_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 `POETIC_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 Poetic's outer seatbelt (EPERM). Read-only and edit/mixed both use Poetic'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 `poetic doctor --probe --provider grok` still runs an active headless edit probe (`buildGrokArgv` + `executeProviderCommand`, `--max-turns 8`, `--always-approve`, `POETIC_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 `POETIC_GROK_*` env vars in the Configuration subsection below.
+
+#### Configuration
+
+Poetic invokes `grok` in headless mode. Configure transport behavior via environment variables:
+
+| Variable                         | Purpose                                                                                                                                 | Default |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `POETIC_GROK_CLI_COMMAND`        | Override Grok CLI binary path                                                                                                           | `grok`  |
+| `POETIC_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` |
+| `POETIC_GROK_ALLOW_RULES`        | Comma-separated `--allow` rules when permission mode is `dontAsk` (required for `dontAsk`)                                              | unset   |
+| `POETIC_GROK_AUTO_APPROVE`       | Set to `0` to omit `--always-approve` (suppressed automatically under `dontAsk`)                                                        | enabled |
+| `POETIC_GROK_ALWAYS_APPROVE`     | Legacy alias for `POETIC_GROK_AUTO_APPROVE`                                                                                              | enabled |
+| `POETIC_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) |
+| `POETIC_GROK_OUTPUT_FORMAT`      | `plain`, `json`, or `streaming-json`. When unset, follows `POETIC_PROVIDER_STREAMING` (default on → `streaming-json`; set `POETIC_PROVIDER_STREAMING=0` for buffered `json`) | `streaming-json` (when streaming on) |
+| `POETIC_GROK_MEMORY`             | Set to `1` to allow Grok memory                                                                                                         | disabled (`--no-memory`) |
+| `POETIC_GROK_ALLOW_BROWSER_AUTH` | Set to `1` to allow requested Grok execution (or an explicit doctor probe) to start browser auth                                         | disabled |
+| `POETIC_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; Poetic rejects them if set via `POETIC_GROK_PERMISSION_MODE`.
+- Read-only consults (`poetic 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 Poetic'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 `POETIC_GROK_PERMISSION_MODE` (e.g. `bypassPermissions`) cannot YOLO past the locked posture.
+- `--always-approve` (and explicit `bypassPermissions`) require an active Poetic policy/sandbox boundary. For edit intent, `POETIC_GROK_AUTO_APPROVE=0` fails closed before launch (no false success without a tool-approval path).
+- Session resume: when `ProviderRunOptions.resumeSessionId` is set, Poetic emits Grok CLI `--resume <id>`. Legacy env names alone do not resume a session.
+- Token usage: when Grok headless envelopes include parseable token counts, Poetic 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
+poetic 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
+poetic compete "Update the target file and add focused tests" \
+  --variant grok:conservative
+git checkout -b fix/my-graded-task
+poetic compete apply <competition-id>
+```
+
+Multi-provider comparison after local validation:
+
+```bash
+poetic compete "Update the target file and add focused tests" \
+  --variant grok:conservative \
+  --variant codex:conservative
+```
+
+**Important**: Poetic 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. Poetic starts the requested `grok --prompt-file`
+execution without inspecting those auth paths first; the CLI's actual result is
+authoritative. Set `POETIC_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, Poetic will not execute it unless you explicitly opt in:
+
+```bash
+POETIC_ALLOW_CURL_BASH=1 poetic 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
+
+`poetic 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
+
+Poetic invokes Kiro in headless mode with:
+
+```bash
+kiro-cli chat --no-interactive --trust-all-tools "<prompt>"
+```
+
+Kiro models come from the static list configured in
+`.poetic/config/providers.yaml`; Poetic does not query the Kiro CLI for a model
+list. Kiro is experimental: default readiness and interactive setup omit it.
+Select it explicitly with `poetic provider setup --providers kiro`, show
+experimental readiness with `poetic provider list --include-experimental`, or
+include it in interactive setup with
+`poetic provider setup --include-experimental`.
+
+| Variable                  | Purpose                              | Default    |
+| ------------------------- | ------------------------------------ | ---------- |
+| `KIRO_API_KEY`            | Kiro API key for headless automation | (none)     |
+| `POETIC_KIRO_CLI_COMMAND` | Override Kiro CLI binary path        | `kiro-cli` |
+| `POETIC_SKIP_KIRO`        | Skip Kiro execution                  | unset      |
+
+#### Usage Patterns
+
+```bash
+poetic run "Review this change for correctness" --provider=kiro
+poetic compete "Add focused tests" --variant kiro:conservative: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 Poetic 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, Poetic will not execute it unless you explicitly opt in:
+
+```bash
+POETIC_ALLOW_CURL_BASH=1 poetic 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
+```
+
+`poetic 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
+
+Poetic invokes Google's Antigravity CLI in print mode with:
+
+```bash
+agy --print-timeout 45m0s --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.
+
+This provider is `supported_validated` as the successor to the sunsetting `gemini`
+provider. Validated 2026-07-25 against an authenticated `agy` 1.1.7: single-file
+and multi-file edits land through the Poetic worktree path, a failing task exits
+non-zero with no changes, and a judged competition produced a correct diff.
+
+`poetic 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. Poetic does not route Antigravity through OpenCode. Antigravity
+is model-fixed to the CLI default until a supported `agy` model-selection flag is
+verified.
+
+| Variable                         | Purpose                                                                                    | Default |
+| -------------------------------- | ------------------------------------------------------------------------------------------ | ------- |
+| `ANTIGRAVITY_API_KEY`            | Optional Antigravity API key for headless environments when supported by the installed CLI | (none)  |
+| `POETIC_ANTIGRAVITY_CLI_COMMAND` | Override Antigravity CLI binary path                                                       | `agy`   |
+| `POETIC_SKIP_ANTIGRAVITY`        | Skip Antigravity execution                                                                 | unset   |
+
+#### Usage Patterns
+
+```bash
+poetic run "Review this change for correctness" --provider=antigravity
+poetic compete "Add focused tests" --variant antigravity:conservative:local
+```
+
+Aliases accepted by Poetic include `agy`, `anti-gravity`, and `antigravity-cli`.
+
+---
+
+### Upstream Models via OpenCode
+
+**Status**: Available through the OpenCode provider, not as standalone Poetic 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
+
+poetic run "Analyze this code" --engine=opencode --model=<provider/model>
+poetic compete "Implement feature" --variant opencode:<provider/model>:conservative
+```
+
+Poetic passes the model selection to OpenCode. Provider endpoints, credentials, and model declarations belong in OpenCode configuration rather than Poetic configuration.
+
+---
+
+### OpenRouter (Pricing Source Only)
+
+**Status**: Not available as an execution provider
+
+**Note**: OpenRouter is used internally by Poetic 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
+POETIC_ALLOW_CURL_BASH=1 poetic 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. Poetic does not interpret an upstream provider's credentials or treat their presence as proof that execution will authenticate.
+
+#### Discovery (CLI-first)
+
+Poetic 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` and `opencode models <provider>` — advisory model IDs for `opencode run --model <id>`. A missing or empty inventory does not replace an execution attempt. Use `--refresh` only when you explicitly want to update the OpenCode cache.
+
+- **Health/diagnostics**: `poetic 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, Poetic still succeeds; models.dev enrichment is skipped and cached data is reused when present.
+- **Refresh**: Use `opencode models --refresh` only when explicitly requested; Poetic does not auto-refresh on every run.
+
+Optional enrichment: Poetic 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
+poetic 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.
+
+Poetic 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
+poetic run "Create a hello world test" --variant opencode:conservative
+
+# Test in competition
+poetic compete "Implement feature" \
+  --variant opencode:conservative \
+  --variant claude:conservative
+```
+
+#### 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.
+
+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.
+
+#### 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.
+
+Poetic 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 `POETIC_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 `POETIC_CHILD_ENV_ALLOWLIST`.
+
+---
+
+### Pi CLI
+
+**Status**: Supported validated native provider adapter. Validated 2026-07-26 against `pi` 0.82.1 with a cloud Anthropic backend, exercised through `poetic run` and `poetic compete` with incremental streaming. The local OpenAI-compatible (self-hosted) path is **not yet validated**.
+
+Pi is unlike Poetic'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 Poetic'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 Poetic 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"
+```
+
+Poetic 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
+
+`poetic 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
+
+Poetic 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 Poetic provider. Poetic 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.
+- **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. Poetic 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, Poetic 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 Poetic'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)  |
+| `POETIC_PI_CLI_COMMAND` | Override Pi CLI binary path                   | `pi`    |
+| `POETIC_SKIP_PI`        | Skip Pi execution                             | unset   |
+
+#### Usage Patterns
+
+```bash
+poetic run "Add a focused test for the parser" --provider pi
+poetic 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. Poetic 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. Poetic 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. Poetic 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. Poetic accrues at each assistant `message_end` and skips the duplicate `turn_end`.
+
+---
+
+## Authentication Semantics
+
+Poetic has four distinct authentication contexts. Understanding which applies prevents confusion between "setup readiness" and "runtime guarantees."
+
+### 1. Setup and Readiness Checks
+
+`poetic 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**. The base provider's `wrapOperation()` does not call `ensureAuth()`. 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: `checkClaudeCliAvailability()` verifies CLI installation only (`claude --version`), 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 (CLI sunsetting)                |
+| **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                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------- |
+| `POETIC_MOCK_PROVIDERS`          | Request mock mode (1=on, 0=off); outside tests also requires `POETIC_ALLOW_MOCK_PROVIDERS=1` or startup scrubs it | `0`                      |
+| `POETIC_ALLOW_MOCK_PROVIDERS`    | Explicit opt-in for mock mode outside test runners (`1` required with `POETIC_MOCK_PROVIDERS=1`) | `0`                            |
+| `CLAUDE_CONFIG_DIR`              | Claude config directory                                                                    | `~/.poetic/config/providers/claude` |
+| `POETIC_CLAUDE_BACKEND`          | Claude backend selector (`anthropic`\|`bedrock`\|`vertex`)                                 | `anthropic`                         |
+| `POETIC_BEDROCK_REGION_PREFIX`   | Bedrock inference profile prefix (`global`\|`us`\|`eu`\|`jp`\|`apac`)                      | `global`                            |
+| `CODEX_HOME`                     | Codex config directory                                                                     | `~/.codex`                          |
+| `POETIC_CODEX_AUTH_MODE`         | `api_key` passes API keys to Codex CLI; otherwise OAuth (default)                          | OAuth                               |
+| `POETIC_CODEX_BACKEND`           | Explicit Codex inference backend (`openai` or `bedrock`); unset follows Codex config       | (auto)                              |
+| `POETIC_TIMEOUT_CODEX_MS`        | Codex subprocess timeout in milliseconds                                                   | `2700000`                           |
+| `OPENAI_API_KEY`                 | OpenAI API key for Codex when `POETIC_CODEX_AUTH_MODE=api_key`                             | (none)                              |
+| `CODEX_API_KEY`                  | Legacy alias for API key auth (readiness + auth module)                                    | (none)                              |
+| `CODEX_TOKEN`                    | Legacy token auth                                                                          | (none)                              |
+| `POETIC_CODEX_ISOLATE_HOME`      | Isolate Codex session/history per worktree (`0` disables)                                  | `1`                                 |
+| `CURSOR_CONFIG_DIR`              | Cursor config directory                                                                    | `~/.poetic/cursor`                  |
+| `CURSOR_API_KEY`                 | Historical Cursor cloud agents key; does not enable Poetic `:cloud` execution              | (none)                              |
+| `POETIC_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                                                                    | `~/.poetic/gemini`                  |
+| `ANTHROPIC_API_KEY`              | Optional legacy Claude API key (CLI login recommended; Poetic 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)                              |
+| `POETIC_SKIP_OPENCODE`           | Skip OpenCode execution (dry-run mode, 1=on)                                               | `0`                                 |
+| `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)                              |
+| `POETIC_CURSOR_CLI_COMMAND`      | Path to Cursor Agent binary (preferred). Legacy `CURSOR_CLI_COMMAND` is still honored.     | `cursor-agent`                      |
+| `CURSOR_CLI_TIMEOUT`             | Timeout in milliseconds                                                                    | `30000`                             |
+| `POETIC_CURSOR_MODEL`            | Default Cursor model for local CLI                                                         | `auto`                              |
+| `POETIC_DEFAULT_PROVIDER`        | Global default provider without flags                                                      | (none)                              |
+| `POETIC_COPILOT_CLI_COMMAND`     | Path to GitHub Copilot CLI binary                                                          | `copilot`                           |
+| `POETIC_COPILOT_WORKFLOW`        | Default Copilot workflow (`suggest`, `chat`, `explain`)                                    | `suggest`                           |
+| `POETIC_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)                              |
+| `POETIC_KIRO_CLI_COMMAND`        | Path to Kiro CLI binary                                                                    | `kiro-cli`                          |
+| `POETIC_SKIP_KIRO`               | Skip Kiro execution                                                                        | unset                               |
+| `POETIC_PI_CLI_COMMAND`          | Path to Pi CLI binary                                                                      | `pi`                                |
+| `POETIC_SKIP_PI`                 | Skip Pi execution                                                                          | unset                               |
+| `ANTIGRAVITY_API_KEY`            | Optional Antigravity API key for headless environments when supported by the installed CLI | (none)                              |
+| `POETIC_ANTIGRAVITY_CLI_COMMAND` | Path to Google Antigravity CLI binary                                                      | `agy`                               |
+| `POETIC_SKIP_ANTIGRAVITY`        | Skip Antigravity execution                                                                 | unset                               |
+| `POETIC_DEBUG`                   | Enable debug logging for all providers                                                     | `0`                                 |
+| `POETIC_VERBOSE`                 | Enable verbose output for all providers                                                    | `0`                                 |
+| `POETIC_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**: Poetic 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=60000  # 60 seconds
+```
+
+**Problem**: `Invalid model: xyz`
+
+**Solution**: Use supported models (`auto`, `gpt-4o`, `gpt-4o-mini`, etc.) or set `POETIC_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 Poetic would otherwise filter that variable, name it in `POETIC_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
+poetic run "Analyze this code" --engine=opencode --model=<provider/model>
+```
+
+---
+
+## Provider Comparison
+
+| Feature                | Claude              | Codex                | Cursor           | Gemini          | Copilot                   | OpenCode              |
+| ---------------------- | ------------------- | -------------------- | ---------------- | --------------- | ------------------------- | --------------------- |
+| **Code Generation**    |                |                 |             |            |                      |                  |
+| **Reasoning**          |                |                 |             |            |                      |                  |
+| **Speed**              |                |                 |             |            |                      |                  |
+| **Context Window**     | 200K+ tokens        | 128K+ tokens         | Provider-routed  | 1M tokens       | Provider-routed           | Upstream-dependent    |
+| **Cost**               | $$$                 | $$$$                 | $$               | $               | $$                        | Upstream-dependent    |
+| **Setup Complexity**   | Medium              | High                 | High             | Low             | Low                       | Medium                |
+| **Enterprise Support** | No                  | Yes                  | Yes              | Yes             | No                        | Depends on upstream   |
+| **Dependencies**       | Single CLI          | Single CLI           | Single CLI       | Single CLI      | Single CLI                | Single CLI            |
+| **Best For**           | Complex refactoring | Enterprise workflows | Quick iterations | General purpose | Experimental agentic local edits | Multi-backend routing |
+
+**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
+   poetic run "Create a hello world test" --engine=claude
+   ```
+
+2. **Run Variant Competition**:
+
+   ```bash
+   poetic run "Implement feature X" --variants=3
+   ```
+
+3. **View Telemetry**:
+
+   ```bash
+   poetic telemetry leaderboard
+   poetic telemetry trends
+   ```
+
+4. **Review Results**:
+   - Check `.poetic/telemetry/db/` for SQLite databases
+   - Check `.poetic/telemetry/logs/` for JSONL logs
+
+---
+
+## Support
+
+- **Documentation**: `docs/CLI_REFERENCE.md`, `docs/TROUBLESHOOTING.md`, [ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/ARCHITECTURE.md)
+- **Issues**: https://github.com/ebrindley/Poetic/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
+- Provider API transport for local runs remains supported
+- Ordinary PR publication and judge-winner semantics unchanged