diff --git a/docs/src/guide/migration.md b/docs/src/guide/migration.md
index 32d2d89ee7f..5efd7b26b7f 100644
--- a/docs/src/guide/migration.md
+++ b/docs/src/guide/migration.md
@@ -6,6 +6,27 @@ stable and breaking changes should generally be communicated (via warnings) for
 give users a chance to migrate.  This page documents the breaking changes between releases and gives advice on how to
 migrate.
 
+## 9.0.0
+
+* Newly created FTS / inverted indexes now default to format v2 instead of v1.
+  The `LANCE_FTS_FORMAT_VERSION` environment variable no longer controls the
+  format used for newly created indexes. Users who need a specific index layout
+  should pass the index creation parameter `format_version` explicitly.
+
+* This affects users who create FTS / inverted indexes and need those indexes to
+  be readable by older Lance versions, or who depend on the v1 index layout. In
+  those cases, pass `format_version=1` when creating the index. Otherwise, newly
+  created indexes will use v2 by default, and older Lance readers may not be able
+  to read them.
+
+  ```python
+  dataset.create_scalar_index("text", "INVERTED", format_version=1)
+  ```
+
+* Existing v1 FTS indexes remain queryable. Operations that maintain an existing
+  v1 index, including append, incremental indexing, optimize, and mem-wal
+  maintained-index flush, should continue preserving the v1 format.
+
 ## 7.2.0
 
 * The `IndexSegmentBuilder` API has been removed from Rust, Python, and Java.