sql-kite 1.0.5 → 1.0.7

package/README.md

@@ -164,8 +164,16 @@ SQL Kite runs **entirely on your machine**.
 
 ### Requirements
 
-* Node.js 18+
-* npm
+* **Node.js 18** (LTS recommended)
+* **npm**
+
+> **Important:** SQL Kite uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3), a native C++ module. Node.js 20+ may have compatibility issues with the current version. **Node.js 18 LTS is recommended** for the best experience.
+
+**Windows users:** If installation fails, you may need native build tools:
+1. Re-run the Node.js installer and check **"Automatically install the necessary tools"**
+2. Or run `C:\Program Files\nodejs\install_tools.bat` to install Python and Visual Studio Build Tools
+
+> **No special characters or spaces in your project path** — `node-gyp` may not handle them correctly.
 
 ### Option 1: Global Installation (Recommended)
 
@@ -285,6 +293,12 @@ lib/database/
   └── engine.local.js
 ```
 
+| File | Purpose |
+|---|---|
+| `index.js` | Auto-switches between dev and production engines |
+| `engine.dev.js` | HTTP client that queries the SQL-Kite server |
+| `engine.local.js` | Local SQLite via expo-sqlite for production |
+
 **2) Use in your app:**
 
 ```javascript
@@ -293,6 +307,29 @@ import { runQuery } from '@/lib/database';
 const users = await runQuery("SELECT * FROM users WHERE active = ?", [1]);
 ```
 
+### How Dev/Prod Switching Works
+
+The switching is **fully automatic** — the user does not need to manually toggle anything.
+
+```javascript
+const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV === 'development';
+```
+
+**Detection order:**
+1. **Expo's `__DEV__` global** — automatically `true` in dev builds, `false` in production
+2. **Fallback:** `process.env.NODE_ENV === 'development'`
+
+| Environment | Engine Used | How it works |
+|---|---|---|
+| Development (`isDev = true`) | `engine.dev.js` | Queries go to SQL-Kite server via HTTP |
+| Production (`isDev = false`) | `engine.local.js` | Queries run locally via expo-sqlite |
+
+### Port Configuration (Dev Mode)
+
+The dev engine connects to the SQL-Kite server using:
+- `SQL_KITE_PORT` environment variable (if set)
+- Default port `3000` (editable in the generated `engine.dev.js`)
+
 ### Two Workflow Modes
 
 **Development Mode:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sql-kite",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "SQL-Kite CLI — Local-first SQLite workspace with branches, migrations and snapshots.",
   "type": "module",
   "preferGlobal": true,
@@ -31,7 +31,7 @@
     "developer-tools"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18 <=20"
   },
   "files": [
     "bin/",