joesobo · joesobo · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git a/.changeset/remove-node-upper-bound.md b/.changeset/remove-node-upper-bound.md
@@ -0,0 +1,14 @@
+---
+"@codegraphy-dev/core": patch
+"@codegraphy-dev/mcp": patch
+"@codegraphy-dev/plugin-api": patch
+"@codegraphy-dev/plugin-csharp": patch
+"@codegraphy-dev/plugin-godot": patch
+"@codegraphy-dev/plugin-markdown": patch
+"@codegraphy-dev/plugin-python": patch
+"@codegraphy-dev/plugin-svelte": patch
+"@codegraphy-dev/plugin-typescript": patch
+"@codegraphy-dev/plugin-vue": patch
+---
+
+Allow current and future Node releases while keeping Node 20 as the minimum supported runtime.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,7 +6,7 @@ Thanks for your interest in contributing to CodeGraphy!
 
 ### Prerequisites
 
-- Node.js 22.22.0 LTS
+- Node.js 20 or newer
 - pnpm 10+
 - VS Code 1.85+
 
@@ -107,7 +107,7 @@ pnpm --filter @codegraphy-dev/extension exec playwright install chromium  # Brow
 pnpm --filter @codegraphy-dev/extension exec vitest run --config vitest.config.ts tests/path/to/file.test.ts
 ```
 
-The repo pins Node in [`.nvmrc`](./.nvmrc) and [`.node-version`](./.node-version). Use that exact runtime before running release or quality-tool commands.
+The published packages support Node 20 and newer. The repo pins Node in [`.nvmrc`](./.nvmrc) and [`.node-version`](./.node-version). Use that exact runtime before running release or quality-tool commands.
 
 ## Reporting issues
 

diff --git a/apps/web/package.json b/apps/web/package.json
@@ -13,7 +13,7 @@
     }
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

diff --git a/docs/MCP.md b/docs/MCP.md
@@ -18,7 +18,7 @@ Every `codegraphy ...` terminal subcommand lives in `@codegraphy-dev/core`. `@co
 
 ## Prerequisites
 
-- Node `22.22.0` or newer within the supported Node 22 range.
+- Node 20 or newer.
 - Codex, Claude, Cursor, or another MCP-capable agent.
 
 ## Quick Start

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,7 @@
 # Docs
 
 Use the root [README](../README.md) for the release overview, marketplace links, package map, and the V2 to V4 migration story.
-The repo-wide local runtime is Node `22.22.0` LTS from [`.nvmrc`](../.nvmrc).
+Published packages support Node 20 and newer. The repo-wide local runtime is Node `22.22.0` LTS from [`.nvmrc`](../.nvmrc).
 
 The rest of the docs are split by purpose:
 

diff --git a/docs/RELEASING.md b/docs/RELEASING.md
@@ -92,7 +92,7 @@ vsce verify-pat codegraphy
 3. Confirm `vsce ls-publishers` shows `codegraphy`.
 4. Confirm `vsce verify-pat codegraphy` succeeds.
 5. Run `pnpm install`.
-   - Use Node `22.22.0` LTS from [`.nvmrc`](../.nvmrc) / [`.node-version`](../.node-version).
+   - Use the repo-pinned Node runtime from [`.nvmrc`](../.nvmrc) / [`.node-version`](../.node-version).
 6. Add changesets only for unreleased user-facing workspace packages. Archive shipped changesets under [`docs/archive/changesets/`](./archive/changesets/).
 7. Run `pnpm run version-packages`.
 8. If the VS Code Marketplace extension changed, verify `packages/extension/package.json` and [`packages/extension/CHANGELOG.md`](../packages/extension/CHANGELOG.md) have matching top entries.

diff --git a/docs/agents/codegraphy-loop.md b/docs/agents/codegraphy-loop.md
@@ -40,11 +40,12 @@ codegraphy-mini:/Users/poleski/Desktop/Projects/CodeGraphyV4
 ```
 
 The heavy-check thread must verify its host, branch, worktree, and Node runtime
-before running commands. Prefer Node 22 there because CodeGraphy requires Node
-`<23`.
+before running commands. Prefer the repo-pinned Node runtime there so remote
+checks match local and CI behavior.
 
-When checking or preparing the remote host over SSH, use the Homebrew Node 22
-path explicitly so `pnpm` and Codex resolve the same runtime:
+When checking or preparing the remote host over SSH, use the Homebrew path for
+the repo-pinned Node runtime explicitly so `pnpm` and Codex resolve the same
+runtime:
 
 ```bash
 ssh codegraphy-mini 'export PATH="/opt/homebrew/Cellar/node@22/22.22.2_2/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"; cd /Users/poleski/Desktop/Projects/CodeGraphyV4; hostname; node --version; pnpm --version; git status --short --branch'

