diff --git a/readme.md b/readme.md
index a47c246..76195bf 100644
--- a/readme.md
+++ b/readme.md
@@ -72,6 +72,23 @@ xo-tui
 npm run dev
 ```
 
+## Updating
+
+XO checks the remote version of the currently checked-out Git branch in the
+background. When an update is available, the TUI status bar displays
+`Update available · press U`. The update is installed only after confirmation,
+then the TUI restarts.
+
+Updates can also be checked or installed directly:
+
+```bash
+xo-cli update --check
+xo-cli update
+```
+
+Automatic updates require a clean working tree and a fast-forward update from
+`origin`. Local changes are never stashed or discarded automatically.
+
 ## TODO
 
 ### Track invitation sync-server connectivity without blocking the UI