diff --git a/packages/react-reconciler/README.md b/packages/react-reconciler/README.md
index 82080513a45..62bf2f24fcf 100644
--- a/packages/react-reconciler/README.md
+++ b/packages/react-reconciler/README.md
@@ -351,3 +351,21 @@ If you use the persistent mode instead of the mutation mode, you would still nee
 You can optionally implement hydration to "attach" to the existing tree during the initial render instead of creating it from scratch. For example, the DOM renderer uses this to attach to an HTML markup.
 
 To support hydration, you need to declare `supportsHydration: true` and then implement the methods in the "Hydration" section [listed in this file](https://github.com/facebook/react/blob/main/packages/react-reconciler/src/forks/ReactFiberConfig.custom.js). File an issue if you need help.
+
+
+### Removal of flushSync
+
+The flushSync export was previously available from react-reconciler but has been removed without a public deprecation period. Custom renderers relying on this API may encounter breaking changes.
+
+# Migration
+
+Custom renderers should migrate to the following APIs instead:
+
+- updateContainerSync — for synchronously updating a container
+- flushSyncWork — for flushing pending synchronous work
+
+These APIs provide more explicit control over synchronous rendering behavior and replace the previous flushSync usage.
+
+# Why this changed
+
+The reconciler internals were updated to better separate renderer responsibilities and reduce reliance on ambiguous synchronous entry points.
\ No newline at end of file