docs: fix stale references across documentation (#1543)

* docs: update README for v2.37 — changelog, extensions, stale refs

- Update "What's New" section from v2.33 to v2.37
- Update extensions table: add Async Jobs and GitHub, remove LSP (Pi SDK core)
- Fix extension count in architecture section (12 → 18)
- Remove stale v2.17 version tags from Token Optimization section

* docs: fix stale references across documentation

- commands.md: update version example from v2.28 to v2.37
- troubleshooting.md: fix Node.js requirement from ≥20.6.0 to ≥22.0.0
- skills.md: fix project-local skills path from .pi/ to .gsd/
- CONTRIBUTING.md: fix scope area paths to include packages/ prefix,
  remove incorrect PR #1232 supply chain attack reference
- vscode-extension: fix Node.js requirement, remove hardcoded RPC
  command count (changes over time)

* docs: add troubleshooting for command not found after install

Addresses #1542 — npm global bin directory not in PATH is a common
issue on macOS, especially with Homebrew Node, version managers, or
oh-my-zsh git aliases.

- Add "command not found: gsd" section to troubleshooting.md
- Add callout to getting-started.md install section

CONTRIBUTING.md

@@ -87,10 +87,10 @@ The codebase is organized into these areas. All are open to contributions:
 
 | Area | Path | Notes |
 |------|------|-------|
-| Terminal UI | `pi-tui` | Components, themes, rendering |
-| AI/LLM layer | `pi-ai` | Provider integrations, model handling |
-| Agent core | `pi-agent-core` | Agent orchestration — RFC required for changes |
-| Coding agent | `pi-coding-agent` | The main coding agent |
+| Terminal UI | `packages/pi-tui` | Components, themes, rendering |
+| AI/LLM layer | `packages/pi-ai` | Provider integrations, model handling |
+| Agent core | `packages/pi-agent-core` | Agent orchestration — RFC required for changes |
+| Coding agent | `packages/pi-coding-agent` | The main coding agent |
 | GSD extension | `src/resources/extensions/gsd/` | GSD workflow — RFC required for auto-mode |
 | Native bindings | `native/` | Platform-specific native code |
 | CI/Build | `.github/`, `scripts/` | Workflows, build scripts |
@@ -123,7 +123,7 @@ CI must pass before your PR will be reviewed. Run these locally to save time.
 
 ## Security
 
-If you find a security vulnerability, **do not open a public issue.** Email the maintainers directly or use GitHub's private vulnerability reporting. See the supply chain attack on GSD-1 (PR #1232) for why this matters.
+If you find a security vulnerability, **do not open a public issue.** Email the maintainers directly or use GitHub's private vulnerability reporting.
 
 ## Questions?
 

docs/commands.md

@@ -214,9 +214,9 @@ The server registers all tools from the agent session and maps MCP `tools/list`
 
 ```bash
 /gsd update
-# Current version: v2.28.0
+# Current version: v2.36.0
 # Checking npm registry...
-# Updated to v2.29.0. Restart GSD to use the new version.
+# Updated to v2.37.0. Restart GSD to use the new version.
 ```
 
 If already up to date, it reports so and takes no action.

docs/getting-started.md

@@ -8,6 +8,8 @@ npm install -g gsd-pi
 
 Requires Node.js ≥ 22.0.0 (24 LTS recommended) and Git.
 
+> **`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [Troubleshooting](./troubleshooting.md#command-not-found-gsd-after-install) for details.
+
 GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`.
 
 ### Set up API keys

docs/skills.md

@@ -82,7 +82,7 @@ The `SKILL.md` file contains instructions the LLM follows when the skill is acti
 Place skills in your project for project-specific guidance:
 
 ```
-.pi/agent/skills/my-project-skill/
+.gsd/agent/skills/my-project-skill/
   SKILL.md
 ```
 

docs/troubleshooting.md

@@ -41,12 +41,37 @@ It checks:
 
 **Fix:** This was fixed in v2.14+. If you're on an older version, update. The dispatch prompt now includes explicit working directory instructions.
 
+### `command not found: gsd` after install
+
+**Symptoms:** `npm install -g gsd-pi` succeeds but `gsd` isn't found.
+
+**Cause:** npm's global bin directory isn't in your shell's `$PATH`.
+
+**Fix:**
+
+```bash
+# Find where npm installed the binary
+npm prefix -g
+# Output: /opt/homebrew (Apple Silicon) or /usr/local (Intel Mac)
+
+# Add the bin directory to your PATH if missing
+echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Workaround:** Run `npx gsd-pi` or `$(npm prefix -g)/bin/gsd` directly.
+
+**Common causes:**
+- **Homebrew Node** — `/opt/homebrew/bin` should be in PATH but sometimes isn't if Homebrew init is missing from your shell profile
+- **Version manager (nvm, fnm, mise)** — global bin is version-specific; ensure your version manager initializes in your shell config
+- **oh-my-zsh** — the `gitfast` plugin aliases `gsd` to `git svn dcommit`. Check with `alias gsd` and unalias if needed
+
 ### `npm install -g gsd-pi` fails
 
 **Common causes:**
 - Missing workspace packages — fixed in v2.10.4+
 - `postinstall` hangs on Linux (Playwright `--with-deps` triggering sudo) — fixed in v2.3.6+
-- Node.js version too old — requires ≥ 20.6.0
+- Node.js version too old — requires ≥ 22.0.0
 
 ### Provider errors during auto mode
 

vscode-extension/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 Initial release.
 
-- Full RPC client — spawns `gsd --mode rpc`, JSON line framing, all 25 RPC commands
+- Full RPC client — spawns `gsd --mode rpc`, JSON line framing, all RPC commands
 - Sidebar dashboard — connection status, model info, thinking level, token usage, cost, quick actions
 - Chat participant — `@gsd` in VS Code Chat with streaming responses
 - 15 commands with keyboard shortcuts

vscode-extension/README.md

@@ -10,7 +10,7 @@ GSD must be installed before activating this extension:
 npm install -g gsd-pi
 ```
 
-Node.js ≥ 20.6.0 and Git are required.
+Node.js ≥ 22.0.0 and Git are required.
 
 ## Features
 
@@ -82,7 +82,7 @@ All commands are accessible via `Ctrl+Shift+P`:
 
 ## How It Works
 
-The extension spawns `gsd --mode rpc` in the background and communicates over JSON-RPC via stdin/stdout. All 25 RPC commands are supported, including streaming events for real-time sidebar updates.
+The extension spawns `gsd --mode rpc` in the background and communicates over JSON-RPC via stdin/stdout. All RPC commands are supported, including streaming events for real-time sidebar updates.
 
 ## Links