feat(flutter): improve the debug symbol upload page

docs/platforms/dart/common/debug-symbols/index.mdx

@@ -1,35 +1,9 @@
 ---
 title: Debug Symbols
-description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications."
 sidebar_order: 3
 ---
 
-Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
+Sentry currently does not support symbolication or debug symbol uploads for pure Dart applications. 
+This feature is being tracked in our GitHub issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508).
 
-<Alert level="warning">
-
-Sentry currently doesn't support uploading debug symbols for pure Dart applications. Please see the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. This feature is being tracked in our GitHub Issue: [sentry-dart/#1508](https://github.com/getsentry/sentry-dart/issues/1508).
-
-</Alert>
-
-## What Are Debug Symbols?
-
-Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
-
-## When to Upload Debug Symbols
-
-With default settings, complete stack traces are available in your Dart errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
-
-## Upload Methods
-
-Sentry offers several methods to upload debug symbols for Dart applications:
-
-1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, Desktop and Web.
-
-2. **[Manual Upload Options](/platforms/dart/debug-symbols/manual-upload):**
-   - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes.
-   - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI.
-   - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes.
-   - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications.
-
-Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. 
+See the [Flutter debug symbols documentation](/platforms/dart/guides/flutter/debug-symbols/) for Flutter applications. 

docs/platforms/dart/guides/flutter/debug-symbols/dart-plugin.mdx

@@ -1,9 +1,9 @@
 ---
 title: Sentry Dart Plugin
-description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Dart application."
+description: "Learn how to use the Sentry Dart Plugin to automatically upload debug symbols for your Flutter application."
 sidebar_order: 1
 ---
 
-The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Dart applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication.
+The [Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin) is the recommended way to upload debug symbols for Flutter applications. It automates the upload process for Android, iOS, macOS, and Web, making it seamless to provide Sentry with the necessary files for symbolication.
 
 <PlatformContent includePath="debug-symbols/dart-plugin" /> 

docs/platforms/dart/guides/flutter/debug-symbols/index.mdx

@@ -1,29 +1,23 @@
 ---
 title: Debug Symbols
-description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Dart applications."
+description: "Learn about uploading debug symbols to enable symbolication of stack traces in your Flutter applications."
 sidebar_order: 3
 ---
 
-Debug symbols are essential for understanding stack traces in your Dart application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
+Debug symbols are essential for understanding stack traces in your Flutter application when errors occur. Without debug symbols, stack traces from minified or obfuscated code can be difficult or impossible to interpret.
 
 ## What Are Debug Symbols?
 
-Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Dart application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
+Debug symbols provide the necessary information to convert program addresses back to function names, source file names, and line numbers. When you build a Flutter application, especially with obfuscation or optimization enabled, this information is typically removed from the main application bundle to reduce size.
 
 ## When to Upload Debug Symbols
 
-With default settings, complete stack traces are available in your Dart errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
+With default settings, complete stack traces are available in your Flutter errors out of the box, unless you use [`split-debug-info`](https://flutter.dev/docs/perf/app-size#reducing-app-size) and [`obfuscate`](https://flutter.dev/docs/deployment/obfuscate) flags. In these cases, you must upload the debug information files generated by the build, so Sentry can show proper stack traces.
 
 ## Upload Methods
 
-Sentry offers several methods to upload debug symbols for Dart applications:
+Sentry offers several methods to upload debug symbols for Flutter applications:
 
-1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest way to automatically upload debug symbols for iOS, Android, and Web.
+1. **[Sentry Dart Plugin (Recommended)](/platforms/dart/guides/flutter/debug-symbols/dart-plugin)** - The easiest and most reliable way to upload debug symbols for Flutter applications. It automatically processes, filters, and uploads the correct symbol files for iOS, Android, and Web - significantly reducing the chances of misconfiguration.
 
-2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload):**
-   - [iOS and macOS](/platforms/apple/dsym/) - Upload dSYM files for symbolication of Apple platform crashes.
-   - [Android](/cli/dif/#uploading-files) - Upload mapping files manually using the Sentry CLI.
-   - [Android NDK](/cli/dif/#uploading-files) - Upload ELF DWARF debug files for native code crashes.
-   - [Web](/cli/releases/#upload-source-maps) - Upload source maps for Flutter web applications.
-
-Choose the method that best suits your workflow and platform requirements. For most users, the Sentry Dart Plugin provides the simplest solution across all platforms. 
+2. **[Manual Upload Options](/platforms/dart/guides/flutter/debug-symbols/manual-upload)** - Because this method is more complex, requires additional manual steps, and is not currently documented, we do not recommend using it unless absolutely necessary.

docs/platforms/dart/guides/flutter/debug-symbols/manual-upload.mdx

@@ -1,9 +1,9 @@
 ---
 title: Manual Upload
-description: "Learn how to manually upload debug symbols for your Dart applications."
+description: "Learn how to manually upload debug symbols for your Flutter applications."
 sidebar_order: 2
 ---
 
-If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Dart applications. This page provides instructions for different platforms.
+If you choose not to use the Sentry Dart Plugin, you can manually upload debug symbols for your Flutter applications. This page provides instructions for different platforms.
 
 <PlatformContent includePath="debug-symbols/manual-upload" /> 

platform-includes/debug-symbols/dart-plugin/dart.flutter.mdx

@@ -39,6 +39,14 @@ sentry:
   # ___PRODUCT_OPTION_END___ source-maps
 ```
 
+<OnboardingOption optionId="source-context">
+<Alert>
+For iOS and Android builds, source context is only supported if you build the Flutter app using the `--split-debug-info` flag.
+
+Additionally source context currently only covers code in the main app package. For example, if your main app package depends on an internal package or a third-party package and an error occurs in that dependency, its source context will not be shown.
+</Alert>
+</OnboardingOption>
+
 <OnboardingOption optionId="dsym">
 The `upload_debug_symbols` option defaults to `true` when not specified.
 </OnboardingOption>