docs: add PATH fix instructions to installation troubleshooting

[johnazariah]

The troubleshooting section for squad: command not found previously told users to check their PATH but didn't explain how to actually fix it when the npm global prefix directory isn't in PATH.

This adds platform-specific instructions for:

• Finding the npm global bin directory with npm prefix -g
• Adding it to PATH on macOS/Linux (shell profile)
• Adding it to PATH on Windows (PowerShell environment variable)

Fixes #1458

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit ee6ebc4

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
❌	Branch up to date	dev is 17 commit(s) ahead — rebase recommended
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (2 outdated skipped)
❌	CI passing	4 check(s) still running

Files Changed (1 file, +65 −5)

File	+/−
docs/src/content/docs/get-started/installation.md	+65 −5

Total: +65 −5

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟢 Impact Analysis — PR #1459

Risk tier: 🟢 LOW

📊 Summary

Metric	Count
Files changed	1
Files added	0
Files modified	1
Files deleted	0
Modules touched	1

🎯 Risk Factors

• 1 files changed (≤5 → LOW)
• 1 module(s) touched (≤1 → LOW)

📦 Modules Affected

docs (1 file)

• docs/src/content/docs/get-started/installation.md

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

Pull request overview

Updates the installation troubleshooting docs to give actionable, platform-specific steps for resolving squad: command not found when the npm global install location isn’t on PATH, addressing the gap described in issue #1458.

Changes:

• Adds a step-by-step troubleshooting flow (confirm install → find global prefix → update PATH → verify).
• Documents how to locate the global prefix with npm prefix -g and where the squad binary is expected to live on macOS/Linux vs Windows.
• Provides platform-specific PATH update instructions using shell profiles (macOS/Linux) and PowerShell (Windows).

[tamirdresher]

Thanks for the improved docs structure — the step-by-step approach is much better than the old 'check your PATH' stub.

One blocking issue with the Windows PowerShell command:

\\powershell

Current (buggy):

[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";" + (npm prefix -g), "User")
\\

\\C:\Program Files\PowerShell\7;C:\Users\tamirdresher\AppData\Local\Programs\GitHub Copilot;C:\Users\tamirdresher\AppData\Local\github-copilot-git-2.53.0-3\cmd;C:\Users\tamirdresher\AppData\Local\github-copilot-git-2.53.0-3\mingw64\bin;C:\Users\tamirdresher\AppData\Local\github-copilot-git-2.53.0-3\mingw64\usr\bin;C:\Users\tamirdresher\AppData\Local\copilot-desktop-gh-2.96.0;C:\Program Files\Microsoft\jdk-21.0.10.7-hotspot\bin;C:\Program Files\Microsoft\jdk-17.0.18.8-hotspot\bin;C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\wbin;C:.Tools\agency\CurrentVersion;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0;C:\Windows\System32\OpenSSH;C:\Program Files\Azure Dev CLI;C:\Program Files\GitHub CLI;C:\Program Files\Microsoft SQL Server\170\Tools\Binn;C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn;C:\Program Files\Microsoft VS Code\bin;C:.tools\dotnet;C:.tools.npm-global;C:\ProgramData\chocolatey\bin;C:\Program Files (x86)\Microsoft SQL Server\160\DTS\Binn;C:\Users\vmadmin\AppData\Local\Microsoft\WindowsApps;c:\nvm;C:\Program Files\nodejs;C:\ES.DevProd\SpringBoard\SBCli\SpringBoardCli;C:\Program Files\GVFS;C:\ES.DevProd\VMSetupScripts;C:\ProgramData\global-npm;C:\Windows\system32\config\systemprofile\AppData\Local\Microsoft\WindowsApps;C:\Program Files\Microsoft Dev Box Agent\Scripts;C:\Program Files\dotnet;C:\Program Files\Go\bin;C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit;C:\Program Files\Git\cmd;C:\Program Files\PowerShell\7;C:\Users\tamirdresher.cargo\bin;C:\Ruby32\bin;C:\Ruby33\bin;C:\Ruby330\bin;C:\Ruby330-x64\bin;C:\Users\tamirdresher\AppData\Local\Programs\Python\Python312\Scripts;C:\Users\tamirdresher\AppData\Local\Programs\Python\Python312;C:\Users\tamirdresher\AppData\Local\Programs\Python\Launcher;C:\Users\tamirdresher\AppData\Local\Microsoft\WindowsApps;C:\Users\tamirdresher\AppData\Local\Microsoft\WinGet\Links;C:\Users\tamirdresher.dotnet\tools;C:\Users\tamirdresher.azure-kubectl;C:\Users\tamirdresher.azure-kubelogin;C:\Users\tamirdresher\go\bin;C:\Users\tamirdresher\AppData\Local\Programs\AzureAuth\0.9.6\\ contains the combined Machine + User PATH entries (inherited at shell startup). Writing that back to the User registry key permanently duplicates all Machine-level paths into User PATH, bloating and corrupting it.

Fix:
\\powershell
[Environment]::SetEnvironmentVariable("PATH", [Environment]::GetEnvironmentVariable("PATH","User") + ";" + (npm prefix -g), "User")
\\

This reads only the existing User-scoped PATH before appending.

Minor suggestion: a brief caveat for nvm/fnm users (their npm prefix points to a shim directory) would prevent follow-up support issues.

[tamirdresher]

Two blocking issues in the "squad: command not found" section — please address both.

1. Windows PowerShell snippet corrupts User PATH

Under Windows (PowerShell) the snippet reads $env:PATH and writes it back to the User scope:

[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";" + (npm prefix -g), "User")

$env:PATH is the process PATH (Machine PATH + User PATH merged at shell startup). Writing it back to the User scope permanently duplicates every Machine entry into the User PATH. Repeat runs also duplicate npm prefix -g. Over time this bloats User PATH toward the 8191-char registry limit and can corrupt it.

Please read only the User scope and dedup before appending:

$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")
}

2. Shell-reload line is labelled for two shells but only runs one

Under macOS / Linux the reload step says:

source ~/.bashrc   # or ~/.zshrc

That literally sources ~/.bashrc even when the user's shell is zsh — the # or ~/.zshrc is only a comment. Please give two genuinely separate commands so users pick the right one:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

Once these two are fixed I'll re-review.

[johnazariah]

Thanks @tamirdresher — addressed both blocking items plus your nvm/fnm suggestion in 8255ddac:

1. Windows PowerShell PATH corruption — the snippet now reads only the User-scoped PATH via [Environment]::GetEnvironmentVariable("PATH", "User") and skips the append when the npm prefix is already present, so it no longer duplicates Machine-level entries or re-adds the prefix on repeat runs:

$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")
}

2. Shell-reload step — split into two genuinely separate Bash and Zsh commands instead of sourcing ~/.bashrc with a # or ~/.zshrc comment.

Bonus — added a :::note caveat for nvm/fnm users, since npm prefix -g there points to a version-specific shim directory.

Docs build + build-output tests pass locally. Ready for re-review.

[tamirdresher]

Approving. Head verified at ee6ebc489fcd87942232439f8eb127705bba0608, checks are green, and the previously requested blockers are all addressed: Windows PowerShell now updates only the User-scoped PATH ([Environment]::GetEnvironmentVariable("PATH","User")), duplicates are prevented (-notcontains $npmPrefix), whitespace is trimmed on the read and the trailing ; is stripped, bash and zsh have separate code blocks, and there is now explicit nvm/fnm guidance. This new APPROVE explicitly supersedes my earlier CHANGES_REQUESTED from 2026-07-13. Not merging — leaving that to maintainers.