docs(guides): Add async examples to README, quickstart, pytest-plugin

why: Help users discover and adopt async APIs.
what:
- Add async section to README with concurrent clone example
- Add async quickstart examples with asyncio.run() patterns
- Document async pytest fixtures in pytest-plugin guide

Author: tony

README.md

@@ -149,6 +149,46 @@ def test_my_git_tool(
     assert (checkout_path / ".git").is_dir()
 ```
 
+### 5. Async Support
+Run VCS operations asynchronously for better concurrency when managing multiple repositories.
+
+[**Learn more about Async Support**](https://libvcs.git-pull.com/topics/asyncio.html)
+
+```python
+import asyncio
+import pathlib
+from libvcs.sync._async.git import AsyncGitSync
+
+async def main():
+    repo = AsyncGitSync(
+        url="https://github.com/vcs-python/libvcs",
+        path=pathlib.Path.cwd() / "libvcs",
+    )
+    await repo.obtain()
+    await repo.update_repo()
+
+asyncio.run(main())
+```
+
+Clone multiple repositories concurrently:
+
+```python
+import asyncio
+from libvcs.sync._async.git import AsyncGitSync
+
+async def clone_all(repos: list[tuple[str, str]]):
+    tasks = [
+        AsyncGitSync(url=url, path=path).obtain()
+        for url, path in repos
+    ]
+    await asyncio.gather(*tasks)  # All clone in parallel
+
+asyncio.run(clone_all([
+    ("https://github.com/vcs-python/libvcs", "./libvcs"),
+    ("https://github.com/vcs-python/vcspull", "./vcspull"),
+]))
+```
+
 ## Project Information
 
 - **Python Support**: 3.10+

docs/pytest-plugin.md

@@ -131,6 +131,64 @@ def setup(set_hgconfig: None):
     pass
 ```
 
+## Async Fixtures
+
+For async testing with [pytest-asyncio], libvcs provides async fixture variants:
+
+[pytest-asyncio]: https://pytest-asyncio.readthedocs.io/
+
+### Configuration
+
+Add pytest-asyncio to your test dependencies and configure strict mode:
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+```
+
+### Available Async Fixtures
+
+- {func}`async_git_repo` - An {class}`~libvcs.sync._async.git.AsyncGitSync` instance ready for testing
+- `async_create_git_remote_repo` - Factory to create temporary git repositories
+
+### Usage Example
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_repo_operations(async_git_repo):
+    """Test async repository operations."""
+    # async_git_repo is an AsyncGitSync instance
+    status = await async_git_repo.cmd.status()
+    assert 'On branch' in status
+
+    # Update the repo
+    await async_git_repo.update_repo()
+```
+
+### Creating Repositories in Async Tests
+
+```python
+import pytest
+from libvcs.sync._async.git import AsyncGitSync
+
+@pytest.mark.asyncio
+async def test_clone_repo(tmp_path, create_git_remote_repo):
+    """Test cloning a repository asynchronously."""
+    remote = create_git_remote_repo()
+    repo = AsyncGitSync(
+        url=f'file://{remote}',
+        path=tmp_path / 'clone',
+    )
+    await repo.obtain()
+    assert (tmp_path / 'clone' / '.git').exists()
+```
+
+See {doc}`/topics/asyncio` for more async patterns.
+
 ## Examples
 
 For usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests).

docs/quickstart.md

@@ -98,3 +98,41 @@ origin.prune()
 ```
 
 See {doc}`/cmd/git/index` for the full API reference.
+
+### Async Usage
+
+All APIs have async equivalents for non-blocking operations:
+
+```python
+import asyncio
+from libvcs.cmd._async.git import AsyncGit
+
+async def main():
+    git = AsyncGit(path='/path/to/repo')
+
+    # Non-blocking git operations
+    await git.run(['init'])
+    status = await git.status()
+    print(status)
+
+asyncio.run(main())
+```
+
+For repository synchronization:
+
+```python
+import asyncio
+from libvcs.sync._async.git import AsyncGitSync
+
+async def main():
+    repo = AsyncGitSync(
+        url='https://github.com/vcs-python/libvcs',
+        path='/tmp/libvcs',
+    )
+    await repo.obtain()  # Clone
+    await repo.update_repo()  # Update
+
+asyncio.run(main())
+```
+
+See {doc}`/topics/asyncio` for the complete async guide.