diff --git a/AGENTS.md b/AGENTS.md
index af28f760..2c12d29a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,25 +1,25 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-01-20T17:18:00+09:00
-**Commit:** 3d3d3e49
+**Generated:** 2026-01-22T22:25:00+09:00
+**Commit:** 85bf266f
 **Branch:** dev
 
 ## OVERVIEW
 
-ClaudeCode plugin implementing multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, Claude Code compatibility layer. "oh-my-zsh" for ClaudeCode.
+OpenCode plugin implementing multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
 
 ## STRUCTURE
 
 ```
 oh-my-opencode/
 ├── src/
-│   ├── agents/        # 10 AI agents (Sisyphus, oracle, librarian, explore, frontend, etc.) - see src/agents/AGENTS.md
+│   ├── agents/        # 10 AI agents (Sisyphus, oracle, librarian, explore, etc.) - see src/agents/AGENTS.md
 │   ├── hooks/         # 31 lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) - see src/hooks/AGENTS.md
 │   ├── tools/         # 20+ tools (LSP, AST-Grep, delegation, session) - see src/tools/AGENTS.md
 │   ├── features/      # Background agents, Claude Code compat layer - see src/features/AGENTS.md
-│   ├── shared/        # 43 cross-cutting utilities - see src/shared/AGENTS.md
+│   ├── shared/        # 50 cross-cutting utilities - see src/shared/AGENTS.md
 │   ├── cli/           # CLI installer, doctor, run - see src/cli/AGENTS.md
-│   ├── mcp/           # Built-in MCPs: websearch, context7, grep_app
+│   ├── mcp/           # Built-in MCPs: websearch, context7, grep_app - see src/mcp/AGENTS.md
 │   ├── config/        # Zod schema, TypeScript types
 │   └── index.ts       # Main plugin entry (589 lines)
 ├── script/            # build-schema.ts, publish.ts, build-binaries.ts
@@ -40,11 +40,11 @@ oh-my-opencode/
 | AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
 | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
 | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
-| Background agents | `src/features/background-agent/` | manager.ts (1165 lines) for task lifecycle |
+| Background agents | `src/features/background-agent/` | manager.ts (1335 lines) for task lifecycle |
 | Skill MCP | `src/features/skill-mcp-manager/` | MCP servers embedded in skills |
-| CLI installer | `src/cli/install.ts` | Interactive TUI (462 lines) |
+| CLI installer | `src/cli/install.ts` | Interactive TUI (520 lines) |
 | Doctor checks | `src/cli/doctor/checks/` | 14 health checks across 6 categories |
-| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
+| Orchestrator hook | `src/hooks/atlas/` | Main orchestration hook (771 lines) |
 
 ## TDD (Test-Driven Development)
 
@@ -144,14 +144,14 @@ bun test               # Run tests (83 test files)
 | File | Lines | Description |
 |------|-------|-------------|
 | `src/agents/atlas.ts` | 1383 | Orchestrator agent, 7-section delegation, wisdom accumulation |
+| `src/features/background-agent/manager.ts` | 1335 | Task lifecycle, concurrency, notification batching |
 | `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (playwright, git-master, frontend-ui-ux) |
 | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, Momus loop |
-| `src/features/background-agent/manager.ts` | 1165 | Task lifecycle, concurrency, notification batching |
+| `src/tools/delegate-task/tools.ts` | 1027 | Category-based task delegation |
 | `src/hooks/atlas/index.ts` | 771 | Orchestrator hook implementation |
-| `src/tools/delegate-task/tools.ts` | 770 | Category-based task delegation |
-| `src/cli/config-manager.ts` | 616 | JSONC parsing, multi-level config |
-| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
+| `src/cli/config-manager.ts` | 641 | JSONC parsing, multi-level config |
 | `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
+| `src/agents/sisyphus.ts` | 615 | Main Sisyphus prompt |
 | `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC |
 
 ## MCP ARCHITECTURE
@@ -171,7 +171,7 @@ Three-tier MCP system:
 ## NOTES
 
 - **Testing**: Bun native test (`bun test`), BDD-style, 83 test files
-- **ClaudeCode**: Requires >= 1.0.150
+- **OpenCode**: Requires >= 1.0.150
 - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
 - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
 - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
diff --git a/docs/configurations.md b/docs/configurations.md
index 30b6e182..7023c873 100644
--- a/docs/configurations.md
+++ b/docs/configurations.md
@@ -308,268 +308,128 @@ Add custom categories in `oh-my-opencode.json`:
 
 Each category supports: `model`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `tools`, `prompt_append`.
 
