docs(mobile): add build-time upload setup

docs/platforms/apple/guides/ios/manual-setup.mdx

@@ -98,3 +98,42 @@ struct SwiftUIApp: App {
     }
 }
 ```
+
+## Add Readable Stack Traces With Debug Symbols
+
+To get readable stack traces for release builds, upload dSYM files to Sentry during your Xcode build. Add `--include-sources` to upload source context at the same time, so Sentry can show code snippets next to stack frames.
+
+1. Install [Sentry CLI](/cli/installation/).
+2. Configure Sentry CLI authentication. Use `SENTRY_AUTH_TOKEN` in your CI/CD environment, or use a local `.sentryclirc` file and add it to `.gitignore`.
+3. In your app target build settings, set `DEBUG_INFORMATION_FORMAT` to `DWARF with dSYM File` and `ENABLE_USER_SCRIPT_SANDBOXING` to `NO` for the configurations that should upload debug symbols.
+4. Add a new Xcode Run Script build phase named `Upload Debug Symbols to Sentry`:
+
+<OrgAuthTokenNote />
+
+```bash
+# This script is responsible for uploading debug symbols and source context for Sentry.
+if [[ "$(uname -m)" == arm64 ]]; then
+  export PATH="/opt/homebrew/bin:$PATH"
+fi
+
+if which sentry-cli >/dev/null; then
+  export SENTRY_ORG=___ORG_SLUG___
+  export SENTRY_PROJECT=___PROJECT_SLUG___
+  ERROR=$(sentry-cli debug-files upload --include-sources "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
+  if [ ! $? -eq 0 ]; then
+    echo "warning: sentry-cli - $ERROR"
+  fi
+else
+  echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases"
+fi
+```
+
+5. Add this path to the Run Script's **Input Files**:
+
+```text
+${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
+```
+
+If you don't want to upload source code, remove the `--include-sources` argument from the Run Script.
+
+For more details, see <PlatformLink to="/dsym/">Uploading Debug Symbols</PlatformLink> and <PlatformLink to="/sourcecontext/">Source Context</PlatformLink>.

docs/platforms/dart/guides/flutter/index.mdx

@@ -31,11 +31,11 @@ Select which Sentry features you'd like to install in addition to Error Monitori
 
 <OnboardingOptionButtons
   options={[
-    'error-monitoring',
-    'performance',
-    'profiling',
-    'session-replay',
-    'logs',
+    "error-monitoring",
+    "performance",
+    "profiling",
+    "session-replay",
+    "logs",
   ]}
 />
 
@@ -92,6 +92,8 @@ If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flu
 
 - Configure the SDK with your DSN and performance monitoring options in your main.dart file.
 - Update your `pubspec.yaml` with the `sentry_flutter` and `sentry_dart_plugin` packages.
+- Add Sentry Dart Plugin configuration for debug symbol uploads.
+- Create `sentry.properties` with an auth token for local uploads (this file is automatically added to `.gitignore`).
 - Add an example error to verify your setup.
 
 </Expandable>
@@ -165,6 +167,12 @@ try {
 ## Next Steps
 
 - Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup
-- <PlatformLink to="/features">Learn about the features of Sentry's Flutter SDK</PlatformLink>
-- <PlatformLink to="/upload-debug/#when-to-upload/">Add readable stack traces to errors</PlatformLink>
-- <PlatformLink to="/tracing/instrumentation">Add performance instrumentation to your app</PlatformLink>
+- <PlatformLink to="/features">
+    Learn about the features of Sentry's Flutter SDK
+  </PlatformLink>
+- <PlatformLink to="/upload-debug/#when-to-upload/">
+    Add readable stack traces to errors
+  </PlatformLink>
+- <PlatformLink to="/tracing/instrumentation">
+    Add performance instrumentation to your app
+  </PlatformLink>

docs/platforms/dart/guides/flutter/manual-setup.mdx

@@ -9,12 +9,7 @@ If you can't (or prefer not to) run the [automatic setup](/platforms/dart/guides
 ## Install
 
 <OnboardingOptionButtons
-  options={[
-    'error-monitoring',
-    'performance',
-    'profiling',
-    'logs',
-  ]}
+  options={["error-monitoring", "performance", "profiling", "logs"]}
 />
 
 Sentry captures data by using an SDK within your application's runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works.
@@ -67,6 +62,55 @@ Future<void> main() async {
 }
 ```
 
+## Add Readable Stack Traces With Debug Symbols
+
+To get readable stack traces for obfuscated Flutter builds and native frames, configure the Sentry Dart Plugin to upload debug symbols during your release workflow.
+
+1. Add `sentry_dart_plugin` as a dev dependency:
+
+```yml {filename:pubspec.yaml}
+dev_dependencies:
+  sentry_dart_plugin: ^{{@inject packages.version('sentry.dart.plugin', '2.0.0') }}
+```
+
+2. Add the non-secret plugin configuration to `pubspec.yaml`:
+
+```yml {filename:pubspec.yaml}
+sentry:
+  upload_debug_symbols: true
+  upload_source_maps: true
+  project: ___PROJECT_SLUG___
+  org: ___ORG_SLUG___
+```
+
+3. Configure Sentry auth for local builds with an ignored `sentry.properties` file, or set `SENTRY_AUTH_TOKEN` in your CI/CD environment:
+
+<OrgAuthTokenNote />
+
+```properties {filename:sentry.properties}
+auth_token=___ORG_AUTH_TOKEN___
+```
+
+```text {filename:.gitignore}
+sentry.properties
+```
+
+4. For production builds, build with debug information and then run the plugin:
+
+```bash
+flutter build <target> --obfuscate --split-debug-info=build/debug-info
+flutter pub run sentry_dart_plugin
+```
+
+For Flutter Web, build with source maps before running the plugin:
+
+```bash
+flutter build web --release --source-maps
+flutter pub run sentry_dart_plugin
+```
+
+For more details, see <PlatformLink to="/debug-symbols/dart-plugin/">Sentry Dart Plugin</PlatformLink>.
+
 ## Verify
 
 Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes.
@@ -86,6 +130,12 @@ try {
 
 ## Next Steps
 
-- <PlatformLink to="/features">Learn about the features of Sentry's Flutter SDK</PlatformLink>
-- <PlatformLink to="/upload-debug/#when-to-upload/">Add readable stack traces to errors</PlatformLink>
-- <PlatformLink to="/tracing/instrumentation">Add performance instrumentation to your app</PlatformLink>
+- <PlatformLink to="/features">
+    Learn about the features of Sentry's Flutter SDK
+  </PlatformLink>
+- <PlatformLink to="/upload-debug/#when-to-upload/">
+    Add readable stack traces to errors
+  </PlatformLink>
+- <PlatformLink to="/tracing/instrumentation">
+    Add performance instrumentation to your app
+  </PlatformLink>