ai-consultants 2.21.1 → 2.22.0

package/.env.example

@@ -0,0 +1,432 @@
+# =============================================================================
+# AI Consultants - Environment Variables
+# =============================================================================
+# Copy this file to .env and customize as needed.
+# All variables have sensible defaults - only override what you need.
+#
+# IMPORTANT: At least 2 consultants must be enabled for the system to work.
+#
+# Export variables before running, or source this file:
+#   source .env && ./scripts/consult_all.sh "Your question"
+#
+# For detailed setup instructions, see: docs/SETUP.md
+
+# =============================================================================
+# API KEYS & AUTHENTICATION
+# =============================================================================
+# Each CLI tool requires its own authentication. Set the appropriate API keys
+# or use the CLI's built-in auth flow.
+
+# Google Gemini API key (only needed for API mode; the agy CLI uses OAuth)
+# Get yours at: https://makersuite.google.com/app/apikey
+# CLI mode uses the Antigravity CLI (agy); sign in by running `agy` once.
+# GEMINI_API_KEY=your-google-api-key
+
+# OpenAI API Key (required for Codex)
+# Get yours at: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=sk-your-openai-api-key
+
+# Mistral API Key
+# Get yours at: https://console.mistral.ai/api-keys/
+# MISTRAL_API_KEY=your-mistral-api-key
+
+# Anthropic API Key (for Claude API mode or synthesis)
+# Get yours at: https://console.anthropic.com/settings/keys
+# ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
+
+
+# =============================================================================
+# API-BASED CONSULTANT KEYS
+# =============================================================================
+# These are required for the API-based consultants (Qwen3, GLM, Grok, DeepSeek)
+
+# Qwen3 (Alibaba DashScope) - The Analyst
+# Get yours at: https://dashscope.console.aliyun.com/
+# QWEN3_API_KEY=your_dashscope_api_key
+
+# GLM (Zhipu AI) - The Methodologist
+# Get yours at: https://open.z.ai/
+# GLM_API_KEY=your_zhipu_api_key
+
+# Grok (xAI) - The Provocateur
+# Get yours at: https://console.x.ai/
+# GROK_API_KEY=your_xai_api_key
+
+# DeepSeek - The Code Specialist
+# Get yours at: https://platform.deepseek.com/
+# DEEPSEEK_API_KEY=your_deepseek_api_key
+
+# MiniMax - The Pragmatic Optimizer (v2.10)
+# Get yours at: https://platform.minimax.io/user-center/basic-information/interface-key
+# MINIMAX_API_KEY=your_minimax_api_key
+
+# =============================================================================
+# ENABLED CONSULTANTS
+# =============================================================================
+# Set to "false" to disable a consultant you haven't configured.
+# MINIMUM 2 consultants must be enabled for comparison/voting to work.
+
+# CLI-based consultants (default: enabled)
+ENABLE_GEMINI=true
+ENABLE_CODEX=true
+ENABLE_MISTRAL=true
+ENABLE_CURSOR=true
+ENABLE_KIMI=true
+ENABLE_QWEN3=true
+ENABLE_MINIMAX=true
+ENABLE_CLAUDE=true
+
+# API-only consultants (default: disabled - require API keys)
+ENABLE_GLM=false
+ENABLE_GROK=false
+ENABLE_DEEPSEEK=false
+
+# =============================================================================
+# CLI/API MODE SWITCHING (v2.6+)
+# =============================================================================
+# 6 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, MiniMax
+# When API mode is enabled, CLI mode is automatically disabled.
+
+# GEMINI_USE_API is auto-resolved when left UNSET (v2.15.1): API mode if
+# GEMINI_API_KEY is present (no CLI install / OAuth needed — best for npm/npx),
+# else the agy CLI. Leave it commented to keep auto-resolution; uncomment only
+# to force a specific mode (an explicit value disables auto-detection).
+# GEMINI_USE_API=false       # Force Google AI API (true) or agy CLI (false)
+# Leave the following commented to keep CLI-first auto-resolution (CLI wins
+# when installed; API is the fallback for a key with no CLI). Uncomment only
+# to force a specific transport for that agent.
+# CODEX_USE_API=false          # Use OpenAI API instead of codex CLI
+# CLAUDE_USE_API=false         # Use Anthropic API instead of claude CLI
+# MISTRAL_USE_API=false        # Use Mistral API instead of vibe CLI
+# QWEN3_USE_API=false          # Use qwen CLI (default) or DashScope API (v2.7)
+# MINIMAX_USE_API=false      # Unset = API for legacy key users, otherwise mmx CLI
+
+# API endpoints (override if using custom endpoints)
+# 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/api/v1/services/aigc/text-generation/generation
+
+# =============================================================================
+# MODEL CONFIGURATION (June 2026 premium defaults)
+# =============================================================================
+
+# Gemini - The Architect (CLI mode via Antigravity CLI: agy)
+GEMINI_MODEL="Gemini 3.1 Pro (High)"
+GEMINI_TIMEOUT=180
+GEMINI_CMD=agy
+# API-mode model ID (only used when GEMINI_USE_API=true)
+GEMINI_API_MODEL=gemini-3.1-pro-preview
+
+# Codex - The Pragmatist
+CODEX_MODEL=gpt-5.5
+CODEX_TIMEOUT=180
+CODEX_CMD=codex
+
+# Mistral Vibe - The Devil's Advocate
+MISTRAL_MODEL=mistral-large-3
+MISTRAL_TIMEOUT=180
+MISTRAL_CMD=vibe
+
+# Cursor - The Integrator
+CURSOR_MODEL=composer-2.5
+CURSOR_TIMEOUT=180
+CURSOR_CMD=agent
+
+# Kimi - The Eastern Sage (K3 via Kimi Code CLI)
+KIMI_MODEL=kimi-code/k3
+KIMI_TIMEOUT=180
+KIMI_CMD=kimi
+
+# Claude - The Synthesizer
+CLAUDE_MODEL=claude-opus-4-8
+CLAUDE_TIMEOUT=240
+CLAUDE_CMD=claude
+
+# Qwen3 - The Analyst (CLI/API switchable v2.7)
+QWEN3_MODEL=qwen3.7-max
+QWEN3_TIMEOUT=180
+QWEN3_CMD=qwen
+
+# =============================================================================
+# API-BASED CONSULTANT CONFIGURATION
+# =============================================================================
+
+# GLM - The Methodologist
+GLM_MODEL=glm-5.2
+GLM_TIMEOUT=180
+GLM_API_URL=https://api.z.ai/api/coding/paas/v4/chat/completions
+
+# Grok - The Provocateur
+GROK_MODEL=grok-4.5
+GROK_TIMEOUT=180
+GROK_API_URL=https://api.x.ai/v1/chat/completions
+
+# DeepSeek - The Code Specialist
+DEEPSEEK_MODEL=deepseek-v4-pro
+DEEPSEEK_TIMEOUT=180
+DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
+
+# MiniMax - The Pragmatic Optimizer (CLI via mmx by default, v2.21; API opt-in)
+MINIMAX_CMD=mmx
+MINIMAX_MODEL=MiniMax-M2.7
+MINIMAX_TIMEOUT=180
+MINIMAX_API_URL=https://api.minimax.io/v1/chat/completions
+
+# Response formats for API-based consultants
+QWEN3_FORMAT=qwen
+GLM_FORMAT=openai
+GROK_FORMAT=openai
+DEEPSEEK_FORMAT=openai
+MINIMAX_FORMAT=openai
+
+# =============================================================================
+# FEATURES v2.8
+# =============================================================================
+
+# Defaults used when --preset / --strategy are omitted
+DEFAULT_PRESET=balanced
+DEFAULT_STRATEGY=majority
+
+# The invoking integration normally sets this per run for self-exclusion.
+INVOKING_AGENT=unknown
+
+# Personas: specialized roles for each consultant
+ENABLE_PERSONA=true
+
+# Auto-synthesis: automatic synthesis of all responses
+ENABLE_SYNTHESIS=true
+SYNTHESIS_CMD=claude
+# Optional synthesis-specific model. Empty delegates model selection to the CLI.
+SYNTHESIS_MODEL=
+SYNTHESIS_EXTRACT_FIELDS=true
+SYNTH_MAX=10
+
+# Multi-Agent Debate (MAD): cross-critique rounds
+ENABLE_DEBATE=false
+DEBATE_ROUNDS=1              # 1 = no debate, 2-3 = with cross-critique
+
+# Self-Reflection (experimental): generate-critique-refine loop
+ENABLE_REFLECTION=false
+REFLECTION_CYCLES=1
+
+# Peer Review: anonymous evaluation
+ENABLE_PEER_REVIEW=false
+PEER_REVIEW_MIN_RESPONSES=3
+REVIEWS_PER_CONSULTANT=3
+
+# Panic Mode: auto-rigor when uncertainty detected
+ENABLE_PANIC_MODE=auto
+PANIC_CONFIDENCE_THRESHOLD=5
+PANIC_EXTRA_DEBATE_ROUNDS=1
+PANIC_KEYWORDS="uncertain|maybe|not sure|possibly|unclear|depends|hard to say|difficult to determine"
+
+# Dynamic orchestration: choose how the panel deliberates
+# auto | fixed | quick | converge | adversarial | tournament | exhaustive
+ORCHESTRATION_MODE=auto
+CONVERGENCE_MAX_ROUNDS=4
+CONVERGENCE_TARGET_CONSENSUS=75
+CONVERGENCE_STALL_EPSILON=5
+ENABLE_ADVERSARIAL_VERIFY=true
+
+# Debate optimization: avoid extra rounds when the panel already agrees
+ENABLE_DEBATE_OPTIMIZATION=true
+DEBATE_CONFIDENCE_SPREAD_THRESHOLD=2
+DEBATE_USE_SUMMARIES=true
+
+# Health gate and quorum: validate the live panel before spending on a full run
+ENABLE_HEALTH_GATE=false       # Adds one small ping per selected consultant
+HEALTH_GATE_TIMEOUT=30
+QUORUM_MIN=2
+QUORUM_ACTION=warn             # warn or stop
+
+# =============================================================================
+# SEMANTIC CACHING (v2.3)
+# =============================================================================
+
+ENABLE_SEMANTIC_CACHE=true
+CACHE_TTL_HOURS=24
+# CACHE_DIR=/custom/cache/path
+
+# API retry and rate-limit controls
+API_BASE_BACKOFF=2
+API_MAX_BACKOFF=60
+API_RATE_LIMIT=30
+
+# Optional response limits by question category
+ENABLE_RESPONSE_LIMITS=false
+MAX_RESPONSE_TOKENS_BY_CATEGORY=QUICK_SYNTAX:200,CODE_REVIEW:800,BUG_DEBUG:800,ARCHITECTURE:1000,SECURITY:1000,DATABASE:600,GENERAL:500
+
+# =============================================================================
+# BUDGET ENFORCEMENT (v2.4, opt-in)
+# =============================================================================
+
+ENABLE_BUDGET_LIMIT=false
+BUDGET_ACTION=warn           # warn or stop
+MAX_SESSION_COST=1.00
+
+# =============================================================================
+# SMART ROUTING
+# =============================================================================
+
+# Question classification (required for smart routing)
+ENABLE_CLASSIFICATION=true
+CLASSIFICATION_MODE=pattern  # pattern (fast) or llm (accurate)
+
+# Smart routing: select consultants based on question category
+ENABLE_SMART_ROUTING=false
+MIN_AFFINITY=7               # Minimum affinity score (1-10) to include
+
+# Cost-aware routing (v2.3)
+ENABLE_COST_AWARE_ROUTING=false
+USE_ECONOMIC_MODELS_FOR_SIMPLE=true
+COMPLEXITY_THRESHOLD_SIMPLE=3
+COMPLEXITY_THRESHOLD_MEDIUM=6
+FALLBACK_CONFIDENCE_THRESHOLD=7
+
+# Capability-aware routing & voting (v2.20, opt-in): weight votes and rank the
+# panel by each consultant's capability on the quality axis a question stresses
+# (intelligence or taste, per references/affinity.json 'category_axis'). cost is
+# a composition/budget axis only, never a vote weight.
+ENABLE_CAPABILITY_WEIGHTING=false   # capability-weighted voting
+ENABLE_CAPABILITY_ROUTING=false     # capability-aware panel composition
+CAPABILITY_WEIGHT_STRENGTH=10       # higher = gentler nudge: weight = conf*(S+cap)/S
+CAPABILITY_DEFAULT=5                # fallback capability for a missing consultant/axis
+
+# Stance-based semantic consensus (v2.21, opt-in): the panel picks from a shared
+# enumerated stance set so agreement is scored by exact match instead of lexical
+# similarity. Adds ~1 LLM call per run; degrades to the lexical cluster on any
+# failure, so it is always safe to enable.
+ENABLE_STANCE_CONSENSUS=false
+STANCE_MAX_OPTIONS=5                # max stance options generated per question
+STANCE_TIMEOUT=60                  # seconds for the stance-generation call (guards a hang)
+
+# =============================================================================
+# COST MANAGEMENT
+# =============================================================================
+
+ENABLE_COST_TRACKING=true
+WARN_AT_COST=0.50            # Warning threshold (USD)
+ENABLE_RELIABILITY_TRACKING=true
+# COST_TRACKING_FILE=/custom/data/costs.json
+# RELIABILITY_FILE=/custom/data/reliability.json
+# COST_RATES_FILE=/custom/config/cost_rates.json
+
+# =============================================================================
+# SESSION MANAGEMENT
+# =============================================================================
+
+SESSION_CLEANUP_DAYS=7       # Auto-cleanup sessions older than N days
+# SESSION_DIR=/custom/state/sessions
+
+# =============================================================================
+# INTERACTIVE MODE
+# =============================================================================
+
+ENABLE_PROGRESS_BARS=true    # Show progress bars during consultation
+ENABLE_EARLY_TERMINATION=true # Allow Ctrl+C to stop with partial results
+
+# =============================================================================
+# PRE-FLIGHT CHECKS
+# =============================================================================
+
+ENABLE_PREFLIGHT=false       # Run health check before each consultation
+PREFLIGHT_QUICK=true         # Quick mode: CLI check only, skip API test
+
+# =============================================================================
+# RETRY & TIMEOUT
+# =============================================================================
+
+MAX_RETRIES=2                # Max retry attempts on failure
+RETRY_DELAY_SECONDS=5        # Pause between retries
+LAUNCH_STAGGER_MAX_SECONDS=2
+
+# Output directory base
+# DEFAULT_OUTPUT_DIR_BASE=/custom/cache/consultations
+
+# Live doctor probe timeout
+DOCTOR_LIVE_TIMEOUT=45
+
+# =============================================================================
+# CONTEXT HANDOFF & TOKEN OPTIMIZATION
+# =============================================================================
+
+TOKEN_OPTIMIZATION_MODE=ast
+MAX_CONTEXT_FILE_BYTES=8000
+ENABLE_AST_EXTRACTION=true
+ENABLE_SYMBOL_COMPRESSION=false
+ENABLE_SEMANTIC_CHUNKING=true
+CHUNK_MAX_TOKENS=500
+CHUNK_OVERLAP_LINES=5
+CHUNK_PRIORITY_KEYWORDS=main,export,public,api,handler,controller
+INCLUDE_DOCSTRINGS=true
+INCLUDE_CRITICAL_COMMENTS=true
+MAX_BODY_SUMMARY_LINES=3
+MIN_IDENTIFIER_LENGTH=8
+PRESERVE_EXPORTS=true
+USE_COMPACT_PROMPTS=true
+FORCE_PROJECT_TREE=false
+ENABLE_SELECTIVE_CONTEXT=false
+MAX_FILES_PER_CONSULTANT=5
+
+# =============================================================================
+# REPORTING & STORAGE
+# =============================================================================
+
+ENABLE_COMPACT_REPORT=true
+REPORT_MAX_JSON_LINES=50
+# RATE_LIMIT_DIR=/custom/cache/ratelimit
+# CHUNK_TEMP_DIR=/custom/cache/chunks
+
+# =============================================================================
+# CUSTOM ROUTING & PERSONAS
+# =============================================================================
+
+# AFFINITY_FILE=/path/to/affinity.json
+
+# Each consultant supports _PERSONA_ID (1-21), _PERSONA (custom prompt), and
+# _PERSONA_NAME (custom display name). Uncomment only the overrides you need.
+# GEMINI_PERSONA_ID=1
+# CODEX_PERSONA_ID=2
+# MISTRAL_PERSONA_ID=3
+# CURSOR_PERSONA_ID=5
+# KIMI_PERSONA_ID=20
+# CLAUDE_PERSONA_ID=18
+# QWEN3_PERSONA_ID=6
+# GLM_PERSONA_ID=7
+# GROK_PERSONA_ID=8
+# DEEPSEEK_PERSONA_ID=17
+# MINIMAX_PERSONA_ID=21
+# GEMINI_PERSONA=Custom persona instructions
+# GEMINI_PERSONA_NAME=Custom persona name
+# CODEX_PERSONA=Custom persona instructions
+# CODEX_PERSONA_NAME=Custom persona name
+# MISTRAL_PERSONA=Custom persona instructions
+# MISTRAL_PERSONA_NAME=Custom persona name
+# CURSOR_PERSONA=Custom persona instructions
+# CURSOR_PERSONA_NAME=Custom persona name
+# KIMI_PERSONA=Custom persona instructions
+# KIMI_PERSONA_NAME=Custom persona name
+# CLAUDE_PERSONA=Custom persona instructions
+# CLAUDE_PERSONA_NAME=Custom persona name
+# QWEN3_PERSONA=Custom persona instructions
+# QWEN3_PERSONA_NAME=Custom persona name
+# GLM_PERSONA=Custom persona instructions
+# GLM_PERSONA_NAME=Custom persona name
+# GROK_PERSONA=Custom persona instructions
+# GROK_PERSONA_NAME=Custom persona name
+# DEEPSEEK_PERSONA=Custom persona instructions
+# DEEPSEEK_PERSONA_NAME=Custom persona name
+# MINIMAX_PERSONA=Custom persona instructions
+# MINIMAX_PERSONA_NAME=Custom persona name
+
+# Calibration judge commands
+TASTE_JUDGE_CMD=
+JUDGE_CLI=claude
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+
+LOG_LEVEL=INFO               # DEBUG, INFO, WARN, ERROR

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model AI deliberation system that queries up to 11 AI
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel to prevent self-consultation. Claude Code won't query Claude, Codex CLI won't query Codex, etc.
 
