docs(error-tracking): document --force flag and re-upload behavior for dSYM uploads

contents/docs/error-tracking/_snippets/cli/upload.mdx

@@ -6,3 +6,5 @@ posthog-cli sourcemap upload --directory ./path/to/assets --release-name my-app
 The CLI will create or reuse the [release](/docs/error-tracking/releases) for the detected or supplied release name and version. The CLI will try to detect release name and version information, but you can set them explicitly with `--release-name` and `--release-version`. We recommend setting the release name, and letting the CLI detect the version, if your project is continuously deployed (the version will be the git commit hash at build time).
 
 > **💡 Tip:** You can use `--delete-after` option to clean up sourcemaps after uploading them.
+
+By default, if a symbol set with the same chunk ID already exists on the server with different content, the CLI silently skips the re-upload. This prevents accidental overwrites of production symbol sets.

contents/docs/error-tracking/upload-source-maps/ios.mdx

@@ -3,9 +3,9 @@ title: Upload dSYMs for iOS
 showStepsToc: true
 ---
 
-import CLIDownload from "../_snippets/cli/download.mdx"
-import CLIAuthenticate from "../_snippets/cli/authenticate.mdx"
-import StepVerifySymbolSetsUpload from '../_snippets/StepVerifySymbolSetsUpload'
+import CLIDownload from "../_snippets/cli/download.mdx";
+import CLIAuthenticate from "../_snippets/cli/authenticate.mdx";
+import StepVerifySymbolSetsUpload from "../_snippets/StepVerifySymbolSetsUpload";
 
 <CalloutBox icon="IconInfo" title="CLI version requirement" type="action">
 
@@ -17,7 +17,7 @@ A minimum CLI version of [0.7.4](https://github.com/PostHog/posthog/releases/tag
 
 <Step title="Download CLI" badge="required">
 
-<CLIDownload/>
+<CLIDownload />
 
 </Step>
 
@@ -38,10 +38,10 @@ In Xcode, configure your build settings to generate dSYMs:
 5. Make sure Release configurations have **DWARF with dSYM File**
 
 <ProductScreenshot
-    imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/DWARF_and_d_SYM_xcode_settings_light_f6a8bb74c3.png"
-    imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/DWARF_and_d_SYM_xcode_settings_7b2c628b52.png"
-    alt="Xcode dSYM setting"
-    classes="rounded"
+  imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/DWARF_and_d_SYM_xcode_settings_light_f6a8bb74c3.png"
+  imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/DWARF_and_d_SYM_xcode_settings_7b2c628b52.png"
+  alt="Xcode dSYM setting"
+  classes="rounded"
 />
 
 <CalloutBox icon="IconWarning" title="Disable User Script Sandboxing" type="action">
@@ -53,10 +53,9 @@ You must disable User Script Sandboxing for the upload script to work:
 
 **Why is this required?**
 
-When User Script Sandboxing is enabled, Xcode only allows run scripts to access files explicitly specified in the build phase's **Input Files**. 
+When User Script Sandboxing is enabled, Xcode only allows run scripts to access files explicitly specified in the build phase's **Input Files**.
 The dSYM upload script needs to walk directories to locate and read dSYM bundles, and execute `posthog-cli` which are currently not allowed with User Script Sandboxing enabled.
 
-
 </CalloutBox>
 
 </Step>
@@ -94,7 +93,6 @@ By default, only debug symbols are uploaded. To include source code snippets in
 1. In the Run Script build phase, click the chevron to expand
 2. Set the **environment Variable** when calling the upload script:
 
-
 <MultiLanguage>
 
 ```bash file=Swift Package Manager
@@ -109,6 +107,8 @@ POSTHOG_INCLUDE_SOURCE=1 ${PODS_ROOT}/PostHog/build-tools/upload-symbols.sh
 
 **Note**: This increases upload size and build times. Only enable if you need source code context in PostHog's error tracking UI.
 
+When `POSTHOG_INCLUDE_SOURCE` is set, the CLI automatically forces overwrites of existing symbol sets. This allows you to upgrade from a source-less upload to one that includes source code context without manually passing `--force`.
+
 </Step>
 
 <Step title="Build and verify" badge="required">
@@ -146,10 +146,10 @@ view.addSubview(button)
 
 </MultiLanguage>
 
-2. Build and run your app in Xcode, 
-    - Make sure the debugger is not attached, since it will intercept the crash and prevent the report from being collected. You can: 
-        - Detach the debugger (click the stop button in Xcode) and run the app directly from the device/simulator home screen
-        - Or uncheck "Debug executable" in the scheme settings before running
+2. Build and run your app in Xcode,
+   - Make sure the debugger is not attached, since it will intercept the crash and prevent the report from being collected. You can:
+     - Detach the debugger (click the stop button in Xcode) and run the app directly from the device/simulator home screen
+     - Or uncheck "Debug executable" in the scheme settings before running
 
 3. Reopen the app from your device or simulator's home screen (not from Xcode).
 
@@ -192,4 +192,16 @@ Ensure `ENABLE_USER_SCRIPT_SANDBOXING` is set to `NO` in your build settings.
 
 ### dSYMs not being generated
 
-Verify that `DEBUG_INFORMATION_FORMAT` is set to **DWARF with dSYM File** for the configuration you're building (Debug or Release).
+Verify that `DEBUG_INFORMATION_FORMAT` is set to **DWARF with dSYM File** for the configuration you're building (Debug or Release).
+
+### Symbol re-uploads are silently skipped
+
+By default, the CLI silently skips re-uploads when a symbol set with the same UUID already exists on the server with different content. This prevents accidental overwrites of production symbol sets from a local development machine.
+
+To overwrite an existing symbol set, pass the `--force` flag:
+
+```bash
+posthog-cli dsym upload --directory ./path/to/dsyms --force
+```
+
+You don't need `--force` when using `POSTHOG_INCLUDE_SOURCE=1` – source-inclusive uploads automatically overwrite existing source-less uploads.