diff --git a/README.md b/README.md
index 28bed77..bd26a2e 100644
--- a/README.md
+++ b/README.md
@@ -209,6 +209,13 @@ The encrypted index file `seedpass_entries_db.json.enc` begins with `schema_vers
 }
 ```
 
+> **Note**
+>
+> Opening a vault created by older versions automatically converts the legacy
+> `seedpass_passwords_db.json.enc` (Fernet) to AES-GCM as
+> `seedpass_entries_db.json.enc`. The original file is kept with a `.fernet`
+> extension.
+
 ## Usage
 
 After successfully installing the dependencies, install the package with:
diff --git a/docs/docs/content/01-getting-started/04-migrations.md b/docs/docs/content/01-getting-started/04-migrations.md
index 2c1cf46..3c9f18e 100644
--- a/docs/docs/content/01-getting-started/04-migrations.md
+++ b/docs/docs/content/01-getting-started/04-migrations.md
@@ -23,3 +23,16 @@ raise an error.
 
 This process happens automatically; users only need to open their vault to
 upgrade older indices.
+
+### Legacy Fernet migration
+
+Older versions stored the vault index in a file named
+`seedpass_passwords_db.json.enc` encrypted with Fernet.  When opening such a
+vault, SeedPass now automatically decrypts the legacy file, re‑encrypts it using
+AES‑GCM, and saves it under the new name `seedpass_entries_db.json.enc`.
+The original Fernet file is preserved as
+`seedpass_entries_db.json.enc.fernet` and the legacy checksum file, if present,
+is renamed to `seedpass_entries_db_checksum.txt.fernet`.
+
+No additional command is required – simply open your existing vault and the
+conversion happens transparently.