-**Version**: 2.21.1
+**Version**: 2.22.0
 
 ## Distribution
 
@@ -802,6 +802,18 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v2.22.0
+- Added the public `ai-consultants configure` / `config` subcommand. Automatic mode detects every current consultant, uses CLI-first transport selection with API fallback when credentials are available, persists to the XDG user config directory, preserves custom values and secrets while refreshing availability-derived `ENABLE_*` flags, backs up rewrites, and keeps files at mode 600.
+- Replaced the stale 1,092-line v2.0 configurator with a compact implementation whose accepted parameter surface is derived from `.env.example`. `--set KEY=VALUE` supports repeatable automation and participates in detection, `--interactive` reviews credentials/transports/panel selection, `--advanced` reviews every parameter, `--show-parameters` exposes the contract, and side-effect-free `--dry-run` redacts secrets.
+- Added `test_configure.sh` (60 assertions) covering public routing, runtime-wide template parity, full-roster detection, API fallback, override precedence/empty values, transport provenance, advanced defaults, export preservation, dry-run isolation/redaction, symlink refusal, backups/permissions, and rejection of removed settings. The npm-pack smoke path now includes `.env.example` and exercises both `init` and `configure` from the installed tarball.
+- **Three interactive/provenance bugs fixed before the subcommand ever shipped** (found in review; none reached a tagged release):
+  - **`--interactive` aborted on the first Enter.** `prompt_value` ended both branches with `[[ -n "$reply" ]] && set_value …`. An empty reply — the documented "press Enter to keep" path — made that `&&` list return 1, and since it was the function's last command, `prompt_value` returned 1; under `set -e` the plain call site in the `for` loop killed the script (exit 1, nothing written). Now an explicit `if` block, so an empty reply returns 0.
+  - **`--advanced` silently wrote garbage.** `done < <(list_parameters)` redirects fd 0 for the *whole loop body*, so `prompt_value`'s nested `read -r -p` consumed the parameter list instead of the terminal — each prompt took the *next parameter's name* as the user's answer (observed: `AFFINITY_FILE` ← `ANTHROPIC_API_KEY`). Fixed with the standard fd-separation idiom (`read … <&3` / `done 3< <(…)`).
+  - **`init` then `configure` disabled four consultants.** `init` copies `.env.example` verbatim, and the template carried uncommented `CODEX_USE_API=false` / `CLAUDE_USE_API` / `MISTRAL_USE_API` / `QWEN3_USE_API`. `has_explicit_value` reads any unmarked value as a user pin, so `configure_switchable` took the explicit-`false` branch: with no CLI and a valid API key the consultant was disabled outright instead of resolving to API. Fixed in the *template*, not the provenance logic — the four switches are now commented out, matching the convention `GEMINI_USE_API`/`MINIMAX_USE_API` already established (commented = auto-resolve, uncommented = force). CLI-first is unaffected: an installed CLI still wins over a present key.
+- **Backup names are now collision-proof.** `${OUTPUT_FILE}.backup.$(date +%Y%m%d_%H%M%S)` is only second-precise, so two runs inside one second resolved to the same path and the second `cp` clobbered the first backup — losing the user's *original* config while keeping a machine-generated one. Now `mktemp "…backup.<ts>.XXXXXX"`, which claims the name atomically (also making concurrent runs safe). Note the collision is unreachable from a sequential test — a real run takes ~1-8s, longer than the granularity — so the regression test stubs `date` on `PATH` to freeze the clock; the backup line is the only `date` caller in this path.
+- **`test_configure.sh` made hermetic against an ambient config environment — `scripts/release.sh` could not run its own gate.** `config.sh` auto-resolves `GEMINI_USE_API`/`MINIMAX_USE_API` and **exports** them; `configure.sh::has_explicit_value` treats any ambient value as a deliberate user pin. `release.sh` sources `lib/common.sh` (→ `config.sh`) *before* running `npm test`, so the gate inherited pinned transports: Tests 4 and 11 failed under `release.sh` while passing from a clean shell — a "flaky" result that was in fact deterministic per-environment. The suite now `unset`s the whole switchable `*_USE_API` set at the top (one place, covering all 10 configure invocations; only the two auto-resolved ones actually leak today, but the set is cleared so a future auto-resolution — as MiniMax gained in v2.21 — cannot silently reopen it). Same class as the v2.21.0 `test_user_config.sh` fix. Verified green both from a clean shell and under `source lib/common.sh; npm test`. Latent since `test_configure.sh` was introduced; it never affected the shipped runtime, only the release gate.
+- Deprecated `setup_wizard.sh` to a compatibility forwarder. Corrected `GOOGLE_API_KEY` to `GEMINI_API_KEY`, removed legacy `/tmp` overrides from the starter template, completed advanced settings/persona coverage, and fixed safe parsing of unquoted `.env` inline comments.
+
 ### v2.21.1
 - **Kimi upgraded to K3.** `KIMI_MODEL` now defaults to `kimi-code/k3`; premium, standard, and economy tiers all resolve to the same K3 alias.
 - **Model selection is now real, not metadata-only.** `query_kimi.sh` passes `--model "$KIMI_MODEL"` to the CLI, overriding a stale user-level Kimi default. A dedicated offline regression test captures the CLI arguments and validates response metadata; a live K3 smoke test returned a structured response with confidence 10.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v2.21.1
