diff --git a/docs/abra/upgrade.md b/docs/abra/upgrade.md
index 32d2932..266628e 100644
--- a/docs/abra/upgrade.md
+++ b/docs/abra/upgrade.md
@@ -22,7 +22,12 @@ abra upgrade --rc
 
 Make sure to back up your `~/.abra/servers` configurations first for safety.
 
-- `mv ~/.abra/apps ~/.abra/recipes`
-- `find ~/.abra/servers/ -type f -exec sed -i "s/^TYPE=/RECIPE=/g" {} \;`
+- Please run `mv ~/.abra/apps ~/.abra/recipes`.
+
 - "app name" as a concept went away, `abra` now uses the domain name of an app as the identifier. However, we don't expect to see breaking behaviour if you have `.env` files like `~/.abra/servers/foo.com/mycoolapp.env` and you still want to run `abra app ps mycoolapp`. `abra` still reads the filename to figure out the identifier. When running `abra app new <recipe>`, `abra` will now take the domain name as the name of the `.env` file.
+
 - `abra` has a new SSH implementation which enforces SSH host key checking. You may run into connection issues as a result of this code churn, please see [this entry](/abra/trouble/#ssh-connection-issues) for help navigating a fix.
+
+- CLI flag/args handling has been made more flexible. We're workign within the constraints of an upstream library issue but have hopefully made it easier to mange passing flags to commands with `abra`. See [this troubleshooting entry](/abra/trouble/#command-line-flag-handling-is-weird) for the full review.
+
+- A number of short style flags have been re-mapped and/or added. This is again related to an issue with the upstream CLI library which sometimes understands short style flags as long style flags. E.g. `--ch` instead of `-ch` for `--chaos`. As a concrete example, `--ch` is now `-C` on `abra app deploy`.