docs(fix): tighten API docs links

why: Keep documentation examples executable and cross-references aligned with
the rendered API surface.

what:
- Replace stale pytest-plugin directive and convert illustrative Python
  fences to doctests
- Link first mentions and add concept-first leads across docs pages
- Repair source docstring xrefs and skipped doctests that feed API docs

Author: tony

MIGRATION

@@ -69,27 +69,16 @@ references these fixtures.
 
 `URL.rule_map` is now a class attribute rather than a dataclass attribute.
 
-Before:
+Before Python 3.11 rejected mutable dataclass defaults:
 
 ```python
-@dataclasses.dataclass(repr=False)
-class GitLabURL(GitURL):
-    rule_map: RuleMap = RuleMap(
-        _rule_map={'gitlab_prefix': GitLabPrefix}
-    )
-```
-
-In python 3.11, that raises an error:
-
-```console
-  File "/home/user/.python/3.11.0/lib/python3.11/dataclasses.py", line 1211, in wrap
-    return _process_class(cls, init, repr, eq, order, unsafe_hash,
-           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File "/home/user/.python/3.11.0/lib/python3.11/dataclasses.py", line 959, in _process_class
-    cls_fields.append(_get_field(cls, name, type, kw_only))
-                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File "/home/user/.python/3.11.0/lib/python3.11/dataclasses.py", line 816, in _get_field
-    raise ValueError(f'mutable default {type(f.default)} for field '
+>>> import dataclasses
+>>> from libvcs.url.base import RuleMap
+>>> @dataclasses.dataclass(repr=False)
+... class GitLabURL:
+...     rule_map: RuleMap = RuleMap(_rule_map={})
+Traceback (most recent call last):
+...
 ValueError: mutable default <class 'libvcs.url.base.RuleMap'> for field rule_map is not allowed: use default_factory
 ```
 

docs/api/index.md

@@ -5,7 +5,8 @@
 # API Reference
 
 libvcs exposes three public subsystems -- URL parsing, command execution,
-and repository synchronization -- plus a pytest plugin for test fixtures.
+and repository synchronization -- plus a {doc}`pytest plugin <pytest-plugin>`
+for test fixtures.
 
 All APIs are pre-1.0 and may change between minor versions.
 Pin to a range, e.g. `libvcs>=0.45,<0.46`.

docs/api/pytest-plugin.md

@@ -2,7 +2,7 @@
 
 # `pytest` Plugin
 
-:::{doc-pytest-plugin} libvcs.pytest_plugin
+:::{auto-pytest-plugin} libvcs.pytest_plugin
 :project: libvcs
 :package: libvcs
 :summary: libvcs ships a pytest plugin for creating isolated Git, Mercurial, and Subversion repositories during tests.
@@ -29,16 +29,14 @@ Keep autouse setup explicit in your own `conftest.py` instead of having the
 plugin force global side effects.
 
 ```python
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def setup(
-    set_home: None,
-    set_vcs_gitconfig: None,
-    set_vcs_hgconfig: None,
-) -> None:
-    pass
+>>> import pytest
+>>> @pytest.fixture(autouse=True)
+... def setup(
+...     set_home: None,
+...     set_vcs_gitconfig: None,
+...     set_vcs_hgconfig: None,
+... ) -> None:
+...     pass
 ```
 
 ## Repository isolation

docs/cmd/git/index.md

@@ -1,14 +1,17 @@
 # `libvcs.cmd.git`
 
