diff --git a/doc/vcsh.1.ronn b/doc/vcsh.1.ronn
index ebc9896f845b2363c385139285fe281acbf9c343..4138c23d53c4fbcd73ee87e86dbff70ceec57cc9 100644
--- a/doc/vcsh.1.ronn
+++ b/doc/vcsh.1.ronn
@@ -261,9 +261,16 @@ locations are <$XDG_CONFIG_HOME/vcsh/overlays-available> and
 <$XDG_CONFIG_HOME/vcsh/overlays-enabled>.
 
 Overlays follow the same rules as hooks and you are free to overwrite any
-and all functions. As the overlays will be sourced and you are replacing
-arbitrary functions, any and all features may stop working, or you may even
-lose data. You have been warned.
+and all functions. Same as hooks, you can use global or repository-specific
+overlays by using either <$VCSH_OVERLAY_D/$VCSH_COMMAND> or
+<$VCSH_OVERLAY_D/$VCSH_REPO_NAME.$VCSH_COMMAND>.
+
+Please note that nothing stops you from, e.g. overwriting `status()` in
+<$VCSH_OVERLAY_D/commit>. As the overlays will be sourced and you are
+replacing arbitrary functions, any and all features may stop working, or you
+may even lose data.
+
+You have been warned.
 
 ## DETAILED HOWTO AND FURTHER READING