doc

README.md

@@ -513,6 +513,25 @@ E.g.:
  :args ["arg"]}
 ```
 
+Note that specs are not merged, such that:
+
+``` clojure
+(cli/dispatch table ["sub1" "--foo" "bar"])
+```
+
+returns `{:dispatch ["sub1"], :opts {:foo "bar"}}` (`"bar"` is not coerced as a keyword).
+
+Note that it is possible to use `:args->opts` but subcommands are always prioritized over arguments:
+
+``` clojure
+(def table
+  [{:cmds ["sub1"] :fn identity :spec sub1-spec :args->opts [:some-opt]}
+   {:cmds ["sub1" "sub2"] :fn identity :spec sub2-spec}])
+
+(cli/dispatch table ["sub1" "dude"]) ;;=> {:dispatch ["sub1"], :opts {:some-opt "dude"}}
+(cli/dispatch table ["sub1" "sub2"]) ;;=> {:dispatch ["sub1" "sub2"], :opts {}}
+```
+
 ## Babashka tasks
 
 For documentation on babashka tasks, go