diff --git a/docs/guide/agent-model-matching.md b/docs/guide/agent-model-matching.md
index c2115039b..ab898ea97 100644
--- a/docs/guide/agent-model-matching.md
+++ b/docs/guide/agent-model-matching.md
@@ -27,7 +27,7 @@ Using Sisyphus with older GPT models would be like taking your best project mana
 
 Hephaestus is the developer who stays in their room coding all day. Doesn't talk much. Might seem socially awkward. But give them a hard technical problem and they'll emerge three hours later with a solution nobody else could have found.
 
-**This is why Hephaestus uses GPT-5.4.** GPT-5.4 is built for exactly this:
+**This is why Hephaestus uses GPT-5.5.** GPT-5.5 is built for exactly this:
 
 - Deep, autonomous exploration without hand-holding
 - Multi-file reasoning across complex codebases
@@ -56,110 +56,186 @@ Agents that support both families (Prometheus, Atlas) auto-detect your model at
 
 ---
 
+## Step 1 — Check What's Actually Available
+
+Before configuring anything, see what your current system can run.
+
+### List all available models
+
+```bash
+opencode models
+```
+
+This prints every `provider/model` combination you can address right now. Providers are derived from your connected auth + the `models.dev` catalogue.
+
+Opencode sorts the output so `opencode*` providers appear first — that's intentional, not cosmetic.
+
+### List connected providers
+
+```bash
+opencode auth list
+```
+
+Shows which providers you've already logged into.
+
+### If the model you want isn't listed
+
+You need to log in to that provider:
+
+```bash
+opencode auth login
+```
+
+The interactive picker prioritizes providers in this order:
+
+| Priority | Provider | Opencode's own hint |
+|---|---|---|
+| 0 | `opencode` | **(Recommended)** |
+| 1 | `opencode-go` | Low cost subscription for everyone |
+| 2 | `openai` | ChatGPT Plus/Pro or API key |
+| 3 | `github-copilot` | — |
+| 4 | `anthropic` | API key |
+| 5 | `google` | — |
+
+You can also skip the picker: `opencode auth login --provider opencode-go`.
+
+### Verify what oh-my-openagent will actually use
+
+```bash
+bunx oh-my-opencode doctor
+```
+
+This shows the **effective model resolution** for every agent and category based on your current auth state. If an agent says "system-default" instead of a real fallback, that's a signal you're missing providers from its chain.
+
+---
+
+## Step 2 — The Recommended Stack
+
+You don't need every provider. You need the right two.
+
+### The Optimal Combination: OpenCode Go + OpenAI Plus/Pro
+
+**~$30/month total.** Beats direct Anthropic + OpenAI + Google subscriptions (~$60+/month) on both cost and coverage.
+
+| Subscription | Cost | What You Get | Covers |
+|---|---|---|---|
+| **OpenCode Go** | $10/mo | `kimi-k2.5`, `kimi-k2.6`, `glm-5`, `glm-5.1`, `minimax-m2.5`, `minimax-m2.7`, `mimo-v2-pro`, `qwen3.5-plus`, `qwen3.6-plus` | Claude-family alternatives (Kimi, GLM), Gemini-family alternatives (Qwen), utility/retrieval (MiniMax) |
+| **OpenAI Plus/Pro** | $20+/mo | `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.5`, `gpt-5.3-codex` | GPT-native agents (Hephaestus, Oracle, Momus), dual-prompt agents' GPT path |
+
+### Why this specific combination
+
+1. **Hephaestus requires GPT-5.4/5.5.** It has no Claude-family fallback. ChatGPT Plus/Pro is the cheapest real path.
+2. **OpenCode Go covers the orchestration and creative surface.** Kimi K2.5/2.6 behaves like Claude for Sisyphus/Atlas. GLM-5 fills the long tail. Qwen handles visual tasks when Gemini isn't available.
+3. **No single provider can cover everything.** Anthropic-only setups break Hephaestus. OpenAI-only setups degrade Sisyphus. You need at least one from each family.
+
+### What if you already have a Claude subscription?
+
+Add `--claude=max20` (or `yes`) on install. Claude Opus 4.7 becomes the default for Sisyphus/Prometheus/Atlas and you still get the OpenCode Go fallbacks for free. Best-in-class orchestration + budget safety net.
+
+### What if you have zero subscriptions?
+
+OpenCode Go alone gets Sisyphus/Atlas/Oracle/Librarian/Explore working. Hephaestus won't activate without GPT access, so you lose autonomous deep work. Consider adding ChatGPT Plus as soon as you can.
+
+---
+
+## Step 3 — Model Family Alternatives (Priority Order)
+
+When the "native" model isn't available, oh-my-openagent walks each agent's fallback chain until something connects. The chains are hardcoded in [`src/shared/model-requirements.ts`](../../src/shared/model-requirements.ts). Here are the **substitution rules** you should internalize.
+
+### Claude Family (communicative, instruction-following)
+
+Used by: Sisyphus, Atlas, Sisyphus-Junior, Metis (Claude path), Prometheus (Claude path), `unspecified-low`, `unspecified-high`.
+
+| Priority | Model | Provider | Why |
+|---|---|---|---|
+| 1 | `claude-opus-4-7` (max) | `anthropic`, `github-copilot`, `opencode`, `vercel` | Best overall compliance with ~1,100-line Sisyphus prompt. |
+| 2 | `claude-sonnet-4-6` | same | Faster, cheaper, still Claude. |
+| 3 | **`kimi-k2.5` or `kimi-k2.6` — RECOMMENDED ALTERNATIVE** | `opencode-go`, `kimi-for-coding`, `moonshotai`, `opencode`, `vercel` | Instruction-following mirrors Claude closely. Default orchestrator when Anthropic isn't connected. |
+| 4 | **`glm-5` or `glm-5.1` — ACCEPTABLE ALTERNATIVE** | `opencode-go`, `zai-coding-plan`, `opencode`, `vercel` | Claude-like, slightly looser on long nested workflows. Solid fallback. |
+| 5 | `big-pickle` (GLM 4.6) | `opencode` | Free-tier safety net. |
+
+> **Kimi ≻ GLM.** Kimi K2.5/2.6 hold up under Sisyphus's nested todo+delegation prompts better than GLM. Use Kimi whenever both are available.
+
+### GPT Family (principle-driven, autonomous)
+
+Used by: Hephaestus, Oracle, Momus, `deep`, `ultrabrain`, `quick`, Prometheus (GPT path), Atlas (GPT path).
+
+| Priority | Model | Provider | Why |
+|---|---|---|---|
+| 1 | `gpt-5.5` / `gpt-5.4` (pro / xhigh / high / medium) | `openai`, `github-copilot`, `opencode`, `vercel` | Native OpenAI is the gold standard for principle-driven prompts. Hephaestus requires this family. |
+| 2 | `gpt-5.3-codex` | same | Still the deep-coding powerhouse. Kept as an explicit override option. |
+| 3 | **DeepSeek — LIMITED ALTERNATIVE** (`deepseek-v3.2`, `deepseek-chat-v3.1`) | `openrouter/deepseek` | Closest OSS equivalent for autonomous coding behavior. Not wired into default chains — add via `fallback_models`. |
+| 4 | **MiniMax — STRONGLY DISCOURAGED** (`minimax-m2.7`, `minimax-m2.5`) | `opencode-go`, `opencode`, `openrouter/minimax` | Used only in **utility** fallback chains (Explore, Librarian, `quick`). Consistency and long-context management issues make it a poor substitute for Hephaestus/Oracle. Do NOT override deep agents to MiniMax. |
+
+> **DeepSeek ≻≻ MiniMax.** DeepSeek retains GPT's autonomous exploration character. MiniMax loses coherence on multi-step deep work. MiniMax is fine for grep-style utility agents, nothing more.
+
+### Gemini Family (visual, different reasoning style)
+
+Used by: `visual-engineering`, `artistry`, Oracle (visual fallback), Multimodal-Looker.
+
+| Priority | Model | Provider | Why |
+|---|---|---|---|
+| 1 | `gemini-3.1-pro` (high) | `google`, `github-copilot`, `opencode`, `vercel` | Best for UI/UX, CSS, design tokens, layout decisions. `artistry` category **requires** this family. |
+| 2 | `gemini-3-flash` | same | Fast variant, writing/doc tasks. |
+| 3 | **Qwen — ALTERNATIVE** (`qwen3.6-plus`, `qwen3.5-plus`) | `opencode-go`, `openrouter/qwen` | Closest vision-capable substitute when Google isn't connected. Uses different reasoning style but handles visual tasks competently. |
+
+> **No GLM/Kimi here.** They're not Gemini substitutes for visual work. Use Qwen.
+
+---
+
+## Cheat Sheet: Substitution Rules
+
+| If you lose... | Swap to (in order) | Avoid |
+|---|---|---|
+| Claude Opus/Sonnet | Kimi K2.5/K2.6 → GLM 5 → Big Pickle | Older GPT models |
+| GPT-5.4/5.5 | GPT-5.3 Codex → DeepSeek v3.2 | MiniMax (except for utility work) |
+| Gemini 3.1 Pro | Qwen 3.6-plus / 3.5-plus | Claude/Kimi (wrong reasoning style for visual) |
+| Grok Code Fast 1 (Explore) | GPT-5.4 Mini Fast → MiniMax M2.7 Highspeed → Claude Haiku | Opus (massive cost waste) |
+
+---
+
 ## Agent Profiles
 