diff --git a/docs/agents/loops/orchestrator.md b/docs/agents/loops/orchestrator.md
@@ -106,7 +106,7 @@ ssh codegraphy-mini 'export PATH="/opt/homebrew/Cellar/node@22/22.22.2_2/bin:/op
 
 The remote work must:
 
-- use the Node 22 PATH above
+- use the repo-pinned Node PATH above
 - fetch the PR branch before running commands
 - run from an isolated remote worktree for that branch
 - record the remote host, worktree, command, and result in the handoff log

diff --git a/docs/handoff/270-node-engine-upper-bound.md b/docs/handoff/270-node-engine-upper-bound.md
@@ -0,0 +1,115 @@
+# Node Engine Upper Bound Investigation
+
+Trello: https://trello.com/c/qiauqiPA
+PR: https://github.com/joesobo/CodeGraphyV4/pull/270
+
+## Current Decision
+
+Remove the Node `<23` engine upper bound from package manifests and keep the
+published Node minimum at `>=20`.
+
+The original Node 26 install failure is fixed in this PR by patching the
+`tree-sitter@0.25.0` native binding build to use C++20.
+The patch is documented in `patches/README.md` and should be removed once
+`tree-sitter` publishes the upstream Node 23+ build fix:
+https://github.com/tree-sitter/node-tree-sitter/issues/276
+Follow-up Trello card:
+https://trello.com/c/Myxab48H
+
+CI should stay pinned to Node `22.22.0`. This card did not find a reason to
+redesign the CI runtime or matrix.
+
+## Evidence
+
+Updated `engines.node` declarations are consistently `>=20` in:
+
+- `package.json`
+- `apps/web/package.json`
+- `packages/core/package.json`
+- `packages/extension/package.json`
+- `packages/mcp/package.json`
+- `packages/plugin-api/package.json`
+- `packages/plugin-csharp/package.json`
+- `packages/plugin-godot/package.json`
+- `packages/plugin-markdown/package.json`
+- `packages/plugin-python/package.json`
+- `packages/plugin-svelte/package.json`
+- `packages/plugin-typescript/package.json`
+- `packages/plugin-vue/package.json`
+
+Local sanity checks on the laptop used Node `v22.22.0` and pnpm `10.32.0`:
+
+- `pnpm install --frozen-lockfile` passed.
+- The pre-commit hook ran `pnpm run typecheck` and passed.
+- The pre-commit hook ran `pnpm run typecheck` again after adding this
+  investigation note and passed.
+
+Mac mini verification used an isolated worktree at
+`/Users/poleski/.codex/worktrees/270-node-engine-upper-bound/CodeGraphyV4`.
+The mini had Node `v26.0.0` available at
+`/opt/homebrew/Cellar/node/26.0.0/bin/node`, and pnpm `10.32.0` ran with that
+Node first in `PATH`.
+
+Under Node `v26.0.0`, `pnpm install --frozen-lockfile` failed while building
+`tree-sitter@0.25.0`:
+
+```text
+/Users/poleski/Library/Caches/node-gyp/26.0.0/include/node/v8config.h:13:2:
+error: "C++20 or later required."
+```
+
+The failing command was:
+
+```bash
+ssh codegraphy-mini 'set -euo pipefail; export PATH="/opt/homebrew/Cellar/node/26.0.0/bin:/opt/homebrew/Cellar/node@22/22.22.2_2/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"; cd /Users/poleski/.codex/worktrees/270-node-engine-upper-bound/CodeGraphyV4; pnpm install --frozen-lockfile'
+```
+
+The same remote worktree was then checked under the currently supported Node 22
+runtime:
+
+- Host: `Poleskis-Mac-mini.local`
+- Node: `v22.22.2`
+- pnpm: `10.32.0`
+- `pnpm install --frozen-lockfile` passed.
+- `pnpm run typecheck` passed.
+- `pnpm run lint` passed, with 32 existing generated-acceptance spacing
+  warnings emitted from
+  `packages/extension/tests/playwright-vscode/generated/acceptance.spec.ts`.
+- `pnpm --filter @codegraphy-dev/mcp test` passed: 1 file, 13 tests.
+- `pnpm run mutate -- packages/mcp/src/mcp/server.ts` passed: 5 mutants, 100%
+  mutation score.
+
+No focused VS Code Playwright slice was run after the Node 26 install failure
+because the next blocker is dependency installation, before VS Code or
+Playwright runtime behavior can be exercised.
+
+## Native Build Fix Options
+
+`tree-sitter@0.25.0` fails to build against Node 26 because Node 26's V8
+headers require C++20. C++20 is a newer version of the C++ language standard;
+native Node addons compile C++ code during install, and the compiler must be
+told which language standard to use.
+
+Next things to test:
+
+1. `npm view tree-sitter version versions --json` showed `0.25.0` is still the
+   latest published `tree-sitter` runtime, so there was no newer runtime package
+   to upgrade to for this failure.
+2. A local pnpm patch now changes the `tree-sitter@0.25.0` native binding build
+   from C++17 to C++20 in `binding.gyp`.
+   This is a temporary backport of the upstream fix while
+   https://github.com/tree-sitter/node-tree-sitter/issues/276 blocks a published
+   npm release with the fix.
+
+The patch fixed the original Node 26 install blocker on `codegraphy-mini`:
+
+- Host: `Poleskis-Mac-mini.local`
+- Node: `v26.0.0`
+- pnpm: `10.32.0`
+- `pnpm install --frozen-lockfile` passed.
+- `pnpm --filter @codegraphy-dev/core typecheck` passed.
+- `pnpm --filter @codegraphy-dev/mcp test` passed: 1 file, 13 tests.
+
+GitHub CI passed on the latest PR commit, including lint, typecheck, unit
+tests, build, release tests, VSIX artifacts, Playwright slices, and extension
+native-runtime jobs.
diff --git a/docs/quality/README.md b/docs/quality/README.md
@@ -51,4 +51,4 @@ Implementation now lives in the external `@poleski/quality-tools` package.
 
 Extension-specific architecture and lifecycle notes live in `packages/extension/docs/`.
 
