From ee6ebc489fcd87942232439f8eb127705bba0608 Mon Sep 17 00:00:00 2001
From: John S Azariah <john.azariah@gmail.com>
Date: Fri, 17 Jul 2026 09:46:44 +1000
Subject: [PATCH] docs: add PATH fix instructions to installation
 troubleshooting

Expand the `squad: command not found` troubleshooting section with
actionable, platform-specific steps for getting the npm global bin
directory onto PATH:

- Confirm the install, locate the global prefix with `npm prefix -g`,
  update PATH, and verify.
- macOS/Linux: add the export line to a shell profile, with separate
  Bash (`source ~/.bashrc`) and Zsh (`source ~/.zshrc`) reload commands.
- Windows (PowerShell): append the npm prefix to the User-scoped PATH,
  reading only the User scope and deduping so repeated runs don't
  duplicate entries or copy Machine-level paths into User PATH.
- Add an nvm/fnm caveat noting `npm prefix -g` points to a
  version-specific directory.

Closes #1458

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/get-started/installation.md  | 70 +++++++++++++++++--
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md
index 3f393ac02..d6496bb06 100644
--- a/docs/src/content/docs/get-started/installation.md
+++ b/docs/src/content/docs/get-started/installation.md
@@ -160,15 +160,75 @@ export default defineConfig({
 
 ### `squad: command not found`
 
-Your npm global bin isn't in your PATH. Fix:
+Your npm global bin directory isn't in your PATH. Follow these steps:
+
+**1. Confirm the package is installed:**
 
 ```bash
-# Check if installed
 npm list -g @bradygaster/squad-cli
+```
+
+If it's not listed, re-run `npm install -g @bradygaster/squad-cli`.
+
+**2. Find your npm global bin directory:**
+
+```bash
+npm prefix -g
+```
+
+This prints the directory where npm installs global packages (e.g. `/usr/local`, `~/.npm-global`, or `C:\Users\<you>\AppData\Roaming\npm`). The `squad` binary lives in the `bin/` subdirectory on macOS/Linux, or directly in that directory on Windows.
+
+**3. Add it to your PATH:**
+
+<details>
+<summary><strong>macOS / Linux</strong></summary>
+
+Add this line to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.profile`):
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+Then reload your shell using the command for the shell you use:
+
+```bash
+# Bash
+source ~/.bashrc
+```
+
+```bash
+# Zsh
+source ~/.zshrc
+```
+
+</details>
+
+<details>
+<summary><strong>Windows (PowerShell)</strong></summary>
+
+Run this in PowerShell to permanently add the npm global directory to your user PATH. It reads only the **User**-scoped PATH (not the merged process PATH) and skips the append if the entry is already present, so repeated runs won't duplicate entries or copy Machine-level paths into your User PATH:
 
-# If installed but not found, check PATH:
-echo $PATH | grep npm          # macOS/Linux
-echo %PATH% | findstr npm      # Windows
+```powershell
+$npmPrefix = (npm prefix -g).Trim()
+$userPath  = [Environment]::GetEnvironmentVariable("PATH", "User")
+if (-not (($userPath -split ';') -contains $npmPrefix)) {
+    $newUserPath = if ([string]::IsNullOrEmpty($userPath)) { $npmPrefix } else { $userPath.TrimEnd(';') + ";" + $npmPrefix }
+    [Environment]::SetEnvironmentVariable("PATH", $newUserPath, "User")
+}
+```
+
+Then **restart your terminal** for the change to take effect.
+
+</details>
+
+:::note
+If you use a Node version manager like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm), `npm prefix -g` points to a version-specific directory that changes when you switch Node versions. Rather than hardcoding it in your PATH, let the version manager manage your PATH (it adds the active version's bin directory automatically), and make sure its shell initialization runs in your profile.
+:::
+
+**4. Verify it works:**
+
+```bash
+squad --version
 ```
 
 ### `Cannot find .squad/ directory`