-## Model Selection System
+## Model Resolution System
 
-The installer automatically configures optimal models based on your subscriptions. This section explains how models are selected for each agent and category.
+At runtime, Oh My OpenCode uses a 3-step resolution process to determine which model to use for each agent and category. This happens dynamically based on your configuration and available models.
 
 ### Overview
 
-**Problem**: Users have different subscription combinations (Claude, OpenAI, Gemini, etc.). The system needs to automatically select the best available model for each task.
+**Problem**: Users have different provider configurations. The system needs to select the best available model for each task at runtime.
 
-**Solution**: A tiered fallback system that:
-1. Prioritizes native provider subscriptions (Claude, OpenAI, Gemini)
-2. Falls back through alternative providers in priority order
-3. Applies capability-specific logic (e.g., Oracle prefers GPT, visual tasks prefer Gemini)
+**Solution**: A simple 3-step resolution flow:
+1. **Step 1: User Override** — If you specify a model in `oh-my-opencode.json`, use exactly that
+2. **Step 2: Provider Fallback** — Try each provider in the requirement's priority order until one is available
+3. **Step 3: System Default** — Fall back to OpenCode's configured default model
 
-### Provider Priority
+### Resolution Flow
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│                     MODEL SELECTION FLOW                        │
+│                     MODEL RESOLUTION FLOW                        │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
+│   Step 1: USER OVERRIDE                                         │
 │   ┌─────────────────────────────────────────────────────────┐   │
-│   │              TIER 1: NATIVE PROVIDERS                   │   │
-│   │         (Your direct subscriptions)                     │   │
-│   │                                                         │   │
-│   │   Claude (anthropic/) ──► OpenAI (openai/) ──► Gemini   │   │
-│   │         │                      │              (google/) │   │
-│   │         ▼                      ▼                   │    │   │
-│   │   Opus/Sonnet/Haiku    GPT-5.2/Codex      Gemini 3 Pro │   │
+│   │ User specified model in oh-my-opencode.json?            │   │
+│   │         YES → Use exactly as specified                  │   │
+│   │         NO  → Continue to Step 2                        │   │
 │   └─────────────────────────────────────────────────────────┘   │
 │                              │                                  │
-│                              ▼ (if no native available)         │
+│                              ▼                                  │
+│   Step 2: PROVIDER PRIORITY FALLBACK                            │
 │   ┌─────────────────────────────────────────────────────────┐   │
-│   │              TIER 2: OPENCODE ZEN                       │   │
-│   │         (opencode/ prefix models)                       │   │
+│   │ For each provider in requirement.providers order:       │   │
 │   │                                                         │   │
-│   │   opencode/claude-opus-4-5, opencode/gpt-5.2, etc.      │   │
+│   │ Example for Sisyphus:                                   │   │
+│   │ anthropic → github-copilot → opencode → antigravity     │   │
+│   │     │            │              │            │          │   │
+│   │     ▼            ▼              ▼            ▼          │   │
+│   │ Try: anthropic/claude-opus-4-5                          │   │
+│   │ Try: github-copilot/claude-opus-4-5                     │   │
+│   │ Try: opencode/claude-opus-4-5                           │   │
+│   │ ...                                                     │   │
+│   │                                                         │   │
+│   │ Found in available models? → Return matched model       │   │
+│   │ Not found? → Try next provider                          │   │
 │   └─────────────────────────────────────────────────────────┘   │
 │                              │                                  │
-│                              ▼ (if no OpenCode Zen)             │
+│                              ▼ (all providers exhausted)        │
+│   Step 3: SYSTEM DEFAULT                                        │
 │   ┌─────────────────────────────────────────────────────────┐   │