-For [`git(1)`](https://git-scm.com/docs/git).
+Use {class}`~libvcs.cmd.git.Git` when you need direct access to
+[`git(1)`](https://git-scm.com/docs/git) from Python, with typed helpers for
+common subcommands and an escape hatch to run raw git arguments.
 
 _Compare to: [`fabtools.git`](https://fabtools.readthedocs.io/en/0.19.0/api/git.html#git-module),
 [`salt.modules.git`](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.git.html),
 [`ansible.builtin.git`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html)_
 
 ## Managers and Commands
 
-libvcs provides **Managers** and **Commands** for git subcommands:
+libvcs provides {ref}`Managers and Commands <traversing-git-repos>` for git
+subcommands:
 
 - **Managers** (`git.branches`, `git.tags`, etc.) let you traverse repository
   entities intuitively with ORM-like filtering via

docs/cmd/git/reflog.md

@@ -4,8 +4,9 @@ For [`git-reflog(1)`](https://git-scm.com/docs/git-reflog).
 
 ## Overview
 
-Manage git reflog using {class}`~libvcs.cmd.git.GitReflogManager` (collection-level)
-and {class}`~libvcs.cmd.git.GitReflogEntryCmd` (per-entry operations).
+Manage git reflog using {class}`~libvcs.cmd.git.GitReflogManager`
+(collection-level), {class}`~libvcs.cmd.git.GitReflogEntry` (entry data), and
+{class}`~libvcs.cmd.git.GitReflogEntryCmd` (per-entry operations).
 
 ### Examples
 

docs/cmd/index.md

@@ -2,8 +2,8 @@
 
 # Commands - `libvcs.cmd`
 
-Run git, hg, and svn from Python through typed wrappers — one class per VCS
-binary, one method per operation.
+Run [`git(1)`], [`hg(1)`], and [`svn(1)`] from Python through typed wrappers
+— one class per VCS binary, one method per operation.
 
 Compare to: [`fabtools.git`](https://fabtools.readthedocs.io/en/0.19.0/api/git.html#git-module),
 [`salt.modules.git`](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.git.html),
@@ -20,7 +20,7 @@ versions.
 
 The {mod}`libvcs.cmd` module provides Python wrappers for VCS command-line tools:
 
-- {mod}`libvcs.cmd.git` - Git commands with {ref}`Managers <traversing-git-repos>` for intuitive entity traversal and Commands for targeted execution
+- {mod}`libvcs.cmd.git` - Git commands with {ref}`Managers and Commands <traversing-git-repos>` for intuitive entity traversal and targeted execution
 - {mod}`libvcs.cmd.hg` - Mercurial commands
 - {mod}`libvcs.cmd.svn` - Subversion commands
 
@@ -63,3 +63,7 @@ git/index
 hg
 svn
 ```
+
+[`git(1)`]: https://git-scm.com/docs/git
+[`hg(1)`]: https://www.mercurial-scm.org/doc/hg.1.html
+[`svn(1)`]: https://svnbook.red-bean.com/en/1.7/svn.ref.svn.html

docs/index.md

@@ -2,7 +2,7 @@
 
 # libvcs
 
-Typed Python utilities for Git, SVN, and Mercurial. Parse URLs,
+Typed Python utilities for [Git], [Subversion], and [Mercurial]. Parse URLs,
 execute commands, and synchronize repositories -- all with a
 consistent, type-friendly API.
 
@@ -92,11 +92,15 @@ libvcs ships a {doc}`pytest plugin </api/pytest-plugin>` with
 session-scoped fixtures for Git, SVN, and Mercurial repositories:
 
 ```python
-def test_my_tool(create_git_remote_repo):
-    repo_path = create_git_remote_repo()
-    assert repo_path.exists()
+>>> def test_my_tool(create_git_remote_repo):
+...     repo_path = create_git_remote_repo()
+...     assert repo_path.exists()
 ```
 
+[Git]: https://git-scm.com/docs/git
+[Subversion]: https://subversion.apache.org/
+[Mercurial]: https://www.mercurial-scm.org/
+
 ```{toctree}
 :hidden:
 

docs/project/adr/0001-faithful-subprocess-output-capture.md

@@ -8,9 +8,10 @@ Proposed. 2026-06-20.
 
 ## Context
 
-The legacy command runner `libvcs._internal.run.run` — used by every
-`Git`, `Hg`, and `Svn` command class via `.run()` — does not return what
-the underlying VCS actually printed. After the process exits it splits
+The legacy command runner {func}`libvcs._internal.run.run` — used by every
+{class}`~libvcs.cmd.git.Git`, {class}`~libvcs.cmd.hg.Hg`, and
+{class}`~libvcs.cmd.svn.Svn` command class via `run()` — does not return
+what the underlying VCS actually printed. After the process exits it splits
 captured stdout into lines, calls `bytes.strip()` on each line, drops any
 line that is empty after stripping, and rejoins with `\n` and no trailing
 newline. stderr is treated the same way and then rejoined with no
@@ -41,8 +42,8 @@ human-readable progress lines, not to capture structured output. The
 runner's own module docstring already states that it "will be deprecated
 by `libvcs._internal.subprocess`".
 
-`libvcs._internal.subprocess.SubprocessCommand` already exists as a thin,
-typed wrapper that returns a real `subprocess.CompletedProcess` with
+{class}`~libvcs._internal.subprocess.SubprocessCommand` already exists as a thin,
+typed wrapper that returns a real {class}`subprocess.CompletedProcess` with
 separate, untouched `stdout` and `stderr`. It is bytes-first with opt-in
 text decoding, and it is currently wired into nothing.
 
@@ -73,8 +74,8 @@ capture path. This is implemented in two phases so the stable
 ### Phase 2 — pristine structured backend
 
 - Route the `cmd/*` classes through
-  `libvcs._internal.subprocess.SubprocessCommand`, which returns a
-  `subprocess.CompletedProcess` (bytes-first, separate
+  {class}`~libvcs._internal.subprocess.SubprocessCommand`, which returns a
+  {class}`subprocess.CompletedProcess` (bytes-first, separate
   stdout/stderr/returncode).
 - Expose a structured accessor that returns the `CompletedProcess` for
   callers that want streams, exit code, and exact bytes. Keep
@@ -102,7 +103,7 @@ The decisive measurement: flipping the default to verbatim broke only
 doctests in `cmd/git.py`, `cmd/hg.py`, and `cmd/svn.py` — example output
 that gained a trailing newline. No functional test, sync-layer call, or
 downstream consumer broke, because those already strip where they need a
-bare value (`vcspull`, like the sync layer, trims defensively). A global
+bare value ([vcspull], like the sync layer, trims defensively). A global
 trailing trim, by contrast, cannot produce an applyable patch: the
 patch's required final newline is exactly what it strips. So verbatim
 becomes the default — fixing the original `git apply` failure for the
@@ -122,7 +123,7 @@ reflects the true, faithful output.
   byte-identical; error messages keep their line structure.
 - The default now returns output with its trailing newline. Callers that
   want a bare value pass `trim=True`; existing consumers are unaffected
-  because the sync layer and `vcspull` already strip defensively before
+  because the sync layer and [vcspull] already strip defensively before
   comparing.
 - The stderr concatenation defect is removed: error lines keep their
   separators. (Phase 2's structured backend additionally avoids the
@@ -150,19 +151,28 @@ reflects the true, faithful output.
 The decision follows the convergent practice of mature VCS and
 subprocess-wrapping tools, none of which trim inside the capture path:
 
-- **pip** added a per-call mode (`stdout_only`) that returns VCS output
+- **[pip]** added a per-call mode (`stdout_only`) that returns VCS output
   verbatim, and replaced its `console_to_str` helper with
   `errors="backslashreplace"`.
-- **uv** captures into a raw `Output { stdout, stderr }` and applies
+- **[uv]** captures into a raw `Output { stdout, stderr }` and applies
   `trim_end()` at each call site for scalar reads.
-- **mise** relies on whole-output trailing trim for scalars, decodes
+- **[mise]** relies on whole-output trailing trim for scalars, decodes
   strictly for data and lossily for stderr.
-- **Mercurial**, **gitoxide**, and **Jujutsu** are bytes-first and keep
+- **[Mercurial]**, **[gitoxide]**, and **[Jujutsu]** are bytes-first and keep
   output verbatim; gitoxide treats newline-stripping as a named, opt-in
   view, and tracks the missing-final-newline case explicitly.
-- **git** itself confirms the constraint: its patch parser requires each
+- **[git]** itself confirms the constraint: its patch parser requires each
   line, including the last, to be newline-terminated.
 
 The lesson shared by all of them: capture pristine, keep streams
 separate, and make trimming and decoding explicit edge transformations.
 `SubprocessCommand` already embodies that shape inside libvcs.
+
+[vcspull]: https://vcspull.git-pull.com/
+[pip]: https://pip.pypa.io/
+[uv]: https://docs.astral.sh/uv/
+[mise]: https://mise.jdx.dev/
+[Mercurial]: https://www.mercurial-scm.org/
+[gitoxide]: https://github.com/GitoxideLabs/gitoxide
+[Jujutsu]: https://jj-vcs.github.io/jj/
+[git]: https://git-scm.com/

docs/project/adr/0002-order-independent-tests.md

@@ -18,7 +18,7 @@ the suite is **order-independent**: every test must pass regardless of what ran
 before it. The suite was not. Two pieces of shared mutable state passed in the
 fixed collection order but failed once tests were reordered:
 
-- `libvcs.url.registry.VCSRegistry` stored its `parser_map` in a class
+- {class}`~libvcs.url.registry.VCSRegistry` stored its `parser_map` in a class
   variable, so constructing any second registry mutated the module-level
   `registry` singleton — whichever test built a custom registry first changed
   URL detection for every later test.
@@ -28,9 +28,10 @@ fixed collection order but failed once tests were reordered:
   every later test that copied it.
 
 These were invisible under the default order and surfaced only when a
-shuffled run (`pytest-randomly`) or a parallel run (`pytest-xdist`) changed
+shuffled run ([pytest-randomly]) or a parallel run ([pytest-xdist]) changed
 which tests ran together and in what sequence. They are also genuine bugs for
-downstream consumers (e.g. vcspull) that build on `VCSRegistry` and the
+downstream consumers (e.g. [vcspull]) that build on
+{class}`~libvcs.url.registry.VCSRegistry` and the
 fixtures, independent of how the tests run.
 
 ## Decision
@@ -56,7 +57,7 @@ py.test -p randomly`).
 
 ### Parallelism is opt-in, not the default
 
-`pytest-xdist` is a development dependency exposed via `just test-parallel`
+[pytest-xdist] is a development dependency exposed via `just test-parallel`
 (`uv run py.test -n auto`). The default `uv run py.test` stays serial.
 
 - The worker count is **not** hardcoded. `-n auto` adapts to the machine; the
@@ -88,7 +89,8 @@ checks (`uv run --with pytest-randomly`) rather than committed.
 ### Positive
 
 - The suite passes under serial, shuffled, and parallel (`-n auto`) execution.
-- Two real isolation bugs in shipped code (`VCSRegistry`, the repo fixtures)
+- Two real isolation bugs in shipped code
+  ({class}`~libvcs.url.registry.VCSRegistry`, the repo fixtures)
   are fixed, benefiting downstream consumers regardless of parallelism.
 - A faster opt-in run is available without changing the stable default.
 
@@ -108,11 +110,15 @@ checks (`uv run --with pytest-randomly`) rather than committed.
 
 ## Prior art
 
-- `pytest-xdist` provides the `load`, `loadscope`, and `loadfile` schedulers;
+- [pytest-xdist] provides the `load`, `loadscope`, and `loadfile` schedulers;
   its guidance is that tests must be independent for `load` to be safe.
-- `pytest-randomly` randomizes order specifically to surface inter-test
+- [pytest-randomly] randomizes order specifically to surface inter-test
   coupling.
 - The broader convention across test suites: parallel execution requires
   order-independent tests, and shared mutable state (global registries, cached
   fixtures handed out by reference) is the usual cause of order-dependent
   failures.
+
+[pytest-randomly]: https://github.com/pytest-dev/pytest-randomly
+[pytest-xdist]: https://pytest-xdist.readthedocs.io/
+[vcspull]: https://vcspull.git-pull.com/

docs/project/code-style.md

@@ -2,6 +2,11 @@
 
 # Code Style
 
+Use this page when you are changing Python code or docstrings and need the
+project's formatting, typing, and import conventions. The command examples are
+the common local checks; the root contributor guide still owns the full
+pre-commit gate.
+
 ## Formatting and linting
 
 libvcs uses [ruff](https://ruff.rs) for formatting **and** linting in a
@@ -21,29 +26,30 @@ $ uv run ruff check . --fix --show-fixes
 [mypy](http://mypy-lang.org/) runs in strict mode:
 
 ```console
-$ uv run mypy src tests
+$ uv run mypy .
 ```
 
 ## Docstrings
 
 All public APIs use **NumPy-style** docstrings:
 
 ```python
-def fetch(url: str, *, branch: str | None = None) -> str:
-    """Fetch a remote branch.
-
-    Parameters
-    ----------
-    url : str
-        Repository URL.
-    branch : str or None
-        Branch name. ``None`` means the default branch.
-
-    Returns
-    -------
-    str
-        The fetched commit hash.
-    """
+>>> def fetch(url: str, *, branch: str | None = None) -> str:
+...     """Fetch a remote branch.
+...
+...     Parameters
+...     ----------
+...     url : str
+...         Repository URL.
+...     branch : str or None
+...         Branch name. ``None`` means the default branch.
+...
+...     Returns
+...     -------
+...     str
+...         The fetched commit hash.
+...     """
+...     return "abc123"
 ```
 
 ## Imports