+Exact runtime chains from [`src/shared/model-requirements.ts`](../../src/shared/model-requirements.ts).
+
 ### Communicators → Claude / Kimi / GLM
 
 These agents have Claude-optimized prompts — long, detailed, mechanics-driven. They need models that reliably follow complex, multi-layered instructions.
 
-| Agent        | Role              | Fallback Chain                         | Notes                                                                                             |
-| ------------ | ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| **Sisyphus** | Main orchestrator | anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → opencode-go\|vercel/kimi-k2.5 → kimi-for-coding/k2p5 → opencode\|moonshotai\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix\|vercel/kimi-k2.5 → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (medium) → zai-coding-plan\|opencode\|vercel/glm-5 → opencode/big-pickle | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Metis**    | Plan gap analyzer | anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (high) → opencode-go\|vercel/glm-5 → kimi-for-coding/k2p5 | Exact runtime chain from `src/shared/model-requirements.ts`. |
+| Agent | Role | Fallback Chain |
+|---|---|---|
+| **Sisyphus** | Main orchestrator | `anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7` (max) → `opencode-go\|vercel/kimi-k2.5` → `kimi-for-coding/k2p5` → `opencode\|moonshotai\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix\|vercel/kimi-k2.5` → `openai\|github-copilot\|opencode\|vercel/gpt-5.4` (medium) → `zai-coding-plan\|opencode\|vercel/glm-5` → `opencode/big-pickle` |
+| **Metis** | Plan gap analyzer | `anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7` (max) → `openai\|github-copilot\|opencode\|vercel/gpt-5.4` (high) → `opencode-go\|vercel/glm-5` → `kimi-for-coding/k2p5` |
 
 ### Dual-Prompt Agents → Claude preferred, GPT supported
 
 These agents ship separate prompts for Claude and GPT families. They auto-detect your model and switch at runtime.
 
