docs: split Android/iOS debugging into subpages

docs.json

@@ -41,6 +41,14 @@
           "title": "Debugging",
           "href": "/debugging"
         },
+        {
+          "title": "Debugging (Android)",
+          "href": "/debugging-android"
+        },
+        {
+          "title": "Debugging (iOS)",
+          "href": "/debugging-ios"
+        },
         {
           "title": "Web (experimental)",
           "href": "/web"
@@ -56,4 +64,4 @@
       ]
     }
   ]
-}
+}

docs/debugging-android.mdx

@@ -0,0 +1,70 @@
+---
+title: Android Debugging
+description: Debug background tasks on Android — job scheduler inspection, adb commands, common issues
+---
+
+Deep-dive debugging for Android. For the debug handlers (logging / notification)
+and custom handlers, see [Debugging Background Tasks](debugging). For tasks not
+running at all, see the [Troubleshooting guide](troubleshooting) first — it is
+almost always OEM battery optimization or OS scheduling policy.
+
+## Job Scheduler Inspection
+
+Use ADB to inspect Android's job scheduler:
+
+```bash
+# View scheduled jobs
+adb shell dumpsys jobscheduler | grep yourapp
+
+# View detailed job info
+adb shell dumpsys jobscheduler yourapp
+
+# Force run job (debug only)
+adb shell cmd jobscheduler run -f yourapp JOB_ID
+```
+
+## Monitor Job Execution
+
+```bash
+# Monitor WorkManager logs
+adb logcat | grep WorkManager
+
+# Monitor app background execution
+adb logcat | grep "yourapp"
+```
+
+## Common Android Issues
+
+**Tasks not running:**
+- Check battery optimization settings
+- Verify app is not in "App Standby" mode
+- Ensure device isn't in Doze mode
+- Check if constraints are too restrictive
+
+Tasks stopping after the app is closed is almost always OEM battery
+optimization or OS scheduling policy — see the
+[Troubleshooting guide](troubleshooting) for per-vendor instructions and
+verification steps.
+
+**Tasks running too often:**
+- Android enforces minimum 15-minute intervals for periodic tasks
+- Use appropriate constraints to limit execution
+
+**Play Console asks for a FOREGROUND_SERVICE_DATA_SYNC declaration/video:**
+- See the [Troubleshooting guide](troubleshooting) — the permission is opt-in
+  since 0.10.6 (`workmanager.enableDataSyncForegroundService=true` in
+  `gradle.properties`), and using the `dataSync` type without it throws at
+  registration instead of failing silently.
+
+## Debug Commands
+
+```bash
+# Check if your app is whitelisted from battery optimization
+adb shell dumpsys deviceidle whitelist
+
+# Check battery optimization status
+adb shell settings get global battery_saver_constants
+
+# Force device into idle mode (testing)
+adb shell dumpsys deviceidle force-idle
+```

docs/debugging-ios.mdx

