diff --git a/README.md b/README.md
index e87c5243..d2d09f3b 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ cargo add worktable
 | **Paged in-memory storage** | Records live in `DataPages` with a free list for reuse. `rkyv` gives zero-copy access to archived rows. |
 | **Concurrency** | Lock-free concurrent indexes with change-data-capture, plus a row-level `LockMap` for ordered access. |
 | **Optional persistence** | `PersistedWorkTable` writes to local disk; the `s3-support` feature syncs that to S3. Both opt-in, so a purely in-memory table pays for neither. |
-| **Schema migration** | `worktable_version!` and `migration_engine!` version a table's schema and generate migrations between versions. |
+| **Schema migration** | `worktable_version!` and `migration_engine!` version a table's schema and generate migrations between versions. See [docs/migration.md](docs/migration.md). |
 | **Memory accounting** | `MemStat` reports actual memory held. |
 
 ## Persistence
diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 00000000..8a901ba2
Binary files /dev/null and b/docs/migration.md differ