diff --git a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
index 30e70bc0e0..adeccf52b8 100644
--- a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
+++ b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
@@ -48,3 +48,120 @@ Java users should match on `ReceiveTimeout.class` instead.
 (`pekko.remote.artery.advanced.tcp-magic`). See
 @ref:[Changing TCP magic header](../additional/rolling-updates.md#changing-tcp-magic-header) for what this means for
 rolling updates. ([PR3425](https://github.com/apache/pekko/pull/3425))
+
+## Configuration Changes in Pekko 2.x
+
+The `reference.conf` defaults have changed in a number of places. If you override any of the settings
+below in your `application.conf`, or rely on their Pekko 1.x defaults, review this list.
+
+### Changed default values
+
+* `pekko.actor.default-dispatcher.fork-join-executor.minimum-runnable` changed from `1` to `-1`.
+The value `-1` selects a JDK-aware default that maintains a minimum number of non-blocked worker
+threads on newer JDKs. Set it explicitly to `1` to restore the Pekko 1.x behavior.
+The internal dispatcher (`pekko.actor.internal-dispatcher.fork-join-executor`) uses the same new default.
+([PR2890](https://github.com/apache/pekko/pull/2890))
+* `pekko.remote.artery.propagate-harmless-quarantine-events` changed from `on` to `off`, so harmless
+quarantine events are no longer propagated by default. ([PR2430](https://github.com/apache/pekko/pull/2430))
+* `pekko.remote.artery.advanced.tcp-magic` changed from `["AKKA", "PEKK"]` to `["PEKK", "AKKA"]`
+(see the TCP magic header note above). ([PR3425](https://github.com/apache/pekko/pull/3425))
+* Artery compression heavy hitter detection is controlled by the new setting
+`pekko.remote.artery.advanced.compression.frequency-sketch-implementation`, which defaults to
+`"fast-frequency-sketch"` (a smaller, aging sketch). Set it to `"count-min-sketch"` to restore the
+Pekko 1.x implementation. ([PR3023](https://github.com/apache/pekko/pull/3023))
+* Persistence plugins no longer use the dedicated `pekko.persistence.dispatchers` by default. The
+`plugin-dispatcher` and `replay-dispatcher` settings in the journal and snapshot-store plugin
+fallbacks changed from `pekko.persistence.dispatchers.default-plugin-dispatcher` /
+`pekko.persistence.dispatchers.default-replay-dispatcher` to `pekko.actor.default-dispatcher`.
+The `pekko.persistence.dispatchers` definitions are deprecated; plugins that need a custom
+dispatcher should define their own. ([PR2482](https://github.com/apache/pekko/pull/2482))
+
+### Removed configuration
+
+* `pekko.actor.typed.timeout` was removed along with the deprecated `TypedActor` API.
+* `pekko.cluster.sharding.passivate-idle-entity-after` was removed; use
+`pekko.cluster.sharding.passivation.default-idle-strategy.idle-entity.timeout` instead.
+* The `pekko.ssl-config` and top-level `ssl-config` sections were removed along with the
+`ssl-config` library dependency.
+
+### New configuration
+
+The full `reference.conf` for each module, with descriptions of every setting, is listed in the
+@ref:[default configuration reference](../general/configuration-reference.md).
+
+@ref:[pekko-actor](../general/configuration-reference.md#config-pekko-actor):
+
+* `pekko.actor.default-dispatcher.fork-join-executor.virtual-thread-start-number`,
+`pekko.actor.default-dispatcher.thread-pool-executor.virtual-thread-start-number` and
+`pekko.actor.default-dispatcher.virtual-thread-executor.virtual-thread-start-number` control the
+starting id for virtual threads created by a dispatcher. ([PR2242](https://github.com/apache/pekko/pull/2242))
+* `pekko.actor.default-dispatcher.thread-pool-executor.virtualize` allows a thread-pool-executor
+based dispatcher to run on virtual threads (JDK 21+). The same settings were added to
+`pekko.actor.default-blocking-io-dispatcher.thread-pool-executor`.
+([PR2169](https://github.com/apache/pekko/pull/2169))
+* `pekko.scheduled-clock-interval` controls how frequently the clock used by recency-based
+passivation strategies is updated. ([PR2766](https://github.com/apache/pekko/pull/2766))
+* The async DNS resolver actors now run on the DNS dispatcher via the new deployment entries
+`pekko.actor.deployment."/IO-DNS/async-dns/*"` and (in
+@ref:[pekko-discovery](../general/configuration-reference.md#config-pekko-discovery))
+`pekko.actor.deployment."/SD-DNS/async-dns/*"`. ([PR2895](https://github.com/apache/pekko/pull/2895))
+
+@ref:[pekko-cluster-sharding-typed](../general/configuration-reference.md#config-cluster-sharding-typed),
+@ref:[pekko-cluster-sharding](../general/configuration-reference.md#config-cluster-sharding) and
+@ref:[pekko-distributed-data](../general/configuration-reference.md#config-distributed-data):
+
+* `pekko.cluster.sharded-daemon-process.keep-alive-from-number-of-nodes` and
+`pekko.cluster.sharded-daemon-process.keep-alive-throttle-interval` tune keep-alive pinging, which
+is now performed from a limited number of nodes instead of every node.
+([PR2755](https://github.com/apache/pekko/pull/2755))
+* `pekko.cluster.sharding.healthcheck.disabled-after` disables the sharding health check after the
+configured duration post member-up. ([PR2785](https://github.com/apache/pekko/pull/2785))
+* `pekko.cluster.distributed-data.expire-keys-after-inactivity` configures automatic expiry of
+inactive Distributed Data keys. ([PR2733](https://github.com/apache/pekko/pull/2733))
+
+@ref:[pekko-persistence](../general/configuration-reference.md#config-pekko-persistence),
+@ref:[pekko-persistence-typed](../general/configuration-reference.md#config-pekko-persistence-typed) and
+@ref:[pekko-persistence-query](../general/configuration-reference.md#config-pekko-persistence-query):
+
+* `pekko.persistence.query.events-by-slice-firehose` is a new section configuring the
+events-by-slice firehose query that fans out one shared journal query to many consumers.
+([PR3277](https://github.com/apache/pekko/pull/3277))
+* `pekko.persistence.typed.event-writer.max-batch-size` and
+`pekko.persistence.typed.event-writer.ask-timeout` configure the event writer.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+* `replay-batch-size` in the journal plugin fallback bounds the number of replayed events queued in
+a recovering persistent actor's mailbox. ([PR3325](https://github.com/apache/pekko/pull/3325))
+* `only-one-snapshot` in the snapshot-store plugin fallback enables retention optimizations for
+snapshot stores that only keep the latest snapshot. ([PR2767](https://github.com/apache/pekko/pull/2767))
+* `pekko.persistence.journal.inmem.delay-writes` can add an artificial write delay in tests.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+
+@ref:[pekko-remote classic](../general/configuration-reference.md#config-pekko-remote) and
+@ref:[pekko-remote Artery](../general/configuration-reference.md#config-pekko-remote-artery):
+
+* `pekko.remote.classic.passive-connection-buffer-size` bounds message buffering during a passive
+connection handoff. ([PR3361](https://github.com/apache/pekko/pull/3361))
+* `pekko.remote.classic.netty.ssl.security.hostname-verification` enables TLS hostname verification
+for classic remoting. ([PR3164](https://github.com/apache/pekko/pull/3164))
+* `pekko.remote.artery.advanced.shutdown-streams-timeout` bounds the graceful drain of Artery
+streams during shutdown. ([PR3317](https://github.com/apache/pekko/pull/3317))
+* `pekko.remote.artery.ssl.rotating-keys-engine.keystore-password` sets the password for the
+in-memory keystore used to wrap PEM-loaded keys; override it in production.
+([PR3397](https://github.com/apache/pekko/pull/3397))
+
+@ref:[pekko-serialization-jackson](../serialization-jackson.md):
+
+* `pekko.serialization.jackson.compression.max-decompressed-size` bounds the size of a payload
+after decompression. ([PR3491](https://github.com/apache/pekko/pull/3491))
+* The new `pekko-serialization-jackson3` module (based on Jackson 3) is configured under
+`pekko.serialization.jackson3`, mirroring the `pekko.serialization.jackson` settings.
+([PR2348](https://github.com/apache/pekko/pull/2348))
+
+@ref:[pekko-stream](../general/configuration-reference.md#config-pekko-stream):
+
+* `pekko.stream.materializer.stage-errors-default-log-level` controls the log level used for
+stream stage errors. ([PR2805](https://github.com/apache/pekko/pull/2805))
+* `pekko.stream.materializer.stage-actor-drain-batch` bounds the number of stage-actor messages
+drained per envelope for lazily materialized stage actors. ([PR3035](https://github.com/apache/pekko/pull/3035))
+* `pekko.stream.materializer.tls.engine` selects the stream TLS engine implementation
+(`"legacy-actor"` or the opt-in `"graph-stage"`). ([PR2878](https://github.com/apache/pekko/pull/2878))