# AI Consultants Setup Guide

This guide walks you through installing and configuring AI Consultants for various AI coding agents.

---

## Supported Agents

AI Consultants follows the open [Agent Skills standard](https://agentskills.io), enabling cross-platform compatibility:

| Agent | Skills Directory | Status |
|-------|-----------------|--------|
| **Claude Code** | `~/.claude/skills/` | ✅ Native |
| **OpenAI Codex CLI** | `~/.codex/skills/` | ✅ Compatible |
| **Gemini CLI** | `~/.gemini/skills/` | ✅ Compatible |
| **GitHub Copilot** | Via SkillPort | ✅ Via AGENTS.md |
| **Cursor** | Via SkillPort | ✅ Via SkillPort |
| **Windsurf** | Via SkillPort | ✅ Via SkillPort |

---

## Claude Code Setup (Recommended)

AI Consultants is designed as a **Claude Code skill**. This is the fastest and easiest way to get started.

### Step 1: Install the Skill

```bash
# One-liner installation
curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash
```

This installs to `~/.claude/skills/ai-consultants/` and makes slash commands available in Claude Code.

### Step 2: Configure the Available Consultants

```bash
ai-consultants configure
```

This detects installed CLIs and available API keys for the complete 10-consultant
roster, selects CLI/API transport, and saves a private persistent configuration
under `~/.config/ai-consultants/`.

### Step 3: Verify Installation

```bash
./scripts/doctor.sh --fix
```

You should see at least 2 consultants marked as available.

### Step 4: Your First Consultation

```
/ai-consultants:consult "What's the best way to structure a REST API?"
```

That's it! You're ready to go.

---

## Claude Code Slash Commands

AI Consultants provides 2 slash commands:

| Command | Description |
|---------|-------------|
| `/ai-consultants:consult` | Main consultation - ask AI consultants a coding question |
| `/ai-consultants:help` | Show all commands and usage |

Configuration can be managed with `ai-consultants configure`, including presets,
strategies, features, personas, API keys, transports, models, timeouts, budgets,
and advanced optimization controls. Settings are saved to the XDG user config
directory, normally `~/.config/ai-consultants/.env`.

---

## OpenAI Codex CLI Setup

Codex CLI supports the Agent Skills standard and can use AI Consultants directly.

### Step 1: Install the Skill

```bash
# Option A: Clone directly
git clone https://github.com/matteoscurati/ai-consultants.git ~/.codex/skills/ai-consultants

# Option B: Symlink from existing installation
ln -s ~/.claude/skills/ai-consultants ~/.codex/skills/ai-consultants

# Option C: Symlink from any location
ln -s /path/to/ai-consultants ~/.codex/skills/ai-consultants
```

### Step 2: Verify Installation

```bash
~/.codex/skills/ai-consultants/scripts/doctor.sh --fix
```

### Step 3: Use in Codex

Once installed, Codex CLI will discover the skill and make slash commands available.

---

## Gemini CLI Setup

Gemini CLI also supports the Agent Skills standard.

### Installation

```bash
# Option A: Clone directly
git clone https://github.com/matteoscurati/ai-consultants.git ~/.gemini/skills/ai-consultants

# Option B: Symlink
ln -s ~/.claude/skills/ai-consultants ~/.gemini/skills/ai-consultants
```

### Verify

```bash
~/.gemini/skills/ai-consultants/scripts/doctor.sh
```

---

## SkillPort Setup (Multi-Agent)

[SkillPort](https://github.com/gotalab/skillport) is a universal skill manager that enables skill portability across agents like Cursor, Copilot, and Windsurf.

### Step 1: Install SkillPort

```bash
npm install -g skillport
```

### Step 2: Add AI Consultants

```bash
# From GitHub
skillport add github.com/matteoscurati/ai-consultants

# Or from local clone
git clone https://github.com/matteoscurati/ai-consultants.git
cd ai-consultants
./scripts/skillport-install.sh
```

### Step 3: Verify Installation

```bash
skillport list                    # Should show ai-consultants
./scripts/skillport-install.sh status  # Detailed status
```

### Step 4: Use in Your Agent

```bash
# Load skill on demand
skillport show ai-consultants
```

SkillPort also generates `AGENTS.md` for agents that use that format (Copilot and Cursor).

---

## Generic agentskills Setup

For any agent that supports the [agentskills.io](https://agentskills.io) standard:

### Installation

```bash
# Clone to the agent's skills directory
git clone https://github.com/matteoscurati/ai-consultants.git ~/.{agent}/skills/ai-consultants

# Replace {agent} with your agent name (claude, codex, gemini, etc.)
```

### Files Available

| File | Purpose |
|------|---------|
| `SKILL.md` | Primary skill specification (agentskills.io format) |
| `AGENTS.md` | Alternative discovery format (Copilot/Cursor) |
| `scripts/` | Executable scripts for consultations |

---

## Prerequisites

Before installing consultant CLIs, ensure you have:

### Required
- **jq** for JSON processing
- **curl** for API connectivity checks

### Recommended
- **Bash 4.0+** (macOS ships with 3.2 - install newer version)
- **timeout/gtimeout** for command timeouts (has POSIX fallback)
- **Node.js 18+** for npm-based CLIs
- **Python 3.8+** for pip-based CLIs

### Optional
- **bc** for cost calculations (usually pre-installed)

### Install Bash 4+ (macOS)

```bash
brew install bash
sudo bash -c 'echo /opt/homebrew/bin/bash >> /etc/shells'
```

### Install jq

```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Verify
jq --version
```

### Install timeout (macOS)

macOS doesn't include `timeout` by default. Install coreutils for `gtimeout`:

```bash
brew install coreutils

# Verify (gtimeout on macOS, timeout on Linux)
gtimeout --version
```

> **Note:** If timeout/gtimeout is not available, AI Consultants uses a POSIX fallback.

---

## Consultant CLIs

You need **at least 2 consultants** configured for AI Consultants to work.

### Antigravity CLI — `agy` (The Architect)

The Gemini consultant runs on the Antigravity CLI (`agy`), the successor to the
deprecated Gemini CLI (transitioned 2026-06-18).

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Authentication (OAuth — sign in once, credentials are cached)
agy            # launch without arguments to sign in

# Optional: list available models (after sign-in)
agy models
```

> API mode (`GEMINI_USE_API=true`) is an alternative that talks to the Google AI
> endpoint with `GEMINI_API_KEY` and `GEMINI_API_MODEL` instead of the agy CLI.

Get API key: [Google AI Studio](https://makersuite.google.com/app/apikey)

### Codex CLI (The Pragmatist)

```bash
npm install -g @openai/codex

# Authentication
export OPENAI_API_KEY="sk-your-key"
```

Get API key: [OpenAI Platform](https://platform.openai.com/api-keys)

### Mistral Vibe CLI (The Devil's Advocate)

```bash
pip install mistral-vibe

# Authentication
export MISTRAL_API_KEY="your-key"
```

Get API key: [Mistral Console](https://console.mistral.ai/api-keys/)

### Claude CLI (The Synthesizer) - v2.2

```bash
# Claude CLI is part of Claude Code
# See https://docs.anthropic.com/en/docs/claude-code for installation

# Verify installation
claude --version
```

### Qwen CLI (The Analyst) - v2.7

```bash
npm install -g @qwen-code/qwen-code@latest

# Verify installation
qwen --version

# Or use API mode
export QWEN3_USE_API=true
export QWEN3_API_KEY="your-dashscope-key"
```

Get API key: [Alibaba Cloud DashScope](https://dashscope.console.aliyun.com/)

**CLI/API Mode**: Qwen3 defaults to CLI mode (`QWEN3_USE_API=false`). Set to `true` to use the DashScope API.

### Kimi K3 via Kimi Code CLI (The Eastern Sage) - v2.21.1

```bash
curl -L code.kimi.com/install.sh | bash
```

Verify: `kimi --version`

AI Consultants pins K3 for every consultation, independently of the model in
your user-level Kimi configuration:

```bash
export KIMI_MODEL=kimi-code/k3
./scripts/query_kimi.sh "Review this API boundary"
```

`max_quality` selects `kimi-code/k3-256k`, whose availability is verified from
the Kimi provider inventory before the request.

### MiniMax (CLI via mmx) - v2.21

MiniMax runs via the `mmx` CLI by default (CLI-first, OAuth). Install and sign in:

```bash
npm install -g mmx-cli
mmx auth login          # OAuth (browser); or: mmx auth login --api-key <key>
```

API mode is opt-in: set `MINIMAX_USE_API=true` with `MINIMAX_API_KEY`.

Verify: `mmx --version`

---

## Self-Exclusion (v2.2)

When AI Consultants is invoked from a specific AI agent, that agent is automatically excluded from the consultant panel to prevent self-consultation.

### How It Works

| Invoking Agent | Excluded Consultant | Other Consultants |
|----------------|---------------------|-------------------|
| Claude Code | Claude | Gemini, Codex, Mistral, Qwen, etc. |
| Codex CLI | Codex | Claude, Gemini, Mistral, Qwen, etc. |
| Gemini CLI | Gemini | Claude, Codex, Mistral, Qwen, etc. |
| Cursor | None | All enabled consultants; Cursor is a host, not a panel member |
| Qwen CLI | Qwen3 | Claude, Gemini, Codex, Mistral, etc. |
| Kimi CLI | Kimi | All except Kimi |
| Bash (direct) | None | All enabled consultants (up to 10) |

### Automatic Detection

When using slash commands, `INVOKING_AGENT` is set automatically:
- Claude Code: `/ai-consultants:consult` sets `INVOKING_AGENT=claude`
- Codex CLI: `/ai-consultants:consult` sets `INVOKING_AGENT=codex`
- Gemini CLI: `/ai-consultants:consult` sets `INVOKING_AGENT=gemini`

The same identity excludes the host from synthesis. A Claude-hosted run must
not create `claude.json` or report `synthesis_provider=claude`; equivalent
invariants apply to Codex and Gemini. Natural-language skill invocations follow
the execution contract in `SKILL.md`.

### Manual Usage (Bash)

```bash
# Claude excluded from panel
INVOKING_AGENT=claude ./scripts/consult_all.sh "Question"

# Codex excluded from panel
INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"

# No exclusion (all enabled consultants)
./scripts/consult_all.sh "Question"
```

---

## CLI/API Mode Switching (v2.6+)

Seven consultants can switch between CLI mode (using local CLI tools) and API mode (direct API calls): **Gemini, Codex, Claude, Mistral, Qwen3, Grok, and MiniMax**. Grok is CLI-first and runs in an isolated, tool-free strict sandbox. It falls back automatically only when Grok Build is missing, cannot launch, or lacks usable authentication and a key is available; request failures after launch are surfaced without an API fallback.

Grok's normal OAuth mode is `GROK_OAUTH_MODE=shared`, which is safe for the
parallel panel: each call gets a private HOME/workspace/prompt/output, while a
runner-owned persistent `GROK_HOME` lets Grok Build coordinate token refresh
with its own lock. A short ai-consultants lock atomically seeds and publishes
valid generations; a concurrent external `grok login` wins the CAS and makes
the affected run fail without an API fallback. Use
`GROK_OAUTH_MODE=serialized` only as a diagnostic fallback. Forced API mode is
stateless and does not read or create the shared OAuth generation. A newly
created shared generation runs one locked inventory bootstrap to let Grok 1.0.4
initialize its home metadata; the lock is released before inference.

### Why Use API Mode?

- **No CLI installation required**: Use API keys without installing CLI tools
- **Consistent behavior**: API responses are more predictable
- **Easier deployment**: No need to manage CLI binaries

### Configuration

```bash
# Enable API mode for individual consultants
export GEMINI_USE_API=true
export GEMINI_API_KEY="your-google-ai-key"

export CODEX_USE_API=true
export OPENAI_API_KEY="sk-..."

export CLAUDE_USE_API=true
export ANTHROPIC_API_KEY="sk-ant-..."

export MISTRAL_USE_API=true
export MISTRAL_API_KEY="your-mistral-key"

export GROK_USE_API=true
export GROK_API_KEY="your-xai-key"

export QWEN3_USE_API=true   # Enable API mode for Qwen3
export QWEN3_API_KEY="your-dashscope-key"
```

### API Endpoints (Custom)

```bash
GEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models
CODEX_API_URL=https://api.openai.com/v1/chat/completions
CLAUDE_API_URL=https://api.anthropic.com/v1/messages
MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
QWEN3_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
```

### Mode Detection

Check current mode with doctor command:

```bash
./scripts/doctor.sh --verbose
# Shows:
#   ✓ Gemini: API mode (key: AIza...1234)
#   ○ Codex: CLI mode
#   ○ Claude: CLI mode
#   ○ Mistral: CLI mode
#   ✓ Qwen3: API mode (key: sk-...abcd)
```

---

## Configuration Presets (v2.2)

Presets let you quickly configure how many consultants to use.

### Available Presets

| Preset | Consultants | Use Case |
|--------|-------------|----------|
| `minimal` | 2 (Gemini + Codex) | Quick, cheap |
| `balanced` | 3 (+ Mistral) | Standard |
| `thorough` | 3 | Comprehensive |
| `max_quality` | All 10, maximum models and max provider effort | Critical decisions |
| `high-stakes` | Expanded panel | Critical decisions |
| `security` | Security-focused | Security reviews |
| `cost-capped` | Budget-friendly | Low cost |

### Set Default Preset

**Bash:**
```bash
# Add to .env
DEFAULT_PRESET=balanced
```

### Override Per Consultation

**Claude Code:** Specify in your question context.

**Bash:**
```bash
./scripts/consult_all.sh --preset high-stakes "Critical question"
```

---

## Synthesis Strategies (v2.2)

Strategies control how consultant responses are combined.

### Available Strategies

| Strategy | Description |
|----------|-------------|
| `coverage` | Union of every distinct point/risk across consultants, deduplicated (default) |
| `majority` | Produce one blended recommendation |
| `risk_averse` | Weight conservative responses higher |
| `security_first` | Prioritize security-focused insights |
| `cost_capped` | Prefer simpler, cheaper solutions |
| `compare_only` | No recommendation, just comparison |

### Set Default Strategy

**Bash:**
```bash
# Add to .env
DEFAULT_STRATEGY=risk_averse
```

### Strategy Recommendations

| Use Case | Recommended Strategy |
|----------|---------------------|
| General questions | `coverage` |
| Production deployments | `risk_averse` |
| Security audits | `security_first` |
| Budget constraints | `cost_capped` |
| Learning/exploration | `compare_only` |

---

## Ready-to-run configurations

These examples can be prefixed to one command or saved in
`~/.config/ai-consultants/.env`.

### Security gate with a required quorum

```bash
ENABLE_HEALTH_GATE=true \
QUORUM_MIN=3 \
QUORUM_ACTION=stop \
ai-consultants --preset security --strategy security_first \
  "Find authentication bypasses" src/auth.ts@PRIMARY
```

More scenarios—including CLI-only, hybrid API, hard-budget, and
large-context runs—are in [`docs/RECIPES.md`](RECIPES.md).

---

## Environment Configuration

### Automatic configuration (recommended)

```bash
# Detect the full roster and write ~/.config/ai-consultants/.env
ai-consultants configure

# Set any supported parameter non-interactively
ai-consultants configure \
  --set DEFAULT_PRESET=balanced \
  --set ENABLE_SYNTHESIS=true

# Guided or exhaustive review
ai-consultants configure --interactive
ai-consultants configure --advanced

# Parameter discovery and safe preview
ai-consultants configure --show-parameters
ai-consultants configure --dry-run
```

Existing custom values and credentials are preserved automatically;
availability-derived `ENABLE_*` flags are refreshed and can be pinned with
`--set`. Unless `--force` is supplied, the previous file is retained as a
timestamped mode-600 backup.
Automatically selected `*_USE_API` modes carry an `# ai-consultants:auto`
marker, so rerunning the command can react to installed or removed CLIs and new
credentials. Unmarked modes, environment values, and `--set` remain user pins.
The configurator uses the complete [`.env.example`](../.env.example) contract,
so advanced parameters are also accepted through repeatable `--set KEY=VALUE`
arguments.

Do not place API keys in `--set` arguments: command lines can be retained in
shell history or observed by other local processes. Use `--interactive`,
`--advanced`, or exported environment variables for credentials.

### Using .env file

```bash
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ai-consultants"
# For a new configuration only; keep existing credentials/settings if present.
cp -n .env.example "${XDG_CONFIG_HOME:-$HOME/.config}/ai-consultants/.env"
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/ai-consultants/.env"
```

Edit that user configuration `.env`. A different existing private directory must
be selected explicitly with `AI_CONSULTANTS_CONFIG_DIR`; project `.env` files
are not discovered automatically:


```bash
# Enable/disable consultants (10 available)
ENABLE_GEMINI=true
ENABLE_CODEX=true
ENABLE_CLAUDE=false    # Auto-excluded when invoked from Claude Code
ENABLE_MISTRAL=false
ENABLE_QWEN3=false     # v2.7: The Analyst (CLI/API)
ENABLE_GROK=true       # Grok Build CLI; API fallback when unavailable
ENABLE_GLM=false
ENABLE_DEEPSEEK=false
ENABLE_KIMI=true
ENABLE_MINIMAX=true
MINIMAX_API_KEY=your-key

# Self-exclusion (v2.2)
INVOKING_AGENT=unknown  # Set automatically by slash commands

# API Keys
GEMINI_API_KEY=your-key
OPENAI_API_KEY=sk-your-key
MISTRAL_API_KEY=your-key
ANTHROPIC_API_KEY=sk-ant-your-key
QWEN3_API_KEY=your-dashscope-key
GROK_API_KEY=your-xai-key  # optional fallback; Grok Build normally uses login

# CLI/API Mode Switching (v2.6+)
# GEMINI_USE_API auto-resolves when unset (v2.15.1): API if GEMINI_API_KEY is
# set, else the agy CLI. Set it explicitly only to force a specific mode.
CODEX_USE_API=false
CLAUDE_USE_API=false
MISTRAL_USE_API=false
QWEN3_USE_API=false    # Default: CLI mode
MINIMAX_USE_API=false  # Default: mmx CLI mode

# Defaults (v2.8)
DEFAULT_PRESET=balanced
DEFAULT_STRATEGY=coverage

# Features
ENABLE_SYNTHESIS=true
ENABLE_HEALTH_GATE=false
QUORUM_MIN=2
QUORUM_ACTION=warn

# Budget (v2.4)
ENABLE_BUDGET_LIMIT=false
MAX_SESSION_COST=1.00
BUDGET_ACTION=warn
```

### Minimum Requirements

**At least 2 consultants must be enabled.**

Example configurations:

**OpenAI + Google:**
```bash
ENABLE_GEMINI=true
ENABLE_CODEX=true
ENABLE_MISTRAL=false
```

**OpenAI + Anthropic:**
```bash
ENABLE_CODEX=true
ENABLE_CLAUDE=true
ENABLE_GEMINI=false
ENABLE_MISTRAL=false
```

---

## Verification

### Doctor Command

```bash
./scripts/doctor.sh
```

Checks:
- CLI tools installed
- API keys configured
- Configuration valid

**Auto-fix issues:**
```bash
./scripts/doctor.sh --fix
```

### Configuration

Auto-detect the available CLI and API transports:

```bash
./bin/ai-consultants configure
```

Use `--interactive` for a guided review, `--advanced` for every supported
parameter, or `--dry-run` to preview the generated configuration without
writing it. The deprecated `setup_wizard.sh` and `preflight_check.sh` entry
points remain compatibility forwarders but are not the maintained interface.

---

## Troubleshooting

### "Command not found" errors

```bash
# Check npm global path
npm list -g --depth=0

# Check pip packages
pip list | grep mistral
```

### Authentication failures

**Gemini (Antigravity CLI):**
```bash
agy            # launch with no arguments to (re-)sign in via browser OAuth
agy models     # verify auth: lists available models when signed in
```
(Or skip the CLI entirely: set `GEMINI_API_KEY` to run Gemini over the API.)

**Codex:**
```bash
echo $OPENAI_API_KEY  # Verify set
```

### Timeout errors

Increase timeout in `.env`:
```bash
GEMINI_TIMEOUT=300
CODEX_TIMEOUT=300
```

### "Less than 2 consultants" error

Either:
1. Install another CLI
2. Configure an API-backed consultant
3. Run `./scripts/doctor.sh --fix`

### Claude Code Issues

| Issue | Solution |
|-------|----------|
| "Unknown skill" | Run install script again |
| Commands not showing | Restart Claude Code |
| "Exit code 1" | Run `./scripts/doctor.sh` |
| Configuration not saving | Check file permissions on `~/.claude/skills/` |

---

## Platform-Specific Notes

### macOS

Install coreutils for better timeout handling:
```bash
brew install coreutils bash
```

### Windows

Use WSL (Windows Subsystem for Linux):
```bash
wsl --install
# Then follow Linux instructions
```

### Linux

No special requirements. Ensure `timeout` is available.

---

## Next Steps

After setup:

**Claude Code:**
```
/ai-consultants:consult "How do I optimize a SQL query?"
```

**Bash:**
```bash
# Test your configuration
output_dir=$(./scripts/consult_all.sh --preset minimal "How do I optimize a SQL query?")

# View the report
less "$output_dir/report.md"
```

See [README.md](../README.md) for usage examples and full documentation.

For a configuration outside the standard user config directory, set
`AI_CONSULTANTS_CONFIG_DIR=/absolute/private/config-directory` explicitly.
The loader does not discover project `.env` files. Keep credentials in your
existing private configuration; do not copy them into this repository.

Claude CLI uses `stream-json --verbose`. Only response-bearing assistant
messages attest the content model; terminal `modelUsage` records billing
participants separately. A missing or conflicting content model remains
`requested-only` and cannot pass a model-promotion gate. Successful terminal
completion is required even when partial response text or billing is available.

Codex defaults to `gpt-6-astra`; premium and maximum select Astra, standard
selects `gpt-5.6-terra`, economy selects `gpt-5.6-luna`. Sol remains an explicit
`CODEX_MODEL=gpt-5.6-sol` override. Configure migrates exact unpinned persisted
`gpt-5.5` and `gpt-5.6-sol` values to Astra and records `migrated-from` provenance.
Use `# ai-consultants:pin`, an environment override or `--set` to keep a model.

Astra uses `high` effort when no effort is configured. Explicit `low`, `medium`,
`high`, `xhigh`, and `max` prevail; `none`/`minimal` fail before dispatch.
The default completion budget is 16384 tokens, including reasoning; override
`CODEX_API_MAX_TOKENS` explicitly as needed. The text-only Chat Completions
request uses `max_completion_tokens` and `reasoning_effort`, without tools.
See the [official migration guide](https://developers.openai.com/api/docs/guides/latest-model).
CLI JSON events supply token telemetry; the final message file supplies content.
A CLI `-m` selection remains `requested-only`, not provider attestation.

[Astra Standard pricing](https://developers.openai.com/api/docs/models/gpt-6-astra)
is $10/M input and $50/M output. More than 272K input tokens doubles input
and multiplies output by 1.5 for the whole request. Reported cost is an estimate
unless a provider cost is supplied: cache writes, cached-input discounts and
service processing rates can change the invoice.

Grok CLI and doctor passively inspect the container-runtime socket deny paths,
including Docker Desktop locations. Symlink endpoints (including dangling links)
block CLI dispatch because the sandbox cannot safely resolve those deny rules.
Absent paths and ordinary socket files pass this check. Nothing is removed and
Docker configuration is never changed. Runtime `sandbox_profile_refused` and
`sandbox_not_applied` diagnostics fail even with exit zero; they cannot trigger
retry or API fallback. OAuth synchronization and per-run isolation remain active.


Grok compatibility includes a provider-free parser probe of the complete advisory
argument list. Hidden flags such as `--no-memory` are still required in the
actual request even when omitted from public help. Unsupported mandatory flags
block dispatch; the optional `--no-auto-update` guard is used when its parser
probe succeeds, including on CLIs that hide it from help.

### DeepSeek V4.1 Flash

DeepSeek uses the HTTP API with `DEEPSEEK_MODEL=deepseek-flash` in every tier.
This is the official API alias for DeepSeek-V4.1-Flash as of 2026-09-10, not a
version identity inferred from the requested name. Provider-reported model
metadata is retained unchanged. `max_quality` continues to request `max` effort;
other tiers leave effort to the provider unless explicitly configured. The
provider defaults to thinking mode at high effort. Existing text-only Chat
Completions requests and the 16,384-token completion budget remain compatible.

`configure` migrates exact unpinned `deepseek-v4-pro` and `deepseek-v4-flash`
values; `# ai-consultants:pin`, environment overrides and `--set` preserve explicit
choices. Old Flash aliases are still accepted but route to V4.1 Flash upstream.
An explicit pin preserves the requested ID, not a guarantee against provider
routing changes. Peak cache-miss costs are estimates, excluding cache/off-peak
discounts. An authorized one-attempt API smoke on 2026-09-10 passed with a structured
response and provider-reported `deepseek-flash`; no version identity was invented
from the alias. No CLI transport is introduced.

Sources: [models/pricing](https://api-docs.deepseek.com/quick_start/pricing/) and
[thinking mode](https://api-docs.deepseek.com/guides/thinking_mode/).