README Quick Start fails on macOS: Node 26 incompatibility and missing tree-sitter CLI prerequisite

Aggiorna la sezione Quick Start di README e, se appropriato, CONTRIBUTING.md; usa package.json e gli script prebuild/build di packages/parser-tree-sitter per confermare i requisiti della versione di Node e di tree-sitter CLI. Riproduci la configurazione macOS documentata con Node 22 e la CLI, quindi esegui pnpm install e pnpm build. Il lavoro è completo quando una nuova configurazione Apple Silicon dispone di istruzioni complete sui prerequisiti e raggiunge una compilazione riuscita.

Summary

Following the README's Quick Start on macOS (Apple Silicon, fresh Homebrew toolchain), both pnpm install and pnpm build fail out of the box. Two prerequisites are not documented.

Environment

• macOS (Apple Silicon), Darwin 25.4.0
• Homebrew-installed Node and pnpm
• Repo at main (commit 4670b96)

Issue 1 — Node version ceiling not stated

The README says "Node.js >= 20", but tree-sitter@0.25.0's native binding fails to compile against Node 26's V8 headers. Homebrew's default node formula is currently 26.0.0, so anyone running brew install node lands on a broken version.

Representative error from pnpm install:

.../node_modules/tree-sitter install: /Users/.../node-gyp/26.0.0/include/node/v8-internal.h:1604:19:
  error: non-static data member 'is_convertible_v' cannot be declared as a template
.../node_modules/tree-sitter install:  error: 'is_convertible_v' cannot be specialized:
  Users are not allowed to specialize this standard library entity
.../node_modules/tree-sitter install: 3 warnings and 20 errors generated.
.../node_modules/tree-sitter install: make: *** [Release/obj.target/tree_sitter_runtime_binding/src/binding.o] Error 1
.../node_modules/tree-sitter install: gyp ERR! node -v v26.0.0
ELIFECYCLE  Command failed with exit code 1.

The repo's package.json pins volta.node to 22.22.1, which works — so Volta users are fine, but the README's plain "Node.js >= 20" guidance points the rest of us at a broken version.

Suggestion: state an upper bound (e.g. "Node 20–22 LTS") or recommend Volta explicitly so the pinned version is honored.

Issue 2 — tree-sitter CLI is a hidden prerequisite

packages/parser-tree-sitter invokes tree-sitter generate in its prebuild and build scripts, but the CLI is not a devDependency — it has to be installed system-wide. Neither the README nor CONTRIBUTING.md mentions this. (The preinstall.cjs hints at cargo install tree-sitter-cli inside a warning branch that only fires when parser.c is missing, which it usually isn't.)

pnpm install succeeds, but pnpm build fails:

@agentscript/parser-tree-sitter:build: > tree-sitter generate
@agentscript/parser-tree-sitter:build: sh: tree-sitter: command not found
ELIFECYCLE  Command failed with exit code 1.

On macOS, the fix is brew install tree-sitter-cli. Worth noting that brew install tree-sitter installs only the library — the formulas were recently split, so following an obvious-looking guess gets you the wrong package.

Suggestion: add a Prerequisites bullet for the tree-sitter CLI with install commands per OS (brew, cargo, etc.).

Working setup on macOS

brew install node@22
brew link --overwrite --force node@22
brew install tree-sitter-cli
pnpm install
pnpm build

After this, pnpm build completes cleanly (16/16 packages) and pnpm ui:dev runs.