diff --git a/README.rst b/README.rst
index 62261e3..a4a0160 100644
--- a/README.rst
+++ b/README.rst
@@ -31,16 +31,21 @@ Features
 - CCT189 the MITA LCD phantom for assessing low contrast detectability
 - Uniform water phantoms for assessing noise and noise texture
 
-In addition, this repo contains examples of measurements using these digital image quality phantoms
+In addition, this repo contains examples of measurements using these digital image quality phantoms including:
 
-- `phantom creation and simulation <demo_01_phantom_creation.sh>`_, including different scanner configurations and acquisition protocols
-- examples of how to `view the dataset <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/01_viewing_images.ipynb>`_ and `evaluate pediatric generalizability of denoisers <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/02_pediatric_denoising_evaluation.ipynb>`_ are shown in the notebooks directory
+- `running simulations interactively with python <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/00_running_simulations.ipynb>`_
+- `viewing the simulated dataset <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/01_viewing_images.ipynb>`_ 
+- `evaluating pediatric generalizability of denoisers <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/02_pediatric_denoising_evaluation.ipynb>`_
 
 .. image:: pediatric_subgroup_performance.png
         :width: 600
         :align: center
+        :caption: Example from the `uniform phantom denoising performance assessment notebook <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/02_pediatric_denoising_evaluation.ipynb>`_ demonstrating the pediatric subgroup denoising performance of a `RED-CNN <https://ieeexplore.ieee.org/document/7947200/>`_ image-based deep learning denoiser using the `pediatricIQphantoms dataset <https://zenodo.org/doi/10.5281/zenodo.10064035>`_
 
-Example from the `uniform phantom denoising performance assessment notebook <https://github.com/DIDSR/pediatricIQphantoms/blob/main/notebooks/02_pediatric_denoising_evaluation.ipynb>`_ demonstrating the pediatric subgroup denoising performance of a `RED-CNN <https://ieeexplore.ieee.org/document/7947200/>`_ image-based deep learning denoiser using the `pediatricIQphantoms dataset <https://zenodo.org/doi/10.5281/zenodo.10064035>`_ 
+- `Command line usage for phantom creation and simulation <demo_01_phantom_creation.sh>`_
+  - demonstrates command line usage including simulating different scanner configurations and acquisition protocols
+  - run with `bash demo_01_phantom_creation.sh`
+- `Command line usage for more complex simulation experiments with changing acquisition parameters <demo_02_multiple_recon_kernels.sh>`_
 
 Start Here
 ----------
diff --git a/demo_01_phantom_creation.sh b/demo_01_phantom_creation.sh
index 63c7054..4d9e1b9 100644
--- a/demo_01_phantom_creation.sh
+++ b/demo_01_phantom_creation.sh
@@ -1,3 +1,7 @@
+# run with: `bash demo_01_phantom_creation.sh`
+#
+# Shell script example of how to reproduce simulations using a config file, here 'configs/defaults.toml'
+# See documentation for more: <https://pediatriciqphantoms.readthedocs.io/en/latest/notebooks/00_running_simulations.html#Command-Line-Interface-Tool:-make_phantoms>
 config='configs/defaults.toml'
 
 make_phantoms $config
\ No newline at end of file
diff --git a/demo_02_multiple_recon_kernels.sh b/demo_02_multiple_recon_kernels.sh
index 9a7d483..94a0daf 100644
--- a/demo_02_multiple_recon_kernels.sh
+++ b/demo_02_multiple_recon_kernels.sh
@@ -1,3 +1,7 @@
+# run with: `bash demo_02_multiple_recon_kernels.sh`
+#
+# Shell script example of how to reproduce sets of simulations with changing parameters using a config file, here 'configs/multiple_recon_kernels.toml'
+# See Usage documentation for more: <https://pediatriciqphantoms.readthedocs.io/en/latest/usage.html#command-line-interface>
 config='configs/multiple_recon_kernels.toml'
 
 make_phantoms $config
\ No newline at end of file