-│   │              TIER 3: GITHUB COPILOT                     │   │
-│   │         (github-copilot/ prefix models)                 │   │
-│   │                                                         │   │
-│   │   github-copilot/claude-opus-4.5, etc.                  │   │
-│   └─────────────────────────────────────────────────────────┘   │
-│                              │                                  │
-│                              ▼ (if no Copilot)                  │
-│   ┌─────────────────────────────────────────────────────────┐   │
-│   │              TIER 4: Z.AI CODING PLAN                   │   │
-│   │         (zai-coding-plan/ prefix models)                │   │
-│   │                                                         │   │
-│   │   zai-coding-plan/glm-4.7 (GLM models only)             │   │
-│   └─────────────────────────────────────────────────────────┘   │
-│                              │                                  │
-│                              ▼ (ultimate fallback)              │
-│   ┌─────────────────────────────────────────────────────────┐   │
-│   │              FALLBACK: FREE TIER                        │   │
-│   │                                                         │   │
-│   │   opencode/glm-4.7-free                                 │   │
+│   │ Return systemDefaultModel (from opencode.json)          │   │
 │   └─────────────────────────────────────────────────────────┘   │
 │                                                                 │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-### Native Tier Cross-Fallback
+### Agent Provider Chains
 
-Within the Native tier, models fall back based on capability requirements:
+Each agent has a defined provider priority chain. The system tries providers in order until it finds an available model:
 
-| Capability | 1st Choice | 2nd Choice | 3rd Choice |
-|------------|------------|------------|------------|
-| **High-tier tasks** (Sisyphus, Atlas) | Claude Opus | OpenAI GPT-5.2 | Gemini 3 Pro |
-| **Standard tasks** | Claude Sonnet | OpenAI GPT-5.2 | Gemini 3 Flash |
-| **Quick tasks** | Claude Haiku | OpenAI GPT-5.1-mini | Gemini 3 Flash |
-| **Deep reasoning** (Oracle) | OpenAI GPT-5.2-Codex | Claude Opus | Gemini 3 Pro |
-| **Visual/UI tasks** | Gemini 3 Pro | OpenAI GPT-5.2 | Claude Sonnet |
-| **Writing tasks** | Gemini 3 Flash | OpenAI GPT-5.2 | Claude Sonnet |
+| Agent | Model (no prefix) | Provider Priority Chain |
+|-------|-------------------|-------------------------|
+| **Sisyphus** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **oracle** | `gpt-5.2` | openai → anthropic → google → github-copilot → opencode |
+| **librarian** | `glm-4.7-free` | opencode → github-copilot → anthropic |
+| **explore** | `grok-code` | opencode → anthropic → github-copilot |
+| **multimodal-looker** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
+| **Prometheus (Planner)** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **Metis (Plan Consultant)** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **Momus (Plan Reviewer)** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **Atlas** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
 
-### Agent-Specific Rules
+### Category Provider Chains
 
-#### Standard Agents
+Categories follow the same resolution logic:
 
-| Agent | Capability | Example (Claude + OpenAI + Gemini) |
-|-------|------------|-------------------------------------|
-| **Sisyphus** | High-tier (isMax20) or Standard | `anthropic/claude-opus-4-5` or `anthropic/claude-sonnet-4-5` |
-| **Oracle** | Deep reasoning | `openai/gpt-5.2-codex` |
-| **Prometheus** | High-tier/Standard | Same as Sisyphus |
-| **Metis** | High-tier/Standard | Same as Sisyphus |
-| **Momus** | Deep reasoning | `openai/gpt-5.2-codex` |
-| **Atlas** | High-tier/Standard | Same as Sisyphus |
-| **multimodal-looker** | Visual | `google/gemini-3-pro-preview` |
+| Category | Model (no prefix) | Provider Priority Chain |
+|----------|-------------------|-------------------------|
+| **visual-engineering** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
+| **ultrabrain** | `gpt-5.2-codex` | openai → anthropic → google → github-copilot → opencode |
+| **artistry** | `gemini-3-pro-preview` | google → openai → anthropic → github-copilot → opencode |
+| **quick** | `claude-haiku-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **unspecified-low** | `claude-sonnet-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **unspecified-high** | `claude-opus-4-5` | anthropic → github-copilot → opencode → antigravity → google |
+| **writing** | `gemini-3-flash-preview` | google → openai → anthropic → github-copilot → opencode |
 
-#### Special Case: explore Agent
+### Checking Your Configuration
 
-The `explore` agent has unique logic for cost optimization:
+Use the `doctor` command to see how models resolve with your current configuration:
 
