diff --git a/HACKING.md b/HACKING.md
index 7ba584881..8a3c22f7c 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -67,6 +67,14 @@ sudo xcode-select --switch /Applications/Xcode.app
 > You do not need to be running on macOS 26 to build Ghostty, you can
 > still use Xcode 26 on macOS 15 stable.
 
+> [!WARNING]
+>
+> Zig 0.15.x has a [known linking issue](https://codeberg.org/ziglang/zig/issues/31658)
+> with **Xcode 26.4**. If you are on Xcode 26.4, you must use a
+> Homebrew-installed Zig (`brew install zig@0.15`) or our Nix flake,
+> both of which contain a patch that works around the issue. Alternatively,
+> you can downgrade to **Xcode 26.3**.
+
 ## AI and Agents
 
 If you're using AI assistance with Ghostty, Ghostty provides an
diff --git a/flake.lock b/flake.lock
index af1781c9b..46deffc2f 100644
--- a/flake.lock
+++ b/flake.lock
@@ -88,11 +88,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1773145353,
-        "narHash": "sha256-dE8zx8WA54TRmFFQBvA48x/sXGDTP7YaDmY6nNKMAYw=",
+        "lastModified": 1776789209,
+        "narHash": "sha256-G6B7Q4TXn7MZ1mB+f9rymjsYF5PLWoSvmbxijb/99bw=",
         "owner": "mitchellh",
         "repo": "zig-overlay",
-        "rev": "8666155d83bf792956a7c40915508e6d4b2b8716",
+        "rev": "14fe971844e841297ddd2ce9783d6892b467af39",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index 84b5ef9c5..0a4e5340a 100644
--- a/flake.nix
+++ b/flake.nix
@@ -75,7 +75,10 @@
   in {
     devShells = forAllPlatforms (pkgs: {
       default = pkgs.callPackage ./nix/devShell.nix {
-        zig = zig.packages.${pkgs.stdenv.hostPlatform.system}."0.15.2";
+        zig =
+          if pkgs.stdenv.hostPlatform.isDarwin
+          then zig.packages.${pkgs.stdenv.hostPlatform.system}.brew."0.15.2"
+          else zig.packages.${pkgs.stdenv.hostPlatform.system}."0.15.2";
         wraptest = pkgs.callPackage ./nix/pkgs/wraptest.nix {};
         zon2nix = zon2nix;