diff --git a/docs/embedding-migrations.md b/docs/embedding-migrations.md
index e9c425128..9fdc40a8f 100644
--- a/docs/embedding-migrations.md
+++ b/docs/embedding-migrations.md
@@ -115,12 +115,17 @@ BEGIN;
 -- 1. Drop the HNSW index. It can't survive the column type change.
 DROP INDEX IF EXISTS idx_chunks_embedding;
 
--- 2. Alter the column type.
-ALTER TABLE content_chunks ALTER COLUMN embedding TYPE vector(<NEW_DIMS>);
-
--- 3. Clear stale embeddings so they don't survive into the new space.
+-- 2. Clear stale embeddings FIRST. This must happen BEFORE the column
+--    alter: pgvector refuses to cast existing vectors across dimensions
+--    ("expected <NEW_DIMS> dimensions, not <OLD_DIMS>"), so altering a
+--    column that still holds old-width vectors aborts the transaction.
+--    NULLs cast fine. (The old vectors are unusable in the new space
+--    anyway — wiping them is step 3 of the recipe's rationale.)
 UPDATE content_chunks SET embedding = NULL, embedded_at = NULL;
 
+-- 3. Alter the column type (all rows are NULL now, so the cast succeeds).
+ALTER TABLE content_chunks ALTER COLUMN embedding TYPE vector(<NEW_DIMS>);
+
 -- 4. Recreate the HNSW index ONLY IF dims <= 2000. Above that, leave it
 --    indexless and rely on exact scans (gbrain searchVector handles this
 --    automatically — search just gets slower, not broken).