-| Agent          | Role              | Fallback Chain                         | Notes                                                                |
-| -------------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------- |
-| **Prometheus** | Strategic planner | anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (high) → opencode-go\|vercel/glm-5 → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Atlas**      | Todo orchestrator | anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6 → opencode-go\|vercel/kimi-k2.5 → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (medium) → opencode-go\|vercel/minimax-m2.7 | Exact runtime chain from `src/shared/model-requirements.ts`. |
+| Agent | Role | Fallback Chain |
+|---|---|---|
+| **Prometheus** | Strategic planner | `anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7` (max) → `openai\|github-copilot\|opencode\|vercel/gpt-5.4` (high) → `opencode-go\|vercel/glm-5` → `google\|github-copilot\|opencode\|vercel/gemini-3.1-pro` |
+| **Atlas** | Todo orchestrator | `anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6` → `opencode-go\|vercel/kimi-k2.5` → `openai\|github-copilot\|opencode\|vercel/gpt-5.4` (medium) → `opencode-go\|vercel/minimax-m2.7` |
 
 ### Deep Specialists → GPT
 
-These agents are built for GPT's principle-driven style. Their prompts assume autonomous, goal-oriented execution. Don't override to Claude.
+These agents are built for GPT's principle-driven style. Their prompts assume autonomous, goal-oriented execution. **Don't override to Claude.**
 
-| Agent          | Role                    | Fallback Chain                         | Notes                                            |
-| -------------- | ----------------------- | -------------------------------------- | ------------------------------------------------ |
-| **Hephaestus** | Autonomous deep worker  | openai\|github-copilot\|venice\|opencode\|vercel/gpt-5.4 (medium) | Single-entry chain. Requires one of those providers. The craftsman. |
-| **Oracle**     | Architecture consultant | openai\|github-copilot\|opencode\|vercel/gpt-5.4 (high) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → opencode-go\|vercel/glm-5 | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Momus**      | Ruthless reviewer       | openai\|github-copilot\|opencode\|vercel/gpt-5.4 (xhigh) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → opencode-go\|vercel/glm-5 | Exact runtime chain from `src/shared/model-requirements.ts`. |
+| Agent | Role | Fallback Chain |
+|---|---|---|
+| **Hephaestus** | Autonomous deep worker | `openai\|github-copilot\|venice\|opencode\|vercel/gpt-5.5` (medium) — single-entry chain, requires one of those providers. The craftsman. |
+| **Oracle** | Architecture consultant | `openai\|github-copilot\|opencode\|vercel/gpt-5.5` (high) → `google\|github-copilot\|opencode\|vercel/gemini-3.1-pro` (high) → `anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7` (max) → `opencode-go\|vercel/glm-5` |
+| **Momus** | Ruthless reviewer | `openai\|github-copilot\|opencode\|vercel/gpt-5.5` (xhigh) → `anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7` (max) → `google\|github-copilot\|opencode\|vercel/gemini-3.1-pro` (high) → `opencode-go\|vercel/glm-5` |
 
 ### Utility Runners → Speed over Intelligence
 
 These agents do grep, search, and retrieval. They intentionally use the fastest, cheapest models available. **Don't "upgrade" them to Opus** — that's hiring a senior engineer to file paperwork.
 
