Say which two things 2.0.0 breaks

CHANGELOG.md

@@ -12,11 +12,12 @@ Tier 5, complete, and the release the transport seam was built for. `kdrant-tran
 opt-in gRPC engine behind the same `QdrantClient`, and `kdrant-core` compiles for the JVM and eight
 Kotlin/Native targets. Adding a second engine changed no line of `kdrant-core`.
 
-**The major bump is for the artifact layout, not the API.** The JVM public API is unchanged byte for
-byte — `apiCheck` reports no diff against `1.2.0`. `kdrant-core`'s JVM classes moved to
-`kdrant-core-jvm` because the module is multiplatform now: a Gradle build changes only the version
-number, a Maven build naming `kdrant-core` has to move. See
-[STABILITY.md](STABILITY.md#upgrading-from-1-x).
+**Two things make this a major.** `kdrant-core`'s JVM classes moved to `kdrant-core-jvm`, because the
+module is multiplatform now: a Gradle build changes only the version number, a Maven build naming
+`kdrant-core` has to move. And `ScrollRequest` and `SearchRequest` gained a `shardKey` parameter, which
+changed their generated constructor and `copy`, so code that called `copy()` on either against a `1.x`
+jar has to be recompiled. Source stays compatible. The multiplatform migration itself changed no public
+API at all. See [STABILITY.md](STABILITY.md#upgrading-from-1-x).
 
 ### Added
 
@@ -85,8 +86,8 @@ number, a Maven build naming `kdrant-core` has to move. See
 - **`kdrant-core`'s artifact layout changed with the multiplatform move.** The `kdrant-core` coordinate
   now carries Gradle module metadata and the JVM classes live in `kdrant-core-jvm`. A Gradle build
   resolves the right variant from the same coordinate and needs no change; a Maven build names the
-  artifact directly and must move to `kdrant-core-jvm`, which the BOM now constrains as well. The JVM
-  public API is unchanged, byte for byte — `apiCheck` reports no diff.
+  artifact directly and must move to `kdrant-core-jvm`, which the BOM now constrains as well. The
+  migration changed no public API: the `*.api` dump is identical either side of it.
 - The default dispatcher is platform-dependent, and is the one declaration the migration had to split.
   It stays `Dispatchers.IO` on the JVM. On Kotlin/Native it is `Dispatchers.Default`, because the
   coroutines library still keeps its native IO dispatcher internal. Passing your own dispatcher works

README.md

@@ -354,8 +354,8 @@ the target would ship a DSL with nothing to send.
 `kdrant-transport-grpc` is an opt-in gRPC engine behind the same `QdrantClient`, generated from Qdrant's
 own `.proto` files rather than wrapping the official client, so a REST build still resolves no gRPC, no
 protobuf and no Netty — checked on every build, not asserted. And `kdrant-core` moved to Kotlin
-Multiplatform: the JVM plus eight Kotlin/Native targets, with the JVM public API unchanged byte for
-byte. Both engines are now held to one shared behavioural suite against a real Qdrant. The major bump is
+Multiplatform: the JVM plus eight Kotlin/Native targets, a migration that changed no public API at
+all. Both engines are now held to one shared behavioural suite against a real Qdrant. The major bump is
 for the artifact layout, not the API: `kdrant-core`'s JVM classes moved to `kdrant-core-jvm`, which a
 Gradle build does not notice and a Maven build does. See
 [STABILITY.md](STABILITY.md#upgrading-from-1-x).

STABILITY.md

@@ -68,20 +68,28 @@ Within a major version:
 
 ## Upgrading from `1.x`
 
-`2.0.0` breaks one thing, and it is not the API. **The JVM public API is unchanged, byte for byte** —
-`apiCheck` reports no diff against `1.2.0`. What changed is where `kdrant-core`'s JVM classes are
-published.
-
-`kdrant-core` is now a Kotlin Multiplatform library, so its own coordinate carries Gradle module
-metadata and the JVM classes live in `kdrant-core-jvm`. Gradle reads that metadata and resolves the
-variant, so **a Gradle build changes nothing but the version number**. Maven does not read it, so a
-Maven build naming `kdrant-core` gets no classes and must move to `kdrant-core-jvm`. Depending on
-`kdrant-transport-rest` or `kdrant-transport-grpc`, which is what the README recommends, is unaffected
-either way.
-
-The rest of `2.0.0` is additive: the gRPC engine is a module you do not have, and every `1.x` call site
+`2.0.0` breaks two things, and **source compatibility is not one of them**: every `1.x` call site
 compiles unchanged.
 
+**Where `kdrant-core`'s JVM classes are published.** The module is Kotlin Multiplatform now, so its own
+coordinate carries Gradle module metadata and the classes live in `kdrant-core-jvm`. Gradle reads that
+metadata and resolves the variant, so a Gradle build changes nothing but the version number. Maven does
+not read it, so a Maven build naming `kdrant-core` gets no classes and must move to `kdrant-core-jvm`.
+Depending on `kdrant-transport-rest` or `kdrant-transport-grpc`, which is what the README recommends, is
+unaffected either way.
+
+**`ScrollRequest` and `SearchRequest` gained a `shardKey` parameter.** That is the case
+[above](#what-may-still-change-in-a-minor) arriving for real: the constructor keeps its defaults and
+source keeps compiling, but the generated `copy` and `componentN` changed, so code that called `copy()`
+on either type against a `1.x` jar has to be recompiled. Nothing else in the `*.api` dump was removed.
+
+**The multiplatform migration itself changed no public API.** The dump is identical either side of it,
+which is worth stating because it is the part that sounds like it should have broken something. What
+broke is the two lines above.
+
+The rest of `2.0.0` is additive: the gRPC engine is a module you do not have yet, and cluster support,
+formula and MMR reranking, shard-scope snapshots and the Koog module are new operations.
+
 ## Java interoperability
 
 Kdrant is deliberately **Kotlin-coroutine-first** — that is the wedge (see the [README](README.md)). The