diff --git a/deploy/README.md b/deploy/README.md
index f452a1b..ff0e9ff 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -4,7 +4,9 @@
 API server under systemd + `navi-code` in PATH. One command, SSH-only access,
 web UI off by default.
 
-## Install
+## Deploy
+
+Two commands from zero to a working module:
 
 ```bash
 ssh server
@@ -12,6 +14,23 @@
 bash deploy/install.sh
 ```
 
+What `install.sh` does (idempotent — safe to re-run, e.g. after `git pull`):
+
+1. Checks prerequisites: Python 3.11+, Docker + compose plugin.
+2. Provisions `.env` — on the `deploy` branch it already ships with the
+   deployment defaults (web UI off, auth off, Ollama Cloud, profile
+   `navi_code`); the script generates the DB password in place of the
+   `CHANGEME` placeholder.
+3. Starts dockerized PostgreSQL (pgvector image, `restart: always`, bound to
+   `127.0.0.1:5432`, data in the `navi-pgdata` docker volume) and installs
+   the `vector` + `pg_trgm` extensions Navi's DDL expects.
+4. Builds `.venv` and installs navi — the `navi-server` and `navi-code` entry
+   points.
+5. Writes and enables the systemd unit `navi.service` (`Restart=always`):
+   the server lives from installation — starts on boot, restarts on crash.
+6. Waits for `/health` to answer, then symlinks `navi-code` and `navi-server`
+   into `/usr/local/bin`.
+
 After the install finishes, fill in the one remaining secret and restart:
 
 ```bash