docs/cli(docs[search]): Document search command

why: Keep CLI documentation aligned with the new search subcommand.
what:
- add search command docs and API reference stubs
- update CLI indexes and README examples

Author: tony

README.md

@@ -136,6 +136,14 @@ $ vcspull list --json | jq '.[].name'
 `--json` emits a single JSON array, while `--ndjson` streams newline-delimited
 objects that are easy to consume from shell pipelines.
 
+Search across repositories with an rg-like query syntax:
+
+```console
+$ vcspull search django
+$ vcspull search name:django url:github
+$ vcspull search --fixed-strings 'git+https://github.com/org/repo.git'
+```
+
 ### Check repository status
 
 Get a quick health check for all configured workspaces:

docs/api/cli/index.md

@@ -12,6 +12,7 @@ sync
 add
 discover
 list
+search
 status
 fmt
 ```

docs/api/cli/search.md

@@ -0,0 +1,3 @@
+# vcspull search - `vcspull.cli.search`
+
+.. automodule:: vcspull.cli.search

docs/cli/index.md

@@ -10,6 +10,7 @@ sync
 add
 discover
 list
+search
 status
 fmt
 ```
@@ -36,5 +37,5 @@ completion
     :nodescription:
 
     subparser_name : @replace
-        See :ref:`cli-sync`, :ref:`cli-add`, :ref:`cli-discover`, :ref:`cli-list`, :ref:`cli-status`, :ref:`cli-fmt`
+        See :ref:`cli-sync`, :ref:`cli-add`, :ref:`cli-discover`, :ref:`cli-list`, :ref:`cli-search`, :ref:`cli-status`, :ref:`cli-fmt`
 ```

docs/cli/search.md

@@ -0,0 +1,102 @@
+(cli-search)=
+
+# vcspull search
+
+The `vcspull search` command looks up repositories across your vcspull
+configuration with an rg-like query syntax. Queries are regex by default, can
+scope to specific fields, and can emit structured JSON for automation.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: vcspull.cli
+    :func: create_parser
+    :prog: vcspull
+    :path: search
+    :nodescription:
+```
+
+## Basic usage
+
+Search all fields (name, path, url, workspace) with regex:
+
+```console
+$ vcspull search django
+• django → ~/code/django
+```
+
+## Field-scoped queries
+
+Target specific fields with prefixes:
+
+```console
+$ vcspull search name:django url:github
+• django → ~/code/django
+  url: git+https://github.com/django/django.git
+```
+
+Available field prefixes:
+- `name:`
+- `path:`
+- `url:`
+- `workspace:` (alias: `root:` or `ws:`)
+
+## Literal matches
+
+Use `-F/--fixed-strings` to match literal text instead of regex:
+
+```console
+$ vcspull search --fixed-strings 'git+https://github.com/org/repo.git'
+```
+
+## Case handling
+
+`-i/--ignore-case` forces case-insensitive matching. `-S/--smart-case` matches
+case-insensitively unless your query includes uppercase characters.
+
+```console
+$ vcspull search -S Django
+```
+
+## Boolean matching
+
+By default all terms must match. Use `--any` to match if *any* term matches:
+
+```console
+$ vcspull search --any django flask
+```
+
+Invert matches with `-v/--invert-match`:
+
+```console
+$ vcspull search -v --fixed-strings github
+```
+
+## JSON output
+
+Emit matches as JSON for automation:
+
+```console
+$ vcspull search --json django
+```
+
+Output format:
+
+```json
+[
+  {
+    "name": "django",
+    "url": "git+https://github.com/django/django.git",
+    "path": "~/code/django",
+    "workspace_root": "~/code/",
+    "matched_fields": ["name", "url"]
+  }
+]
+```
+
+Use NDJSON for streaming:
+
+```console
+$ vcspull search --ndjson django
+```