diff --git a/src/shell-integration/README.md b/src/shell-integration/README.md
index 1fd11091d..2357a64f6 100644
--- a/src/shell-integration/README.md
+++ b/src/shell-integration/README.md
@@ -83,7 +83,7 @@ from the `zsh` directory. The existing `ZDOTDIR` is retained so that
 after loading the Ghostty shell integration the normal Zsh loading
 sequence occurs.
 
-```bash
+```zsh
 if [[ -n $GHOSTTY_RESOURCES_DIR ]]; then
   source "$GHOSTTY_RESOURCES_DIR"/shell-integration/zsh/ghostty-integration
 fi
diff --git a/src/shell-integration/zsh/.zshenv b/src/shell-integration/zsh/.zshenv
index 4201b295c..437e7f5c4 100644
--- a/src/shell-integration/zsh/.zshenv
+++ b/src/shell-integration/zsh/.zshenv
@@ -15,11 +15,16 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+# This script is sourced automatically by zsh when ZDOTDIR is set to this
+# directory. It therefore assumes it's running within our shell integration
+# environment and should not be sourced manually (unlike ghostty-integration).
+#
 # This file can get sourced with aliases enabled. To avoid alias expansion
 # we quote everything that can be quoted. Some aliases will still break us
 # though.
 
-# Restore the original ZDOTDIR value.
+# Restore the original ZDOTDIR value if GHOSTTY_ZSH_ZDOTDIR is set.
+# Otherwise, unset the ZDOTDIR that was set during shell injection.
 if [[ -n "${GHOSTTY_ZSH_ZDOTDIR+X}" ]]; then
     'builtin' 'export' ZDOTDIR="$GHOSTTY_ZSH_ZDOTDIR"
     'builtin' 'unset' 'GHOSTTY_ZSH_ZDOTDIR'
diff --git a/src/termio/shell_integration.zig b/src/termio/shell_integration.zig
index 8b2648dbd..c2a637b80 100644
--- a/src/termio/shell_integration.zig
+++ b/src/termio/shell_integration.zig
@@ -659,12 +659,12 @@ fn setupZsh(
     resource_dir: []const u8,
     env: *EnvMap,
 ) !void {
-    // Preserve the old zdotdir value so we can recover it.
+    // Preserve an existing ZDOTDIR value. We're about to overwrite it.
     if (env.get("ZDOTDIR")) |old| {
         try env.put("GHOSTTY_ZSH_ZDOTDIR", old);
     }
 
-    // Set our new ZDOTDIR
+    // Set our new ZDOTDIR to point to our shell resource directory.
     var path_buf: [std.fs.max_path_bytes]u8 = undefined;
     const integ_dir = try std.fmt.bufPrint(
         &path_buf,