-| Agent                 | Role               | Fallback Chain                                 | Notes                                                 |
-| --------------------- | ------------------ | ---------------------------------------------- | ----------------------------------------------------- |
-| **Explore**           | Fast codebase grep | openai/gpt-5.4-mini-fast → opencode-go\|vercel/minimax-m2.7-highspeed → opencode-go\|vercel/minimax-m2.7 → anthropic\|opencode\|vercel/claude-haiku-4-5 → openai\|opencode\|vercel/gpt-5.4-nano | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Librarian**         | Docs/code search   | openai/gpt-5.4-mini-fast → opencode-go\|vercel/minimax-m2.7-highspeed → opencode-go\|vercel/minimax-m2.7 → anthropic\|opencode\|vercel/claude-haiku-4-5 → openai\|opencode\|vercel/gpt-5.4-nano | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Multimodal Looker** | Vision/screenshots | openai\|opencode\|vercel/gpt-5.4 (medium) → opencode-go\|vercel/kimi-k2.5 → zai-coding-plan\|vercel/glm-4.6v → openai\|github-copilot\|opencode\|vercel/gpt-5-nano | Exact runtime chain from `src/shared/model-requirements.ts`. |
-| **Sisyphus-Junior**   | Category executor  | anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6 → opencode-go\|vercel/kimi-k2.5 → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (medium) → opencode-go\|vercel/minimax-m2.7 → opencode/big-pickle | Exact runtime chain from `src/shared/model-requirements.ts`. |
-
----
-
-## Model Families
-
-### Claude Family
-
-Communicative, instruction-following, structured output. Best for agents that need to follow complex multi-step prompts.
-
-| Model                 | Strengths                                                                    |
-| --------------------- | ---------------------------------------------------------------------------- |
-| **Claude Opus 4.7**   | Best overall. Highest compliance with complex prompts. Default for Sisyphus. |
-| **Claude Sonnet 4.6** | Faster, cheaper. Good balance for everyday tasks.                            |
-| **Claude Haiku 4.5**  | Fast and cheap. Good for quick tasks and utility work.                       |
-| **Kimi K2.5**         | Behaves very similarly to Claude. Great all-rounder at lower cost.           |
-| **GLM 5**             | Claude-like behavior. Solid for orchestration tasks.                         |
-
-### GPT Family
-
-Principle-driven, explicit reasoning, deep technical capability. Best for agents that work autonomously on complex problems.
-
-| Model             | Strengths                                                                                       |
-| ----------------- | ----------------------------------------------------------------------------------------------- |
-| **GPT-5.3 Codex** | Deep coding powerhouse. Autonomous exploration. Still available for deep category and explicit overrides. |
-| **GPT-5.4**       | High intelligence, strategic reasoning. Default for Oracle, Momus, and a key fallback for Prometheus / Atlas. Uses xhigh variant for Momus. |
-| **GPT-5.4 Mini**  | Fast + strong reasoning. Good for lightweight autonomous tasks. Default for quick category. |
-| **GPT-5-Nano**    | Ultra-cheap, fast. Good for simple utility tasks.                                               |
-
-### Other Models
-
-| Model                | Strengths                                                                                                    |
-| -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| **Gemini 3.1 Pro**   | Excels at visual/frontend tasks. Different reasoning style. Default for `visual-engineering` and `artistry`. |
-| **Gemini 3 Flash**   | Fast. Good for doc search and light tasks.                                                                   |
-| **GPT-5.4 Mini Fast** | Default for Explore and Librarian agents. Blazing-fast reasoning-capable mini model. |
-| **MiniMax M2.7**     | Fast and smart. Used in OpenCode Go and OpenCode Zen utility fallback chains. |
-| **MiniMax M2.7 Highspeed** | High-speed OpenCode catalog entry used in utility fallback chains that prefer the fastest available MiniMax path. |
-
-### OpenCode Go
-
-A premium subscription tier ($10/month) that provides reliable access to Chinese frontier models through OpenCode's infrastructure.
-
-**Available Models:**
-
-| Model                    | Use Case                                                              |
-| ------------------------ | --------------------------------------------------------------------- |
-| **opencode-go/kimi-k2.5** | Vision-capable, Claude-like reasoning. Used by Sisyphus, Atlas, Sisyphus-Junior, Multimodal Looker. |
-| **opencode-go/glm-5**     | Text-only orchestration model. Used by Oracle, Prometheus, Metis, Momus.                           |
-| **opencode-go/minimax-m2.7** | Ultra-cheap, fast responses. Used by Atlas, Sisyphus-Junior, Explore and Librarian fallbacks for utility work. |
-| **opencode-go/minimax-m2.7-highspeed** | Even faster OpenCode Go MiniMax entry used as a secondary fallback for Explore and Librarian when GPT-5.4 Mini Fast is unavailable. |
-
-**When It Gets Used:**
-
-OpenCode Go models appear throughout the fallback chains as intermediate options. Depending on the agent, they can sit before GPT, after GPT, or act as the last structured-model fallback before cheaper utility paths.
-
-**Go-Only Scenarios:**
-
-Some model identifiers like `k2p5` (paid Kimi K2.5) and `glm-5` may only be available through OpenCode Go subscription in certain regions. When configured with these short identifiers, the system resolves them through the opencode-go provider first.
-
-### About Free-Tier Fallbacks
-
-You may see model names like `kimi-k2.5-free`, `minimax-m2.7`, `minimax-m2.7-highspeed`, or `big-pickle` (GLM 4.6) in the source code or logs. These are provider-specific or speed-optimized entries in fallback chains.
-
-You don't need to configure them. The system includes them so it degrades gracefully when you don't have every paid subscription. If you have the paid version, the paid version is always preferred.
+| Agent | Role | Fallback Chain |
+|---|---|---|
+| **Explore** | Fast codebase grep | `openai/gpt-5.4-mini-fast` → `opencode-go\|vercel/minimax-m2.7-highspeed` → `opencode-go\|vercel/minimax-m2.7` → `anthropic\|opencode\|vercel/claude-haiku-4-5` → `openai\|opencode\|vercel/gpt-5.4-nano` |
+| **Librarian** | Docs/code search | same as Explore |
+| **Multimodal Looker** | Vision/screenshots | `openai\|opencode\|vercel/gpt-5.4` (medium) → `opencode-go\|vercel/kimi-k2.5` → `zai-coding-plan\|vercel/glm-4.6v` → `openai\|github-copilot\|opencode\|vercel/gpt-5-nano` |
+| **Sisyphus-Junior** | Category executor | `anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6` → `opencode-go\|vercel/kimi-k2.5` → `openai\|github-copilot\|opencode\|vercel/gpt-5.4` (medium) → `opencode-go\|vercel/minimax-m2.7` → `opencode/big-pickle` |
 
 ---
 
