diff --git a/README.md b/README.md
index 9063c68cb..869acfadb 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ One command. Walk away. Come back to a built project with clean git history.
 
 <pre><code>npm install -g gsd-pi</code></pre>
 
+> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
+
 </div>
 
 ---
diff --git a/docs/node-lts-macos.md b/docs/node-lts-macos.md
new file mode 100644
index 000000000..67582aec1
--- /dev/null
+++ b/docs/node-lts-macos.md
@@ -0,0 +1,75 @@
+# 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
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+brew pin node@24
+```
+
+To unpin later:
+
+```bash
+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](https://github.com/nvm-sh/nvm)** — `nvm install 24 && nvm use 24`
+- **[fnm](https://github.com/Schniz/fnm)** — `fnm install 24 && fnm use 24` (faster, Rust-based)
+- **[mise](https://mise.jdx.dev/)** — `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:
+
+```bash
+node --version   # v24.x.x
+npm install -g gsd-pi
+gsd --version
+```