diff --git a/AGENTS.md b/AGENTS.md
index 1e27efd9a..3cbc4561c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -116,7 +116,7 @@ oh-my-opencode/
 | Agent | Default Model | Purpose |
 |-------|-------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
-| oracle | openai/gpt-5.2 | Strategic advisor, code review |
+| oracle | openai/gpt-5.2 | Read-only consultation. High-IQ debugging, architecture |
 | librarian | anthropic/claude-sonnet-4-5 | Multi-repo analysis, docs |
 | explore | opencode/grok-code | Fast codebase exploration |
 | frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation |
diff --git a/src/features/builtin-commands/templates/refactor.ts b/src/features/builtin-commands/templates/refactor.ts
index 7c882b3d2..c1174982c 100644
--- a/src/features/builtin-commands/templates/refactor.ts
+++ b/src/features/builtin-commands/templates/refactor.ts
@@ -605,7 +605,7 @@ Use \`ast_grep_search\` and \`ast_grep_replace\` for structural transformations.
 ## Agents
 - \`explore\`: Parallel codebase pattern discovery
 - \`plan\`: Detailed refactoring plan generation
-- \`oracle\`: Consult for complex architectural decisions
+- \`oracle\`: Read-only consultation for complex architectural decisions and debugging
 - \`librarian\`: **Use proactively** when encountering deprecated methods or library migration tasks. Query official docs and OSS examples for modern replacements.
 
 ## Deprecated Code & Library Migration