From 47ca8eac02e2d2cddb2e8b1ee4cd2ca4b521a014 Mon Sep 17 00:00:00 2001
From: Siddhi <isiddhisanap@gmail.com>
Date: Wed, 1 Jul 2026 22:32:27 +0530
Subject: [PATCH] docs: add Windows PATH troubleshooting for CLI

---
 docs/content/docs/troubleshooting.mdx | 42 +++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdx
index 537d86973..198168b73 100644
--- a/docs/content/docs/troubleshooting.mdx
+++ b/docs/content/docs/troubleshooting.mdx
@@ -322,7 +322,49 @@ pip install "headroom-ai[all]"
 ```
 
 ## Provider-Specific Issues
+### Windows: `headroom` command not found
 
+If Headroom installs successfully but running:
+
+```bash
+headroom --help
+```
+
+or
+
+```bash
+headroom wrap claude
+```
+
+returns:
+
+```text
+'headroom' is not recognized as an internal or external command
+```
+
+the CLI may have been installed successfully but Python's **Scripts** directory is not available on your `PATH`.
+
+You can verify that the executable exists with:
+
+```powershell
+python -m pip show -f headroom-ai
+```
+
+If `headroom.exe` appears in the output, add your Python Scripts directory to your `PATH`.
+
+For example:
+
+```text
+C:\Users\<username>\AppData\Local\Programs\Python\Python312\Scripts
+```
+
+After updating your `PATH`, restart your terminal and run:
+
+```bash
+headroom --help
+```
+
+to confirm the CLI is available.
 ### OpenAI: Invalid API key
 
 ```python