zsh: improve ZDOTDIR documentation

The main thing to emphasize is that end users should never source
.zshenv directly; it's only meant to be used as part of our shell
injection environment.

At the moment, there's no way to guard against accidentally use, but we
can consider making e.g. GHOSTTY_SHELL_FEATURES always defined in this
environment to that it can be used to differentiate the cases.

In practice, it's unlikely that people actually source this .zshenv
script directly, so hopefully this additional documentation clarifies
things well enough.

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

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'

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,