diff --git a/dvmp/dvmp.sh b/dvmp/dvmp.sh
index ca4a1750e0c81b0148af6f166705c857263c5c4d..23d60a01de89dd700a78a73748886510a98e01d8 100644
--- a/dvmp/dvmp.sh
+++ b/dvmp/dvmp.sh
@@ -1,53 +1,76 @@
 #!/bin/bash
 
-## Load the environment
+## =============================================================================
+## Run the DVMP benchmarks in 5 steps:
+## 1. Build/install detector package
+## 2. Detector simulation through npsim
+## 3. Digitization and reconstruction through Juggler
+## 4. Root-based Physics analyses
+## 5. Finalize
+## =============================================================================
+
+echo "Running the DVMP benchmarks"
+
+## make sure we launch this script from the project root directory
+PROJECT_ROOT="$( cd "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"/..
+pushd ${PROJECT_ROOT}
+
+## =============================================================================
+## Load the environment variables. To build the detector we need the following
+## variables:
+##
+## - JUGGLER_INSTALL_PREFIX: Install prefix for Juggler (simu/recon)
+## - JUGGLER_DETECTOR:       the detector package we want to use for this benchmark
+## - DETECTOR_PATH:          full path to the detector definitions
+##
+## You can ready config/env.sh for more in-depth explanations of the variables
+## and how they can be controlled.
 source config/env.sh
 
-# these variables might not need exported.
-export JUGGLER_FILE_NAME_TAG="dvmp"
+## Extra environment variables for DVMP:
+## file tag for these tests
+JUGGLER_FILE_NAME_TAG="dvmp"
 # Generator file, hardcoded for now FIXME
-export JUGGLER_GEN_FILE="results/dvmp/jpsi_central_electron-10on100-gen.hepmc"
-
+JUGGLER_GEN_FILE="results/dvmp/jpsi_central_electron-10on100-gen.hepmc"
 # FIXME use the input file name, as we will be generating a lot of these
 # in the future...
-export JUGGLER_SIM_FILE="sim_${JUGGLER_FILE_NAME_TAG}.root"
-export JUGGLER_REC_FILE="rec_${JUGGLER_FILE_NAME_TAG}.root"
+JUGGLER_SIM_FILE="sim_${JUGGLER_FILE_NAME_TAG}.root"
+JUGGLER_REC_FILE="rec_${JUGGLER_FILE_NAME_TAG}.root"
 
-echo "JUGGLER_N_EVENTS      = ${JUGGLER_N_EVENTS}"
-echo "JUGGLER_DETECTOR      = ${JUGGLER_DETECTOR}"
-echo "JUGGLER_FILE_NAME_TAG = ${JUGGLER_FILE_NAME_TAG}"
 
-### Build the detector constructors.
+## =============================================================================
+## Step 1: Build/install the desired detector package
 bash util/build_detector.sh
 
-pushd ${JUGGLER_DETECTOR}
-
-## run geant4 simulations
+## =============================================================================
+## Step 2: Run the simulation
+echo "Running Geant4 simulation"
 npsim --runType batch \
       --part.minimalKineticEnergy 1000*GeV  \
       -v WARNING \
       --numberOfEvents ${JUGGLER_N_EVENTS} \
-      --compactFile ${JUGGLER_DETECTOR}.xml \
-      --inputFiles ../${JUGGLER_GEN_FILE} \
-      --outputFile  ${JUGGLER_SIM_FILE}
+      --compactFile ${DETECTOR_PATH}/${JUGGLER_DETECTOR}.xml \
+      --inputFiles ${JUGGLER_GEN_FILE} \
+      --outputFile ${JUGGLER_SIM_FILE}
 if [[ "$?" -ne "0" ]] ; then
-  echo "ERROR running script"
+  echo "ERROR running npsim"
   exit 1
 fi
 
-# Need to figure out how to pass file name to juggler from the commandline
+## =============================================================================
+## Step 3: Run digitization & reconstruction
+echo "Running Geant4 simulation"
+# FIXME Need to figure out how to pass file name to juggler from the commandline
 xenv -x ${JUGGLER_INSTALL_PREFIX}/Juggler.xenv \
-  gaudirun.py ../options/tracker_reconstruction.py
+  gaudirun.py options/tracker_reconstruction.py
 if [[ "$?" -ne "0" ]] ; then
   echo "ERROR running juggler"
   exit 1
 fi
 ls -l
-popd
-
-pwd
-mkdir -p results/dvmp
 
+## =============================================================================
+## Step 4: Analysis
 echo "STAND-IN FOR ANALYSIS SCRIPT"
 #root -b -q "dis/scripts/rec_dis_electrons.cxx(\"${JUGGLER_DETECTOR}/${JUGGLER_REC_FILE}\")"
 #if [[ "$?" -ne "0" ]] ; then
@@ -55,7 +78,19 @@ echo "STAND-IN FOR ANALYSIS SCRIPT"
 #  exit 1
 #fi
 
+## =============================================================================
+## Step 5: finalize
+echo "Finalizing ${JUGGLER_FILE_NAME_TAG} benchmark"
+
+## Copy over reconsturction artifacts as long as we don't have
+## too many events
 if [[ "${JUGGLER_N_EVENTS}" -lt "500" ]] ; then 
-cp ${JUGGLER_DETECTOR}/${JUGGLER_REC_FILE} results/dvmp/.
+  cp ${JUGGLER_REC_FILE} results/dvmp/.
 fi
 
+## cleanup output files
+rm ${JUGGLER_REC_FILE} ${JUGGLER_SIM_FILE}
+
+## =============================================================================
+## All done!
+echo "${JUGGLER_FILE_NAME_TAG} benchmarks complete"
diff --git a/util/build_detector.sh b/util/build_detector.sh
index 41716d5c46f6b01df5356f875d34a886cbf3e4b1..066b11c2f1257286c0c282b59fb272866fc79d5d 100755
--- a/util/build_detector.sh
+++ b/util/build_detector.sh
@@ -1,14 +1,13 @@
 #!/bin/bash
 
-## make sure we launch this script from the project root directory
-PROJECT_ROOT="$( cd "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"/..
-pushd ${PROJECT_ROOT}
-
 ## =============================================================================
 ## Build and install the JUGGLER_DETECTOR detector package into our local prefix
-## This script will only work when executed from the project root directory. 
 ## =============================================================================
 
+## make sure we launch this script from the project root directory
+PROJECT_ROOT="$( cd "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"/..
+pushd ${PROJECT_ROOT}
+
 ## =============================================================================
 ## Load the environment variables. To build the detector we need the following
 ## variables:
diff --git a/util/start_dev_shell.sh b/util/start_dev_shell.sh
index a895514ab4884f341e43441a377152bceeab0f21..d452525c4fce25ea3bb207a38cdc3b5e22ae9b14 100755
--- a/util/start_dev_shell.sh
+++ b/util/start_dev_shell.sh
@@ -2,7 +2,6 @@
 
 ## =============================================================================
 ## Setup (if needed) and start a development shell environment on Linux or MacOS
-## This script will only work when executed from the project root directory. 
 ## =============================================================================
 
 ## make sure we launch this script from the project root directory