diff --git a/docs/docs/06_migration-guide/01_v2x-v3x.md b/docs/docs/06_migration-guide/01_v2x-v3x.md
deleted file mode 100644
index 1d07b784..00000000
--- a/docs/docs/06_migration-guide/01_v2x-v3x.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# `v2.x` → `v3.x`
-
--   The root registration method was _renamed_ from `register` (resp. `registerAsync`) to `forRoot` (resp. `forRootAsync`) to align with the convention.
-
-    ```diff
-    // highlight-start
-    - ClsModule.register({
-    + ClsModule.forRoot({
-    // highlight-end
-          middleware: { mount: true },
-      }),
-    ```
-
--   Namespace injection support with `forFeature` was dropped entirely, and now that method is used to register [Proxy Providers](../03_features-and-use-cases/06_proxy-providers.md). If you still have a use case for namespaces, you can create a namespaced `ClsService` and use a custom provider to inject it.  
-    Example:
-
-    ```ts
-    class MyContextService extends ClsService<MyStore> {}
-    const myContextService = new MyContextService(new AsyncLocalStorage());
-
-    // [...]
-    providers: [
-        {
-            provide: MyContextService,
-            useValue: myContextService,
-        },
-    ];
-    ```
diff --git a/docs/docs/06_migration-guide/01_v3x-v4x.md b/docs/docs/06_migration-guide/01_v3x-v4x.md
new file mode 100644
index 00000000..8e5c4a40
--- /dev/null
+++ b/docs/docs/06_migration-guide/01_v3x-v4x.md
@@ -0,0 +1,61 @@
+# `v3.x` → `v4.x`
+
+The `v4` major version should be largely backwards compatible with `v3`. However, breaking changes were introduced in some less-used APIs that should be mentioned.
+
+## Changed base type of Proxy Providers
+
+The default underlying value of [Proxy Providers](../03_features-and-use-cases/06_proxy-providers.md) was changed to `{}`. This means that the `typeof` operator will now return `'object'`, which is more intuitive. ([Link to original discussion](https://github.com/Papooch/nestjs-cls/issues/82))
+
+The use-case of using a Proxy Provider as a function is still supported, but now requires the `type` option to be set to `'function'`.
+
+```ts
+ClsModule.forFeature({
+    provide: 'class-proxy',
+    useClass: SomeClass,
+});
+ClsModule.forFeature({
+    provide: 'function-proxy',
+    useFactory: () => someFunction,
+    // highlight-start
+    type: 'function',
+    // highlight-end
+});
+```
+
+```ts
+@Injectable()
+class SomeService {
+    constructor(
+        @Inject('class-proxy')
+        private readonly someClass: SomeClass,
+        @Inject('function-proxy')
+        private readonly functionProvider: () => void,
+    ) {
+        console.log(typeof this.someClass); // 'object'
+        console.log(typeof this.functionProvider); // 'function'
+    }
+}
+```
+
+## Changed default of `ifNested` option
+
+The default of the [`ifNested`](../04_api/01_service-interface.md#clscontextoptions) option was changed from `override` to `inherit`, which more closely aligns with _most_ real-world use-cases.
+
+If you used the `ClsService#run` method _without_ explicitly setting the `ifNested` option, you should check if the new default behavior is compatible with your use-case and adjust accordingly.
+
+```ts
+this.cls.run(
+    // highlight-start
+    { ifNested: 'override' },
+    // highlight-end
+    () => {
+        // ... rest of the code
+    },
+);
+```
+
+## Changed default of `resolveProxyProviders` in `UseCls` decorator
+
+This value was undocumented in `v3`, but the default was `false`. It was changed to `true` in `v4` to align with the default behavior of other enhancers.
+
+This change should not affect most use-cases, because you either don't use Proxy Providers at all, or you use them and therefore had to set it to `true` anyway. The only case where this might be a breaking change is if you used the `@UseCls` in a module where you explicitly _did not_ want to resolve Proxy Providers and therefore did not import their dependencies. In that case, you should set the `resolveProxyProviders` option to `false` in the decorator.
diff --git a/docs/docs/06_migration-guide/02_v2x-v3x.md b/docs/docs/06_migration-guide/02_v2x-v3x.md
new file mode 100644
index 00000000..37d9f82e
--- /dev/null
+++ b/docs/docs/06_migration-guide/02_v2x-v3x.md
@@ -0,0 +1,32 @@
+# `v2.x` → `v3.x`
+
+## Root registration method renamed
+
+-   The root registration method was _renamed_ from `register` (resp. `registerAsync`) to `forRoot` (resp. `forRootAsync`) to align with the convention.
+
+```diff
+// highlight-start
+- ClsModule.register({
++ ClsModule.forRoot({
+// highlight-end
+        middleware: { mount: true },
+  }),
+```
+
+## Namespace support dropped
+
+Namespace injection support with `forFeature` was dropped entirely, and now that method is used to register [Proxy Providers](../03_features-and-use-cases/06_proxy-providers.md). If you still have a use case for namespaces, you can create a namespaced `ClsService` and use a custom provider to inject it.  
+ Example:
+
+```ts
+class MyContextService extends ClsService<MyStore> {}
+const myContextService = new MyContextService(new AsyncLocalStorage());
+
+// [...]
+providers: [
+    {
+        provide: MyContextService,
+        useValue: myContextService,
+    },
+];
+```