+# AI Consultants v2.22.0
 
 > **A harness for every question.** A panel of up to 11 frontier models that writes its own playbook per question — fan out, debate to convergence, cross-examine under adversarial review, or run a tournament — and checks its work before it reaches you.
 
-[![Version](https://img.shields.io/badge/version-2.21.1-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-2.22.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -513,13 +513,42 @@ Control how responses are combined:
 
 ### Environment Variables
 
-**Most users only need:**
+**Automatic configuration (recommended):**
 
 ```bash
-ai-consultants init           # creates ~/.config/ai-consultants/{config.sh,.env}
-$EDITOR ~/.config/ai-consultants/.env
+# Detect installed CLIs and available API keys, then write the persistent config
+ai-consultants configure
+
+# Review the consultant selection and transports interactively
+ai-consultants configure --interactive
+
+# Set any persistent parameter without opening an editor
+ai-consultants configure \
+  --set DEFAULT_PRESET=balanced \
+  --set ENABLE_DEBATE=true \
+  --set ORCHESTRATION_MODE=converge
+
+# Inspect the complete machine-readable parameter surface
+ai-consultants configure --show-parameters
 ```
 
+The configurator covers every persistent setting in `scripts/config.sh`, plus
+credentials, persona overrides, transport controls, advanced context knobs, and
+calibration commands. Existing custom values and secrets are preserved, while
+`ENABLE_*` flags are refreshed from detected availability (and can be pinned
+with `--set`). Rewrites create a private timestamped backup. Use `--advanced` to
+review every parameter or `--dry-run` to preview a redacted result.
+Auto-selected `*_USE_API` values are marked `# ai-consultants:auto`, allowing a
+later run to adapt when a CLI or credential changes. Environment variables,
+`--set`, and unmarked values remain explicit user choices.
+
+Enter credentials through `--interactive`/`--advanced` or export them before the
+run; avoid passing API keys through `--set`, where the shell may retain them in
+history or expose them in the process list.
+
+For a manual starter template instead, run `ai-consultants init` and edit
+`~/.config/ai-consultants/.env`.
+
 For ad-hoc overrides without persisting, the most common knobs:
 
 ```bash
@@ -688,6 +717,10 @@ Each consultation generates:
 
 ## Changelog
 
+### v2.22.0
+
+- **`ai-consultants configure`**: a public automatic configurator. It detects your installed CLIs and API keys, picks CLI-first transports, and writes a private XDG config while preserving your existing settings and secrets. Drive it with repeatable `--set KEY=VALUE`, review it with `--interactive` / `--advanced`, or preview it with `--dry-run`. See the [v2.22.0 release note](docs/releases/v2.22.0.md).
+
 ### v2.21.1
 
 - **Kimi K3**: Kimi now defaults to `kimi-code/k3`, and the adapter passes the model explicitly with `--model`.
@@ -759,7 +792,7 @@ Each consultation generates:
 
 - **Claude consultant**: New consultant with "The Synthesizer" persona
 - **Self-exclusion**: Invoking agent automatically excluded from panel
-- **Presets**: Quick configuration with `--preset minimal/balanced/high-stakes/local`
+- **Presets**: Quick configuration with `--preset minimal/balanced/high-stakes/security`
 - **Doctor command**: Diagnostic and auto-fix tool
 - **Synthesis strategies**: `--strategy majority/risk_averse/security_first/compare_only`
 - **Confidence intervals**: Statistical confidence ranges (e.g., "8 +/- 1.2")

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 2.21.1
+  version: 2.22.0
 ---
 
-# AI Consultants v2.21.1 - AI Expert Panel
+# AI Consultants v2.22.0 - AI Expert Panel
 
 **A harness for every question.** Convene a panel of AI "consultants" for coding questions — and let the engine pick *how* they deliberate: a quick read, a convergence loop, an adversarial refutation gate, a tournament, or an exhaustive sweep. Each consultant has a **configurable persona** that shapes its analysis.
 
@@ -100,13 +100,16 @@ Query is classified, then sent to consultants in parallel. Responses are scored,
 All settings use environment variables. Key toggles:
 
 ```bash
+ai-consultants configure     # Auto-detect CLIs/API keys and persist all settings
 ENABLE_DEBATE=true           # Multi-agent debate
 ENABLE_SYNTHESIS=true        # Automatic synthesis
 ENABLE_PANIC_MODE=auto       # Auto-rigor for uncertainty
 ENABLE_BUDGET_LIMIT=false    # Budget enforcement (v2.4)
 ```
 
-Enable opt-in consultants: `ENABLE_KIMI`, `ENABLE_QWEN3`, `ENABLE_CLAUDE`, `ENABLE_MINIMAX`.
+Use `ai-consultants configure --show-parameters` for the exact accepted keys,
+`--set KEY=VALUE` for repeatable automation, or `--advanced` to review all of
+them interactively.
 
 CLI/API switching: `GEMINI_USE_API`, `CODEX_USE_API`, `CLAUDE_USE_API`, `MISTRAL_USE_API`, `QWEN3_USE_API`.
 

package/bin/ai-consultants

@@ -55,13 +55,14 @@ Usage:
   ai-consultants --preset <name> "question"   Use a configuration preset
   ai-consultants --strategy <name> "question" Use a synthesis strategy
   ai-consultants doctor [--fix] [--json]      Run diagnostics
+  ai-consultants configure [options]          Auto-configure all persistent settings
   ai-consultants update-clis [--dry-run]      Check & update installed consultant CLIs
   ai-consultants init [--force]               Scaffold ~/.config/ai-consultants/{config.sh,.env}
   ai-consultants install                      Install slash commands to ~/.claude/commands/
   ai-consultants version                      Show version
   ai-consultants help                         Show this help
 
-Presets:   minimal, balanced, thorough, high-stakes, local, security, cost-capped,
+Presets:   minimal, balanced, thorough, high-stakes, security, cost-capped,
            max_quality, medium, fast
 
 Strategies: majority, risk_averse, security_first, cost_capped, compare_only
@@ -70,6 +71,7 @@ Examples:
   npx ai-consultants "How to optimize this SQL query?"
   npx ai-consultants --preset balanced "Redis or Memcached?"
   npx ai-consultants doctor --fix
+  npx ai-consultants configure --set DEFAULT_PRESET=balanced
 
 Documentation: https://github.com/matteoscurati/ai-consultants
 EOF
@@ -79,6 +81,10 @@ EOF
     shift
     exec "$SCRIPTS_DIR/doctor.sh" "$@"
     ;;
+  configure|config)
+    shift
+    exec "$SCRIPTS_DIR/configure.sh" "$@"
+    ;;
   update-clis|update)
     shift
     exec "$SCRIPTS_DIR/update_clis.sh" "$@"

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v2.21.1
+# Cost Rates - AI Consultants v2.22.0
 
 This page documents the per-token rates used by the cost tracking system.