-These commands assume the repo-pinned Node runtime from [`.nvmrc`](../../.nvmrc), currently `22.22.0` LTS. `@poleski/quality-tools` uses `path.matchesGlob`, so older Node versions are not supported.
+These commands assume the repo-pinned Node runtime from [`.nvmrc`](../../.nvmrc), currently `22.22.0` LTS. `@poleski/quality-tools` uses `path.matchesGlob`, so Node 20 or newer is required.
diff --git a/package.json b/package.json
@@ -52,7 +52,7 @@
 		"url": "https://github.com/joesobo/CodeGraphyV4/issues"
 	},
 	"engines": {
-		"node": ">=20.20.0 <23",
+		"node": ">=20",
 		"vscode": "^1.85.0"
 	},
 	"files": [

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -17,7 +17,7 @@
     }
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"

diff --git a/packages/extension/docs/README.md b/packages/extension/docs/README.md
@@ -18,7 +18,7 @@ Current extension behavior to keep in mind while reading the package docs:
 - CSS Snippets are built into the extension: workspace-local `.css` files listed in `.codegraphy/settings.json` under `cssSnippets` can style stable `data-codegraphy-*` hooks without rebuilding a VS Code theme
 - the language plugins in `packages/plugin-*` are now mostly for ecosystem filters and optional semantic enrichment rather than baseline file coloring
 
-Local tooling and CI are pinned to Node `22.22.0` LTS.
+Published packages support Node 20 and newer. Local tooling and CI are pinned to Node `22.22.0` LTS.
 
 The source tree is split by runtime boundary:
 

