diff --git a/docs/IOS_CODE_SIGNING.md b/docs/IOS_CODE_SIGNING.md
new file mode 100644
index 0000000..397e3df
--- /dev/null
+++ b/docs/IOS_CODE_SIGNING.md
@@ -0,0 +1,273 @@
+# iOS Code Signing Guide
+
+**Author**: Matthew Raymer  
+**Date**: 2025-11-12  
+**Status**: Active
+
+## Overview
+
+iOS apps require code signing to run on devices or simulators. This guide explains how to handle signing for different scenarios.
+
+## Signing Scenarios
+
+### 1. Simulator Builds (Development)
+
+**For simulator builds, signing can be disabled:**
+
+```bash
+xcodebuild -workspace App.xcworkspace \
+    -scheme App \
+    -sdk iphonesimulator \
+    -destination 'platform=iOS Simulator,name=iPhone 15' \
+    CODE_SIGN_IDENTITY="" \
+    CODE_SIGNING_REQUIRED=NO \
+    CODE_SIGNING_ALLOWED=NO \
+    clean build
+```
+
+**Why this works:**
+- Simulator doesn't require valid code signatures
+- Faster builds (no signing overhead)
+- No need for Apple Developer account
+
+### 2. Device Builds (Development)
+
+**For physical devices, you need proper signing:**
+
+#### Option A: Automatic Signing (Recommended)
+
+1. **Open Xcode project:**
+   ```bash
+   open App.xcworkspace
+   ```
+
+2. **Configure in Xcode:**
+   - Select project in navigator
+   - Select target "App"
+   - Go to "Signing & Capabilities" tab
+   - Check "Automatically manage signing"
+   - Select your Team (Apple Developer account)
+   - Xcode will create provisioning profile automatically
+
+3. **Build from command line:**
+   ```bash
+   xcodebuild -workspace App.xcworkspace \
+       -scheme App \
+       -sdk iphoneos \
+       -configuration Debug \
+       -destination 'generic/platform=iOS' \
+       DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
+       CODE_SIGN_STYLE=Automatic \
+       clean build
+   ```
+
+#### Option B: Manual Signing
+
+1. **Get your Team ID:**
+   ```bash
+   # List available teams
+   security find-identity -v -p codesigning
+   ```
+
+2. **Create provisioning profile** (via Apple Developer Portal or Xcode)
+
+3. **Build with explicit signing:**
+   ```bash
+   xcodebuild -workspace App.xcworkspace \
+       -scheme App \
+       -sdk iphoneos \
+       -configuration Debug \
+       -destination 'generic/platform=iOS' \
+       DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
+       CODE_SIGN_STYLE=Manual \
+       PROVISIONING_PROFILE_SPECIFIER="Your Profile Name" \
+       CODE_SIGN_IDENTITY="iPhone Developer" \
+       clean build
+   ```
+
+### 3. Command-Line Build Scripts
+
+**Update build scripts to handle both scenarios:**
+
+```bash
+#!/bin/bash
+
+# Detect if building for simulator or device
+SDK="${1:-iphonesimulator}"
+DESTINATION="${2:-'platform=iOS Simulator,name=iPhone 15'}"
+
+if [ "$SDK" = "iphonesimulator" ]; then
+    # Simulator: Disable signing
+    xcodebuild -workspace App.xcworkspace \
+        -scheme App \
+        -sdk "$SDK" \
+        -destination "$DESTINATION" \
+        CODE_SIGN_IDENTITY="" \
+        CODE_SIGNING_REQUIRED=NO \
+        CODE_SIGNING_ALLOWED=NO \
+        clean build
+else
+    # Device: Use automatic signing
+    xcodebuild -workspace App.xcworkspace \
+        -scheme App \
+        -sdk "$SDK" \
+        -configuration Debug \
+        -destination 'generic/platform=iOS' \
+        CODE_SIGN_STYLE=Automatic \
+        DEVELOPMENT_TEAM="${DEVELOPMENT_TEAM:-}" \
+        clean build
+fi
+```
+
+## Common Signing Issues
+
+### Issue 1: "No signing certificate found"
+
+**Solution:**
+```bash
+# Check available certificates
+security find-identity -v -p codesigning
+
+# If none found, create one in Xcode:
+# Xcode > Preferences > Accounts > Select Team > Download Manual Profiles
+```
+
+### Issue 2: "Provisioning profile not found"
+
+**Solution:**
+```bash
+# List provisioning profiles
+ls ~/Library/MobileDevice/Provisioning\ Profiles/
+
+# Or use automatic signing (recommended)
+# Xcode will create profiles automatically
+```
+
+### Issue 3: "Code signing is required for product type"
+
+**Solution:**
+- For simulator: Add `CODE_SIGNING_REQUIRED=NO`
+- For device: Configure signing in Xcode or provide `DEVELOPMENT_TEAM`
+
+### Issue 4: "Bundle identifier conflicts"
+
+**Solution:**
+- Change bundle identifier in `Info.plist`:
+  ```xml
+  <key>CFBundleIdentifier</key>
+  <string>com.yourcompany.yourapp</string>
+  ```
+- Or use unique identifier for test apps
+
+## Project Configuration
+
+### Automatic Signing (Recommended)
+
+In Xcode project settings (`project.pbxproj` or Xcode UI):
+
+```
+CODE_SIGN_STYLE = Automatic;
+DEVELOPMENT_TEAM = YOUR_TEAM_ID;
+```
+
+### Manual Signing
+
+```
+CODE_SIGN_STYLE = Manual;
+CODE_SIGN_IDENTITY = "iPhone Developer";
+PROVISIONING_PROFILE_SPECIFIER = "Your Profile Name";
+```
+
+## Environment Variables
+
+**Set these for command-line builds:**
+
+```bash
+# For device builds
+export DEVELOPMENT_TEAM="YOUR_TEAM_ID"
+export CODE_SIGN_STYLE="Automatic"
+
+# For simulator builds (optional)
+export CODE_SIGNING_REQUIRED="NO"
+export CODE_SIGNING_ALLOWED="NO"
+```
+
+## Quick Reference
+
+### Simulator Build (No Signing)
+```bash
+xcodebuild ... \
+    CODE_SIGN_IDENTITY="" \
+    CODE_SIGNING_REQUIRED=NO \
+    CODE_SIGNING_ALLOWED=NO
+```
+
+### Device Build (Automatic Signing)
+```bash
+xcodebuild ... \
+    CODE_SIGN_STYLE=Automatic \
+    DEVELOPMENT_TEAM="YOUR_TEAM_ID"
+```
+
+### Device Build (Manual Signing)
+```bash
+xcodebuild ... \
+    CODE_SIGN_STYLE=Manual \
+    CODE_SIGN_IDENTITY="iPhone Developer" \
+    PROVISIONING_PROFILE_SPECIFIER="Profile Name"
+```
+
+## Testing Signing Configuration
+
+**Test if signing works:**
+
+```bash
+# Check code signature
+codesign -dv --verbose=4 /path/to/App.app
+
+# Verify signature
+codesign --verify --verbose /path/to/App.app
+
+# Check entitlements
+codesign -d --entitlements - /path/to/App.app
+```
+
+## Troubleshooting
+
+### Check Current Signing Status
+
+```bash
+# In Xcode project directory
+xcodebuild -showBuildSettings -workspace App.xcworkspace -scheme App | grep CODE_SIGN
+```
+
+### Clean Derived Data
+
+```bash
+# Sometimes signing issues are cached
+rm -rf ~/Library/Developer/Xcode/DerivedData
+```
+
+### Reset Signing in Xcode
+
+1. Open project in Xcode
+2. Select target
+3. Signing & Capabilities tab
+4. Uncheck "Automatically manage signing"
+5. Re-check "Automatically manage signing"
+6. Select team again
+
+## Best Practices
+
+1. **Use Automatic Signing** for development (easiest)
+2. **Disable signing for simulator** builds (faster)
+3. **Use unique bundle IDs** for test apps
+4. **Keep certificates updated** in Keychain
+5. **Use environment variables** for team IDs in CI/CD
+
+## References
+
+- [Apple Code Signing Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/)
+- [Xcode Signing Documentation](https://developer.apple.com/documentation/xcode/managing-your-team-s-signing-assets)
+- [Capacitor iOS Setup](https://capacitorjs.com/docs/ios/configuration)
+
diff --git a/test-apps/ios-test-app/SETUP.md b/test-apps/ios-test-app/SETUP.md
index 43842fd..c618a03 100644
--- a/test-apps/ios-test-app/SETUP.md
+++ b/test-apps/ios-test-app/SETUP.md
@@ -252,6 +252,51 @@ iOS handles background execution differently than Android:
 - **UserDefaults**: For schedules and configuration (like Android's SharedPreferences)
 - **Core Data**: For content cache and history (like Android's Room database)
 
+## Code Signing
+
+### Simulator Builds (Default)
+
+**No signing required** - The build scripts automatically disable signing for simulator builds:
+
+```bash
+CODE_SIGN_IDENTITY=""
+CODE_SIGNING_REQUIRED=NO
+CODE_SIGNING_ALLOWED=NO
+```
+
+This is handled automatically by the build scripts.
+
+### Device Builds
+
+**For physical devices, you need proper signing:**
+
+1. **Open project in Xcode:**
+   ```bash
+   cd test-apps/ios-test-app/App
+   open App.xcworkspace
+   ```
+
+2. **Configure signing:**
+   - Select project in navigator
+   - Select target "App"
+   - Go to "Signing & Capabilities" tab
+   - Check "Automatically manage signing"
+   - Select your Team (Apple Developer account)
+
+3. **Build for device:**
+   ```bash
+   xcodebuild -workspace App.xcworkspace \
+       -scheme App \
+       -sdk iphoneos \
+       -configuration Debug \
+       -destination 'generic/platform=iOS' \
+       CODE_SIGN_STYLE=Automatic \
+       DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
+       clean build
+   ```
+
+**See `docs/IOS_CODE_SIGNING.md` for complete signing guide.**
+
 ## Troubleshooting
 
 ### Plugin Not Found