fix(doctor): actionable Windows install hints, consistent search paths (#180)

* fix(doctor): actionable Windows install hints, consistent search paths

- _make_build_hint(): replace bare `python scripts/build_renderdoc.py`
  with step-by-step git clone + uv run commands for Windows; use
  `uv run` for macOS; update docs URL to /docs/install/ on all platforms
- _check_win_renderdoc_install(): delegate to _platform.renderdoc_search_paths()
  instead of hardcoded candidate list, aligning with _check_win_python_version()
- renderdoccmd_search_paths(): add %LOCALAPPDATA%\rdc\renderdoc\ so the
  build script install dir is discovered
- build_renderdoc.py: copy renderdoccmd.exe (optional) on Windows builds
- Update tests for new hint text and search path delegation

* docs(install): add Windows bootstrap commands to README and docs site

Add step-by-step Windows renderdoc build instructions (git clone + uv run)
to PyPI install section, RenderDoc bootstrap section, and Astro docs page.
Update Module Discovery to list platform-specific search paths.

* fix: address PR review feedback

- Replace %TEMP% with relative path in Windows hint (shell-agnostic)
- Add git clone step to macOS hint for PyPI users
- List uv in prerequisites for Windows/macOS hints
- Use _OPTIONAL_ARTIFACTS constant instead of hardcoded string
- Fix docs search paths to match actual _platform.py code

Author: BANANASJIM

README.md

@@ -37,11 +37,13 @@ bash <(curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/sc
 rdc doctor                            # verify everything works
 ```
 
-**PyPI — Windows**
+**PyPI — Windows** (requires git, uv, Visual Studio Build Tools)
 
 ```bash
 uv tool install rdc-cli               # or: pipx install rdc-cli
-rdc doctor                            # prints renderdoc setup instructions
+git clone --depth 1 https://github.com/BANANASJIM/rdc-cli.git rdc-cli
+uv run rdc-cli\scripts\build_renderdoc.py
+rdc doctor                            # verify everything works
 ```
 
 **PyPI — macOS** (Split client only)
@@ -77,12 +79,21 @@ pixi run setup-renderdoc              # build renderdoc (pixi installs toolchain
 | macOS | ❌ (not supported yet) | ✅ (recommended) |
 | Windows | ✅ | ✅ |
 
-### RenderDoc bootstrap (Linux)
+### RenderDoc bootstrap
+
+**Linux** (one-liner, no repo clone needed):
 
 ```bash
 bash <(curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh)
 ```
 
+**Windows** (requires git, uv, Visual Studio 2022 Build Tools with C++ workload):
+
+```bash
+git clone --depth 1 https://github.com/BANANASJIM/rdc-cli.git rdc-cli
+uv run rdc-cli\scripts\build_renderdoc.py
+```
+
 If building from source, use the pixi wrapper instead: `pixi run setup-renderdoc`
 
 ## Quickstart

docs-astro/src/pages/docs/install.astro

@@ -83,10 +83,16 @@ rdc open --connect host:54321 --token TOKEN</code></pre>
 
   <h3>Bootstrap (Recommended)</h3>
   <p>
-    One-liner for Linux (no repo clone needed):
+    <strong>Linux</strong> one-liner (no repo clone needed):
   </p>
   <pre><code>bash &lt;(curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh)</code></pre>
 
+  <p>
+    <strong>Windows</strong> (requires git, uv, Visual Studio 2022 Build Tools with C++ workload):
+  </p>
+  <pre><code>git clone --depth 1 https://github.com/BANANASJIM/rdc-cli.git rdc-cli
+uv run rdc-cli\scripts\build_renderdoc.py</code></pre>
+
   <p>
     If you are building from source, use the pixi wrapper task:
   </p>
@@ -103,8 +109,9 @@ export RENDERDOC_PYTHON_PATH=$PWD/build/lib</code></pre>
   <p>rdc-cli searches for the renderdoc module in this order:</p>
   <ol>
     <li><code>RENDERDOC_PYTHON_PATH</code> environment variable</li>
-    <li><code>~/.local/renderdoc</code> (where the bootstrap installs)</li>
-    <li><code>/usr/lib/renderdoc</code>, <code>/usr/local/lib/renderdoc</code></li>
+    <li><strong>macOS:</strong> <code>~/.local/renderdoc</code>, <code>/opt/homebrew/opt/renderdoc/lib</code>, <code>/usr/local/opt/renderdoc/lib</code></li>
+    <li><strong>Windows:</strong> <code>C:\Program Files\RenderDoc</code>, <code>%LOCALAPPDATA%\renderdoc</code>, <code>%LOCALAPPDATA%\rdc\renderdoc</code></li>
+    <li><strong>Linux:</strong> <code>/usr/lib/renderdoc</code>, <code>/usr/local/lib/renderdoc</code></li>
     <li>Sibling directory of <code>renderdoccmd</code> on PATH</li>
   </ol>
 

scripts/build_renderdoc.py

@@ -66,9 +66,12 @@ def default_install_dir() -> Path:
     return Path.home() / ".local" / "renderdoc"
 
 
+_OPTIONAL_ARTIFACTS = frozenset({"renderdoccmd.exe"})
+
+
 def _artifact_names(plat: str) -> list[str]:
     if plat == "windows":
-        return ["renderdoc.pyd", "renderdoc.dll"]
+        return ["renderdoc.pyd", "renderdoc.dll", "renderdoccmd.exe"]
     return ["renderdoc.so", "librenderdoc.so"]
 
 
@@ -396,12 +399,15 @@ def copy_artifacts(build_dir: Path, install_dir: Path, plat: str) -> None:
     install_dir.mkdir(parents=True, exist_ok=True)
 
     for name in names:
-        # On Windows, renderdoc.dll lives in x64/Release/ (parent of pymodules)
-        if plat == "windows" and name == "renderdoc.dll":
+        # On Windows, renderdoc.dll and renderdoccmd.exe live in x64/Release/ (parent of pymodules)
+        if plat == "windows" and name in ("renderdoc.dll", "renderdoccmd.exe"):
             artifact = src.parent / name
         else:
             artifact = src / name
         if not artifact.exists():
+            if name in _OPTIONAL_ARTIFACTS:
+                _log(f"WARNING: {name} not found at {artifact}, skipping")
+                continue
             # macOS may produce .dylib instead of .so for librenderdoc
             if plat == "macos" and name == "librenderdoc.so":
                 alt = src / "librenderdoc.dylib"
@@ -458,7 +464,8 @@ def _install_vulkan_layer(install_dir: Path, build_dir: Path) -> None:
 
 
 def _artifacts_present(install_dir: Path, plat: str) -> bool:
-    return all((install_dir / n).exists() for n in _artifact_names(plat))
+    required = [n for n in _artifact_names(plat) if n not in _OPTIONAL_ARTIFACTS]
+    return all((install_dir / n).exists() for n in required)
 
 
 def main(argv: list[str] | None = None) -> None:

src/rdc/_platform.py

@@ -213,6 +213,9 @@ def renderdoccmd_search_paths() -> list[Path]:
     """Return candidate paths for the renderdoccmd binary."""
     if _WIN:  # pragma: no cover
         paths = [Path(r"C:\Program Files\RenderDoc\renderdoccmd.exe")]
+        localappdata = os.environ.get("LOCALAPPDATA", "")
+        if localappdata:
+            paths.append(Path(localappdata) / "rdc" / "renderdoc" / "renderdoccmd.exe")
         userprofile = os.environ.get("USERPROFILE", "")
         if userprofile:
             paths.append(

src/rdc/commands/doctor.py

@@ -42,24 +42,28 @@ def _make_build_hint(platform: str) -> str:
     if platform == "win32":
         return (
             "  renderdoc is not available on PyPI and must be built from source.\n"
-            "  Build script: python scripts/build_renderdoc.py\n"
-            "  Full instructions: https://bananasjim.github.io/rdc-cli/\n"
+            "  Quick setup (requires git, uv, Visual Studio Build Tools):\n"
+            "    git clone --depth 1 https://github.com/BANANASJIM/rdc-cli.git rdc-cli\n"
+            "    uv run rdc-cli\\scripts\\build_renderdoc.py\n"
+            "  Full instructions: https://bananasjim.github.io/rdc-cli/docs/install/\n"
             "  Then re-run: rdc doctor"
         )
     if platform == "darwin":
         return (
             "  renderdoc is not available on PyPI and must be built from source.\n"
             "  Build prerequisites: brew install cmake ninja\n"
-            "  Build script: python scripts/build_renderdoc.py\n"
-            "  Full instructions: https://bananasjim.github.io/rdc-cli/\n"
+            "  Quick setup (requires git, uv):\n"
+            "    git clone --depth 1 https://github.com/BANANASJIM/rdc-cli.git rdc-cli\n"
+            "    uv run rdc-cli/scripts/build_renderdoc.py\n"
+            "  Full instructions: https://bananasjim.github.io/rdc-cli/docs/install/\n"
             "  Then re-run: rdc doctor"
         )
     return (
         "  renderdoc is not available on PyPI and must be built from source.\n"
         "  Quick build script (no pixi required):\n"
         "    bash <(curl -fsSL"
         " https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh)\n"
-        "  Full instructions: https://bananasjim.github.io/rdc-cli/\n"
+        "  Full instructions: https://bananasjim.github.io/rdc-cli/docs/install/\n"
         "  Then re-run: rdc doctor"
     )
 
@@ -225,17 +229,16 @@ def _check_win_renderdoc_install() -> CheckResult:
     if sys.platform != "win32":
         return CheckResult("win-renderdoc-install", True, "n/a")
 
-    candidates: list[Path] = [
-        Path(r"C:\Program Files\RenderDoc\renderdoc.dll"),
-    ]
-    localappdata = os.environ.get("LOCALAPPDATA", "")
-    if localappdata:
-        candidates.append(Path(localappdata) / "renderdoc" / "renderdoc.dll")
-        candidates.append(Path(localappdata) / "RenderDoc" / "renderdoc.dll")
+    from rdc import _platform
+
+    candidates: list[Path] = []
 
     env_path = os.environ.get("RENDERDOC_PYTHON_PATH")
     if env_path:
-        candidates.insert(0, Path(env_path) / "renderdoc.dll")
+        candidates.append(Path(env_path) / "renderdoc.dll")
+
+    for search_dir in _platform.renderdoc_search_paths():
+        candidates.append(Path(search_dir) / "renderdoc.dll")
 
     for p in candidates:
         if p.exists():

tests/unit/test_build_renderdoc.py

@@ -405,6 +405,23 @@ def test_copy_artifacts_windows(tmp_path: Path) -> None:
     br.copy_artifacts(build_dir, out, "windows")
     assert (out / "renderdoc.pyd").exists()
     assert (out / "renderdoc.dll").exists()
+    assert not (out / "renderdoccmd.exe").exists()
+
+
+def test_copy_artifacts_windows_with_renderdoccmd(tmp_path: Path) -> None:
+    build_dir = tmp_path / "build"
+    release = build_dir / "renderdoc" / "x64" / "Release"
+    pymodules = release / "pymodules"
+    pymodules.mkdir(parents=True)
+    (pymodules / "renderdoc.pyd").write_text("fake")
+    (release / "renderdoc.dll").write_text("fake")
+    (release / "renderdoccmd.exe").write_text("fake")
+
+    out = tmp_path / "install"
+    br.copy_artifacts(build_dir, out, "windows")
+    assert (out / "renderdoc.pyd").exists()
+    assert (out / "renderdoc.dll").exists()
+    assert (out / "renderdoccmd.exe").exists()
 
 
 def test_copy_artifacts_missing_source(tmp_path: Path) -> None:

tests/unit/test_doctor.py

@@ -79,7 +79,7 @@ def test_doctor_shows_build_hint_when_renderdoc_missing(monkeypatch: pytest.Monk
         "  Quick build script (no pixi required):\n"
         "    bash <(curl -fsSL"
         " https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh)\n"
-        "  Full instructions: https://bananasjim.github.io/rdc-cli/\n"
+        "  Full instructions: https://bananasjim.github.io/rdc-cli/docs/install/\n"
         "  Then re-run: rdc doctor",
     )
     monkeypatch.setattr("rdc.commands.doctor.find_renderdoc", lambda: None)
@@ -95,7 +95,7 @@ def test_doctor_shows_build_hint_when_renderdoc_missing(monkeypatch: pytest.Monk
 def test_doctor_hint_contains_docs_url() -> None:
     from rdc.commands.doctor import _RENDERDOC_BUILD_HINT
 
-    assert "https://bananasjim.github.io/rdc-cli/" in _RENDERDOC_BUILD_HINT
+    assert "https://bananasjim.github.io/rdc-cli/docs/install/" in _RENDERDOC_BUILD_HINT
 
 
 # ── Group W: _check_win_python_version() ─────────────────────────────
@@ -273,8 +273,11 @@ def test_non_windows_returns_ok(self, monkeypatch: pytest.MonkeyPatch) -> None:
     def test_found_at_program_files(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """TP-W3-012: renderdoc.dll found at Program Files."""
         monkeypatch.setattr("rdc.commands.doctor.sys.platform", "win32")
-        env = {"LOCALAPPDATA": r"C:\Users\test\AppData\Local"}
-        monkeypatch.setattr("rdc.commands.doctor.os.environ", env)
+        monkeypatch.setattr("rdc.commands.doctor.os.environ", {})
+        monkeypatch.setattr(
+            "rdc._platform.renderdoc_search_paths",
+            lambda: [r"C:\Program Files\RenderDoc"],
+        )
 
         original_exists = Path.exists
 
@@ -292,17 +295,32 @@ def test_found_via_env(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) ->
         """TP-W3-013: renderdoc.dll found via RENDERDOC_PYTHON_PATH."""
         monkeypatch.setattr("rdc.commands.doctor.sys.platform", "win32")
         (tmp_path / "renderdoc.dll").write_text("fake")
-        env = {"RENDERDOC_PYTHON_PATH": str(tmp_path), "LOCALAPPDATA": ""}
+        env = {"RENDERDOC_PYTHON_PATH": str(tmp_path)}
         monkeypatch.setattr("rdc.commands.doctor.os.environ", env)
+        monkeypatch.setattr("rdc._platform.renderdoc_search_paths", lambda: [])
         r = _check_win_renderdoc_install()
         assert r.ok is True
         assert str(tmp_path) in r.detail
 
+    def test_found_at_localappdata_rdc(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        """renderdoc.dll found at %LOCALAPPDATA%\\rdc\\renderdoc via search paths."""
+        monkeypatch.setattr("rdc.commands.doctor.sys.platform", "win32")
+        rdc_dir = tmp_path / "rdc" / "renderdoc"
+        rdc_dir.mkdir(parents=True)
+        (rdc_dir / "renderdoc.dll").write_text("fake")
+        monkeypatch.setattr("rdc.commands.doctor.os.environ", {})
+        monkeypatch.setattr("rdc._platform.renderdoc_search_paths", lambda: [str(rdc_dir)])
+        r = _check_win_renderdoc_install()
+        assert r.ok is True
+        assert "renderdoc.dll" in r.detail
+
     def test_not_found_anywhere(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """TP-W3-014: renderdoc.dll not found anywhere."""
         monkeypatch.setattr("rdc.commands.doctor.sys.platform", "win32")
-        env: dict[str, str] = {"LOCALAPPDATA": ""}
-        monkeypatch.setattr("rdc.commands.doctor.os.environ", env)
+        monkeypatch.setattr("rdc.commands.doctor.os.environ", {})
+        monkeypatch.setattr("rdc._platform.renderdoc_search_paths", lambda: [])
         monkeypatch.setattr("rdc.commands.doctor.Path.exists", lambda _self: False)
         r = _check_win_renderdoc_install()
         assert r.ok is False
@@ -319,13 +337,16 @@ def test_linux_hint_contains_bash_script(self) -> None:
         """TP-W3-015: Linux hint has bash script URL."""
         hint = _make_build_hint("linux")
         assert "build-renderdoc.sh" in hint
-        assert "https://bananasjim.github.io/rdc-cli/" in hint
+        assert "https://bananasjim.github.io/rdc-cli/docs/install/" in hint
 
-    def test_windows_hint_contains_py_script(self) -> None:
-        """TP-W3-016: Windows hint has Python build script."""
+    def test_windows_hint_contains_actionable_commands(self) -> None:
+        """TP-W3-016: Windows hint has actionable git clone + uv run commands."""
         hint = _make_build_hint("win32")
+        assert "git clone" in hint
+        assert "uv run" in hint
         assert "build_renderdoc.py" in hint
-        assert "https://bananasjim.github.io/rdc-cli/" in hint
+        assert "%TEMP%" not in hint
+        assert "https://bananasjim.github.io/rdc-cli/docs/install/" in hint
 
 
 # ── TP-W3-017: run_doctor() result count ─────────────────────────────
@@ -602,8 +623,10 @@ class TestMakeBuildHintDarwin:
     def test_darwin_hint_contains_homebrew(self) -> None:
         hint = _make_build_hint("darwin")
         assert "brew install cmake ninja" in hint
+        assert "git clone" in hint
+        assert "uv run" in hint
         assert "build_renderdoc.py" in hint
-        assert "https://bananasjim.github.io/rdc-cli/" in hint
+        assert "https://bananasjim.github.io/rdc-cli/docs/install/" in hint
 
 
 class TestImportRenderdocDiagnostics: