diff --git a/iOS_BUILD_ISSUE.md b/iOS_BUILD_ISSUE.md
new file mode 100644
index 0000000..67b0b7c
--- /dev/null
+++ b/iOS_BUILD_ISSUE.md
@@ -0,0 +1,115 @@
+# iOS Build Issue - Libbox Module Not Found
+
+## 🚨 Problem Summary
+
+The iOS build is failing with the error:
+```
+error: Unable to find module dependency: 'Libbox'
+import Libbox
+```
+
+## 🔍 Root Cause Analysis
+
+After extensive debugging, we've identified the root cause:
+
+**The Library target does NOT link Libbox.xcframework in its Build Phases**
+
+### Evidence
+
+From `project.pbxproj` file analysis:
+
+**Library target's Frameworks build phase** (line 515-524):
+```
+3AEC211A2A459B4700A63465 /* Frameworks */ = {
+  isa = PBXFrameworksBuildPhase;
+  files = (
+    0451E1D62CC3AE2800E9A49F /* GRDB in Frameworks */,
+    3A7E90382A46778E00D53052 /* BinaryCodable in Frameworks */,
+    3AF3A3D22B2207F3001FD7C1 /* libresolv.tbd in Frameworks */,
+  );
+};
+```
+
+**Notice**: Libbox.xcframework is NOT in this list!
+
+However, Libbox.xcframework IS linked in other targets:
+- Line 507: Libbox.xcframework is linked in another target's Frameworks phase
+- Line 178: Libbox.xcframework is referenced in the project
+
+### What This Means
+
+- **Libbox.xcframework exists** in the project and is correctly tracked by Git
+- **Libbox.xcframework binary** is ~60MB and should be downloaded correctly
+- **Library target** uses Libbox in its Swift code (import Libbox)
+- **But Library target** doesn't link Libbox.xcframework in its Build Phases
+
+This is a **missing framework linking configuration** issue.
+
+## 🔧 Required Fix
+
+### Option 1: Fix in Xcode (Recommended)
+
+1. Open `iOS-SwiftUI-Code/uuvpn.xcodeproj` in Xcode
+2. Select the **Library** target (not the SFI scheme)
+3. Go to **Build Phases** tab
+4. Expand **Link Binary With Libraries**
+5. Click **+** button
+6. Add **Libbox.xcframework**
+7. Build and test locally
+8. Commit and push the changes
+
+### Option 2: Manual pbxproj Edit (Advanced)
+
+This requires manually editing `project.pbxproj` to add:
+1. A PBXBuildFile entry for Libbox in Library's Frameworks phase
+2. Add the file reference to Library's Frameworks build phase
+
+This is complex and error-prone. **Not recommended** unless you're experienced with Xcode project file format.
+
+## 📊 Verification
+
+After fixing, verify by building locally:
+
+```bash
+cd iOS-SwiftUI-Code
+xcodebuild -project uuvpn.xcodeproj -scheme SFI -sdk iphonesimulator -configuration Debug
+```
+
+If successful, commit and push, then the GitHub Actions build should work.
+
+## 🎯 Why This Happened
+
+This appears to be a project configuration issue in the original UUVPN repository. The Library target needs Libbox to compile, but the framework linking was never added to the Library target's Build Phases.
+
+## 📝 Additional Notes
+
+- Libbox.xcframework is a precompiled binary framework (~60MB)
+- It contains binaries for iOS (device), iOS Simulator, macOS, and tvOS
+- The framework is used for VPN core functionality
+- Multiple files in Library import Libbox:
+  - ExtensionProvider.swift
+  - Profile+Transferable.swift
+  - Profile+Share.swift
+  - Extension+RunBlocking.swift
+  - HTTPClient.swift
+  - ProfileServer.swift
+  - Profile+Update.swift
+  - Extension+Iterator.swift
+  - NWSocket.swift
+  - ExtensionPlatformInterface.swift
+  - CommandClient.swift
+  - ExtensionProfile.swift
+
+## ⚠️ Current Status
+
+- ✅ Libbox.xcframework exists in repository
+- ✅ Libbox.xcframework is tracked by Git
+- ✅ Libbox binary file is ~60MB (not a placeholder)
+- ❌ Library target does NOT link Libbox.xcframework
+- ❌ iOS build fails due to missing module dependency
+
+**Action Required**: Fix project configuration in Xcode
+
+---
+
+Generated by CI/CD debugging on 2026-07-02
\ No newline at end of file