Lex Christopherson d20d5e8fb5 docs: add Mintlify documentation site and move internal docs

Add a proper public-facing documentation site using Mintlify with 19 MDX
pages covering getting started, auto mode, commands, configuration, and
all user-facing features. Move internal/SDK documentation (Pi SDK, TUI,
context & hooks, research notes, ADRs) to docs-internal/ since they
should not be part of the public documentation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-25 09:54:41 -06:00

1.9 KiB

Raw Blame History

Pinning Node.js LTS on macOS with Homebrew

If you installed Node.js via Homebrew (brew install node), you're tracking the latest current release — which can include odd-numbered development versions (e.g. 23.x, 25.x). These aren't LTS and may have breaking changes or instability.

GSD requires Node.js v22 or later and works best on an LTS (even-numbered) release. This guide shows how to pin Node 24 LTS using Homebrew.

Check your current version

node --version

If this shows an odd number (e.g. v23.x, v25.x), you're on a development release.

Install Node 24 LTS

Homebrew provides versioned formulas for LTS releases:

# Unlink the current (possibly non-LTS) version
brew unlink node

# Install Node 24 LTS
brew install node@24

# Link it as the default
brew link --overwrite node@24

Verify:

node --version
# Should show v24.x.x

Why pin to LTS?

Stability — LTS releases receive bug fixes and security patches for 30 months
Compatibility — npm packages (including GSD) test against LTS versions
No surprises — brew upgrade won't jump you to an unstable development release

Prevent accidental upgrades

By default, brew upgrade will upgrade all packages, which could move you off the pinned version. Pin the formula:

brew pin node@24

To unpin later:

brew unpin node@24

Switching between versions

If you need multiple Node versions (e.g. 22 and 24), consider using a version manager instead:

nvm — nvm install 24 && nvm use 24
fnm — fnm install 24 && fnm use 24 (faster, Rust-based)
mise — mise use node@24 (polyglot version manager)

These let you set per-project Node versions via .node-version or .nvmrc files.

Verify GSD works

After pinning:

node --version   # v24.x.x
npm install -g gsd-pi
gsd --version

1.9 KiB Raw Blame History