docs: add agent-model matching guide for newcomers

- Add docs/guide/agent-model-matching.md with TL;DR table, detailed
  breakdown per agent, configuration examples, decision tree, common
  pitfalls, and default fallback chains
- Update README.md to reference the guide in TOC, Just Install This
  section, and Features overview

README.md

@@ -115,6 +115,7 @@ Yes, technically possible. But I cannot recommend using it.
     - [🪄 The Magic Word: `ultrawork`](#-the-magic-word-ultrawork)
     - [For Those Who Want to Read: Meet Sisyphus](#for-those-who-want-to-read-meet-sisyphus)
       - [Just Install This](#just-install-this)
+    - [Which Model Should I Use?](#which-model-should-i-use)
     - [For Those Who Want Autonomy: Meet Hephaestus](#for-those-who-want-autonomy-meet-hephaestus)
   - [Installation](#installation)
     - [For Humans](#for-humans)
@@ -222,6 +223,10 @@ Need to look something up? It scours official docs, your entire codebase history
 
 If you don't want all this, as mentioned, you can just pick and choose specific features.
 
+#### Which Model Should I Use?
+
+New to oh-my-opencode and not sure which model to pair with which agent? Check the **[Agent-Model Matching Guide](docs/guide/agent-model-matching.md)** — a quick reference for newcomers covering recommended models, fallback chains, and common pitfalls for each agent.
+
 ### For Those Who Want Autonomy: Meet Hephaestus
 
 ![Meet Hephaestus](.github/assets/hephaestus.png)
@@ -307,6 +312,7 @@ See the full [Features Documentation](docs/features.md) for detailed information
 - **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search)
 - **Session Tools**: List, read, search, and analyze session history
 - **Productivity Features**: Ralph Loop, Todo Enforcer, Comment Checker, Think Mode, and more
+- **[Agent-Model Matching Guide](docs/guide/agent-model-matching.md)**: Which model works best with which agent
 
 ## Configuration
 

docs/guide/agent-model-matching.md

@@ -0,0 +1,166 @@
+# Agent-Model Matching Guide for Newcomers
+
+> **Quick Reference**: Which model to use with which agent for the best results
+
+This guide helps you match the right AI model to each oh-my-opencode agent based on real-world usage and testing.
+
+---
+
+## TL;DR
+
+| Agent | Best Models | Avoid |
+|-------|-------------|-------|
+| **Sisyphus** | Claude Opus, Sonnet, Kimi K2.5, GLM 5 | GPT ❌ |
+| **Hephaestus** | GPT-5.3-codex only | Non-GPT ❌ |
+| **Prometheus** | Claude Opus | GPT (untested) |
+| **Atlas** | Claude Opus, GPT-5.2+ | — |
+
+---
+
+## Detailed Breakdown
+
+### Sisyphus (ultraworker)
+**Purpose**: Primary orchestrator for complex multi-step tasks
+
+**Recommended Models** (in order of preference):
+1. **Claude Opus-4-6** — The best overall performance
+2. **Claude Sonnet-4-6** — Satisfiable, often better than pure Claude Code + Opus
+3. **Kimi K2.5** — Good for broad tasks, excellent cost-performance
+4. **GLM 5** — Good for various tasks, not as capable on broad tasks as Kimi
+5. **MiniMax** — Budget option when cost matters
+
+**⚠️ NEVER USE GPT** — Sisyphus is optimized for Claude-style models and performs poorly on GPT.
+
+**Configuration Example**:
+```json
+{
+  "agent": {
+    "sisyphus": {
+      "model": "anthropic/claude-opus-4-6",
+      "variant": "max"
+    }
+  }
+}
+```
+
+---
+
+### Hephaestus (deep worker)
+**Purpose**: Deep coding tasks requiring extensive reasoning
+
+**Required Model**: **GPT-5.3-codex** (always)
+
+Think of Hephaestus as "Codex on steroids" — it's specifically designed and tuned for GPT models.
+
+**⚠️ DO NOT USE** if you don't have GPT access. DeepSeek *might* work but is not officially supported.
+
+**Configuration Example**:
+```json
+{
+  "agent": {
+    "hephaestus": {
+      "model": "openai/gpt-5.3-codex",
+      "variant": "medium"
+    }
+  }
+}
+```
+
+---
+
+### Prometheus (planner)
+**Purpose**: Strategic planning and work plan generation
+
+**Recommended Model**: **Claude Opus-4-6** (strongly recommended)
+
+Prometheus is optimized for Claude's reasoning capabilities. GPT compatibility is not yet tested but may be evaluated in the future.
+
+**Configuration Example**:
+```json
+{
+  "agent": {
+    "plan": {
+      "model": "anthropic/claude-opus-4-6",
+      "variant": "max"
+    }
+  }
+}
+```
+
+---
+
+### Atlas (orchestrator)
+**Purpose**: Todo list orchestration and multi-agent coordination
+
+**Recommended Models**:
+1. **Claude Opus-4-6** — Best performance (recommended)
+2. **GPT-5.2+** — Good enough, has GPT-optimized prompt
+
+Atlas has model-specific prompt detection and will automatically use GPT-optimized instructions when running on GPT models.
+
+**Configuration Example**:
+```json
+{
+  "agent": {
+    "atlas": {
+      "model": "anthropic/claude-opus-4-6"
+    }
+  }
+}
+```
+
+---
+
+## Quick Decision Tree
+
+```
+Do you have GPT access?
+├── YES → Use Hephaestus for deep coding, Atlas for orchestration
+└── NO  → Use Sisyphus (Claude/Kimi/GLM) for all tasks
+
+Need planning/strategy?
+├── YES → Use Prometheus (Claude Opus recommended)
+└── NO  → Skip Prometheus, use other agents directly
+
+Complex multi-step task?
+├── YES → Use Sisyphus (Claude-family models)
+└── NO  → Use category-specific agents or Hephaestus
+```
+
+---
+
+## Common Pitfalls to Avoid
+
+1. **Don't use GPT with Sisyphus** — Performance will be subpar
+2. **Don't use non-GPT with Hephaestus** — It's specifically built for GPT
+3. **Don't force Prometheus on GPT** — It's untested; use Claude for now
+4. **Don't overthink Atlas** — It adapts automatically to your model
+
+---
+
+## Model Fallback Chains (Default Behavior)
+
+The system will automatically fall back through these chains if your preferred model is unavailable:
+
+**Sisyphus**: Opus → Kimi K2.5 → GLM 4.7 → Big Pickle
+**Hephaestus**: GPT-5.3-codex only (no fallback)
+**Prometheus**: Opus → Kimi K2.5 → GLM 4.7 → GPT-5.2 → Gemini 3 Pro
+**Atlas**: Kimi K2.5 → GLM 4.7 → Opus → GPT-5.2 → Gemini 3 Pro
+
+---
+
+## Tips for Newcomers
+
+- **Start with Sisyphus + Claude Opus** for general tasks
+- **Use Hephaestus when you need deep reasoning** (requires GPT)
+- **Try GLM 5 or Kimi K2.5** for cost-effective alternatives to Claude
+- **Check the model requirements** in your config to avoid mismatches
+- **Use `variant: "max"` or `variant: "high"`** for best results on capable models
+
+---
+
+## See Also
+
+- [AGENTS.md](../AGENTS.md) — Full agent documentation
+- [configurations.md](./configurations.md) — Configuration reference
+- [orchestration-guide.md](./orchestration-guide.md) — How orchestration works