diff --git a/packages/extension/package.json b/packages/extension/package.json
@@ -5,7 +5,7 @@
   "description": "CodeGraphy VS Code extension core",
   "license": "MIT",
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "scripts": {
     "build": "pnpm run build:extension && pnpm run build:webview",

diff --git a/packages/mcp/README.md b/packages/mcp/README.md
@@ -8,7 +8,7 @@ The MCP package owns only the agent-agnostic `codegraphy-mcp` server command. Co
 
 ## Prerequisites
 
-- Node `22.22.0` or newer within the supported Node 22 range.
+- Node 20 or newer.
 - Codex, Claude, Cursor, or another MCP-capable agent.
 
 ## Quick Start

diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -5,7 +5,7 @@
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"

diff --git a/packages/plugin-api/package.json b/packages/plugin-api/package.json
@@ -3,7 +3,7 @@
   "version": "5.0.0",
   "description": "Type definitions for CodeGraphy plugins",
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "repository": {
     "type": "git",

diff --git a/packages/plugin-csharp/package.json b/packages/plugin-csharp/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/packages/plugin-godot/package.json b/packages/plugin-godot/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/packages/plugin-markdown/package.json b/packages/plugin-markdown/package.json
@@ -13,7 +13,7 @@
     }
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"

diff --git a/packages/plugin-python/package.json b/packages/plugin-python/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/packages/plugin-svelte/package.json b/packages/plugin-svelte/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/packages/plugin-typescript/package.json b/packages/plugin-typescript/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/packages/plugin-vue/package.json b/packages/plugin-vue/package.json
@@ -21,7 +21,7 @@
     "url": "https://github.com/joesobo/CodeGraphyV4/issues"
   },
   "engines": {
-    "node": ">=20.20.0 <23"
+    "node": ">=20"
   },
   "keywords": [
     "codegraphy",

diff --git a/patches/README.md b/patches/README.md
@@ -0,0 +1,15 @@
+# Dependency Patches
+
+## `tree-sitter@0.25.0`
+
+CodeGraphy carries a temporary pnpm patch for `tree-sitter@0.25.0` so the
+native Node binding builds with C++20 on Node 23 and newer.
+
+Upstream has already merged the equivalent fix in
+tree-sitter/node-tree-sitter#258, but the fixed npm release is not currently
+published. The follow-up issue is:
+
+https://github.com/tree-sitter/node-tree-sitter/issues/276
+
+Remove this patch once `tree-sitter` publishes a release that includes the
+Node 23+ C++20 build fix, then replace it with a normal dependency update.
diff --git a/patches/tree-sitter@0.25.0.patch b/patches/tree-sitter@0.25.0.patch
@@ -0,0 +1,29 @@
+diff --git a/binding.gyp b/binding.gyp
+index bb40aa7e8d41644ba690761e9064fc1d0f2dcd6b..1e1641b2e3d6733642ea0ff06cd88b3b3023fd6c 100644
+--- a/binding.gyp
++++ b/binding.gyp
+@@ -25,13 +25,13 @@
+         "NAPI_VERSION=<(napi_build_version)",
+       ],
+       "cflags_cc": [
+-        "-std=c++17"
++        "-std=c++20"
+       ],
+       "conditions": [
+         ["OS=='mac'", {
+           "xcode_settings": {
+             "GCC_SYMBOLS_PRIVATE_EXTERN": "YES", # -fvisibility=hidden
+-            "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
++            "CLANG_CXX_LANGUAGE_STANDARD": "c++20",
+             "MACOSX_DEPLOYMENT_TARGET": "10.9",
+           },
+         }],
+@@ -39,7 +39,7 @@
+           "msvs_settings": {
+             "VCCLCompilerTool": {
+               "AdditionalOptions": [
+-                "/std:c++17",
++                "/std:c++20",
+               ],
+               "RuntimeLibrary": 0,
+             },
Original file line number	Diff line number	Diff line change
Expand Up		@@ -51,4 +51,4 @@ Implementation now lives in the external `@poleski/quality-tools` package.

		Extension-specific architecture and lifecycle notes live in `packages/extension/docs/`.

		These commands assume the repo-pinned Node runtime from [`.nvmrc`](../../.nvmrc), currently `22.22.0` LTS. `@poleski/quality-tools` uses `path.matchesGlob`, so older Node versions are not supported.
		These commands assume the repo-pinned Node runtime from [`.nvmrc`](../../.nvmrc), currently `22.22.0` LTS. `@poleski/quality-tools` uses `path.matchesGlob`, so Node 20 or newer is required.