@@ -167,108 +243,188 @@ You don't need to configure them. The system includes them so it degrades gracef
 
 When agents delegate work, they don't pick a model name — they pick a **category**. The category maps to the right model automatically.
 
-| Category             | When Used                  | Fallback Chain                               |
-| -------------------- | -------------------------- | -------------------------------------------- |
-| `visual-engineering` | Frontend, UI, CSS, design  | google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → zai-coding-plan\|opencode\|vercel/glm-5 → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → opencode-go\|vercel/glm-5 → kimi-for-coding/k2p5 |
-| `ultrabrain`         | Maximum reasoning needed   | openai\|opencode\|vercel/gpt-5.4 (xhigh) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → opencode-go\|vercel/glm-5 |
-| `deep`               | Deep coding, complex logic | openai\|github-copilot\|venice\|opencode\|vercel/gpt-5.4 (medium) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) |
-| `artistry`           | Creative, novel approaches | google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → openai\|github-copilot\|opencode\|vercel/gpt-5.4 |
-| `quick`              | Simple, fast tasks         | openai\|github-copilot\|opencode\|vercel/gpt-5.4-mini → anthropic\|github-copilot\|opencode\|vercel/claude-haiku-4-5 → google\|github-copilot\|opencode\|vercel/gemini-3-flash → opencode-go\|vercel/minimax-m2.7 → opencode\|vercel/gpt-5-nano |
-| `unspecified-high`   | General complex work       | anthropic\|github-copilot\|opencode\|vercel/claude-opus-4-7 (max) → openai\|github-copilot\|opencode\|vercel/gpt-5.4 (high) → zai-coding-plan\|opencode\|vercel/glm-5 → kimi-for-coding/k2p5 → opencode-go\|vercel/glm-5 → opencode\|vercel/kimi-k2.5 → opencode\|moonshotai\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix\|vercel/kimi-k2.5 |
-| `unspecified-low`    | General standard work      | anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6 → openai\|opencode\|vercel/gpt-5.3-codex (medium) → opencode-go\|vercel/kimi-k2.5 → google\|github-copilot\|opencode\|vercel/gemini-3-flash → opencode-go\|vercel/minimax-m2.7 |
-| `writing`            | Text, docs, prose          | google\|github-copilot\|opencode\|vercel/gemini-3-flash → opencode-go\|vercel/kimi-k2.5 → anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-4-6 → opencode-go\|vercel/minimax-m2.7 |
+| Category | Used For | Default Model | Fallback Chain |
+|---|---|---|---|
+| `visual-engineering` | Frontend, UI, CSS, design | `google/gemini-3.1-pro` (high) | Gemini → `zai-coding-plan/glm-5` → `claude-opus-4-7` (max) → `opencode-go/glm-5` → `kimi-for-coding/k2p5` |
+| `artistry` | Creative, novel approaches | `google/gemini-3.1-pro` (high) | Gemini → `claude-opus-4-7` (max) → `gpt-5.4` — requires Gemini family to activate |
+| `ultrabrain` | Maximum reasoning needed | `openai/gpt-5.4` (xhigh) | GPT-5.4 xhigh → `gemini-3.1-pro` (high) → `claude-opus-4-7` (max) → `opencode-go/glm-5` |
+| `deep` | Deep coding, complex logic | `openai/gpt-5.5` (medium) | GPT-5.5 → `claude-opus-4-7` (max) → `gemini-3.1-pro` (high) |
+| `quick` | Simple, fast tasks | `openai/gpt-5.4-mini` | GPT-5.4-mini → `claude-haiku-4-5` → `gemini-3-flash` → `opencode-go/minimax-m2.7` → `opencode/gpt-5-nano` |
+| `unspecified-high` | General complex work | `anthropic/claude-opus-4-7` (max) | Opus → `gpt-5.4` (high) → `zai-coding-plan/glm-5` → `kimi-for-coding/k2p5` → `opencode-go/glm-5` → `opencode/kimi-k2.5` → `moonshotai/kimi-k2.5` |
+| `unspecified-low` | General standard work | `anthropic/claude-sonnet-4-6` | Sonnet → `gpt-5.3-codex` (medium) → `opencode-go/kimi-k2.5` → `google/gemini-3-flash` → `opencode-go/minimax-m2.7` |
+| `writing` | Text, docs, prose | `kimi-for-coding/k2p5` | Kimi → `gemini-3-flash` → `opencode-go/kimi-k2.5` → `claude-sonnet-4-6` → `opencode-go/minimax-m2.7` |
 
 See the [Orchestration System Guide](./orchestration.md) for how agents dispatch tasks to categories.
 
 ### Vercel AI Gateway fallback coverage
 