@@ -0,0 +1,84 @@
+---
+title: iOS Debugging
+description: Debug background tasks on iOS — console logging, Xcode, BGTaskScheduler, common issues
+---
+
+Deep-dive debugging for iOS/macOS. For the debug handlers (logging / notification)
+and custom handlers, see [Debugging Background Tasks](debugging).
+
+## Console Logging
+
+iOS background tasks have limited execution time. Add detailed logging:
+
+```dart
+@pragma('vm:entry-point')
+void callbackDispatcher() {
+  Workmanager().executeTask((task, inputData) async {
+    print('[iOS BG] Task started: $task at ${DateTime.now()}');
+
+    try {
+      // Your task logic
+      final result = await performTask();
+      print('[iOS BG] Task completed successfully');
+      return true;
+    } catch (e) {
+      print('[iOS BG] Task failed: $e');
+      return false;
+    }
+  });
+}
+```
+
+## Xcode Debugging
+
+**For Background Fetch tasks:**
+Use **Debug → Perform Fetch** from the Xcode run menu while your app is running.
+
+**For BGTaskScheduler tasks (processing/periodic):**
+Use Xcode's console to trigger tasks manually:
+
+```objc
+// Trigger specific BGTaskScheduler task
+e -l objc -- (void)[[BGTaskScheduler sharedScheduler]
+  _simulateLaunchForTaskWithIdentifier:@"com.yourapp.task.identifier"]
+```
+
+## Monitor Scheduled Tasks
+
+Check what tasks iOS has scheduled:
+
+```dart
+// iOS 13+ only
+if (Platform.isIOS) {
+  final tasks = await Workmanager().printScheduledTasks();
+  print('Scheduled tasks: $tasks');
+}
+```
+
+This prints output like:
+```
+[BGTaskScheduler] Task Identifier: your.task.id earliestBeginDate: 2023.10.10 PM 11:10:12
+[BGTaskScheduler] There are no scheduled tasks
+```
+
+## Common iOS Issues
+
+**Background App Refresh disabled:**
+- Check iOS Settings → General → Background App Refresh
+- See [Apple's Background App Refresh Guide](https://support.apple.com/en-us/102425)
+
+**Tasks never run:**
+- App hasn't been used recently (iOS learning algorithm) — [iOS Power Management](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html)
+- Task identifiers don't match between Info.plist and AppDelegate — [check iOS setup](quickstart#option-b-processing-tasks-for-complex-operations)
+- Missing BGTaskSchedulerPermittedIdentifiers in Info.plist — [review iOS configuration](quickstart#ios)
+
+**Tasks stop working:**
+- iOS battery optimization kicked in — [WWDC 2020: Background execution demystified](https://developer.apple.com/videos/play/wwdc2020/10063/)
+- App removed from recent apps too often
+- User disabled background refresh — [check Background Fetch setup](quickstart#option-a-periodic-tasks-recommended-for-most-use-cases)
+- Task taking longer than 30 seconds — [BGTaskScheduler Documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler)
+
+**Tasks run but don't complete:**
+- Hitting 30-second execution limit — [Background Tasks Best Practices](https://developer.apple.com/documentation/backgroundtasks/bgtask)
+- Network requests timing out
+- Heavy processing blocking the thread — [WWDC 2019: Advances in App Background Execution](https://developer.apple.com/videos/play/wwdc2019/707/)

docs/debugging.mdx

@@ -173,141 +173,10 @@ WorkmanagerDebug.setCurrent(CustomDebugHandler())
 
 For detailed information about task statuses, lifecycle, and notification formats, see the [Task Status Tracking](task-status) guide.
 
-## Android Debugging
+## Platform deep-dives
 
-### Job Scheduler Inspection
-
-Use ADB to inspect Android's job scheduler:
-
-```bash
-# View scheduled jobs
-adb shell dumpsys jobscheduler | grep yourapp
-
-# View detailed job info  
-adb shell dumpsys jobscheduler yourapp
-
-# Force run job (debug only)
-adb shell cmd jobscheduler run -f yourapp JOB_ID
-```
-
-### Monitor Job Execution
-
-```bash
-# Monitor WorkManager logs
-adb logcat | grep WorkManager
-
-# Monitor app background execution
-adb logcat | grep "yourapp"
-```
-
-### Common Android Issues
-
-**Tasks not running:**
-- Check battery optimization settings
-- Verify app is not in "App Standby" mode
-- Ensure device isn't in Doze mode
-- Check if constraints are too restrictive
-
-Tasks stopping after the app is closed is almost always OEM battery
-optimization or OS scheduling policy - see the
-[Troubleshooting guide](troubleshooting) for per-vendor instructions and
-verification steps.
-
-**Tasks running too often:**
-- Android enforces minimum 15-minute intervals for periodic tasks
-- Use appropriate constraints to limit execution
-
-### Debug Commands
-
-```bash
-# Check if your app is whitelisted from battery optimization
-adb shell dumpsys deviceidle whitelist
-
-# Check battery optimization status
-adb shell settings get global battery_saver_constants
-
-# Force device into idle mode (testing)
-adb shell dumpsys deviceidle force-idle
-```
-
-## iOS Debugging
-
-### Console Logging
-
-iOS background tasks have limited execution time. Add detailed logging:
-
-```dart
-@pragma('vm:entry-point')
-void callbackDispatcher() {
-  Workmanager().executeTask((task, inputData) async {
-    print('[iOS BG] Task started: $task at ${DateTime.now()}');
-
-    try {
-      // Your task logic
-      final result = await performTask();
-      print('[iOS BG] Task completed successfully');
-      return true;
-    } catch (e) {
-      print('[iOS BG] Task failed: $e');
-      return false;
-    }
-  });
-}
-```
-
-### Xcode Debugging
-
-**For Background Fetch tasks:**
-Use **Debug → Perform Fetch** from the Xcode run menu while your app is running.
-
-**For BGTaskScheduler tasks (processing/periodic):**
-Use Xcode's console to trigger tasks manually:
-
-```objc
-// Trigger specific BGTaskScheduler task
-e -l objc -- (void)[[BGTaskScheduler sharedScheduler] 
-  _simulateLaunchForTaskWithIdentifier:@"com.yourapp.task.identifier"]
-```
-
-### Monitor Scheduled Tasks
-
-Check what tasks iOS has scheduled:
-
-```dart
-// iOS 13+ only
-if (Platform.isIOS) {
-  final tasks = await Workmanager().printScheduledTasks();
-  print('Scheduled tasks: $tasks');
-}
-```
-
-This prints output like:
-```
-[BGTaskScheduler] Task Identifier: your.task.id earliestBeginDate: 2023.10.10 PM 11:10:12
-[BGTaskScheduler] There are no scheduled tasks
-```
-
-### Common iOS Issues
-
-**Background App Refresh disabled:**
-- Check iOS Settings → General → Background App Refresh
-- See [Apple's Background App Refresh Guide](https://support.apple.com/en-us/102425)
-
-**Tasks never run:**
-- App hasn't been used recently (iOS learning algorithm) - [iOS Power Management](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html)
-- Task identifiers don't match between Info.plist and AppDelegate - [check iOS setup](quickstart#option-b-processing-tasks-for-complex-operations)
-- Missing BGTaskSchedulerPermittedIdentifiers in Info.plist - [review iOS configuration](quickstart#ios)
-
-**Tasks stop working:**
-- iOS battery optimization kicked in - [WWDC 2020: Background execution demystified](https://developer.apple.com/videos/play/wwdc2020/10063/)
-- App removed from recent apps too often
-- User disabled background refresh - [check Background Fetch setup](quickstart#option-a-periodic-tasks-recommended-for-most-use-cases)
-- Task taking longer than 30 seconds - [BGTaskScheduler Documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler)
-
-**Tasks run but don't complete:**
-- Hitting 30-second execution limit - [Background Tasks Best Practices](https://developer.apple.com/documentation/backgroundtasks/bgtask)
-- Network requests timing out
-- Heavy processing blocking the thread - [WWDC 2019: Advances in App Background Execution](https://developer.apple.com/videos/play/wwdc2019/707/)
+- [Android Debugging](debugging-android) — job scheduler inspection, adb commands, common Android issues.
+- [iOS Debugging](debugging-ios) — console logging, Xcode simulation, BGTaskScheduler, common iOS issues.
 
 ## General Debugging Tips
 
@@ -389,7 +258,7 @@ Future<bool> isTaskHealthy(String taskName, Duration maxAge) async {
 4. **Check debug notifications** to confirm execution
 5. **Use ADB commands** to force execution if needed
 
-### iOS Testing Workflow  
+### iOS Testing Workflow
 
 1. **Test on physical device** (simulator doesn't support background tasks)
 2. **Enable Background App Refresh** in iOS Settings