diff --git a/docs/env-checklist.md b/docs/env-checklist.md
new file mode 100644
index 00000000..ef3aa8cd
--- /dev/null
+++ b/docs/env-checklist.md
@@ -0,0 +1,14 @@
+# Environment Checklist
+
+Before running the examples:
+
+- Python version matches the repo requirement
+- Virtualenv is activated
+- `pip install -r requirements.txt` completed successfully
+- Credentials/config file exists and is gitignored
+- No secrets appear in your `git diff`
+
+If something fails:
+- re-create the venv
+- re-install requirements
+- verify file paths used by scripts