diff --git a/README.md b/README.md
index 8368d909..23c1c63e 100644
--- a/README.md
+++ b/README.md
@@ -64,11 +64,12 @@ haiku-rag serve
 ```python
 from haiku.rag.client import HaikuRAG
 from haiku.rag.research import (
+    PlanNode,
     ResearchContext,
     ResearchDeps,
     ResearchState,
     build_research_graph,
-    PlanNode,
+    stream_research_graph,
 )
 
 async with HaikuRAG("database.lancedb") as client:
@@ -90,22 +91,40 @@ async with HaikuRAG("database.lancedb") as client:
 
     # Multi‑agent research pipeline (Plan → Search → Evaluate → Synthesize)
     graph = build_research_graph()
+    question = (
+        "What are the main drivers and trends of global temperature "
+        "anomalies since 1990?"
+    )
     state = ResearchState(
-        question=(
-            "What are the main drivers and trends of global temperature "
-            "anomalies since 1990?"
-        ),
-        context=ResearchContext(original_question="…"),
+        context=ResearchContext(original_question=question),
         max_iterations=2,
         confidence_threshold=0.8,
-        max_concurrency=3,
+        max_concurrency=2,
     )
     deps = ResearchDeps(client=client)
-    start = PlanNode(provider=None, model=None)
-    result = await graph.run(start, state=state, deps=deps)
-    report = result.output
-    print(report.title)
-    print(report.executive_summary)
+
+    # Blocking run (final result only)
+    result = await graph.run(
+        PlanNode(provider="openai", model="gpt-4o-mini"),
+        state=state,
+        deps=deps,
+    )
+    print(result.output.title)
+
+    # Streaming progress (log/report/error events)
+    async for event in stream_research_graph(
+        graph,
+        PlanNode(provider="openai", model="gpt-4o-mini"),
+        state,
+        deps,
+    ):
+        if event.type == "log":
+            iteration = event.state.iterations if event.state else state.iterations
+            print(f"[{iteration}] {event.message}")
+        elif event.type == "report":
+            print("\nResearch complete!\n")
+            print(event.report.title)
+            print(event.report.executive_summary)
 ```
 
 ## MCP Server
diff --git a/docs/agents.md b/docs/agents.md
index 59e314cc..5e6374ec 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -76,30 +76,75 @@ haiku-rag research "How does haiku.rag organize and query documents?" \
   --verbose
 ```
 
-Python usage:
+Python usage (blocking result):
 
 ```python
 from haiku.rag.client import HaikuRAG
 from haiku.rag.research import (
+    PlanNode,
     ResearchContext,
     ResearchDeps,
     ResearchState,
     build_research_graph,
-    PlanNode,
 )
 
 async with HaikuRAG(path_to_db) as client:
     graph = build_research_graph()
+    question = "What are the main drivers and trends of global temperature anomalies since 1990?"
     state = ResearchState(
-        question="What are the main drivers and trends of global temperature anomalies since 1990?",
-        context=ResearchContext(original_question=... ),
+        context=ResearchContext(original_question=question),
         max_iterations=2,
         confidence_threshold=0.8,
-        max_concurrency=3,
+        max_concurrency=2,
     )
     deps = ResearchDeps(client=client)
-    result = await graph.run(PlanNode(provider=None, model=None), state=state, deps=deps)
+
+    result = await graph.run(
+        PlanNode(provider="openai", model="gpt-4o-mini"),
+        state=state,
+        deps=deps,
+    )
+
     report = result.output
     print(report.title)
     print(report.executive_summary)
 ```
+
+Python usage (streamed events):
+
+```python
+from haiku.rag.client import HaikuRAG
+from haiku.rag.research import (
+    PlanNode,
+    ResearchContext,
+    ResearchDeps,
+    ResearchState,
+    build_research_graph,
+    stream_research_graph,
+)
+
+async with HaikuRAG(path_to_db) as client:
+    graph = build_research_graph()
+    question = "What are the main drivers and trends of global temperature anomalies since 1990?"
+    state = ResearchState(
+        context=ResearchContext(original_question=question),
+        max_iterations=2,
+        confidence_threshold=0.8,
+        max_concurrency=2,
+    )
+    deps = ResearchDeps(client=client)
+
+    async for event in stream_research_graph(
+        graph,
+        PlanNode(provider="openai", model="gpt-4o-mini"),
+        state,
+        deps,
+    ):
+        if event.type == "log":
+            iteration = event.state.iterations if event.state else state.iterations
+            print(f"[{iteration}] {event.message}")
+        elif event.type == "report":
+            print("\nResearch complete!\n")
+            print(event.report.title)
+            print(event.report.executive_summary)
+```
diff --git a/docs/cli.md b/docs/cli.md
index 4afc96aa..751d40e7 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -113,6 +113,8 @@ Flags:
 - `--max-concurrency`: number of sub-questions searched in parallel each iteration (default: 3)
 - `--verbose`: show planning, searching previews, evaluation summary, and stop reason
 
+When `--verbose` is set the CLI also consumes the internal research stream, printing every `log` event as agents progress through planning, search, evaluation, and synthesis. If you build your own integration, call `stream_research_graph` to access the same `log`, `report`, and `error` events and render them however you like while the graph is running.
+
 ## Server
 
 Start the MCP server: