feat(providers): detect + configure claude/codex hosts and LLM providers

[pacphi]

What

Adds ak x provider [status|pick|off] so ruflo and agentic-qe can be configured to use one or both frontier CLIs (claude, codex). ak's job stays what it is — a thin, reversible detect → heal → verify facilitator: the capability already exists downstream, so ak detects and wires it rather than reimplementing it.

Grounded in rUv source: ruflo ADR-034 Optional MCP Backends (ENABLE_CLAUDE_CODE/ENABLE_CODEX), @claude-flow/codex, ruflo init --dual, ruflo providers, and agentic-qe's AQE_LLM_PROVIDER selector + HybridRouter fallback chain.

Design — two independent axes, claude-default

Default is claude-only, codex opt-in, so existing repos see zero change until a user opts in (isDefault() makes the heal a deliberate no-op).

• Hosts (which agent CLI runs the ruflo loop): claude / codex, or both at once via dual-mode. Written as ENABLE_* env into .claude/settings.local.json (same seam as CLAUDE_FLOW_DB_PATH).
• Providers (which LLM the routers use, independent of host):
  • agentic-qe — AQE_LLM_PROVIDER (any of claude-code/claude/openai/gemini/openrouter/azure-openai/bedrock/cognitum/ollama), plus a deterministic, ordered fallback chain written to .agentic-qe/llm-config.json from kit.json (complete FallbackChain, per-provider enabled, _managedBy: agentic-kit tag).
  • ruflo — API providers via ruflo providers configure.
  • API keys stay in the environment, never kit.json (aqe refuses to persist them anyway).

Install & update — install-method-aware

• First install: installs an enabled host only when entirely absent (npm i -g @anthropic-ai/claude-code / @openai/codex).
• Updates: npm-managed hosts ride the existing cached drift check (bin nudge + ak status + ak sync).
• Never touches an external install (mise/brew/native) — reports it as self-managed and advises, rather than shadowing it with an npm copy.

Reversible

ak x provider off strips the managed env keys (leaving your other settings) and restores the pre-ak llm-config.json from its one-time .bak, or removes an ak-created file. It never touches a foreign llm-config.json (no _managedBy tag).

Wired through the lifecycle

ak status (hosts + providers rows, drift), ak sync (re-applies env + router), ak setup (project-scope wiring + codex hint), ak x verify providers (asserts on-disk chain matches kit.json), a new codex-gated CLAUDE.md managed block, and a progressive-disclosure user guide in docs/PROVIDERS.md.

Honest constraint, verified in source

aqe is not limited to claude-code (my first read was wrong): AQE_LLM_PROVIDER=<type> force-selects any provider in ALL_PROVIDER_TYPES, and its HybridRouter auto-enables any provider with an API key in the env. codex the CLI simply isn't an aqe provider type — its OpenAI models are reachable via openai.

Tests

52 kit unit tests (new tests/kit/providers.test.mjs covers env write/undo round-trips, the complete-chain writer, backup-restore vs remove, foreign-file safety, install-method guards) + statusline suite pass. Model IDs in docs/examples are current as of July 2026 (Claude Opus 4.8, GPT-5.6, Gemini 3.5 Flash) with a note to use whatever your provider offers.

🤖 Generated with Claude Code