docs: align Studio extension architecture guides

Author: hyperb1iss

docs/extending/index.md

@@ -107,9 +107,11 @@ The LLM makes intelligent decisions—avoid hardcoded heuristics. Let Iris explo
 
 Tools should be focused and composable. Each tool does one thing well. Iris orchestrates them.
 
-### 3. Pure Reducer Pattern (Studio)
+### 3. Reducer-Centric Event Flow (Studio)
 
-State transitions are pure functions: `(state, event) → (state, effects)`. Side effects are data, not execution.
+Studio still uses a central reducer for shared workflows and explicit side effects, but it is not a
+fully pure reducer architecture end-to-end. Handlers and `StudioApp` also perform some direct UI
+and coordination updates.
 
 ### 4. Structured Output
 

docs/extending/modes.md

@@ -18,16 +18,16 @@ Each mode has:
 2. **Handler** — Input processing logic
 3. **Renderer** — UI drawing code
 
-## Architecture: Pure Reducer Pattern
+## Architecture: Reducer-Centric Event Flow
 
-Studio uses a predictable state management pattern:
+Studio uses a predictable reducer-centered state management pattern:
 
 ```
 Input Event
     ↓
 Handler (maps input → StudioEvent)
     ↓
-Reducer (pure function: state + event → new state + side effects)
+Reducer (central state/event layer)
     ↓
 Side Effects (spawn agent, load data, etc.)
     ↓
@@ -36,7 +36,9 @@ State Updated
 Renderer (draw UI from state)
 ```
 
-**Key principle**: State transitions are pure functions. Side effects are returned as data, not executed directly.
+**Key principle**: The reducer remains the shared event-processing core, but Studio is not a fully
+pure reducer architecture end-to-end. Handlers and `StudioApp` still apply some immediate UI and
+coordination updates directly, while reducer-driven flows return explicit side effects as data.
 
 ## Step-by-Step: Adding a New Mode
 

tests/studio_docs_guidance_tests.rs

@@ -0,0 +1,27 @@
+#![allow(clippy::unwrap_used)]
+
+use std::fs;
+
+const STUDIO_GUIDE_PATHS: &[&str] = &["docs/extending/index.md", "docs/extending/modes.md"];
+
+#[test]
+fn studio_extension_guides_no_longer_claim_a_pure_reducer_architecture() {
+    for path in STUDIO_GUIDE_PATHS {
+        let doc = fs::read_to_string(path).unwrap();
+        assert!(
+            !doc.contains("Pure Reducer Pattern"),
+            "{path} still teaches the old pure reducer story"
+        );
+        assert!(
+            !doc.contains("State transitions are pure functions"),
+            "{path} still claims Studio is fully pure end-to-end"
+        );
+        assert!(
+            doc.contains("reducer")
+                && doc.contains("not a")
+                && doc.contains("fully")
+                && doc.contains("pure reducer architecture"),
+            "{path} should describe Studio as reducer-centric but not fully pure"
+        );
+    }
+}