diff --git a/README.md b/README.md
index a9762e5..0f71077 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
 # ahab
 
+A wrapper around `docker compose` for our dockerized django projects, so the
+same commands work in every repository.
+
 ## installing
 
 You will need rust installed. Clone repo and run:
@@ -7,20 +10,86 @@ You will need rust installed. Clone repo and run:
 cargo install --path .
 ```
 
-To print underlying commands build with `debug` flag.
+To print the underlying docker commands as they run, build with debug
+assertions:
 ```bash
 cargo install --path . --debug
 ```
 
 ## shell completion
 
-Completion files are generated **during build process** in `target/*/build/*/out/*`. Depending on your shell of choice move generated file to correct place in you file system.
+`ahab completions <shell>` writes a completion script to stdout, for bash,
+elvish, fish, powershell or zsh:
+
+```bash
+ahab completions zsh > ~/.local/share/zsh/completions/_ahab
+eval "$(ahab completions zsh)"      # or one line in .zshrc, never goes stale
+```
+
+Completions are also generated during the build. They land in
+`target/*/build/*/out/` by default, and `SHELL_COMPLETIONS_DIR_<SHELL>`
+installs a single shell's file straight into place:
+
+```bash
+SHELL_COMPLETIONS_DIR_ZSH=~/.local/share/zsh/completions \
+SHELL_COMPLETIONS_DIR_FISH=~/.config/fish/completions \
+  cargo install --path .
+```
+
+`SHELL_COMPLETIONS_DIR` writes every shell into one directory instead.
+
+## compose
+
+Wrappers around the matching `docker compose` call, plus `exec` and `bash`
+which default to the django service.
+
+```bash
+ahab compose up                     # also build, down, ps, start, stop
+ahab compose rebuild                # stop, build, up
+ahab compose restart                # stop, up, so containers are recreated
+ahab compose bash                   # shell in the django service
+ahab compose exec <cmd>
+```
+
+## django
+
+```bash
+ahab django manage <args>           # manage.py in a fresh container
+ahab django makemigrations
+ahab django migrate <args>
+ahab django shell
+ahab django test
+ahab django make-command <app> <name>
+```
+
+## postgres
+
+```bash
+ahab postgres dump <path>           # pg_dump, custom format
+ahab postgres import <path>         # drop, create, pg_restore
+```
+
+## link
+
+`ahab link` moves untracked paths out of the repository into an out-of-repo
+store and symlinks them back, so a sandbox that mounts the repository sees a
+dangling symlink instead of the contents, while the host resolves it as before.
+
+```bash
+ahab link add .env secrets/         # move out, leave symlinks behind
+ahab link check                     # what a sandbox can still read
+ahab link check --porcelain         # `<code> <path>`, for scripts
+```
+
+The store lives under
+`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/`, derived
+from the git `origin` remote.
 
 ## configuration
 
 Currently `ahab` respects the following environment variables.
 
 - `COMPOSE_FILE`: control which docker-compose file is used - defaults to `docker/local/docker-compose.yaml`
-- `AHAB_DJANGO_CONTAINER`: control which  compose service is used for sending django commands - defaults to `django`
+- `AHAB_DJANGO_CONTAINER`: control which compose service is used for sending django commands - defaults to `django`
 - `AHAB_POSTGRES_CONTAINER`: control which compose service is used for sending postgres commands - defaults to `db`
 - `AHAB_LINK_ROOT`: root of the out-of-repo store `ahab link` moves paths into - defaults to `${XDG_DATA_HOME:-$HOME/.local/share}/ahab`