Add REPL usage documentation and fix raw mode handling

- Fix raw mode enabling to not duplicate with UI border mode
- Add REPL_USAGE.md with comprehensive guide
- Add examples/repl_demo_terminal.py example script

REPL_USAGE.md

@@ -0,0 +1,116 @@
+# REPL Usage Guide
+
+The REPL (Read-Eval-Print Loop) effect provides an interactive command-line interface for controlling Mainline's pipeline in real-time.
+
+## How to Access the REPL
+
+### Method 1: Using CLI Arguments (Recommended)
+
+Run Mainline with the `repl` effect added to the effects list:
+
+```bash
+# With empty source (for testing)
+python mainline.py --pipeline-source empty --pipeline-effects repl
+
+# With headlines source (requires network)
+python mainline.py --pipeline-source headlines --pipeline-effects repl
+
+# With poetry source
+python mainline.py --pipeline-source poetry --pipeline-effects repl
+```
+
+### Method 2: Using a Preset
+
+Add a preset to your `~/.config/mainline/presets.toml` or `./presets.toml`:
+
+```toml
+[presets.repl]
+description = "Interactive REPL control"
+source = "headlines"
+display = "terminal"
+effects = ["repl"]
+viewport_width = 80
+viewport_height = 24
+```
+
+Then run:
+```bash
+python mainline.py --preset repl
+```
+
+### Method 3: Using Graph Config
+
+Create a TOML file (e.g., `repl_config.toml`):
+
+```toml
+source = "empty"
+display = "terminal"
+effects = ["repl"]
+```
+
+Then run:
+```bash
+python mainline.py --graph-config repl_config.toml
+```
+
+## REPL Commands
+
+Once the REPL is active, you can type commands:
+
+- **help** - Show available commands
+- **status** - Show pipeline status and metrics
+- **effects** - List all effects in the pipeline
+- **effect \<name\> \<on|off\>** - Toggle an effect
+- **param \<effect\> \<param\> \<value\>** - Set effect parameter
+- **pipeline** - Show current pipeline order
+- **clear** - Clear output buffer
+- **quit/exit** - Show exit message (use Ctrl+C to actually exit)
+
+## Keyboard Controls
+
+- **Enter** - Execute command
+- **Up/Down arrows** - Navigate command history
+- **Backspace** - Delete last character
+- **Ctrl+C** - Exit Mainline
+
+## Visual Features
+
+The REPL displays:
+- **HUD header** (top 3 lines): Shows FPS, frame time, command count, and output buffer size
+- **Content area**: Main content from the data source
+- **Separator line**: Visual divider
+- **REPL area**: Output buffer and input prompt
+
+## Example Session
+
+```
+MAINLINE REPL | FPS: 60.0 | 12.5ms
+COMMANDS: 3 | [2/3]
+OUTPUT: 5 lines
+────────────────────────────────────────
+Content from source appears here...
+More content...
+────────────────────────────────────────
+> help
+Available commands:
+  help - Show this help
+  status - Show pipeline status
+  effects - List all effects
+  effect <name> <on|off> - Toggle effect
+  param <effect> <param> <value> - Set parameter
+  pipeline - Show current pipeline order
+  clear - Clear output buffer
+  quit - Show exit message
+> effects
+Pipeline effects:
+  1. repl
+> effect repl off
+Effect 'repl' set to off
+```
+
+## Notes
+
+- The REPL effect needs a content source to overlay on (e.g., headlines, poetry, empty)
+- The REPL uses terminal display with raw input mode
+- Command history is preserved across sessions (up to 50 commands)
+- Pipeline mutations (enabling/disabling effects) are handled automatically

engine/app/main.py

@@ -478,7 +478,8 @@ def run_pipeline_mode_direct():
             break
 
     # Enable raw mode for REPL if present and not already enabled
-    if repl_effect and hasattr(display, "set_raw_mode"):
+    # Also enable for UI border mode (already handled above)
+    if repl_effect and ui_panel is None and hasattr(display, "set_raw_mode"):
         display.set_raw_mode(True)
 
     # Run pipeline loop

examples/repl_demo_terminal.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+REPL Demo with Terminal Display - Shows how to use the REPL effect
+
+Usage:
+    python examples/repl_demo_terminal.py
+
+This demonstrates the REPL effect with terminal display and interactive input.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from engine.effects.plugins import discover_plugins
+from engine.pipeline.hybrid_config import PipelineConfig
+
+
+def main():
+    """Run REPL demo with terminal display."""
+    print("REPL Demo with Terminal Display")
+    print("=" * 50)
+
+    # Discover plugins
+    discover_plugins()
+
+    # Create a pipeline with REPL effect
+    # Using empty source so there's content to overlay on
+    config = PipelineConfig(
+        source="empty",
+        effects=[{"name": "repl", "intensity": 1.0}],
+        display="terminal",
+    )
+
+    pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
+
+    # Initialize pipeline
+    if not pipeline.initialize():
+        print("Failed to initialize pipeline")
+        return
+
+    print("\nREPL is now active!")
+    print("Try typing commands:")
+    print("  help - Show available commands")
+    print("  status - Show pipeline status")
+    print("  effects - List all effects")
+    print("  pipeline - Show current pipeline order")
+    print("  clear - Clear output buffer")
+    print("\nPress Ctrl+C to exit")
+
+
+if __name__ == "__main__":
+    main()