diff --git a/docs/DEV.md b/docs/DEV.md
index 44de92a5..0361753d 100644
--- a/docs/DEV.md
+++ b/docs/DEV.md
@@ -96,6 +96,16 @@ real API ([CONTRIBUTING.md](https://github.com/corbitsdev/corbits-builder/blob/m
 | `bun run vendor:verify`   | Checks `vendor/interchange` matches its pinned upstream commit.                                                                  |
 | `bun run skills:react-ui` | Regenerates the designer's `@corbits/react-ui` API reference.                                                                    |
 
+## Migrations
+
+Create migrations with `bun run db:generate`. The migrator skips any migration
+whose journal `when` is not later than the newest one a database has applied,
+and `apps/hub/src/db/migrate.test.ts` fails when the journal is out of order.
+Never move a `when` that has merged: databases keep the value they applied.
+
+Until 8 November 2026 01:06:40 UTC, a generated `when` sorts before 0038's; set
+it to one more than the previous entry's. Delete this paragraph after that date.
+
 ## Seeding dummy projects
 
 `bun run dev:seed` populates a workspace tenant (defaulting to the first