docs: improve README with usage instructions

README.md

@@ -13,16 +13,18 @@ short_description: Epistemic stagnation detection via Bayesian surprise
 
 # 🧠 Epistemic Stagnation Monitor
 
-Feed a sequence of messages to the **EpiplexityMonitor** and watch how embedding novelty and perplexity combine to detect when an agent gets stuck repeating itself.
+Detect when an agent gets stuck repeating itself by combining embedding novelty and perplexity into a single "epiplexity" score -- like neural habituation signaling that a brain region has stopped learning.
 
-## Features
+## What to Try
 
-- **5 presets**: Healthy exploration, gradual stagnation, sudden loop, convergence, recovery
-- **Tunable parameters**: Alpha mixing, window size, threshold
-- **Real-time status**: HEALTHY → EXPLORING → CONVERGING → STAGNANT → CRITICAL
+1. Select a preset from the **Preset** dropdown (e.g. "Gradual stagnation" or "Sudden loop") and click **Run Monitor** to see how the epiplexity score evolves and health status transitions from HEALTHY through STAGNANT to CRITICAL.
+2. Adjust the **Alpha** slider to change the mix between embedding novelty and perplexity, then re-run to see how it affects detection sensitivity.
+3. Try the "Recovery" preset to see how the monitor detects stagnation and then recovers when novel messages resume.
 
 ## How It Works
 
-Each message is embedded and compared to the running window. **Epiplexity** = α × embedding_novelty + (1-α) × normalized_perplexity. When the integral of epiplexity drops below the threshold for `critical_duration` steps, the monitor flags stagnation.
+The EpiplexityMonitor embeds each message and compares it to a sliding window. Epiplexity combines embedding novelty with normalized perplexity -- when this score stays below the threshold for too long, the monitor flags stagnation, triggering healing interventions.
 
-[GitHub](https://github.com/coredipper/operon) | [PyPI](https://pypi.org/project/operon-ai/)
+## Learn More
+
+[GitHub](https://github.com/coredipper/operon) | [PyPI](https://pypi.org/project/operon-ai/) | [Paper](https://github.com/coredipper/operon/tree/main/article)

requirements.txt

@@ -1,2 +1,2 @@
 gradio>=4.0
-operon-ai>=0.14.0
+operon-ai>=0.15.0