-`src/shared/model-requirements.ts` now includes `vercel` on nearly every gateway-compatible fallback entry across both agent and category chains. Treat it as a universal extra provider path for the listed model IDs, not as a different model family. If a row above shows `|vercel` in the provider set, that is the current source-of-truth runtime fallback, not a docs-only convenience alias.
+`src/shared/model-requirements.ts` includes `vercel` on nearly every gateway-compatible fallback entry across both agent and category chains. Treat it as a universal extra provider path for the listed model IDs, not as a different model family.
 
 ---
 
 ## Customization
 
-### Example Configuration
+### Example A — Recommended Stack (OpenCode Go + OpenAI Plus/Pro)
 
 ```jsonc
 {
   "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
 
   "agents": {
-    // Main orchestrator: Claude Opus or Kimi K2.5 work best
+    // Sisyphus: Kimi K2.6 is the top alternative to Claude for orchestration
     "sisyphus": {
-      "model": "kimi-for-coding/k2p5",
-      "ultrawork": { "model": "anthropic/claude-opus-4-7", "variant": "max" },
+      "model": "opencode-go/kimi-k2.6",
+      "ultrawork": { "model": "opencode-go/kimi-k2.6" },
     },
 
-    // Research agents: cheaper models are fine
-    "librarian": { "model": "google/gemini-3-flash" },
-    "explore": { "model": "github-copilot/grok-code-fast-1" },
+    // Hephaestus: needs GPT. ChatGPT Plus gets you here.
+    "hephaestus": { "model": "openai/gpt-5.5", "variant": "medium" },
 
-    // Architecture consultation: GPT or Claude Opus
+    // Oracle: GPT preferred for architecture reasoning
     "oracle": { "model": "openai/gpt-5.4", "variant": "high" },
 
-    // Prometheus inherits sisyphus model; just add prompt guidance
-    "prometheus": {
-      "prompt_append": "Leverage deep & quick agents heavily, always in parallel.",
-    },
+    // Prometheus inherits Sisyphus behavior
+    "prometheus": { "model": "opencode-go/kimi-k2.6" },
+
+    // Atlas also communicative — Kimi works great
+    "atlas": { "model": "opencode-go/kimi-k2.5" },
+
+    // Utility agents stay cheap
+    "explore": { "model": "opencode-go/minimax-m2.7-highspeed" },
+    "librarian": { "model": "opencode-go/minimax-m2.7-highspeed" },
   },
 
   "categories": {
-    "quick": { "model": "opencode/gpt-5-nano" },
-    "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },
-    "unspecified-high": { "model": "anthropic/claude-opus-4-7", "variant": "max" },
-    "visual-engineering": {
-      "model": "google/gemini-3.1-pro",
-      "variant": "high",
-    },
-    "writing": { "model": "google/gemini-3-flash" },
+    "visual-engineering": { "model": "opencode-go/qwen3.6-plus" },  // Qwen as Gemini alt
+    "deep": { "model": "openai/gpt-5.5", "variant": "medium" },
+    "ultrabrain": { "model": "openai/gpt-5.4", "variant": "xhigh" },
+    "quick": { "model": "openai/gpt-5.4-mini" },
+    "unspecified-low": { "model": "opencode-go/kimi-k2.5" },
+    "unspecified-high": { "model": "opencode-go/kimi-k2.6" },
+    "writing": { "model": "opencode-go/kimi-k2.5" },
   },
 
-  // Limit expensive providers; let cheap ones run freely
   "background_task": {
     "providerConcurrency": {
-      "anthropic": 3,
       "openai": 3,
-      "opencode": 10,
-      "zai-coding-plan": 10,
-    },
-    "modelConcurrency": {
-      "anthropic/claude-opus-4-7": 2,
-      "opencode/gpt-5-nano": 20,
+      "opencode-go": 10,
     },
   },
 }
 ```
 
