rdc-cli 0.3.3__tar.gz → 0.3.4__tar.gz

{rdc_cli-0.3.3 → rdc_cli-0.3.4}/.github/workflows/ci.yml

@@ -95,12 +95,13 @@ jobs:
         run: uv run mypy src
 
   test:
-    name: Test (py${{ matrix.python-version }})
-    runs-on: ubuntu-latest
+    name: Test (py${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.12", "3.14"]
+        os: [ubuntu-latest, windows-latest]
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

{rdc_cli-0.3.3/src/rdc_cli.egg-info → rdc_cli-0.3.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: rdc-cli
-Version: 0.3.3
-Summary: Unix-friendly CLI for RenderDoc .rdc captures
+Version: 0.3.4
+Summary: CLI for RenderDoc .rdc captures
 Author: Jim
 License-Expression: MIT
 Classifier: Programming Language :: Python :: 3
@@ -58,7 +58,7 @@ rdc close
 
 ## Install
 
-**PyPI** (recommended — any Linux distro)
+**PyPI — Linux** (recommended)
 
 ```bash
 pipx install rdc-cli                  # install the CLI
@@ -67,6 +67,14 @@ curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/b
 rdc doctor                            # verify everything works
 ```
 
+**PyPI — Windows** (experimental)
+
+```bash
+pipx install rdc-cli
+python scripts/build_renderdoc.py     # needs cmake + Visual Studio Build Tools
+rdc doctor
+```
+
 **AUR** (Arch Linux — builds renderdoc automatically, no extra setup)
 
 ```bash
@@ -161,6 +169,7 @@ Run `rdc --help` for the full list, or `rdc <command> --help` for details.  See
 | Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |
 | Diff | `diff` (with `--draws`, `--stats`, `--framebuffer`, `--pipeline`, etc.) |
 | VFS | `ls`, `cat`, `tree` |
+| Remote | `remote connect`, `remote list`, `remote capture` |
 | Utility | `doctor`, `completion`, `capture`, `count`, `script`, `install-skill` |
 
 All list commands output TSV. All commands support `--json`. Footer/summary goes to stderr — stdout is always clean data.

{rdc_cli-0.3.3 → rdc_cli-0.3.4}/README.md

@@ -29,7 +29,7 @@ rdc close
 
 ## Install
 
-**PyPI** (recommended — any Linux distro)
+**PyPI — Linux** (recommended)
 
 ```bash
 pipx install rdc-cli                  # install the CLI
@@ -38,6 +38,14 @@ curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/b
 rdc doctor                            # verify everything works
 ```
 
+**PyPI — Windows** (experimental)
+
+```bash
+pipx install rdc-cli
+python scripts/build_renderdoc.py     # needs cmake + Visual Studio Build Tools
+rdc doctor
+```
+
 **AUR** (Arch Linux — builds renderdoc automatically, no extra setup)
 
 ```bash
@@ -132,6 +140,7 @@ Run `rdc --help` for the full list, or `rdc <command> --help` for details.  See
 | Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |
 | Diff | `diff` (with `--draws`, `--stats`, `--framebuffer`, `--pipeline`, etc.) |
 | VFS | `ls`, `cat`, `tree` |
+| Remote | `remote connect`, `remote list`, `remote capture` |
 | Utility | `doctor`, `completion`, `capture`, `count`, `script`, `install-skill` |
 
 All list commands output TSV. All commands support `--json`. Footer/summary goes to stderr — stdout is always clean data.

{rdc_cli-0.3.3 → rdc_cli-0.3.4}/docs-astro/src/data/commands.json

@@ -162,7 +162,7 @@
           "name": "search",
           "id": "search",
           "help": "Search shader disassembly text for PATTERN (regex).",
-          "usage": "rdc search <PATTERN> [--stage TEXT] [--limit INTEGER] [-C INTEGER] [-i] [--json]"
+          "usage": "rdc search <PATTERN> [--stage TEXT] [--limit INTEGER] [-C INTEGER] [--case-sensitive] [--json]"
         },
         {
           "name": "passes",
@@ -432,6 +432,31 @@
         }
       ]
     },
+    {
+      "name": "Remote",
+      "id": "remote",
+      "description": "Connect to a remote RenderDoc server for remote capture.",
+      "commands": [
+        {
+          "name": "remote connect",
+          "id": "remote-connect",
+          "help": "Connect to a remote RenderDoc server.",
+          "usage": "rdc remote connect <URL> [--json]"
+        },
+        {
+          "name": "remote list",
+          "id": "remote-list",
+          "help": "List capturable applications on a remote host.",
+          "usage": "rdc remote list [--url TEXT] [--json]"
+        },
+        {
+          "name": "remote capture",
+          "id": "remote-capture",
+          "help": "Capture on a remote host and transfer to local.",
+          "usage": "rdc remote capture <APP> -o <PATH> [--url TEXT] [--args TEXT] [--workdir TEXT] [--frame INTEGER] [--timeout FLOAT] [--api-validation] [--callstacks] [--hook-children] [--ref-all-resources] [--soft-memory-limit INTEGER] [--json]"
+        }
+      ]
+    },
     {
       "name": "Utilities",
       "id": "utilities",

{rdc_cli-0.3.3 → rdc_cli-0.3.4}/docs-astro/src/layouts/Docs.astro

@@ -15,6 +15,7 @@ const currentPath = Astro.url.pathname.replace(/\/$/, '');
 const sidebar = [
   { label: 'Overview', href: `${base}docs/` },
   { label: 'Installation', href: `${base}docs/install/` },
+  { label: 'Windows Install', href: `${base}docs/install/windows/` },
   { label: 'Usage Patterns', href: `${base}docs/usage/` },
   { label: 'Commands', href: `${base}docs/commands/` },
   { label: 'VFS Paths', href: `${base}docs/vfs/` },

rdc_cli-0.3.4/docs-astro/src/pages/docs/install/windows.astro

@@ -0,0 +1,105 @@
+---
+import Docs from '../../../layouts/Docs.astro';
+---
+
+<Docs title="Windows Installation">
+  <h2>Prerequisites</h2>
+  <ul>
+    <li>Windows 10 / 11 64-bit</li>
+    <li>Python 3.12.x (exact minor version must match the renderdoc <code>.pyd</code>)</li>
+    <li>Visual Studio 2022 Build Tools with "Desktop development with C++" workload</li>
+    <li>Git (for building renderdoc from source)</li>
+  </ul>
+
+  <h2>Install rdc-cli</h2>
+  <pre><code>pip install rdc-cli</code></pre>
+  <p>
+    This installs the <code>rdc</code> command. You still need the renderdoc
+    Python module &mdash; see below.
+  </p>
+
+  <h2>RenderDoc Python Module</h2>
+  <p>
+    The renderdoc Python module (<code>renderdoc.cpython-3*.pyd</code>) is
+    <strong>not</strong> available on PyPI. Your Python minor version must
+    exactly match the one used to compile the module.
+  </p>
+
+  <h3>Option A: RenderDoc Installer</h3>
+  <p>
+    Download and install
+    <a href="https://renderdoc.org/builds">RenderDoc for Windows</a>.
+    The installer places <code>renderdoc.dll</code> in
+    <code>C:\Program Files\RenderDoc</code>. The Python bindings
+    (<code>.pyd</code>) may be included depending on the installer version.
+  </p>
+
+  <h3>Option B: Build from Source</h3>
+  <p>
+    A cross-platform build script is planned for Phase W2. In the meantime,
+    see <code>scripts/build_renderdoc.py</code> (coming in Phase W2) or
+    build manually:
+  </p>
+  <pre><code>git clone --depth 1 https://github.com/baldurk/renderdoc.git
+cd renderdoc
+cmake -B build -G "Visual Studio 17 2022" -DENABLE_PYRENDERDOC=ON -DENABLE_QRENDERDOC=OFF
+cmake --build build --config Release
+set RENDERDOC_PYTHON_PATH=%cd%\build\lib\Release</code></pre>
+
+  <h2>Configure RENDERDOC_PYTHON_PATH</h2>
+  <p>
+    Set the environment variable to point at the directory containing the
+    <code>.pyd</code> file:
+  </p>
+  <pre><code>set RENDERDOC_PYTHON_PATH=C:\path\to\renderdoc\build\lib</code></pre>
+  <p>
+    To make it permanent, add it via
+    <strong>System Properties &rarr; Environment Variables</strong>.
+  </p>
+
+  <h2>Validate with rdc doctor</h2>
+  <pre><code>rdc doctor</code></pre>
+  <p>
+    A successful output on Windows shows 8 checks, including the three
+    Windows-specific checks:
+  </p>
+  <ul>
+    <li><code>win-python-version</code> &mdash; Python version matches <code>.pyd</code></li>
+    <li><code>win-vs-build-tools</code> &mdash; Visual Studio Build Tools detected</li>
+    <li><code>win-renderdoc-install</code> &mdash; RenderDoc <code>.dll</code> found</li>
+  </ul>
+
+  <h2>Known Limitations</h2>
+  <ul>
+    <li>
+      Daemon process management (<code>rdc session start</code>) is not yet
+      functional on Windows. Phase W2 will implement the required OS-level
+      process APIs.
+    </li>
+    <li>
+      All analysis commands (<code>rdc open</code>, <code>rdc info</code>,
+      <code>rdc shaders</code>, etc.) will work once the daemon is running.
+    </li>
+  </ul>
+
+  <h2>Troubleshooting</h2>
+  <h3>Python version mismatch</h3>
+  <p>
+    If <code>rdc doctor</code> reports a version mismatch between your
+    running Python and the <code>.pyd</code>, install the matching Python
+    version or rebuild renderdoc with your current Python.
+  </p>
+
+  <h3>renderdoc module not found</h3>
+  <p>
+    Ensure <code>RENDERDOC_PYTHON_PATH</code> points to the directory
+    containing <code>renderdoc.pyd</code> (not <code>renderdoc.dll</code>).
+  </p>
+
+  <h3>vswhere.exe not found</h3>
+  <p>
+    Install <a href="https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022">
+    Visual Studio 2022 Build Tools</a> with the "Desktop development with
+    C++" workload selected.
+  </p>
+</Docs>

rdc_cli-0.3.4/openspec/changes/2026-02-23-phase-w2-build-script/proposal.md

@@ -0,0 +1,173 @@
+# Phase W2: Cross-Platform Build Script
+
+## Motivation
+
+Two near-identical bash scripts currently handle the renderdoc build:
+
+- `scripts/build-renderdoc.sh` — standalone, curl-pipe install pattern, installs to `~/.local/renderdoc/`
+- `scripts/setup-renderdoc.sh` — pixi dev env, installs to `.local/renderdoc/` (relative to repo root)
+
+The differences are cosmetic: output path and whether SHA256 verification is performed. Both will break on Windows (no bash, no `nproc`, no `.so` artifacts). Phase W1 added `src/rdc/_platform.py`; W2 extends platform-awareness to the build tooling by replacing both scripts with a single Python script.
+
+## Scope
+
+- New file: `scripts/build_renderdoc.py` (stdlib only, Python 3.10+)
+- `pixi.toml`: update `setup-renderdoc` task to call the Python script
+- `scripts/build-renderdoc.sh` and `scripts/setup-renderdoc.sh`: retained, marked deprecated
+- `scripts/ensure-renderdoc.sh`: unchanged (worktree symlink helper, bash-only is fine)
+
+## Design
+
+### Script Architecture
+
+The script is a single self-contained Python file with no third-party imports. It is structured as a sequence of functions called from `main()`:
+
+```
+main()
+  check_prerequisites()
+  clone_renderdoc()
+  download_swig()
+  configure_build()
+  run_build()
+  copy_artifacts()
+```
+
+Top-level constants mirror those in the bash scripts:
+
+```python
+RDOC_TAG = "v1.41"
+SWIG_URL = "https://github.com/baldurk/swig/archive/renderdoc-modified-7.zip"
+SWIG_SHA256 = "9d7e5013ada6c42ec95ab167a34db52c1cc8c09b89c8e9373631b1f10596c648"
+SWIG_SUBDIR = "swig-renderdoc-modified-7"
+```
+
+`main()` accepts an optional positional argument `INSTALL_DIR`; if omitted, `default_install_dir()` is used. `--build-dir` is also accepted to override the build cache location.
+
+### Platform Detection
+
+A private helper `_platform()` returns one of `"linux"`, `"macos"`, `"windows"`:
+
+```python
+import sys
+
+def _platform() -> str:
+    if sys.platform == "win32":
+        return "windows"
+    if sys.platform == "darwin":
+        return "macos"
+    return "linux"
+```
+
+### Build Flow
+
+**`check_prerequisites()`**
+
+Required tools per platform:
+
+| Tool | Linux | macOS | Windows |
+|------|-------|-------|---------|
+| `cmake` | yes | yes | yes |
+| `git` | yes | yes | yes |
+| `python3` / `python` | yes | yes | yes |
+| `ninja` | yes | yes | no |
+| `vswhere.exe` | no | no | yes |
+
+On Windows, the function also verifies Visual Studio Build Tools are present by running `vswhere -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -format value -property installationPath` and confirming a non-empty result.
+
+**`clone_renderdoc(build_dir: Path)`**
+
+Idempotent: skips if `build_dir / "renderdoc"` exists. Uses `git clone --depth 1 --branch RDOC_TAG`.
+
+**`download_swig(build_dir: Path)`**
+
+Idempotent: skips if `build_dir / "renderdoc-swig"` exists.
+
+Uses `urllib.request.urlretrieve` (stdlib). After download, verifies SHA256 with `hashlib`. Extracts with `zipfile.ZipFile`. Raises `SystemExit(1)` on checksum mismatch and deletes the corrupt archive.
+
+**`configure_build(build_dir: Path)`**
+
+CMake flags common to all platforms:
+
+```
+-DCMAKE_BUILD_TYPE=Release
+-DENABLE_PYRENDERDOC=ON
+-DENABLE_QRENDERDOC=OFF
+-DENABLE_RENDERDOCCMD=OFF
+-DENABLE_GL=OFF
+-DENABLE_GLES=OFF
+-DENABLE_VULKAN=ON
+-DRENDERDOC_SWIG_PACKAGE=<build_dir>/renderdoc-swig
+```
+
+Generator selection:
+
+- Linux/macOS: `-G Ninja`
+- Windows: `-G "Visual Studio 17 2022" -A x64`
+
+On ALL Linux, strips `-flto=auto` from `CFLAGS`, `CXXFLAGS`, `LDFLAGS` in the environment passed to `subprocess.run`.
+
+**`run_build(build_dir: Path)`**
+
+Runs `cmake --build <build_dir>/renderdoc/build`. Uses `os.cpu_count()` for parallelism.
+
+On Linux/macOS: `-j <n>`. On Windows: `--` `/m:<n>` (MSBuild parallel flag).
+
+**`copy_artifacts(build_dir: Path, out_dir: Path)`**
+
+Artifact paths by platform:
+
+| Platform | Source | Destination |
+|----------|--------|-------------|
+| Linux | `build/lib/renderdoc.so`, `build/lib/librenderdoc.so` | `out_dir/` |
+| macOS | `build/lib/renderdoc.so`, `build/lib/librenderdoc.so` (or `.dylib`) | `out_dir/` |
+| Windows | `build/Release/renderdoc.pyd`, `build/Release/renderdoc.dll` | `out_dir/` |
+
+Uses `shutil.copy2`.
+
+### Output Paths
+
+`default_install_dir()` returns the renderdoc artifact directory:
+
+```python
+def default_install_dir() -> Path:
+    if _platform() == "windows":
+        base = os.environ.get("LOCALAPPDATA", str(Path.home()))
+        return Path(base) / "renderdoc"
+    return Path.home() / ".local" / "renderdoc"
+```
+
+The build cache is always `<install_dir_parent>/renderdoc-build`, or overridden with `--build-dir`.
+
+### Backward Compatibility
+
+`scripts/build-renderdoc.sh` and `scripts/setup-renderdoc.sh` are retained verbatim. A deprecation notice comment is prepended at the top of each:
+
+```bash
+# DEPRECATED: use scripts/build_renderdoc.py instead.
+# Kept for curl-pipe users on systems without Python 3.10+.
+```
+
+The `pixi.toml` `setup-renderdoc` task is updated:
+
+```toml
+setup-renderdoc = "python scripts/build_renderdoc.py .local/renderdoc --build-dir .local/renderdoc-build"
+```
+
+## Non-Goals
+
+- Building renderdoc for non-Python use (GUI, renderdoccmd)
+- Supporting renderdoc versions other than v1.41
+- Automatic Python version detection for the SWIG binding target
+- Package manager integration (apt, brew, winget)
+- `ensure-renderdoc.sh` replacement (worktree symlink logic stays bash)
+- Modifying `src/rdc/_platform.py` (Windows stubs deferred to W3)
+
+## Risks
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Windows build untested in CI | Medium | Manual verification section in test-plan; CI matrix is Linux-only for now |
+| SWIG ZIP layout changes across renderdoc versions | Low | SHA256 pin + explicit `SWIG_SUBDIR` constant |
+| `urllib.request` slow vs `curl` for large archives | Low | Progress callback via `reporthook` in `urlretrieve` |
+| Visual Studio version drift (2022 to future) | Low | Document assumption; add `--vs-version` flag as future option |
+| macOS artifact path differs from Linux | Medium | `copy_artifacts` handles `.dylib` fallback for `librenderdoc` |

rdc_cli-0.3.4/openspec/changes/2026-02-23-phase-w2-build-script/tasks.md

@@ -0,0 +1,90 @@
+# Phase W2: Tasks
+
+## Prerequisites
+
+- [x] Phase W1 merged (PR #124 -- `src/rdc/_platform.py` exists)
+- [x] OpenSpec reviewed and approved by Jim
+
+## Implementation Tasks
+
+### T1 -- Create `scripts/build_renderdoc.py`
+
+File: `scripts/build_renderdoc.py`
+
+Implement in this order (each function is independently testable):
+
+1. Constants block at module top:
+   ```python
+   RDOC_TAG = "v1.41"
+   SWIG_URL = "https://github.com/baldurk/swig/archive/renderdoc-modified-7.zip"
+   SWIG_SHA256 = "9d7e5013ada6c42ec95ab167a34db52c1cc8c09b89c8e9373631b1f10596c648"
+   SWIG_SUBDIR = "swig-renderdoc-modified-7"
+   ```
+
+2. `_platform() -> str` -- returns `"linux"`, `"macos"`, or `"windows"`
+
+3. `default_install_dir() -> Path` -- `~/.local/renderdoc` or `%LOCALAPPDATA%\renderdoc`
+
+4. `check_prerequisites(plat: str) -> None` -- verifies required tools per platform
+
+5. `clone_renderdoc(build_dir: Path) -> None` -- idempotent `git clone --depth 1 --branch RDOC_TAG`
+
+6. `download_swig(build_dir: Path) -> None` -- idempotent download + SHA256 verify + unzip + rename
+
+7. `strip_lto(env: dict) -> dict` -- removes `-flto=auto` from `CFLAGS`/`CXXFLAGS`/`LDFLAGS`
+
+8. `configure_build(build_dir, swig_dir, plat) -> None` -- cmake configure; strips LTO on ALL Linux
+
+9. `run_build(build_dir, plat, jobs) -> None` -- `cmake --build` with platform-specific parallelism
+
+10. `copy_artifacts(build_dir, install_dir, plat) -> None` -- copies platform-specific artifacts; macOS `.dylib` fallback
+
+11. `main(argv) -> None` -- `argparse` entry point; short-circuits if artifacts already present
+
+Constraints:
+- stdlib only (no third-party imports)
+- Python 3.10+ syntax
+- No `print()` -- use `sys.stdout.write()`
+- Use `subprocess.run(..., check=True)` throughout
+
+### T2 -- Add deprecation notices to bash scripts
+
+File: `scripts/build-renderdoc.sh`, line 2 (after shebang):
+```bash
+# DEPRECATED: use scripts/build_renderdoc.py instead.
+# Kept for curl-pipe users on systems without Python 3.10+.
+```
+
+File: `scripts/setup-renderdoc.sh`, line 2 (after shebang):
+```bash
+# DEPRECATED: use scripts/build_renderdoc.py instead.
+# Kept for curl-pipe users on systems without Python 3.10+.
+```
+
+### T3 -- Update `pixi.toml`
+
+Replace the `setup-renderdoc` task:
+
+```toml
+setup-renderdoc = "python scripts/build_renderdoc.py .local/renderdoc --build-dir .local/renderdoc-build"
+```
+
+### T4 -- SKIPPED (moved to W3)
+
+`_platform.py` Windows stubs implementation deferred to Phase W3 per review.
+
+## Testing Tasks
+
+### T5 -- Write `tests/unit/test_build_renderdoc.py`
+
+Cover all test cases from `test-plan.md`. Target: full branch coverage of `scripts/build_renderdoc.py`.
+
+### T6 -- Scaffold `tests/integration/test_build_renderdoc_integration.py`
+
+Single skipped test function. No CI execution.
+
+## Documentation Tasks
+
+### T7 -- Archive OpenSpec (post-merge)
+
+After PR merge: `mv openspec/changes/2026-02-23-phase-w2-build-script openspec/changes/archive/`

rdc_cli-0.3.4/openspec/changes/2026-02-23-phase-w2-build-script/test-plan.md

@@ -0,0 +1,116 @@
+# Phase W2: Test Plan
+
+## Unit Tests
+
+File: `tests/unit/test_build_renderdoc.py`
+
+All tests use `unittest.mock` to avoid network and filesystem side-effects. The script is imported as a module after adding `scripts/` to `sys.path`.
+
+### Platform detection
+
+| Test | Description |
+|------|-------------|
+| `test_platform_linux` | `sys.platform = "linux"` -> `_platform()` returns `"linux"` |
+| `test_platform_macos` | `sys.platform = "darwin"` -> `_platform()` returns `"macos"` |
+| `test_platform_windows` | `sys.platform = "win32"` -> `_platform()` returns `"windows"` |
+
+### Default install dir
+
+| Test | Description |
+|------|-------------|
+| `test_default_install_dir_linux` | `_platform()` mocked to `"linux"` -> `Path.home() / ".local/renderdoc"` |
+| `test_default_install_dir_macos` | `_platform()` mocked to `"macos"` -> `Path.home() / ".local/renderdoc"` |
+| `test_default_install_dir_windows` | `_platform()` mocked to `"windows"`, `LOCALAPPDATA` set -> `Path(LOCALAPPDATA) / "renderdoc"` |
+| `test_default_install_dir_windows_no_localappdata` | `LOCALAPPDATA` unset -> falls back to `Path.home() / "renderdoc"` |
+
+### Prerequisite checking
+
+| Test | Description |
+|------|-------------|
+| `test_check_prerequisites_all_present_linux` | All tools found -> no exception |
+| `test_check_prerequisites_missing_cmake` | `cmake` not in PATH -> `SystemExit(1)` |
+| `test_check_prerequisites_missing_ninja_linux` | `ninja` missing on Linux -> `SystemExit(1)` |
+| `test_check_prerequisites_windows_no_ninja` | Windows does not require ninja -> no error |
+| `test_check_prerequisites_windows_vswhere_empty` | `vswhere.exe` returns empty -> `SystemExit(1)` |
+| `test_check_prerequisites_windows_vswhere_missing` | `vswhere.exe` not found -> `SystemExit(1)` |
+
+### Clone renderdoc
+
+| Test | Description |
+|------|-------------|
+| `test_clone_renderdoc_fresh` | Target dir absent -> `git clone` called with `--depth 1 --branch v1.41` |
+| `test_clone_renderdoc_idempotent` | Target dir exists -> `git clone` not called |
+
+### SWIG download
+
+| Test | Description |
+|------|-------------|
+| `test_download_swig_fresh_ok` | Dir absent, SHA256 matches -> extracted and renamed |
+| `test_download_swig_idempotent` | `renderdoc-swig` exists -> download skipped |
+| `test_download_swig_sha256_mismatch` | Hash differs -> `SystemExit(1)`, archive deleted |
+
+### LTO flag stripping
+
+| Test | Description |
+|------|-------------|
+| `test_strip_lto_removes_flag` | env has `-flto=auto` in all three vars -> stripped |
+| `test_strip_lto_no_flags_present` | No `-flto=auto` -> no change |
+| `test_strip_lto_does_not_mutate_original` | Original dict unchanged |
+
+### CMake configuration
+
+| Test | Description |
+|------|-------------|
+| `test_configure_linux_uses_ninja` | Linux -> `-G Ninja` |
+| `test_configure_macos_uses_ninja` | macOS -> `-G Ninja` |
+| `test_configure_windows_uses_vs` | Windows -> `-G "Visual Studio 17 2022" -A x64` |
+| `test_configure_common_flags` | All -> `-DENABLE_PYRENDERDOC=ON` etc. present |
+| `test_configure_swig_package_path` | `-DRENDERDOC_SWIG_PACKAGE` set correctly |
+| `test_configure_linux_strips_lto` | Linux env `-flto=auto` stripped |
+
+### Build
+
+| Test | Description |
+|------|-------------|
+| `test_run_build_parallel_flag_linux` | Linux -> `-j N` |
+| `test_run_build_parallel_flag_windows` | Windows -> `/m:N` after `--` |
+
+### Artifact copy
+
+| Test | Description |
+|------|-------------|
+| `test_copy_artifacts_linux` | Linux -> copies `renderdoc.so` and `librenderdoc.so` |
+| `test_copy_artifacts_macos` | macOS -> same as Linux |
+| `test_copy_artifacts_macos_dylib_fallback` | macOS `.dylib` fallback works |
+| `test_copy_artifacts_windows` | Windows -> copies `.pyd` and `.dll` |
+| `test_copy_artifacts_missing_source` | Missing artifact -> `SystemExit(1)` |
+
+### CLI argument parsing
+
+| Test | Description |
+|------|-------------|
+| `test_main_default_install_dir` | No args -> `default_install_dir()` used |
+| `test_main_custom_install_dir` | Positional arg -> used as install dir |
+| `test_main_custom_build_dir` | `--build-dir` -> passed through |
+| `test_main_idempotent_skip` | Artifacts present -> all build steps skipped |
+
+## Integration Tests
+
+File: `tests/integration/test_build_renderdoc_integration.py`
+
+Single `@pytest.mark.skip` test. No CI execution. Manual verification only.
+
+## Manual Verification
+
+### Linux (primary target)
+
+1. `rm -rf ~/.local/renderdoc ~/.local/renderdoc-build`
+2. `python scripts/build_renderdoc.py`
+3. Confirm `~/.local/renderdoc/renderdoc.so` and `librenderdoc.so` present
+4. Run again: must print "already exists" and exit without rebuilding
+
+### Linux (pixi task path)
+
+1. `rm -rf .local/renderdoc .local/renderdoc-build`
+2. `pixi run setup-renderdoc`
+3. Confirm `.local/renderdoc/renderdoc.so` exists