From 3952de42f65fb32435abc53a12fe821f17f4fb11 Mon Sep 17 00:00:00 2001
From: Jack Felke <jrinnfelke@gmail.com>
Date: Fri, 13 Mar 2026 13:25:19 -0700
Subject: [PATCH] fix: correct Node version badge from 18+ to 20+ and add
 troubleshooting entry

The README badge said Node 18+ but package.json engines requires >=20.
Added troubleshooting section for users hitting cryptic errors on Node 18/19.
---
 README.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6d03f5d..7cd99fb 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blueviolet)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev)
-[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node 20+](https://img.shields.io/badge/node-20%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
 
 [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
 
@@ -662,6 +662,16 @@ node --version
 
 On Apple Silicon Macs, make sure you're running a native arm64 Node — not Rosetta. Check with `node -e "console.log(process.arch)"` (should print `arm64`).
 
+### Crashes or syntax errors on Node 18 or 19
+
+Preflight requires **Node 20+**. On Node 18/19 you may see cryptic errors like `SyntaxError: Unexpected token` or failed native module loads because preflight uses Node 20 features (built-in `fetch`, `import.meta.resolve`, native test runner in CI). Check your version:
+
+```bash
+node --version   # Must be v20.x or higher
+```
+
+If you're on 18, upgrade via [nvm](https://github.com/nvm-sh/nvm): `nvm install 20 && nvm use 20`.
+
 ### First run is slow (~90MB model download)
 
 The local embedding provider ([Xenova/all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2)) downloads a ~90MB model on first use. This is a one-time cost — subsequent runs use the cached model. If the download hangs behind a corporate proxy, switch to OpenAI embeddings: