diff --git a/CLAUDE.md b/CLAUDE.md
index c94857a..69e504e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,6 +14,29 @@ A high-performance Rust-based TUI player for playing music and video files. Buil
 
 ## Architecture
 
+### State Management
+
+**CRITICAL:** Player state must be derived from MPV, not maintained separately.
+
+**Single Source of Truth:** MPV properties via IPC
+- `idle-active` (bool) - No file loaded or file ended
+- `pause` (bool) - Playback is paused
+
+**Derive PlayerState:**
+```rust
+if player.is_idle → PlayerState::Stopped
+if !player.is_idle && player.is_paused → PlayerState::Paused
+if !player.is_idle && !player.is_paused → PlayerState::Playing
+```
+
+**Rationale:**
+- Eliminates state synchronization bugs
+- MPV is always the authoritative source
+- No need to update state in multiple places
+- Simpler auto-play logic
+
+**Anti-pattern:** DO NOT maintain `state.player_state` that can desync from MPV
+
 ### Cache-Only Operation
 
 **CRITICAL:** Left panel shows ONLY cached data. Never browse filesystem directly during operation.