diff --git a/docs/abra/upgrade.md b/docs/abra/upgrade.md
index fd79d10..8c962e0 100644
--- a/docs/abra/upgrade.md
+++ b/docs/abra/upgrade.md
@@ -30,6 +30,14 @@ abra upgrade --rc
   logic prefers local filesystem access when this flag is passed. E.g. if there
   is a local copy of the catalogue, then don't `git pull`.
 
+- There is more `--chaos`! There is more consistent flag handling for manually
+  overriding when to update the local recipe or leave it alone when hacking on
+  changes.
+
+- Secrets are now only generated by reading the recipe config, not the env
+  vars. This should hopefully not affect you. If you're seeing weird behaviour,
+  please see [`#464`](https://git.coopcloud.tech/coop-cloud/organising/issues/464).
+
 - There is a new linting rule for catching invalid tags in recipe versions.
   This is an seemingly unavoidable issue that requires some maintenance work.
   If you run into the error, here's some