diff --git a/README.md b/README.md
index 3517097..ca2a0ce 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,23 @@ $ switchdocs setup --apply  # add it to ~/.opam/config via `opam option`
   package/library names for a leading `/` (`/o` → `/odoc`, `/odoc.model`, …), or
   the units under a `/pkg/` path. The engine for shell completion.
 
+## Shell completion (zsh)
+
+A zsh completion is shipped in `completions/zsh/_switchdocs`. It completes the
+subcommands and, for `show` and `complete`, the reference argument — by calling
+`switchdocs complete`, so completion always matches the command's own resolver
+(`Stdlib` open, package-qualified `/pkg/...` paths, kind tags like `type-`,
+section labels, …). Type `.` or `/` and press TAB again to drill in.
+
+`opam install` puts it under `$OPAM_SWITCH_PREFIX/share/zsh/site-functions`; if
+that directory is on your `$fpath` (before `compinit`) completion works out of
+the box. Otherwise point `$fpath` at the source directory in `~/.zshrc`:
+
+```zsh
+fpath=(/path/to/odoc-switchdocs/completions/zsh $fpath)
+autoload -U compinit && compinit
+```
+
 ## Development
 
 ```
diff --git a/completions/dune b/completions/dune
new file mode 100644
index 0000000..c4c2278
--- /dev/null
+++ b/completions/dune
@@ -0,0 +1,7 @@
+; Install the zsh completion to <prefix>/share/zsh/site-functions, the standard
+; place zsh looks for site completions (if that dir is on the user's $fpath).
+(install
+ (section share_root)
+ (package odoc-switchdocs)
+ (files
+  (zsh/_switchdocs as zsh/site-functions/_switchdocs)))
diff --git a/completions/zsh/_switchdocs b/completions/zsh/_switchdocs
new file mode 100644
index 0000000..9820224
--- /dev/null
+++ b/completions/zsh/_switchdocs
@@ -0,0 +1,50 @@
+#compdef switchdocs
+#
+# zsh completion for switchdocs.
+#
+# Install: put this file's directory on $fpath before compinit, e.g. add to
+# ~/.zshrc (adjust the path):
+#
+#     fpath=(/path/to/odoc-switchdocs/completions/zsh $fpath)
+#     autoload -U compinit && compinit
+#
+# Reference arguments (to `show` and `complete`) are completed by calling
+# `switchdocs complete`, which resolves the partial reference against the whole
+# switch and returns the candidates — so completion is always in sync with the
+# command's own resolver (Stdlib open, package-qualified `/pkg/...` paths, kind
+# tags like `type-`, section labels, …).
+
+local -a cmds
+cmds=(
+  'show:print an item'\''s documentation as Markdown'
+  'complete:list the completions of a partial reference'
+  'search:search the switch documentation'
+  'sync:bring the switch documentation up to date'
+  'rebuild:mark packages stale and rebuild their docs'
+  'order:print the dependency order sync would use'
+  'setup:configure the opam hooks'
+)
+
+# Word 1 is "switchdocs"; word 2 is the subcommand.
+if (( CURRENT == 2 )); then
+  _describe -t commands 'switchdocs command' cmds
+  return
+fi
+
+case ${words[2]} in
+  (show|complete)
+    local cur=${words[CURRENT]} prev=${words[CURRENT-1]}
+    if [[ $cur == -* ]]; then
+      compadd -- --prefix --help
+    elif [[ $prev == (--prefix|-p) ]]; then
+      _files -/
+    else
+      # Hand the current word to `switchdocs complete`; it returns full
+      # reference strings. Empty suffix so dotted/slashed references can be
+      # drilled into (type `.` and complete again).
+      local -a refs
+      refs=(${(f)"$(switchdocs complete -- "$cur" 2>/dev/null)"})
+      compadd -S '' -- $refs
+    fi
+    ;;
+esac