From 111537f4600757626290780f6b78cbb9ac8d774e Mon Sep 17 00:00:00 2001 From: Jeremy McSpadden Date: Thu, 19 Mar 2026 23:14:03 -0500 Subject: [PATCH] docs: fix stale references across documentation (#1543) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 | 10 +++++----- docs/commands.md | 4 ++-- docs/getting-started.md | 2 ++ docs/skills.md | 2 +- docs/troubleshooting.md | 27 ++++++++++++++++++++++++++- vscode-extension/CHANGELOG.md | 2 +- vscode-extension/README.md | 4 ++-- 7 files changed, 39 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59eaefba8..acf637fc2 100644 --- a/CONTRIBUTING.md +++ b/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? diff --git a/docs/commands.md b/docs/commands.md index 7a1932ac3..f607b6795 100644 --- a/docs/commands.md +++ b/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. diff --git a/docs/getting-started.md b/docs/getting-started.md index a52480c2b..85180167b 100644 --- a/docs/getting-started.md +++ b/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 diff --git a/docs/skills.md b/docs/skills.md index 5a9cab0dd..71f039546 100644 --- a/docs/skills.md +++ b/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 ``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 382cc25e2..796402ec5 100644 --- a/docs/troubleshooting.md +++ b/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 diff --git a/vscode-extension/CHANGELOG.md b/vscode-extension/CHANGELOG.md index 32d2e8fd4..836dad293 100644 --- a/vscode-extension/CHANGELOG.md +++ b/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 diff --git a/vscode-extension/README.md b/vscode-extension/README.md index 6e0a0a824..f0f249c43 100644 --- a/vscode-extension/README.md +++ b/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