diff --git a/README.md b/README.md
index f6340e2..352e590 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,10 @@ before sharing.
 
 ## Usage
 
-First build the docker container for the tool
+### Build the container
+
+First build the docker container for the tool. You should do this once every
+time you pull from the repo again.
 
     $ ./build.sh
     Sending build context to Docker daemon  716.3kB
@@ -35,22 +38,36 @@ First build the docker container for the tool
     Successfully built 1c3e3a1b45f5
     Successfully tagged sigint:latest
 
+
+### Run the tool
+
 The following command will run the analysis against the signal config directory
 you point it to, and dump the output to ./output/table.csv
 
-## Linux
+#### Linux
 
     $ ./run.sh -c ~/.config/Signal
 
     INFO:main:writing message count table to /output/table.csv
 
-## Macos
+#### Macos
 
     $ ./run.sh -c ~/Library/Application\ Support/Signal
 
     INFO:main:writing message count table to /output/table.csv
 
-## Group Filtering
+#### Providing a Password
+
+If you get the following error while running the command:
+
+    Exception: you must use the -p option to pass the password in for your signal db
+
+Then you need to find the `Signal Safe Storage` [^1] entry in your keychain (on
+macos) and pass that as an argument to the script:
+
+    $ ./run.sh -c ~/Library/Application\ Support/Signal -p YOURPASSWORD
+
+### Group Filtering
 
 Adding -f will filter the groups under consideration to only those listed in
 config/chat_list.txt
@@ -62,3 +79,12 @@ name column from the spreadsheet into config/chat_list.txt and narrow down to
 only the ones you care about and run it again with -f. This will ensure the
 output spreadsheet only has columns for users in the groups you care about, and
 not every single user you ever saw on Signal.
+
+[^1]: [after some alarmist press](https://candid.technology/signal-encryption-key-flaw-desktop-app-fixed/)
+    about Signal Desktop not encrypting data at rest securely, they
+    [switched to using](https://github.com/signalapp/Signal-Desktop/issues/6944#issuecomment-2243704263)
+    Electron's [safe storage api](https://www.electronjs.org/docs/latest/api/safe-storage)
+    which automatically creates a per-application private key when used, and
+    stores that key in the OS keychain. I found the docs to be lacking on
+    details but [this blogpost](https://control-plane.io/posts/abusing-vscode-from-malicious-extensions-to-stolen-credentials-part-2/#electron-safestorage)
+    and [this gist](https://gist.github.com/flatz/3f242ab3c550d361f8c6d031b07fb6b1) were both helpful.