From 78f9ed7c0c2b0bc8a5088f201d41db763c23292d Mon Sep 17 00:00:00 2001
From: oho <oho@ohos-Mac-mini.local>
Date: Tue, 13 Jan 2026 08:45:07 +0100
Subject: [PATCH] docs: add Xcode requirements and build troubleshooting

- Add "Requires: macOS 13.0+, Xcode 15.0+" to README
- Add "Build Won't Complete" troubleshooting section to MACOS_APP_MANUAL
- Document xcodebuild not found and Command Line Tools issues
---
 README.md                |  2 ++
 docs/MACOS_APP_MANUAL.md | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 827cc0c..aacc62b 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,8 @@ Control Alpha Arena from your menu bar:
 - Quick access to dashboard and logs
 - Network mode toggle (localhost/LAN)
 
+**Requires:** macOS 13.0+, Xcode 15.0+ (from App Store)
+
 ```bash
 # Build and install
 cd macos-app && ./build.sh install
diff --git a/docs/MACOS_APP_MANUAL.md b/docs/MACOS_APP_MANUAL.md
index 9ff27be..ff55488 100644
--- a/docs/MACOS_APP_MANUAL.md
+++ b/docs/MACOS_APP_MANUAL.md
@@ -267,6 +267,22 @@ Trading: Active (simulation)
 
 ## Troubleshooting
 
+### Build Won't Complete
+
+**"xcodebuild not found"**
+- Install Xcode from the App Store (not just Command Line Tools)
+- Xcode download: https://apps.apple.com/app/xcode/id497799835
+
+**"Xcode Command Line Tools selected instead of Xcode"**
+```bash
+# Switch to full Xcode
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+```
+
+**Build errors about missing types**
+- Ensure you have the latest code: `git pull`
+- The Xcode project must include all Swift files in the build
+
 ### App Won't Launch
 
 **"App is damaged and can't be opened"**