From be98577d5e6c5f04fc2ef26db787b239561ca676 Mon Sep 17 00:00:00 2001
From: Robert Lippmann <robert.lippmann.development@gmail.com>
Date: Wed, 27 May 2026 16:31:44 -0400
Subject: [PATCH] docs: add controller preview example

---
 README.md                              | 20 +++++++++++++++++
 examples/08_controller_preview_diff.py | 30 ++++++++++++++++++++++++++
 examples/README.md                     |  6 ++++++
 examples/integrations/README.md        |  2 +-
 4 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 examples/08_controller_preview_diff.py

diff --git a/README.md b/README.md
index 35600c0..b61ffac 100644
--- a/README.md
+++ b/README.md
@@ -119,6 +119,26 @@ else:
     render(call_llm(user_input))
 ```
 
+Controller quick example:
+
+```python
+from context_compiler import create_engine, preview, state_diff, step
+
+engine = create_engine()
+
+before = engine.state
+dry_run = preview(engine, "prohibit peanuts")
+print(dry_run["would_mutate"])  # True
+planned_change = state_diff(before, dry_run["state_after"])
+print(planned_change["changed"])  # True
+
+after_preview = engine.state
+print(state_diff(before, after_preview)["changed"])  # False (preview does not mutate state)
+
+applied = step(engine, "prohibit peanuts")
+print(applied["decision"]["kind"])  # update
+```
+
 ## Installation
 
 Requirements:
diff --git a/examples/08_controller_preview_diff.py b/examples/08_controller_preview_diff.py
new file mode 100644
index 0000000..bfcd36a
--- /dev/null
+++ b/examples/08_controller_preview_diff.py
@@ -0,0 +1,30 @@
+"""Example 8: controller preview + state diff + apply flow."""
+
+from _util import print_decision_summary, print_state_summary
+
+from context_compiler import create_engine, preview, state_diff, step
+
+
+def main() -> None:
+    engine = create_engine()
+
+    state_before = engine.state
+    print_state_summary(state_before, "state before preview")
+
+    print("\nPreview: prohibit peanuts")
+    preview_result = preview(engine, "prohibit peanuts")
+    print("would_mutate:", preview_result["would_mutate"])
+    print_decision_summary(preview_result["decision"])
+
+    state_after_preview = engine.state
+    diff_after_preview = state_diff(state_before, state_after_preview)
+    print("state changed after preview:", diff_after_preview["changed"])
+
+    print("\nApply: prohibit peanuts")
+    step_result = step(engine, "prohibit peanuts")
+    print_decision_summary(step_result["decision"])
+    print_state_summary(step_result["state"], "state after step")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/README.md b/examples/README.md
index 19424c9..da8c127 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -40,3 +40,9 @@ Shows `compile_transcript(messages)` from a fresh engine and `engine.apply_trans
 
 Demonstrates explicit single-policy correction without `reset policies`.  
 Shows `prohibit peanuts` -> `remove policy peanuts` -> `use peanuts`.
+
+## 08_controller_preview_diff.py
+
+Shows controller-layer dry-run behavior with `preview(engine, user_input)`.  
+Shows structural state inspection with `state_diff(state_before, state_after)`.  
+Shows `step(engine, user_input)` after preview to apply the same input.
diff --git a/examples/integrations/README.md b/examples/integrations/README.md
index 5bdb26f..a1c611c 100644
--- a/examples/integrations/README.md
+++ b/examples/integrations/README.md
@@ -17,7 +17,7 @@ export OPENAI_API_KEY=...
 export PROVIDER=openai
 ```
 
-Checkpoint continuation in these integration examples requires `context-compiler>=0.6.14`.
+Checkpoint continuation in these integration examples requires `context-compiler>=0.7.0`.
 
 ### Run