-```
-┌────────────────────────────────────────┐
-│           EXPLORE AGENT LOGIC          │
-├────────────────────────────────────────┤
-│                                        │
-│   Has Claude + isMax20?                │
-│         │                              │
-│    YES  │  NO                          │
-│    ▼    │  ▼                           │
-│ ┌──────┐│┌────────────────────┐        │
-│ │Haiku ││ │ opencode/grok-code │        │
-│ │4.5   │││ (free & fast)       │        │
-│ └──────┘│└────────────────────┘        │
-│                                        │
-│ Rationale:                             │
-│ • max20 users want to use Claude quota │
-│ • Others save quota with free grok     │
-└────────────────────────────────────────┘
+```bash
+bunx oh-my-opencode doctor --verbose
 ```
 
-#### Special Case: librarian Agent
-
-The `librarian` agent prioritizes Z.ai when available:
-
-```
-┌────────────────────────────────────────┐
-│          LIBRARIAN AGENT LOGIC         │
-├────────────────────────────────────────┤
-│                                        │
-│   Has Z.ai Coding Plan?                │
-│         │                              │
-│    YES  │  NO                          │
-│    ▼    │  ▼                           │
-│ ┌──────────────┐ ┌──────────────────┐  │
-│ │zai-coding-   │ │ Normal fallback  │  │
-│ │plan/glm-4.7  │ │ chain applies    │  │
-│ └──────────────┘ └──────────────────┘  │
-│                                        │
-│ Rationale:                             │
-│ • GLM excels at documentation tasks    │
-│ • Z.ai provides dedicated GLM access   │
-└────────────────────────────────────────┘
-```
-
-### Category-Specific Rules
-
-Categories follow the same fallback logic as agents:
-
-| Category | Primary Capability | Fallback Chain |
-|----------|-------------------|----------------|
-| `visual-engineering` | Visual | Gemini → OpenAI → Claude |
-| `ultrabrain` | Deep reasoning | OpenAI → Claude → Gemini |
-| `artistry` | Visual/Creative | Gemini → OpenAI → Claude |
-| `quick` | Quick tasks | Claude Haiku → OpenAI mini → Gemini Flash |
-| `unspecified-low` | Standard | Claude Sonnet → OpenAI → Gemini Flash |
-| `unspecified-high` | High-tier | Claude Opus → OpenAI → Gemini Pro |
-| `writing` | Writing | Gemini Flash → OpenAI → Claude |
-
-### Subscription Scenarios
-
-#### Scenario 1: Claude Only (Standard Plan)
-
-```json
-// User has: Claude Pro (not max20)
-{
-  "agents": {
-    "Sisyphus": { "model": "anthropic/claude-sonnet-4-5" },
-    "oracle": { "model": "anthropic/claude-opus-4-5" },
-    "explore": { "model": "opencode/grok-code" },
-    "librarian": { "model": "opencode/glm-4.7-free" }
-  }
-}
-```
-
-#### Scenario 2: Claude Only (Max20 Plan)
-
-```json
-// User has: Claude Max (max20 mode)
-{
-  "agents": {
-    "Sisyphus": { "model": "anthropic/claude-opus-4-5" },
-    "oracle": { "model": "anthropic/claude-opus-4-5" },
-    "explore": { "model": "anthropic/claude-haiku-4-5" },
-    "librarian": { "model": "opencode/glm-4.7-free" }
-  }
-}
-```
-
-#### Scenario 3: ChatGPT Only
-
-```json
-// User has: OpenAI/ChatGPT Plus only
-{
-  "agents": {
-    "Sisyphus": { "model": "openai/gpt-5.2" },
-    "oracle": { "model": "openai/gpt-5.2-codex" },
-    "explore": { "model": "opencode/grok-code" },
-    "multimodal-looker": { "model": "openai/gpt-5.2" },
-    "librarian": { "model": "opencode/glm-4.7-free" }
-  }
-}
-```
-
-#### Scenario 4: Full Stack (Claude + OpenAI + Gemini)
-
-```json
-// User has: All native providers
-{
-  "agents": {
-    "Sisyphus": { "model": "anthropic/claude-opus-4-5" },
-    "oracle": { "model": "openai/gpt-5.2-codex" },
-    "explore": { "model": "anthropic/claude-haiku-4-5" },
-    "multimodal-looker": { "model": "google/gemini-3-pro-preview" },
-    "librarian": { "model": "opencode/glm-4.7-free" }
-  }
-}
-```
-
-#### Scenario 5: GitHub Copilot Only
-
-```json
-// User has: GitHub Copilot only (no native providers)
-{
-  "agents": {
-    "Sisyphus": { "model": "github-copilot/claude-sonnet-4.5" },
-    "oracle": { "model": "github-copilot/gpt-5.2-codex" },
-    "explore": { "model": "opencode/grok-code" },
-    "librarian": { "model": "github-copilot/gpt-5.2" }
-  }
-}
-```
-
-### isMax20 Flag Impact
-
-The `isMax20` flag (Claude Max 20x mode) affects high-tier task model selection:
-
-| isMax20 | High-tier Capability | Result |
-|---------|---------------------|--------|
-| `true` | Uses `unspecified-high` | Opus-class models |
-| `false` | Uses `unspecified-low` | Sonnet-class models |
-
-**Affected agents**: Sisyphus, Prometheus, Metis, Atlas
-
-**Why?**: Max20 users have 20x more Claude usage, so they can afford Opus for orchestration. Standard users should conserve quota with Sonnet.
+The "Model Resolution" check shows:
+- Each agent/category's model requirement
+- Provider fallback chain
+- User overrides (if configured)
+- Effective resolution path
 
 ### Manual Override
 
-You can always override automatic selection in `oh-my-opencode.json`:
+Override any agent or category model in `oh-my-opencode.json`:
 
 ```json
 {
   "agents": {
     "Sisyphus": {
-      "model": "anthropic/claude-sonnet-4-5"  // Force specific model
+      "model": "anthropic/claude-sonnet-4-5"
     },
     "oracle": {
-      "model": "openai/o3"  // Use different model
+      "model": "openai/o3"
     }
   },
   "categories": {
     "visual-engineering": {
-      "model": "anthropic/claude-opus-4-5"  // Override category default
+      "model": "anthropic/claude-opus-4-5"
     }
   }
 }
 ```
 
+When you specify a model override, it takes precedence (Step 1) and the provider fallback chain is skipped entirely.
+
 ## Hooks
 
 Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md
index 7a2e1a27..2d86b949 100644
--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@@ -2,16 +2,16 @@
 
 ## OVERVIEW
 
-8 AI agents for multi-model orchestration. Sisyphus (primary), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus.
+10 AI agents for multi-model orchestration. Sisyphus (primary), Atlas (orchestrator), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus, Sisyphus-Junior.
 
 ## STRUCTURE
 
 ```
 agents/
-├── atlas.ts    # Orchestrator (1383 lines) - 7-phase delegation
+├── atlas.ts                    # Master Orchestrator (1383 lines) - 7-phase delegation
 ├── sisyphus.ts                 # Main prompt (615 lines)
-├── sisyphus-junior.ts          # Delegated task executor
-├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation
+├── sisyphus-junior.ts          # Delegated task executor (136 lines)
+├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation (360 lines)
 ├── oracle.ts                   # Strategic advisor (GPT-5.2)
 ├── librarian.ts                # Multi-repo research (GLM-4.7-free)
 ├── explore.ts                  # Fast grep (Grok Code)
@@ -19,8 +19,8 @@ agents/
 ├── prometheus-prompt.ts        # Planning (1196 lines) - interview mode
 ├── metis.ts                    # Plan consultant - pre-planning analysis
 ├── momus.ts                    # Plan reviewer - validation
-├── types.ts                    # AgentModelConfig interface
-├── utils.ts                    # createBuiltinAgents(), getAgentName()
+├── types.ts                    # AgentModelConfig, AgentPromptMetadata
+├── utils.ts                    # createBuiltinAgents(), resolveModelWithFallback()
 └── index.ts                    # builtinAgents export
 ```
 
@@ -29,18 +29,20 @@ agents/
 | Agent | Model | Temperature | Purpose |
 |-------|-------|-------------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator, todo-driven |
+| Atlas | anthropic/claude-opus-4-5 | 0.1 | Master orchestrator, delegate_task |
 | oracle | openai/gpt-5.2 | 0.1 | Read-only consultation, debugging |
 | librarian | opencode/glm-4.7-free | 0.1 | Docs, GitHub search, OSS examples |
 | explore | opencode/grok-code | 0.1 | Fast contextual grep |
 | multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis |
 | Prometheus | anthropic/claude-opus-4-5 | 0.1 | Strategic planning, interview mode |
-| Metis | anthropic/claude-sonnet-4-5 | 0.1 | Pre-planning gap analysis |
+| Metis | anthropic/claude-sonnet-4-5 | 0.3 | Pre-planning gap analysis |
 | Momus | anthropic/claude-sonnet-4-5 | 0.1 | Plan validation |
+| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
 
 ## HOW TO ADD
 
-1. Create `src/agents/my-agent.ts` exporting `AgentConfig`
-2. Add to `builtinAgents` in `src/agents/index.ts`
+1. Create `src/agents/my-agent.ts` exporting factory + metadata
+2. Add to `agentSources` in `src/agents/utils.ts`
 3. Update `AgentNameSchema` in `src/config/schema.ts`
 4. Register in `src/index.ts` initialization
 
@@ -51,17 +53,20 @@ agents/
 | oracle | write, edit, task, delegate_task |
 | librarian | write, edit, task, delegate_task, call_omo_agent |
 | explore | write, edit, task, delegate_task, call_omo_agent |
-| multimodal-looker | Allowlist: read, glob, grep |
+| multimodal-looker | Allowlist: read only |
+| Sisyphus-Junior | task, delegate_task (cannot spawn implementation agents) |
 
 ## KEY PATTERNS
 
 - **Factory**: `createXXXAgent(model?: string): AgentConfig`
-- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata`
-- **Tool restrictions**: `permission: { edit: "deny", bash: "ask" }`
-- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus
+- **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata` with category, cost, triggers
+- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
+- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
+- **Model-specific**: GPT uses `reasoningEffort`, Anthropic uses `thinking` budget
 
 ## ANTI-PATTERNS
 
 - **Trust reports**: NEVER trust subagent "I'm done" - verify outputs
 - **High temp**: Don't use >0.3 for code agents
 - **Sequential calls**: Use `delegate_task` with `run_in_background`
+- **Missing metadata**: Every agent needs `XXX_PROMPT_METADATA` export
diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md
index cd1096a3..7a63a1c2 100644
--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@@ -9,8 +9,8 @@ CLI entry point: `bunx oh-my-opencode`. Interactive installer, doctor diagnostic
 ```
 cli/
 ├── index.ts              # Commander.js entry, 5 subcommands
-├── install.ts            # Interactive TUI installer (462 lines)
-├── config-manager.ts     # JSONC parsing, multi-level merge (730 lines)
+├── install.ts            # Interactive TUI installer (520 lines)
+├── config-manager.ts     # JSONC parsing, multi-level merge (641 lines)
 ├── types.ts              # InstallArgs, InstallConfig, DetectedConfig
 ├── doctor/
 │   ├── index.ts          # Doctor command entry
@@ -18,7 +18,7 @@ cli/
 │   ├── formatter.ts      # Colored output, symbols
 │   ├── constants.ts      # Check IDs, categories, symbols
 │   ├── types.ts          # CheckResult, CheckDefinition
-│   └── checks/           # 14 checks across 6 categories
+│   └── checks/           # 14 checks across 6 categories (21 files)
 │       ├── version.ts    # OpenCode + plugin version
 │       ├── config.ts     # JSONC validity, Zod validation
 │       ├── auth.ts       # Anthropic, OpenAI, Google
diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md
index cda5564c..65581add 100644
--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@@ -8,11 +8,11 @@ Core feature modules + Claude Code compatibility layer. Background agents, skill
 
 ```
 features/
-├── background-agent/           # Task lifecycle (1165 lines manager.ts)
+├── background-agent/           # Task lifecycle (1335 lines manager.ts)
 │   ├── manager.ts              # Launch → poll → complete orchestration
 │   ├── concurrency.ts          # Per-provider/model limits
 │   └── types.ts                # BackgroundTask, LaunchInput
-├── skill-mcp-manager/          # MCP client lifecycle
+├── skill-mcp-manager/          # MCP client lifecycle (520 lines)
 │   ├── manager.ts              # Lazy loading, idle cleanup
 │   └── types.ts                # SkillMcpConfig, transports
 ├── builtin-skills/             # Playwright, git-master, frontend-ui-ux
@@ -24,7 +24,7 @@ features/
 ├── claude-code-mcp-loader/     # .mcp.json with ${VAR} expansion
 ├── claude-code-plugin-loader/  # installed_plugins.json
 ├── claude-code-session-state/  # Session state persistence
-├── opencode-skill-loader/      # Skills from 6 directories
+├── opencode-skill-loader/      # Skills from 6 directories (12 files)
 ├── context-injector/           # AGENTS.md/README.md injection
 ├── boulder-state/              # Todo state persistence
 ├── task-toast-manager/         # Toast notifications
diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md
index 8325b5b7..9b402efd 100644
--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -12,7 +12,7 @@ hooks/
 ├── anthropic-context-window-limit-recovery/  # Auto-summarize at token limit
 ├── todo-continuation-enforcer.ts # Force TODO completion
 ├── ralph-loop/                 # Self-referential dev loop until done
-├── claude-code-hooks/          # settings.json hook compat layer (13 files)
+├── claude-code-hooks/          # settings.json hook compat layer (14 files) - see AGENTS.md
 ├── comment-checker/            # Prevents AI slop/excessive comments
 ├── auto-slash-command/         # Detects /command patterns
 ├── rules-injector/             # Conditional rules from .claude/rules/
@@ -26,6 +26,9 @@ hooks/
 ├── think-mode/                 # Dynamic thinking budget
 ├── keyword-detector/           # ultrawork/search/analyze modes
 ├── background-notification/    # OS notification on task completion
+├── prometheus-md-only/         # Enforces planner read-only mode
+├── agent-usage-reminder/       # Reminds to use specialized agents
+├── auto-update-checker/        # Checks for plugin updates
 └── tool-output-truncator.ts    # Prevents context bloat
 ```
 
diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md
index 7add35f5..0690bbe6 100644
--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## OVERVIEW
 
-43 cross-cutting utilities: path resolution, token truncation, config parsing, Claude Code compatibility.
+50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution, Claude Code compatibility.
 
 ## STRUCTURE
 
@@ -22,6 +22,11 @@ shared/
 ├── env-expander.ts        # ${VAR} expansion in configs
 ├── system-directive.ts    # System directive types
 ├── hook-utils.ts          # Hook helper functions
+├── model-requirements.ts  # Agent/Category model requirements (providers + model)
+├── model-availability.ts  # Available models fetch + fuzzy matching
+├── model-resolver.ts      # 3-step model resolution (override → provider fallback → default)
+├── shell-env.ts           # Cross-platform shell environment
+├── prompt-parts-helper.ts # Prompt parts manipulation
 └── *.test.ts              # Test files (colocated)
 ```
 
@@ -37,6 +42,11 @@ shared/
 | Resolve paths | `getOpenCodeConfigDir()`, `getClaudeConfigDir()` |
 | Migrate config | `migrateConfigFile(path, rawConfig)` |
 | Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` |
+| Get agent model requirements | `AGENT_MODEL_REQUIREMENTS` in `model-requirements.ts` |
+| Get category model requirements | `CATEGORY_MODEL_REQUIREMENTS` in `model-requirements.ts` |
+| Resolve model with fallback | `resolveModelWithFallback()` in `model-resolver.ts` |
+| Fuzzy match model names | `fuzzyMatchModel()` in `model-availability.ts` |
+| Fetch available models | `fetchAvailableModels(client)` in `model-availability.ts` |
 
 ## KEY PATTERNS
 
@@ -52,6 +62,9 @@ if (isOpenCodeVersionAtLeast("1.1.0")) { /* new feature */ }
 
 // Tool permission normalization
 const permissions = migrateToolsToPermission(legacyTools)
+
+// Model resolution with fallback chain
+const model = await resolveModelWithFallback(client, requirements, override)
 ```
 
 ## ANTI-PATTERNS
diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md
index 03c602e4..7b5c2bed 100644
--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## OVERVIEW
 
-20+ tools: LSP (11), AST-Grep (2), Search (2), Session (4), Agent delegation (3), System (2). High-performance C++ bindings via @ast-grep/napi.
+20+ tools: LSP (6), AST-Grep (2), Search (2), Session (4), Agent delegation (4), System (2), Skill (3). High-performance C++ bindings via @ast-grep/napi.
 
 ## STRUCTURE
 
@@ -13,9 +13,9 @@ tools/
 │   ├── tools.ts      # Business logic, ToolDefinition
 │   ├── types.ts      # Zod schemas
 │   └── constants.ts  # Fixed values, descriptions
-├── lsp/              # 11 tools: goto_definition, references, symbols, diagnostics, rename
+├── lsp/              # 6 tools: goto_definition, references, symbols, diagnostics, prepare_rename, rename
 ├── ast-grep/         # 2 tools: search, replace (25 languages via NAPI)
-├── delegate-task/    # Category-based agent routing (761 lines)
+├── delegate-task/    # Category-based agent routing (1027 lines)
 ├── session-manager/  # 4 tools: list, read, search, info
 ├── grep/             # Custom grep with timeout/truncation
 ├── glob/             # Custom glob with 60s timeout, 100 file limit