Add debugging documentation to README

Co-authored-by: anthonykim1 <62267334+anthonykim1@users.noreply.github.com>

Author: Copilot

README.md

@@ -31,6 +31,85 @@ This project will be consumed by the [Python extension](https://marketplace.visu
 
 Our approach prioritizes performance and efficiency by leveraging Rust. We minimize I/O operations by collecting all necessary environment information at once, which reduces repeated I/O and the need to spawn additional processes, significantly enhancing overall performance.
 
+## Debugging Python Environment Issues
+
+If you're experiencing issues with Python interpreter detection in VS Code (such as the Run button not working, Python not being recognized, or interpreters not persisting), you can use PET to diagnose the problem.
+
+### Running PET for Debugging
+
+PET can be run directly from the command line to discover all Python environments on your system. This helps identify whether the issue is with environment discovery or elsewhere.
+
+#### Quick Start
+
+1. **Download or build PET**:
+   - Download pre-built binaries from the [releases page](https://github.com/microsoft/python-environment-tools/releases)
+   - Or build from source: `cargo build --release`
+
+2. **Run PET to find all environments**:
+   ```bash
+   # On Linux/macOS
+   ./pet find --list --verbose
+   
+   # On Windows
+   pet.exe find --list --verbose
+   ```
+
+3. **Share the output** with maintainers when reporting issues
+
+#### Common Commands
+
+- **Find all Python environments** (default behavior):
+  ```bash
+  pet
+  ```
+
+- **Find all environments with detailed logging**:
+  ```bash
+  pet find --list --verbose
+  ```
+
+- **Search only in workspace/project directories**:
+  ```bash
+  pet find --list --workspace
+  ```
+
+- **Search for a specific environment type** (e.g., Conda):
+  ```bash
+  pet find --list --kind conda
+  ```
+
+- **Resolve a specific Python executable**:
+  ```bash
+  pet resolve /path/to/python
+  ```
+
+#### Understanding the Output
+
+The output includes:
+
+- **Discovered Environments**: List of Python installations found, including:
+  - Type (Conda, Venv, System Python, etc.)
+  - Executable path
+  - Version
+  - Prefix (sys.prefix)
+  - Architecture (x64/x86)
+  - Symlinks
+
+- **Timing Information**: How long each locator took to search
+
+- **Summary Statistics**: Count of environments by type
+
+#### Reporting Issues
+
+When reporting Python detection issues, please include:
+
+1. The full output from running `pet find --list --verbose`
+2. Your operating system and version
+3. VS Code and Python extension versions
+4. Description of the issue
+
+This information helps maintainers diagnose whether the problem is with PET's discovery logic or elsewhere in the VS Code Python extension.
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a