diff --git a/scripts/setup/machine-setup/lib/files.sh b/scripts/setup/machine-setup/lib/files.sh
index 82fe37e8..e0168267 100644
--- a/scripts/setup/machine-setup/lib/files.sh
+++ b/scripts/setup/machine-setup/lib/files.sh
@@ -125,3 +125,38 @@ append_once() {
     echo "$end"
   } >>"$file"
 }
+
+# -----------------------------------------------------------------------------
+# Where tmux actually reads its config
+# -----------------------------------------------------------------------------
+#
+# tmux 3.1 added an XDG location and it takes PRECEDENCE. Verified on 3.4 by
+# creating both and asking tmux which marker it ended up with:
+#
+#   both present            -> ~/.config/tmux/tmux.conf
+#   only ~/.tmux.conf       -> ~/.tmux.conf
+#   only the XDG one        -> the XDG one
+#
+# So installing to ~/.tmux.conf on a machine that has the XDG file writes a file
+# tmux will never read, and the script would report success having changed
+# nothing anybody can see. That is the failure this exists to prevent.
+#
+# Rules, in order:
+#   1. an existing XDG config wins  -> that is their real config, target it
+#   2. an existing ~/.tmux.conf     -> target it, since it is what tmux reads
+#   3. neither                      -> ~/.tmux.conf, the path every guide names
+tmux_config_target() {
+  local home="$1"
+  local xdg="${XDG_CONFIG_HOME:-$home/.config}/tmux/tmux.conf"
+  if [[ -f "$xdg" ]]; then
+    echo "$xdg"
+  else
+    echo "$home/.tmux.conf"
+  fi
+}
+
+# True when a ~/.tmux.conf would be shadowed by an XDG config that already exists.
+tmux_dot_conf_is_shadowed() {
+  local home="$1"
+  [[ -f "${XDG_CONFIG_HOME:-$home/.config}/tmux/tmux.conf" && -f "$home/.tmux.conf" ]]
+}
diff --git a/scripts/setup/machine-setup/machine-setup.sh b/scripts/setup/machine-setup/machine-setup.sh
index 97a40974..7b76a3ba 100755
--- a/scripts/setup/machine-setup/machine-setup.sh
+++ b/scripts/setup/machine-setup/machine-setup.sh
@@ -2226,10 +2226,20 @@ if ! skip; then
     fi
 
     if [[ -r "$SCRIPT_DIR/.tmux.conf" ]]; then
-      install_config "$SCRIPT_DIR/.tmux.conf" "${USER_HOME}/.tmux.conf" "$USERNAME" && RC=0 || RC=$?
+      # Not always ~/.tmux.conf — see tmux_config_target. tmux 3.1+ prefers
+      # ~/.config/tmux/tmux.conf, so writing the old path on a machine that has
+      # the new one produces a file tmux never reads and a success message that
+      # means nothing.
+      TMUX_TARGET="$(tmux_config_target "$USER_HOME")"
+      if tmux_dot_conf_is_shadowed "$USER_HOME"; then
+        warn "you have BOTH ~/.tmux.conf and ~/.config/tmux/tmux.conf — tmux reads the second"
+        echo "     Targeting the one it actually reads: ${TMUX_TARGET}"
+      fi
+      install -d -m 0755 -o "$USERNAME" -g "$(user_group)" "$(dirname "$TMUX_TARGET")"
+      install_config "$SCRIPT_DIR/.tmux.conf" "$TMUX_TARGET" "$USERNAME" && RC=0 || RC=$?
       case $RC in
-        0) ok "tmux config installed" ;;
-        1) echo "     tmux config already matches" ;;
+        0) ok "tmux config installed — ${TMUX_TARGET}" ;;
+        1) echo "     tmux config already matches (${TMUX_TARGET})" ;;
       esac
     fi