diff --git a/README.md b/README.md
index 84b9a65..142b3f8 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ tools/remote --env-file .env.<instance> werkator repo-add https://gitea.example.
 ```
 
 It prints the registry entry: add it to `~/.werkator.yml` under `repositories:`, then restart the service.
+The optional `[<name>]` overrides the directory basename: it becomes the route segment (`/repos/<name>/…`) and the UI switcher entry, so it must be unique.
+Needed only when the clone directory name is wrong or collides — e.g. `michael.hoennig.de.git` checked out as `michael.hoennig.de`, or two forges serving a repo of the same name.
 A **public** repository needs nothing else: the clone runs anonymously.
 A **private** repository needs shared credentials once on the host, in `~/.werkator.yml` of the service user, before cloning: