docs(kmp): Flag CocoaPods deprecation and document SPM linking rules

docs/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle.mdx

@@ -8,8 +8,10 @@ The [Sentry Kotlin Multiplatform Gradle Plugin](https://github.com/getsentry/sen
 
 The Gradle Plugin supports the following features:
 - Auto-installation of the Sentry Kotlin Multiplatform SDK.
-- Auto-installation of the Sentry Cocoa SDK via Cocoapods (if the Kotlin Cocoapods plugin is applied).
 - Automatic configuration of the Kotlin/Native linker for seamless usage with the Swift Package Manager.
+- Auto-installation of the Sentry Cocoa SDK via CocoaPods (deprecated, only if the Kotlin CocoaPods plugin is applied).
+
+<Include name="kmp-cocoapods-deprecation.mdx" />
 
 ## Setup
 
@@ -48,7 +50,7 @@ sentryKmp {
       sentryKmpVersion = "{{@inject packages.version('sentry.kotlin.kmp', '0.9.0') }}"
     }
 
-    // Configure the Cocoapods plugin.
+    // Configure the Cocoapods plugin (deprecated).
     cocoapods {
       // Enable auto-installation of the Sentry Cocoa SDK with Cocoapods.
       // Default is enabled.
@@ -60,6 +62,7 @@ sentryKmp {
     }
 
     // Configure the linker. This is only relevant if you are using SPM.
+    // The linker is skipped when the Kotlin CocoaPods plugin is applied.
     linker {
       // Path to the Xcode project that will be used to link the framework.
       // This is used to find the derived data path in which the framework is stored for SPM.
@@ -74,3 +77,20 @@ sentryKmp {
   }
 }
 ```
+
+## How Auto-Install and Linking Interact
+
+The plugin decides how to provide Sentry Cocoa based on whether the Kotlin CocoaPods plugin is applied to the module. The two paths don't combine: when the CocoaPods plugin is applied, linker configuration is skipped, even if you set `xcodeprojPath` or `frameworkPath`.
+
+| Your setup | What the plugin does | Supported |
+| --- | --- | --- |
+| Sentry Cocoa added with Swift Package Manager, Kotlin CocoaPods plugin **not** applied | Links the Kotlin/Native framework against Sentry Cocoa, using `linker` settings to locate it | Yes (recommended) |
+| Kotlin CocoaPods plugin applied, `autoInstall.cocoapods.enabled = true` | Adds the `Sentry` pod if you haven't declared one yourself. A pod you declared is left unchanged | Yes (deprecated) |
+| Kotlin CocoaPods plugin applied, `autoInstall.cocoapods.enabled = false` | Does nothing for Apple targets. You must declare the `Sentry` pod yourself | Yes (deprecated) |
+| Kotlin CocoaPods plugin applied **and** Sentry Cocoa added with Swift Package Manager | Skips linking, so the SPM-provided framework isn't linked | No |
+
+A few additional rules apply:
+
+- Sentry Cocoa installation and linking only run on a macOS host. On other hosts, only the `commonMain` dependency is installed.
+- Linking is set up only for the Apple targets being compiled in the current build, so Android-only builds skip it.
+- If you set both `frameworkPath` and `xcodeprojPath`, `frameworkPath` takes precedence. It must point to a `Sentry.xcframework` or `Sentry-Dynamic.xcframework` folder.

docs/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/index.mdx

@@ -8,7 +8,11 @@ If you can't (or prefer not to) use the [gradle plugin](/platforms/kotlin/guides
 
 ## Install
 
-Sentry captures data by using an SDK within your application’s runtime.
+Sentry captures data by using an SDK within your application's runtime.
+
+<Include name="kmp-cocoapods-deprecation.mdx" />
+
+The manual setup below uses the Kotlin CocoaPods plugin to supply Sentry Cocoa. If you're starting a new project, use the [Gradle plugin with Swift Package Manager](/platforms/kotlin/guides/kotlin-multiplatform/#install) instead.
 
 To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module:
 
@@ -90,8 +94,21 @@ If you already use SPM or prefer it over other package managers on Apple platfor
 
 #### Install
 
-In order to install the Sentry Kotlin Multiplatform SDK, you need to use Cocoapods and Swift Package Manager simultaneously, which might seem unconventional at first, especially if you're accustomed to using SPM for all your dependencies. However, you can achieve a smooth integration by using the [Kotlin Cocoapods plugin](https://kotlinlang.org/docs/native-cocoapods-dsl-reference.html#cocoapods-block) specifically for compiling and building the shared framework. You can then continue to manage all other dependencies with SPM as usual.
+To use Swift Package Manager without the Kotlin CocoaPods plugin, use the [Sentry Gradle plugin](/platforms/kotlin/guides/kotlin-multiplatform/#install). Add the Sentry Cocoa SDK to your Xcode project with [Swift Package Manager](/platforms/apple/install/swift-package-manager/), then apply the Gradle plugin, which links the Kotlin/Native framework against it. Setting up this linking by hand isn't covered in this guide.
+
+Make sure the Sentry Cocoa version you install is compatible with your Sentry Kotlin Multiplatform SDK version. You can find the compatible versions in the [Cocoa SDK version compatibility table](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table).
+
+### Migrating From CocoaPods
+
+If your shared module currently gets Sentry Cocoa through the Kotlin CocoaPods plugin:
 
-Follow the steps for our primary installation method [Cocoapods](/platforms/kotlin/guides/kotlin-multiplatform/manual-setup/#install) to install the Sentry Kotlin Multiplatform SDK.
+1. Remove the `pod("Sentry")` declaration from the `cocoapods {}` block in your shared module's `build.gradle.kts`.
+2. If the Kotlin CocoaPods plugin is only there to supply Sentry, remove `kotlin("native.cocoapods")` and the `cocoapods {}` block, and have your iOS app consume the shared framework through [direct integration](https://kotlinlang.org/docs/multiplatform/multiplatform-direct-integration.html) instead.
+3. Add the Sentry Cocoa SDK to your Xcode project with [Swift Package Manager](/platforms/apple/install/swift-package-manager/), using the version from the compatibility table.
+4. Apply the [Sentry Gradle plugin](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/) so it can link the framework.
 
-After you've consumed the shared framework in your application via Cocoapods, you can continue with SPM for other dependencies without disrupting your existing workflow.
+<Alert>
+
+The Gradle plugin only sets up Swift Package Manager linking when the Kotlin CocoaPods plugin is **not** applied to the module. If your shared module is itself published as a pod (for example, your iOS app consumes it through CocoaPods), the plugin skips linking entirely. Learn more in [how auto-install and linking interact](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/#how-auto-install-and-linking-interact).
+
+</Alert>

includes/kmp-cocoapods-deprecation.mdx

@@ -0,0 +1,7 @@
+<Alert level="warning" title="CocoaPods is deprecated for Sentry Cocoa">
+
+Sentry no longer publishes the Sentry Cocoa SDK to CocoaPods after [v9.19.1](https://github.com/getsentry/sentry-cocoa/releases/tag/9.19.1), and the CocoaPods trunk becomes read-only on December 2, 2026. Existing Kotlin Multiplatform setups that get Sentry Cocoa through the Kotlin CocoaPods plugin keep working, because older versions stay available on CocoaPods, but they won't receive new Sentry Cocoa releases.
+
+For new projects, install Sentry Cocoa with [Swift Package Manager](/platforms/apple/install/swift-package-manager/) and let the [Sentry Gradle plugin](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/) handle linking. See [how auto-install and linking interact](/platforms/kotlin/guides/kotlin-multiplatform/configuration/gradle/#how-auto-install-and-linking-interact) for which setups are supported.
+
+</Alert>

platform-includes/getting-started-install/kotlin.compose-multiplatform.mdx

@@ -9,12 +9,14 @@ plugins {
 The plugin does the following:
 
 - Automatically installs the Sentry KMP dependency to `commonMain`. 
-- If you use the Kotlin Cocoapods plugin, it installs the Sentry Cocoa dependency.
 - If you use Swift Package Manager, it sets up linking to the Sentry Cocoa framework.
+- If you use the Kotlin CocoaPods plugin (deprecated), it installs the Sentry Cocoa dependency.
+
+<Include name="kmp-cocoapods-deprecation.mdx" />
 
 <Alert>
 
-If you use Swift Package Manager instead of Cocoapods, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin.
+If you use Swift Package Manager, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin.
 
 Make sure that you install the Sentry Cocoa SDK version compatible with the corresponding Sentry Kotlin Multiplatform SDK version. You can find the compatible versions in the [Sentry Kotlin Multiplatform SDK README](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table).
 

platform-includes/getting-started-install/kotlin.kotlin-multiplatform.mdx

@@ -9,12 +9,14 @@ plugins {
 The plugin does the following:
 
 - Automatically installs the Sentry KMP dependency to `commonMain`. 
-- If you use the Kotlin Cocoapods plugin, it installs the Sentry Cocoa dependency.
 - If you use Swift Package Manager, it sets up linking to the Sentry Cocoa framework.
+- If you use the Kotlin CocoaPods plugin (deprecated), it installs the Sentry Cocoa dependency.
+
+<Include name="kmp-cocoapods-deprecation.mdx" />
 
 <Alert>
 
-If you use Swift Package Manager instead of Cocoapods, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin.
+If you use Swift Package Manager, you need to install the [Sentry Cocoa dependency with Swift Package Manager](/platforms/apple/install/swift-package-manager/) in your Xcode project first before executing the Gradle plugin.
 
 Make sure that you install the Sentry Cocoa SDK version compatible with the corresponding Sentry Kotlin Multiplatform SDK version. You can find the compatible versions in the [Sentry Kotlin Multiplatform SDK README](https://github.com/getsentry/sentry-kotlin-multiplatform?tab=readme-ov-file#cocoa-sdk-version-compatibility-table).