-Run `opencode models` to see available models, `opencode auth login` to authenticate providers.
+### Example B — All Native (Anthropic + OpenAI + Google)
+
+Highest quality, highest cost. No surprises.
+
+```jsonc
+{
+  "agents": {
+    "sisyphus": {
+      "model": "anthropic/claude-opus-4-7",
+      "variant": "max",
+    },
+    "hephaestus": { "model": "openai/gpt-5.5", "variant": "medium" },
+    "oracle": { "model": "openai/gpt-5.4", "variant": "high" },
+  },
+  "categories": {
+    "visual-engineering": { "model": "google/gemini-3.1-pro", "variant": "high" },
+    "deep": { "model": "openai/gpt-5.5", "variant": "medium" },
+    "unspecified-high": { "model": "anthropic/claude-opus-4-7", "variant": "max" },
+  },
+}
+```
+
+### Example C — OpenCode Go Only (Budget, No GPT)
+
+Cheapest full-stack path. Hephaestus won't activate — accept that trade-off.
+
+```jsonc
+{
+  "agents": {
+    "sisyphus": { "model": "opencode-go/kimi-k2.6" },
+    "atlas": { "model": "opencode-go/kimi-k2.5" },
+    // Omit hephaestus entirely; it needs GPT.
+    "oracle": { "model": "opencode-go/glm-5" },  // Degraded but functional
+    "explore": { "model": "opencode-go/minimax-m2.7-highspeed" },
+    "librarian": { "model": "opencode-go/minimax-m2.7-highspeed" },
+  },
+  "categories": {
+    "visual-engineering": { "model": "opencode-go/qwen3.6-plus" },
+    "deep": { "model": "opencode-go/kimi-k2.6" },  // Not ideal — Kimi isn't GPT, but best available
+    "unspecified-high": { "model": "opencode-go/kimi-k2.6" },
+    "unspecified-low": { "model": "opencode-go/kimi-k2.5" },
+    "quick": { "model": "opencode-go/minimax-m2.7" },
+    "writing": { "model": "opencode-go/kimi-k2.5" },
+  },
+}
+```
+
+### Example D — Adding DeepSeek as GPT Alternative
+
+If you have OpenRouter and want DeepSeek in the chain when GPT is unavailable:
+
+```jsonc
+{
+  "agents": {
+    "oracle": {
+      "model": "openai/gpt-5.4",
+      "variant": "high",
+      "fallback_models": [
+        "anthropic/claude-opus-4-7",
+        { "model": "openrouter/deepseek/deepseek-v3.2", "temperature": 0.7 },
+        "opencode-go/glm-5",
+      ],
+    },
+  },
+}
+```
+
+`fallback_models` accepts a mix of plain model strings and per-fallback objects with `variant`, `reasoningEffort`, `temperature`, `top_p`, `maxTokens`, `thinking`.
+
+---
 
 ### Safe vs Dangerous Overrides
 
 **Safe** — same personality type:
 
