add search doc page

README.md

@@ -95,13 +95,14 @@ openupm remove com.my.package
 Checkout [the commands doc page](./docs/cmd-remove.md) for more information.
 
 ### Search packages
-```
-openupm search <keyword>
-```
 
-If the registry doesn't support the new search endpoint, it will fall back to the old `/-/all` endpoint. If no package was found, it will search the Unity official registry instead.
+Use `openupm search` to search for remote packages by name.
+
+```sh
+openupm search something
+```
 
-Because the upstream Unity registry doesn't support the search endpoint as of December 2019, the search command will only query the current registry.
+Checkout [the commands doc page](./docs/cmd-search.md) for more information.
 
 ### View package information
 ```

docs/cmd-add.md

@@ -110,14 +110,8 @@ If you need to run openupm from somewhere else you can change the working direct
 openupm add com.my.package -c /home/user/dev/MyProject
 ```
 
-### Windows system user
+### Windows system-user authentication
 
-By default openupm collects registry authentication credentials from the users local `.upmconfig.toml`.
-
-If you want to authenticate with registries using the `.upmconfig.toml` file for the Windows system user then pass the `--system-user` option.
-
-```sh
-openupm add com.my.package --system-user
-```
+This command supports Windows system-user authentication. For more information check out the corresponding [article](./help-system-user.md).
 
 [^1]: openupm does not validate or resolve indirect dependencies for url-based dependencies.

docs/cmd-search.md

@@ -0,0 +1,35 @@
+# `openupm search`
+
+The `search` command searches all packages on a remote registry matching a keyword and prints their names.
+
+Generally, this command will attempt to use the chosen registries' [search endpoint](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md#get-v1search). If the registry doesn't support that, it will fall back to the `/-/all` endpoint. 
+
+Because the Unity registry doesn't support any of the required endpoints (as of writing this in late 2024), the search command will not fall back to the Unity registry.
+
+This command has the following aliases: `s`, `se` and `find`. On this doc page we will always use the primary command name `search`.
+
+## Arguments
+
+### Keyword
+
+Specify a keyword which you want to search.
+
+When using the npm search endpoint then the keyword will be used for the `text` query parameter.
+
+When using the `/-/all` fallback all packages whose name includes the keyword will be printed. For this the keyword is case-insensitive.
+
+## Options
+
+### Registry
+
+By default openupm searches packages on the openupm registry. This behavior is configurable, specifically if you want to work with 3rd party registries. 
+
+You can override the primary registry from which to resolve packages using the  `--registry` option.
+
+```sh
+openupm search something --registry https://packages.my.registry
+```
+
+### Windows system-user authentication
+
+This command supports Windows system-user authentication. For more information check out the corresponding [article](./help-system-user.md).

docs/help-system-user.md

@@ -0,0 +1,11 @@
+# Using system-user authentication
+
+By default openupm resolves registry authentication credentials from the users local `.upmconfig.toml` (Ie the one stored at `~/.upmconfig.toml`).
+
+When you are using openupm on Windows and would like to use the system-users `.upmconfig.toml` instead, you can use the `--system-user` option.
+
+```sh
+openupm add com.my.package --system-user
+```
+
+See [the Unity docs on the topic](https://docs.unity3d.com/Manual/upm-config.html) for more information.