diff --git a/demos/README.md b/demos/README.md
new file mode 100644
index 0000000000..afb41bb729
--- /dev/null
+++ b/demos/README.md
@@ -0,0 +1,18 @@
+The `demo_*.sh` scripts in this directory demo
+various features of `jj`.
+
+The `run_scripts.sh` script can be used to:
+
+- Run them inside a standardized environment instead of the user's local environment.
+- Generate SVG and PNG images for the scripts.
+
+This requires ImageMagick and `term-transcript-cli` to be
+installed. See `run_scripts.sh`'s error messages for some
+more details.
+
+One way to make all the images and check the output is:
+
+```shell
+$ cd demos
+$  ./run_scripts.sh demo_*.sh |less
+```