docs: add Windows PATH troubleshooting for CLI

[siddhisanap]

Description

Adds a Windows troubleshooting section for users who successfully install Headroom but encounter:

'headroom' is not recognized as an internal or external command

The documentation explains how to verify that headroom.exe was installed successfully and how to resolve the issue by ensuring the Python Scripts directory is available on the system PATH.

Closes #1470

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

---

Changes Made

• Added Windows CLI troubleshooting documentation.
• Documented how to verify that headroom.exe is installed.
• Added instructions for locating the Python Scripts directory.
• Added guidance for resolving PATH-related issues after installation.

---

Testing

Test Output

Verified installation using:

python -m pip show headroom-ai

Output:

Name: headroom-ai
Version: 0.27.0
Editable project location: C:\Users\isidd\headroom

Verified CLI executable:

dir C:\Users\isidd\AppData\Local\Programs\Python\Python312\Scripts\headroom*

Output:

headroom.exe

Verified the CLI:

headroom --help

Output (truncated):

Headroom - The Context Optimization Layer for LLM Applications.

Manage memories, run the optimization proxy, and analyze metrics.

---

Real Behavior Proof

Environment

• OS: Windows 11
• Python: 3.12.4
• Headroom: 0.27.0
• Installation method:

pip install -e ".[all]"

Exact command / steps

1. Cloned the repository.
2. Installed Headroom using:

pip install -e ".[all]"

3. Verified installation:

python -m pip show headroom-ai

4. Verified that headroom.exe exists:

dir C:\Users\isidd\AppData\Local\Programs\Python\Python312\Scripts\headroom*

5. Initially received:

'headroom' is not recognized as an internal or external command

6. Added the Python Scripts directory to the Windows PATH.

7. Restarted PowerShell.

8. Verified successfully:

headroom --help

Observed Result

The installation completed successfully, but the CLI was not initially available because the Python Scripts directory was missing from the Windows PATH.

After adding the Scripts directory to PATH and restarting the terminal, the headroom command worked correctly.

Not Tested

• Linux
• macOS
• Non-editable (pip install headroom-ai) installation
• npm installation

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Missing required section Review Readiness.
• Check at least one verification item in Testing.
• Fill in Real Behavior Proof → Environment.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.
• Check I have performed a self-review before requesting human review.
• Check This PR is ready for human review or convert the PR back to draft.

Please update the PR body, or move the PR back to draft while it is still in progress.

[JerrettDavis]

Thanks for adding this; the content addresses the Windows PATH failure mode clearly. One placement issue before this is ready: the new section is inserted under \Provider-Specific Issues, but this is an installation/PATH problem rather than an OpenAI/Claude/provider problem. Please move \Windows: headroom command not found\ into the existing \Installation Issues\ section so users scanning the troubleshooting page can find it in the right category. A blank line before the next heading would also keep the MDX formatting tidy.