From fb6167b0c461fb4a9952c1403a1212aa2b30005a Mon Sep 17 00:00:00 2001
From: "Brian.oh" <49855381+dev07060@users.noreply.github.com>
Date: Tue, 7 Jul 2026 05:11:34 +0900
Subject: [PATCH] docs: add iOS pod install troubleshooting for static linkage

---
 README.md                      |  2 ++
 docs/guides/troubleshooting.md | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 5732ca3..94e8a20 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,8 @@ dependencies:
   mobile_rag_engine: ^0.20.0
 ```
 
+> **iOS Setup:** Open your `ios/Podfile` and change `use_frameworks!` to `use_frameworks! :linkage => :static`. This is required because the underlying ONNX Runtime uses statically linked binaries.
+
 ### 2. Download Model Files
 
 ```bash
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index c1bf527..9bff4c7 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -260,6 +260,22 @@ dyld: Library not loaded: @rpath/libonnxruntime.dylib
 
 ## Build Issues
 
+### iOS: Transitive dependencies include statically linked binaries
+
+**Symptom:**
+```
+[!] The 'Pods-Runner' target has transitive dependencies that include statically linked binaries: (onnxruntime-objc and onnxruntime-c)
+```
+
+**Cause:** `mobile_rag_engine` (since 0.19.0) uses `flutter_onnxruntime` which relies on statically linked ONNX Runtime binaries. Flutter's default iOS project uses dynamic frameworks (`use_frameworks!`).
+
+**Solution:** Update your `ios/Podfile` to use static linkage for frameworks:
+1. Open `ios/Podfile`
+2. Change `use_frameworks!` to `use_frameworks! :linkage => :static`
+3. Run `pod install` again.
+
+---
+
 ### iOS: Pod Install Failed
 
 ```bash