From 7446b0545ad56638e1a7c1e34ef8002a2c813050 Mon Sep 17 00:00:00 2001
From: Nick Fisher <nick.fisher@avinium.com>
Date: Wed, 18 Jun 2025 14:34:03 +0800
Subject: [PATCH] update docs

---
 docs.json          |  1 +
 docs/debugging.mdx | 31 +++++++++++++++++++++++++++++
 docs/ios.mdx       | 49 +++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 78 insertions(+), 3 deletions(-)
 create mode 100644 docs/debugging.mdx

diff --git a/docs.json b/docs.json
index a61dab9d..61b82573 100644
--- a/docs.json
+++ b/docs.json
@@ -13,6 +13,7 @@
       ]
     ],
     ["Misc.", [
+      ["Debugging", "/debugging"],
       ["Playground", "https://dartpad.thermion.dev"],
       ["Showcase", "/showcase"],
       ["Windows", "/windows"],
diff --git a/docs/debugging.mdx b/docs/debugging.mdx
new file mode 100644
index 00000000..03bb1949
--- /dev/null
+++ b/docs/debugging.mdx
@@ -0,0 +1,31 @@
+# Debugging
+
+If something is crashing or not working as expected, you can enable verbose logging and/or debug builds (particularly useful for debugging with lldb or getting legible stack traces):
+
+Add a `hooks` section to your app's `pubspec.yaml`, e.g.
+```
+name: example_cli
+description: A sample command-line application.
+version: 1.0.0
+
+environment:
+  sdk: ^3.3.0
+
+hooks:
+  user_defines:
+    thermion_dart: 
+      mode: debug
+      tracing: enabled
+
+# Add the below
+hooks:
+  user_defines:
+    thermion_dart: 
+      mode: debug
+      tracing: enabled
+```
+
+> [!CAUTION]
+> Debug builds won't work for Android. This is a known upstream issue with Filament.
+
+Unless `mode: debug` is specified in your `pubspec.yaml`, Thermion will use release builds under the hood, even if your app is compiled/runing in debug mode.
\ No newline at end of file
diff --git a/docs/ios.mdx b/docs/ios.mdx
index c6501786..da8917d5 100644
--- a/docs/ios.mdx
+++ b/docs/ios.mdx
@@ -2,11 +2,54 @@
 
 ### Min iOS version
 
-Thermion requires a minimum iOS version of 13.0
-
-In your application's `ios/Podfile`, make sure the following line is present (and not commented out):
+Thermion requires a minimum iOS version of 13.0. When building a Flutter application, ensure your application's `ios/Podfile` contains the following:
 
 ```ruby
 platform :ios, '13.0'
 ```
 
+and in ios/Info.plist:
+
+```xml
+<key>LSMinimumSystemVersion</key>
+<string>13.0</string>
+```
+
+When submitting to the App Store, you may encounter an error saying `thermion_dart.framework does not supported the minimum deployment target in Info.plist`. 
+
+This is because Flutter hardcodes a deployment target of iOS 12.0 when invoking the native assets build, which conflicts with actual requirement.
+
+After running `flutter build ios` (but before archiving the build and submitting to the App Store), run the following script to replace the `MinimumOSVersion`:
+
+```
+#!/bin/zsh
+
+# Array of directories containing Info.plist files
+directories=(
+    "./build/ios/iphoneos/Runner.app/Frameworks/thermion_dart.framework"
+    "./build/ios/Release-iphoneos/Runner.app/Frameworks/thermion_dart.framework"
+    "./build/native_assets/ios/thermion_dart.framework"
+)
+
+# Loop through each directory
+for dir in "${directories[@]}"; do
+    plist_path="$dir/Info.plist"
+    
+    # Check if Info.plist exists in the directory
+    if [[ -f "$plist_path" ]]; then
+        echo "Processing: $plist_path"
+        
+        # Use PlistBuddy to change the MinimumOSVersion
+        /usr/libexec/PlistBuddy -c "Set :MinimumOSVersion 13.0" "$plist_path" 2>/dev/null
+        
+        if [[ $? -eq 0 ]]; then
+            echo "✓ Successfully updated version to 13.0"
+        else
+            echo "✗ Failed to update version in $plist_path"
+        fi
+    else
+        echo "✗ Info.plist not found in $dir"
+    fi
+done
+```
+