diff --git a/.opencode/agents/tier4-qa.md b/.opencode/agents/tier4-qa.md
index 0f8cd1e2..51619f6e 100644
--- a/.opencode/agents/tier4-qa.md
+++ b/.opencode/agents/tier4-qa.md
@@ -21,6 +21,18 @@ ONLY output the requested analysis. No pleasantries.
 You operate statelessly. Each analysis starts fresh.
 Do not assume knowledge from previous analyses or sessions.
 
+## Architecture Reference
+
+When analyzing errors, trace data flow through thread domains documented in:
+- `docs/guide_architecture.md`: Thread domains, event system, AI client, HITL mechanism
+- `docs/guide_mma.md`: 4-tier orchestration, DAG engine, worker lifecycle
+
+Key threading model:
+- GUI main thread: UI rendering only
+- asyncio worker thread: AI communication
+- HookServer thread: API hook handling
+- NEVER write GUI state from background threads
+
 ## CRITICAL: MCP Tools Only (Native Tools Banned)
 
 You MUST use Manual Slop's MCP tools. Native OpenCode tools are unreliable.