diff --git a/doc/source/user/age.md b/doc/source/user/age.md
index 19eb26f4b..3bec56737 100644
--- a/doc/source/user/age.md
+++ b/doc/source/user/age.md
@@ -41,7 +41,14 @@ secrets.cfg file. If you do not change the file, the file will not even be re-en
 Essentially, you just have to rename the secret files from `secret-*` to `secret-*.gpg`
 as well as renaming the `secrets.cfg` file to `secrets.cfg.gpg`.
 
-You can also use the script in `rename-secrets.py` to do this for you.
+Upgrading a project to the new secrets format is done by running `./batou migrate`
+if your batou version supports age secrets. This will append `.gpg` to all existing
+secret files, since only gpg was supported before.
+
+You can still use the gpg encrypted secrets on newer batou versions. In case you
+want to use age encrypted secrets, edit the `secrets.cfg(.gpg)` file using
+`./batou secrets edit` and add the `secret_provider = age` key to the `[batou]`
+section. Once you close the editor, the secrets will be re-encrypted using age.
 
 ## New environment variables
 
@@ -59,6 +66,8 @@ You can run this in your shell or add it to your `.bashrc` or `.zshrc` file:
 export BATOU_AGE_IDENTITIES=$HOME/.ssh/id_ed25519
 ```
 
+## SSH Key decryption using 1password integration
+
 If your ssh key is encrypted, you can use the `BATOU_AGE_IDENTITY_PASSPHRASE` environment
 variable to provide a 1password reference url to your ssh key passphrase.
 
diff --git a/src/batou/secrets/__init__.py b/src/batou/secrets/__init__.py
index d1c9a8f52..ee6d7b00f 100644
--- a/src/batou/secrets/__init__.py
+++ b/src/batou/secrets/__init__.py
@@ -205,7 +205,7 @@ def change_secret_provider(
         self.environment.secret_provider = new_secret_provider
         old_secret_provider.purge()
         output.annotate(
-            f"Secret provider changed from {old_secret_provider} to {new_secret_provider}."
+            f"Secret provider changed from {old_secret_provider.secret_provider_str()} to {new_secret_provider.secret_provider_str()}."
         )
 
     def purge(self):
@@ -510,13 +510,15 @@ def process_age_recipients(members, environment_path):
             old_key_meta_file_content = f.read()
         if old_key_meta_file_content != key_meta_file_content:
             print(
-                "WARNING: The key meta file has changed!\n"
-                "Please make sure that the new keys are correct!"
+                "WARNING: The age encryption public-key metadata file has changed!\n"
+                "This means that some secrets are now encrypted with a different set of keys.\n"
+                "Please make sure that the new keys are correct and check the file in once you are done."
             )
     else:
         print(
-            "WARNING: The key meta file does not exist!\n"
-            "Please make sure that the new keys are correct!"
+            "WARNING: The age encryption public-key metadata file does not exist!\n"
+            "This is not a problem if you are setting up the environment for the first time.\n"
+            "Please make sure that the new keys are correct and check the file in once you are done."
         )
     # write the new key meta file
     with open(key_meta_file_path, "w") as f: