rdc-cli 0.3.6__tar.gz → 0.3.8__tar.gz

{rdc_cli-0.3.6/src/rdc_cli.egg-info → rdc_cli-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdc-cli
-Version: 0.3.6
+Version: 0.3.8
 Summary: CLI for RenderDoc .rdc captures
 Author: Jim
 License-Expression: MIT
@@ -61,7 +61,7 @@ rdc close
 **PyPI — Linux** (recommended)
 
 ```bash
-pipx install rdc-cli                  # install the CLI
+uv tool install rdc-cli               # or: pipx install rdc-cli
 python scripts/build_renderdoc.py     # one-time build (needs cmake + ninja)
 rdc doctor                            # verify everything works
 ```
@@ -69,7 +69,7 @@ rdc doctor                            # verify everything works
 **PyPI — Windows** (experimental)
 
 ```bash
-pipx install rdc-cli
+uv tool install rdc-cli               # or: pipx install rdc-cli
 python scripts/build_renderdoc.py     # needs cmake + Visual Studio Build Tools
 rdc doctor
 ```
@@ -77,7 +77,7 @@ rdc doctor
 **PyPI — macOS** (Split client only)
 
 ```bash
-pipx install rdc-cli
+uv tool install rdc-cli               # or: pipx install rdc-cli
 # Local replay on macOS is not supported right now.
 # Use Split mode and run replay on a Linux/Windows daemon:
 #   rdc open /tmp/frame.rdc --listen 0.0.0.0:54321   # on replay host
@@ -99,8 +99,8 @@ yay -S rdc-cli        # stable: tracks tagged releases
 git clone https://github.com/BANANASJIM/rdc-cli.git
 cd rdc-cli
 pixi install && pixi run sync
-# Build renderdoc once (pixi installs toolchain on macOS automatically)
-pixi run setup-renderdoc
+pixi run install                      # editable install + shell completions
+pixi run setup-renderdoc              # build renderdoc (pixi installs toolchain on macOS)
 ```
 
 ### Platform Support Matrix
@@ -180,9 +180,9 @@ rdc capture --output /tmp/game.rdc -- /path/to/game
 rdc open /tmp/game_frame0.rdc --listen 0.0.0.0:54321
 
 # On macOS client (no local renderdoc required)
-PYTHONPATH=src .venv/bin/rdc open --connect host:54321 --token TOKEN
-PYTHONPATH=src .venv/bin/rdc capture --output /tmp/mac_capture.rdc -- /usr/bin/vkcube
-PYTHONPATH=src .venv/bin/rdc remote capture /usr/bin/vkcube -o /tmp/mac_remote.rdc
+rdc open --connect host:54321 --token TOKEN
+rdc capture --output /tmp/mac_capture.rdc -- /usr/bin/vkcube
+rdc remote capture /usr/bin/vkcube -o /tmp/mac_remote.rdc
 rdc close --shutdown
 ```
 
@@ -238,6 +238,8 @@ Options available on most list/query commands (not every command supports all):
 
 ### Shell completions
 
+Completions are installed automatically by `pixi run install`. To install manually:
+
 ```bash
 rdc completion bash > ~/.local/share/bash-completion/completions/rdc
 rdc completion zsh  > ~/.zfunc/_rdc
@@ -248,6 +250,7 @@ rdc completion fish > ~/.config/fish/completions/rdc.fish
 
 ```bash
 pixi run sync                 # install deps + git hooks + renderdoc symlink
+pixi run install              # editable install + shell completions
 pixi run check                # lint + typecheck + test
 pixi run verify               # full packaging verification
 ```

{rdc_cli-0.3.6 → rdc_cli-0.3.8}/README.md

@@ -32,7 +32,7 @@ rdc close
 **PyPI — Linux** (recommended)
 
 ```bash
-pipx install rdc-cli                  # install the CLI
+uv tool install rdc-cli               # or: pipx install rdc-cli
 python scripts/build_renderdoc.py     # one-time build (needs cmake + ninja)
 rdc doctor                            # verify everything works
 ```
@@ -40,7 +40,7 @@ rdc doctor                            # verify everything works
 **PyPI — Windows** (experimental)
 
 ```bash
-pipx install rdc-cli
+uv tool install rdc-cli               # or: pipx install rdc-cli
 python scripts/build_renderdoc.py     # needs cmake + Visual Studio Build Tools
 rdc doctor
 ```
@@ -48,7 +48,7 @@ rdc doctor
 **PyPI — macOS** (Split client only)
 
 ```bash
-pipx install rdc-cli
+uv tool install rdc-cli               # or: pipx install rdc-cli
 # Local replay on macOS is not supported right now.
 # Use Split mode and run replay on a Linux/Windows daemon:
 #   rdc open /tmp/frame.rdc --listen 0.0.0.0:54321   # on replay host
@@ -70,8 +70,8 @@ yay -S rdc-cli        # stable: tracks tagged releases
 git clone https://github.com/BANANASJIM/rdc-cli.git
 cd rdc-cli
 pixi install && pixi run sync
-# Build renderdoc once (pixi installs toolchain on macOS automatically)
-pixi run setup-renderdoc
+pixi run install                      # editable install + shell completions
+pixi run setup-renderdoc              # build renderdoc (pixi installs toolchain on macOS)
 ```
 
 ### Platform Support Matrix
@@ -151,9 +151,9 @@ rdc capture --output /tmp/game.rdc -- /path/to/game
 rdc open /tmp/game_frame0.rdc --listen 0.0.0.0:54321
 
 # On macOS client (no local renderdoc required)
-PYTHONPATH=src .venv/bin/rdc open --connect host:54321 --token TOKEN
-PYTHONPATH=src .venv/bin/rdc capture --output /tmp/mac_capture.rdc -- /usr/bin/vkcube
-PYTHONPATH=src .venv/bin/rdc remote capture /usr/bin/vkcube -o /tmp/mac_remote.rdc
+rdc open --connect host:54321 --token TOKEN
+rdc capture --output /tmp/mac_capture.rdc -- /usr/bin/vkcube
+rdc remote capture /usr/bin/vkcube -o /tmp/mac_remote.rdc
 rdc close --shutdown
 ```
 
@@ -209,6 +209,8 @@ Options available on most list/query commands (not every command supports all):
 
 ### Shell completions
 
+Completions are installed automatically by `pixi run install`. To install manually:
+
 ```bash
 rdc completion bash > ~/.local/share/bash-completion/completions/rdc
 rdc completion zsh  > ~/.zfunc/_rdc
@@ -219,6 +221,7 @@ rdc completion fish > ~/.config/fish/completions/rdc.fish
 
 ```bash
 pixi run sync                 # install deps + git hooks + renderdoc symlink
+pixi run install              # editable install + shell completions
 pixi run check                # lint + typecheck + test
 pixi run verify               # full packaging verification
 ```

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-design-deviation-fixes/proposal.md

@@ -0,0 +1,68 @@
+# Design Deviation Fixes
+
+**Date**: 2026-02-28
+**Priority**: DEV-1 (P2), DEV-2 (P3), DEV-3 (P3)
+
+## Motivation
+
+An audit of the rdc-cli codebase against the canonical design documents identified three deviations from spec. Two are cosmetic or documentation-level issues (P3); one is a missing VFS feature that breaks the path-addressing contract (P2).
+
+- **DEV-1**: The VFS router does not expose `/draws/{eid}/bindings/{set}/{binding}` leaf nodes despite the spec in `设计/路径寻址设计.md` requiring them. Users and tooling that navigate the VFS tree cannot read individual binding details at the slot level.
+- **DEV-2**: `设计/命令总览.md` annotates `diff --trace` and `diff --trace-all` as Phase 4, but those flags depend on pixel tracing and shader debug, which are Phase 5C capabilities. The wrong annotation creates misleading roadmap expectations.
+- **DEV-3**: `rdc open --listen` omits the `connect with:` convenience line from its output, which the split-mode design (`设计/远程Split模式.md`) requires. Users must manually compose the connection command from separate host/port/token lines.
+
+## Scope
+
+| ID | Component | Kind | Priority |
+|----|-----------|------|----------|
+| DEV-1 | `src/rdc/vfs/router.py`, `tree_cache.py`, `vfs.py` | Feature gap | P2 |
+| DEV-2 | `Documents/Obsidian Vault/rdoc-cli/设计/命令总览.md` | Doc correction | P3 |
+| DEV-3 | `src/rdc/commands/session.py` | Output line gap | P3 |
+
+## Design
+
+### DEV-1: VFS binding leaf node route
+
+The VFS currently treats `/draws/{eid}/bindings/{set}` as a terminal directory. The spec requires a further level: `/draws/{eid}/bindings/{set}/{binding}` where `{binding}` is the slot index (fixedBindNumber), returning per-slot binding details.
+
+**router.py**: Add a leaf route entry immediately after the existing bindings set route:
+
+```python
+_r(
+    r"/draws/(?P<eid>\d+)/bindings/(?P<set>\d+)/(?P<binding>\d+)",
+    "leaf", "bindings",
+    [("eid", int), ("set", int), ("binding", int)],
+)
+```
+
+**tree_cache.py**: The `binding_sets` field on the per-event cache entry currently stores `set[int]` (set indices only). Change it to `dict[int, set[int]]` mapping set index to a set of slot indices. During tree population, collect `fixedBindNumber` from both `readOnlyResources` and `readWriteResources` for each pipeline stage, mirroring the cbuffer leaf pattern used at lines 327-349. Generate `VfsNode` leaf children under each set directory node for each discovered slot.
+
+**vfs.py**: Add an `_EXTRACTORS["bindings"]` entry that formats leaf content as TSV with columns: `EID`, `STAGE`, `KIND`, `SET`, `SLOT`, `NAME`. The extractor passes the resolved `(eid, set, binding)` triple to `_handle_bindings`, which already accepts set and binding filter parameters.
+
+### DEV-2: diff --trace Phase annotation correction
+
+In `设计/命令总览.md`, lines 165-166 annotate `diff --trace` and `diff --trace-all` as Phase 4. Change both annotations to Phase 5C to reflect their true dependency on pixel tracing and shader debug infrastructure.
+
+No code changes are required.
+
+### DEV-3: --listen connect hint output
+
+In `src/rdc/commands/session.py`, after the `token:` output line (currently line 179), insert:
+
+```python
+click.echo(
+    f"connect with: rdc open --connect"
+    f" {result['host']}:{result['port']}"
+    f" --token {result['token']}"
+)
+```
+
+This produces a ready-to-copy connection command consistent with the spec in `设计/远程Split模式.md`. The format matches the `rdc open --connect HOST:PORT --token TOKEN` invocation documented there.
+
+## Risks
+
+**DEV-1**: Changing `binding_sets` from `set[int]` to `dict[int, set[int]]` alters the shape of children lists in the VFS tree. Completion logic and `ls` output that iterate over binding set children must be verified to handle the new slot-level leaf nodes without regressions. Mitigation: follow the cbuffer implementation pattern exactly, which is already exercised by existing tests.
+
+**DEV-2**: Documentation only. Zero code risk. Annotation change may prompt questions from users who see Phase 5C on the roadmap for those flags.
+
+**DEV-3**: Existing tests that assert the exact `rdc open --listen` output will fail if they check for a specific number of output lines or match on the full stdout string. Those tests must be updated to include the new hint line. No behavioral change occurs.

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-design-deviation-fixes/tasks.md

@@ -0,0 +1,25 @@
+# Tasks: Design Deviation Fixes
+
+## DEV-1: VFS Binding Leaf Node Route (Agent A — worktree)
+
+- [ ] `src/rdc/vfs/router.py` — Add leaf route for `/draws/{eid}/bindings/{set}/{binding}` with `handler="bindings"`
+- [ ] `src/rdc/vfs/tree_cache.py` — Change `binding_sets: set[int]` to `dict[int, set[int]]`; collect `fixedBindNumber` from `readOnlyResources` and `readWriteResources`; create `VfsNode` leaf nodes and set children lists on set-directory nodes (mirror cbuffer pattern at lines 342-349)
+- [ ] `src/rdc/commands/vfs.py` — Add `_EXTRACTORS["bindings"]` with TSV formatter
+- [ ] `tests/unit/test_vfs_router.py` — Add binding leaf route resolution tests
+- [ ] `tests/unit/test_vfs_tree_cache.py` (or equivalent) — Add binding leaf node population tests
+- [ ] `tests/unit/test_vfs_commands.py` — Add binding extractor TSV tests (T1-5, T1-6)
+
+## DEV-2: diff --trace Phase Annotation (main agent — doc only)
+
+- [ ] Obsidian `设计/命令总览.md` — Change Phase `"4"` to `"5C"` on the `diff --trace` and `diff --trace-all` lines (lines 165–166)
+
+## DEV-3: --listen Connect Hint (Agent B — worktree)
+
+- [ ] `src/rdc/commands/session.py` — Add `"connect with:"` output line after the token line in `--listen` mode
+- [ ] `tests/unit/test_split_core.py` — Add assertion for `"connect with:"` line in `test_listen_outputs_connection_info`
+
+## Post-implementation
+
+- [ ] Merge worktree outputs back to feature branch
+- [ ] Run `pixi run lint && pixi run test` — zero failures allowed
+- [ ] New Opus subagent code review

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-design-deviation-fixes/test-plan.md

@@ -0,0 +1,45 @@
+# Test Plan: Design Deviation Fixes (DEV-1, DEV-2, DEV-3)
+
+## DEV-1: VFS Binding Leaf Node Route
+
+### `tests/unit/test_vfs_router.py` — router resolution
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| T1-1 | VFS router | `resolve_path("/draws/142/bindings/0/0")` | Returns `PathMatch(kind="leaf", handler="bindings", args={"eid": 142, "set": 0, "binding": 0})` |
+| T1-2 | VFS router | `resolve_path("/draws/142/bindings/0/5")` | Returns `PathMatch(kind="leaf", handler="bindings", args={"eid": 142, "set": 0, "binding": 5})` |
+
+### `tests/unit/test_vfs_tree_cache.py` — tree population
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| T1-3 | Tree cache | `populate_draw_subtree` called for a draw with bindings | Creates child nodes at path `bindings/{set}/{binding}` for each descriptor |
+| T1-4 | Tree cache | Binding child nodes structure | Each binding child has `kind="leaf"` and `name` equal to the binding slot number as a string |
+
+### `tests/unit/test_vfs_commands.py` — extractor behavior
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| T1-5 | VFS extractor | `_EXTRACTORS["bindings"]` called with valid rows | Formats output as TSV with header line `EID\tSTAGE\tKIND\tSET\tSLOT\tNAME` followed by data rows |
+| T1-6 | VFS extractor | `_EXTRACTORS["bindings"]` called with empty rows list | Returns only the header line with no data rows and no error |
+
+---
+
+## DEV-2: `diff --trace` Phase Annotation (doc-only)
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| T2-1 | Documentation | Manual check of `设计/命令总览.md` for `diff --trace` entries | Phase annotation shows `5C` (changed from `4`) for all `diff --trace` command lines |
+
+No automated code tests required for this item.
+
+---
+
+## DEV-3: `--listen` "connect with:" Output Line
+
+### `tests/unit/test_split_core.py` — CLI output assertions
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| T3-1 | `--listen` output | `test_listen_outputs_connection_info` asserts "connect with:" line | Output contains the line `connect with: rdc open --connect 0.0.0.0:9999 --token secret123` |
+| T3-2 | `--listen` output | Existing host/port/token line assertions still pass | Output still contains separate host, port, and token lines (no regression) |

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-dev-install-enhancement/proposal.md

@@ -0,0 +1,136 @@
+# Dev Install Enhancement
+
+**Date**: 2026-02-28
+**Priority**: P3
+
+## Motivation
+
+`pixi run install` currently executes a single `uv tool install -e . --force`, placing the `rdc` binary at `~/.local/bin/rdc`. Shell tab-completion — one of the primary developer ergonomics features — is entirely absent from this flow. After installing, users must discover the `rdc completion` subcommand, know their shell's completion drop-in directory, redirect output manually, and reload their shell.
+
+The project's `pixi.toml` also omits `win-64` from its platform list. Windows developers cannot create a pixi environment at all, even though the Python code and `uv` itself are cross-platform. Adding `win-64` unblocks Windows contributors.
+
+Both gaps can be resolved in a single changeset: replace the one-liner `install` task with a Python script `scripts/dev_install.py` that orchestrates the full install sequence (binary + completions).
+
+## Scope
+
+| ID | Component | Kind | Priority |
+|----|-----------|------|----------|
+| DI-1 | `scripts/dev_install.py` (new) | Feature | P3 |
+| DI-2 | `pixi.toml` — `install` task + `win-64` platform | Config change | P3 |
+
+## Design
+
+### DI-1: scripts/dev_install.py
+
+The script runs via `uv run python scripts/dev_install.py`, giving it full access to the project's Python environment. It directly imports completion generation from `rdc.commands.completion` instead of shelling out to `rdc completion`, eliminating the PATH dependency.
+
+**Step 1 — binary install**
+
+```python
+subprocess.run(["uv", "tool", "install", "-e", ".", "--force"], check=True)
+```
+
+Exits with a non-zero code if `uv` fails, propagating the error naturally.
+
+**Step 2 — shell detection**
+
+Reuse and extend `rdc.commands.completion._detect_shell()` to handle Windows:
+
+```python
+def _detect_shell() -> str:
+    if sys.platform == "win32":
+        return "powershell"
+    name = Path(os.environ.get("SHELL", "bash")).name
+    return name if name in {"bash", "zsh", "fish"} else "bash"
+```
+
+This aligns with the existing `_detect_shell()` in `completion.py` which falls back to `"bash"` when `$SHELL` is unset or unrecognized.
+
+**Step 3 — completion generation (direct import)**
+
+```python
+from rdc.commands.completion import _generate
+
+completion_text = _generate(shell)
+```
+
+This reuses the existing tested code, including bash/zsh patches. No subprocess call to `rdc` is needed.
+
+**Step 4 — write to platform-standard location**
+
+| Shell | Target path |
+|-------|-------------|
+| bash | `~/.local/share/bash-completion/completions/rdc` |
+| zsh | `~/.zfunc/_rdc` |
+| fish | `~/.config/fish/completions/rdc.fish` |
+| powershell | instructions printed to stdout only |
+
+Parent directories are created via `Path.mkdir(parents=True, exist_ok=True)`.
+
+**Step 5 — summary**
+
+```text
+[ok] rdc installed via uv tool install
+[ok] zsh completion written to ~/.zfunc/_rdc
+     hint: add 'fpath=(~/.zfunc $fpath)' and 'autoload -Uz compinit && compinit' to ~/.zshrc
+```
+
+For zsh, the script always prints the fpath hint (harmless if already configured, avoids unreliable detection of zsh's `$fpath` array which is not exported as an environment variable).
+
+For PowerShell, the script prints a note directing users to `rdc completion --help`.
+
+**Full script skeleton**:
+
+```python
+#!/usr/bin/env python3
+"""Developer install: uv tool install + shell completion setup."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+_COMPLETION_PATHS: dict[str, Path] = {
+    "bash": Path.home() / ".local/share/bash-completion/completions/rdc",
+    "zsh": Path.home() / ".zfunc/_rdc",
+    "fish": Path.home() / ".config/fish/completions/rdc.fish",
+}
+
+def _detect_shell() -> str: ...
+def _install_binary() -> None: ...
+def _install_completion(shell: str) -> None: ...
+
+if __name__ == "__main__":
+    _install_binary()
+    shell = _detect_shell()
+    _install_completion(shell)
+```
+
+### DI-2: pixi.toml changes
+
+**Platform list** — add `win-64`:
+
+```toml
+platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"]
+```
+
+**Install task**:
+
+```toml
+install = "uv run python scripts/dev_install.py"
+```
+
+Note: `pixi.lock` will be regenerated to include `win-64` packages. The main dependencies (`python`, `uv`) are available on `win-64` via conda-forge. The `osx-*` target-specific deps (`cmake`, `autoconf`, etc.) do not affect `win-64`.
+
+## Risks
+
+**Completion generation failure**: If `_generate()` raises (e.g., due to a Click version incompatibility), the error is caught and reported as a warning. The binary install is already complete, so the user has a working `rdc` — just without completions. Non-fatal.
+
+**zsh `fpath` not configured**: Writing `~/.zfunc/_rdc` only takes effect if the user's `.zshrc` loads `~/.zfunc` via `fpath`. The script always prints the required snippet. Subsequent installs are silent about this.
+
+**File write permissions**: On some systems, completion directories may have restricted permissions. The script catches `PermissionError` and prints a warning with the manual command, then continues.
+
+**Windows pixi lock growth**: Adding `win-64` causes pixi to resolve packages for a new platform. The lock file grows. Existing CI on Linux/macOS is unaffected. `pixi.lock` changes must be verified on all platforms.

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-dev-install-enhancement/tasks.md

@@ -0,0 +1,13 @@
+# Tasks: Dev Install Enhancement
+
+## Implementation (Opus worktree agent)
+
+- [ ] `scripts/dev_install.py` — create Python script that runs `uv tool install`, detects shell, generates completion via direct import of `rdc.commands.completion._generate`, writes to platform-standard path for bash/zsh/fish (PowerShell prints instructions only), and prints summary
+- [ ] `pixi.toml` — change `install` task to `"uv run python scripts/dev_install.py"`; add `"win-64"` to platforms
+- [ ] `tests/unit/test_dev_install.py` — unit tests covering shell detection, completion file writing per shell, parent dir creation, uv install subprocess call, error handling (non-fatal completion failure, PermissionError), and end-to-end flow
+
+## Post-implementation
+
+- [ ] Merge worktree output back to feature branch
+- [ ] Run `pixi run lint && pixi run test` — zero failures allowed
+- [ ] New Opus subagent code review

rdc_cli-0.3.8/openspec/changes/archive/2026-02-28-dev-install-enhancement/test-plan.md

@@ -0,0 +1,56 @@
+# Test Plan: Dev Install Enhancement
+
+## Shell Detection
+
+### `tests/unit/test_dev_install.py`
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| SD-1 | `_detect_shell` | `SHELL=/bin/zsh` | Returns `"zsh"` |
+| SD-2 | `_detect_shell` | `SHELL=/usr/bin/bash` | Returns `"bash"` |
+| SD-3 | `_detect_shell` | `SHELL=/usr/bin/fish` | Returns `"fish"` |
+| SD-4 | `_detect_shell` | `SHELL` unset | Falls back to `"bash"` |
+| SD-5 | `_detect_shell` | `sys.platform == "win32"` | Returns `"powershell"` regardless of `SHELL` |
+| SD-6 | `_detect_shell` | `SHELL=/usr/local/bin/zsh` (non-standard prefix) | Returns `"zsh"` |
+| SD-7 | `_detect_shell` | `SHELL=/usr/bin/tcsh` (unsupported shell) | Falls back to `"bash"` |
+
+## Completion Installation
+
+### `tests/unit/test_dev_install.py`
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| CI-1 | `_install_completion` | bash → writes to `~/.local/share/bash-completion/completions/rdc` | File exists at correct path with expected content |
+| CI-2 | `_install_completion` | zsh → writes to `~/.zfunc/_rdc` | File exists at correct path with expected content |
+| CI-3 | `_install_completion` | fish → writes to `~/.config/fish/completions/rdc.fish` | File exists at correct path with expected content |
+| CI-4 | `_install_completion` | parent directory does not exist → created automatically | Parent dirs created; file written successfully |
+| CI-5 | `_install_completion` | powershell → no file written, prints instructions | No file created; stdout contains instruction text |
+| CI-6 | `_install_completion` | existing completion file is overwritten | File updated with new content |
+| CI-7 | `_install_completion` | zsh completion prints fpath hint | stdout contains fpath snippet |
+
+## UV Tool Install
+
+### `tests/unit/test_dev_install.py`
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| UV-1 | `_install_binary` | calls subprocess with `["uv", "tool", "install", "-e", ".", "--force"]` | `subprocess.run` invoked with exact args and `check=True` |
+| UV-2 | `_install_binary` | `CalledProcessError` → propagates | Exception raised; subsequent steps not executed |
+
+## Error Handling
+
+### `tests/unit/test_dev_install.py`
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| EH-1 | `_install_completion` | `_generate()` raises → non-fatal | Warning printed; script continues; no file written |
+| EH-2 | `_install_completion` | file write `PermissionError` → non-fatal | Warning printed; script continues |
+
+## End-to-End Flow
+
+### `tests/unit/test_dev_install.py`
+
+| ID | Component | Description | Expected Result |
+|----|-----------|-------------|-----------------|
+| E2E-1 | `main` | full flow with mocked subprocess and `_generate` | Binary install runs first, then shell detected, completion written, summary printed |
+| E2E-2 | `main` | binary install fails → completion install skipped | Only error from uv install shown; no completion attempt |