diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index d89da61..232e515 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -286,3 +286,29 @@ Records point at files via `file_path`. Those files live on the player's drive,
 **not** in this git repo (the repo holds only the catalog metadata). Keep your
 `file_path` values consistent with wherever you mount that drive on the machine
 that will eventually run the room.
+
+## Playing with the simulator (curator's X-ray)
+
+The simulator is a web stand-in for the installation's control panel. It runs the
+real `hef.selection` code against a synthetic catalog so you can feel whether the
+dials surface fitting pieces before any hardware exists.
+
+**Run it (Docker):**
+
+    make sim
+
+then open http://localhost:8000.
+
+**Run it (no Docker):**
+
+    pip install -e ".[sim]"
+    make sim-local
+
+**What you see:** the five real dials (mode + Left/Right/Dark/Light), the model
+knobs (brain/mood weights, pool size, approved-only), and the X-ray — the picked
+piece, the ranked candidate pool with distances, and brain/mood coordinate maps
+showing where your knob point and the candidates sit.
+
+By default it loads a generated fixture catalog. To point it at a real catalog,
+set `HEF_SIM_CATALOG=catalog/library.jsonl` (used automatically when that file is
+non-empty).