-- Sisyphus: Opus → Sonnet, Kimi K2.5, GLM 5 (all communicative models)
+- Sisyphus: Opus → Sonnet, Kimi K2.5/2.6, GLM 5 (all communicative models)
 - Prometheus: Opus → GPT-5.4 (auto-switches to the GPT prompt)
-- Atlas: Claude Sonnet 4.6 → GPT-5.4 (auto-switches to the GPT prompt)
+- Atlas: Claude Sonnet 4.6 → Kimi K2.5, GPT-5.4 (auto-switches to the GPT prompt)
 
 **Dangerous** — personality mismatch:
 
-- Sisyphus → older GPT models: **Still a bad fit. GPT-5.4 is the only dedicated GPT prompt path.**
-- Hephaestus → Claude: **Built for Codex's autonomous style. Claude can't replicate this.**
-- Explore → Opus: **Massive cost waste. Explore needs speed, not intelligence.**
-- Librarian → Opus: **Same. Doc search doesn't need Opus-level reasoning.**
+- **Sisyphus → older GPT models**: Still a bad fit. GPT-5.4 is the only dedicated GPT prompt path.
+- **Hephaestus → Claude**: Built for Codex's autonomous style. Claude can't replicate this.
+- **Hephaestus → MiniMax**: MiniMax loses coherence on multi-step deep work. **Never do this.**
+- **Oracle → MiniMax**: Same reason. Oracle needs sustained reasoning; MiniMax drifts.
+- **Explore → Opus**: Massive cost waste. Explore needs speed, not intelligence.
+- **Librarian → Opus**: Same. Doc search doesn't need Opus-level reasoning.
+- **`visual-engineering` → Kimi/GLM**: Wrong reasoning style. Use Qwen if Gemini is unavailable, not Claude-likes.
 
-### How Model Resolution Works
+---
+
+## How Model Resolution Works
 
 Each agent has a fallback chain. The system tries models in priority order until it finds one available through your connected providers. You don't need to configure providers per model. Just authenticate (`opencode auth login`) and the system figures out which models are available and where.
 
+Resolution pipeline (from [`src/shared/model-resolution-pipeline.ts`](../../src/shared/model-resolution-pipeline.ts)):
+
+```
+1. Override          → User's explicit config or UI-selected model (primary agents only)
+2. Category default  → From category config (when agent has category set)
+3. User fallback_models → Configured strings/objects tried before hardcoded chain
+4. Provider fallback → AGENT_MODEL_REQUIREMENTS / CATEGORY_MODEL_REQUIREMENTS
+5. System default    → Ultimate safety net
+```
+
 Core-agent tab cycling is deterministic via injected runtime order field. The fixed priority order is Sisyphus (order: 1), Hephaestus (order: 2), Prometheus (order: 3), and Atlas (order: 4), then the remaining agents follow.
 
 Your explicit configuration always wins. If you set a specific model for an agent, that choice takes precedence even when resolution data is cold.
 
 Variant and `reasoningEffort` overrides are normalized to model-supported values, so cross-provider overrides degrade gracefully instead of failing hard.
 
-Model capabilities are models.dev-backed, with a refreshable cache and capability diagnostics. Use `bunx oh-my-opencode refresh-model-capabilities` to update the cache, or configure `model_capabilities.auto_refresh_on_start` to refresh at startup.
+Model capabilities are `models.dev`-backed, with a refreshable cache and capability diagnostics. Use `bunx oh-my-opencode refresh-model-capabilities` to update the cache, or configure `model_capabilities.auto_refresh_on_start` to refresh at startup.
 
 To see which models your agents will actually use, run `bunx oh-my-opencode doctor`. This shows effective model resolution based on your current authentication and config.
 
@@ -284,17 +440,17 @@ You can load agent system prompts from external files using `file://` URLs in th
 {
   "agents": {
     "sisyphus": {
-      "prompt": "file:///path/to/custom-prompt.md"
+      "prompt": "file:///path/to/custom-prompt.md",
     },
     "oracle": {
-      "prompt_append": "file:///path/to/additional-context.md"
-    }
+      "prompt_append": "file:///path/to/additional-context.md",
+    },
   },
   "categories": {
     "deep": {
-      "prompt_append": "file:///path/to/deep-category-append.md"
-    }
-  }
+      "prompt_append": "file:///path/to/deep-category-append.md",
+    },
+  },
 }
 ```