From de454fc38577d5c501febbe1ed47e8f030b0485d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 6 Jan 2026 22:18:08 +0100
Subject: [PATCH] docs: add macOS build toolchain troubleshooting

---
 docs/mac/dev-setup.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/mac/dev-setup.md b/docs/mac/dev-setup.md
index 0b266f669..2b0e2301a 100644
--- a/docs/mac/dev-setup.md
+++ b/docs/mac/dev-setup.md
@@ -62,6 +62,21 @@ sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Rela
 
 ## Troubleshooting
 
+### Build Fails: Toolchain or SDK Mismatch
+The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.
+
+**System dependencies (required):**
+- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
+- **Xcode 26.2** (Swift 6.2 toolchain)
+
+**Checks:**
+```bash
+xcodebuild -version
+xcrun swift --version
+```
+
+If versions don’t match, update macOS/Xcode and re-run the build.
+
 ### App Crashes on Permission Grant
 If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.