docs: reposition around Lua 5.1 interop rather than general scripting

README.md

@@ -1,11 +1,20 @@
 # node-lua-runner
 
-Embed **Lua 5.1** in your Node.js programs.
+**Real Lua 5.1 in Node.js** — for tooling that has to interoperate with a Lua 5.1 runtime you
+don't control.
 
-Lua and [LuaFileSystem](https://github.com/lunarmodules/luafilesystem) are compiled directly into
-the addon, so there is no system Lua to install and nothing to configure — `npm install` builds
-everything from source on Linux, macOS and Windows, on both x64 and ARM64.
+Lua 5.1 is what Redis scripting, OpenResty/nginx, NodeMCU and ESP-based firmware, and a great
+deal of game modding still run on. If you are writing an editor plugin, a build tool or a test
+harness that has to speak to one of those, the language version has to match exactly — and it has
+to be the real interpreter, not a reimplementation.
 
+This package embeds the genuine Lua 5.1.5 interpreter, compiled into a native addon, with the full
+standard library and real filesystem and process access. Lua and
+[LuaFileSystem](https://github.com/lunarmodules/luafilesystem) are compiled in, so there is no
+system Lua to install — `npm install` builds everything from source on Linux, macOS and Windows,
+on x64 and ARM64.
+
+- [Is this the right package?](#is-this-the-right-package)
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Documentation](#documentation)
@@ -14,6 +23,29 @@ everything from source on Linux, macOS and Windows, on both x64 and ARM64.
 - [Caveats](#caveats)
 - [License](#license)
 
+## Is this the right package?
+
+**Use this when** you need Lua **5.1 specifically**, or you need Lua scripts to touch the real
+filesystem and run real processes, or you need the actual Lua C API rather than an approximation
+of it.
+
+**Use something else when** you just want to run some Lua and don't care which version. Two good
+options that need **no C++ toolchain at all**, which is a genuine advantage:
+
+| | Approach | Toolchain needed |
+|---|---|---|
+| [wasmoon](https://www.npmjs.com/package/wasmoon) | "A real lua VM with JS bindings made with webassembly" | none |
+| [fengari](https://www.npmjs.com/package/fengari) | "A Lua VM written in JS ES6" | none |
+| **node-lua-runner** | Native addon around the genuine Lua 5.1.5 C sources | C/C++ compiler |
+
+Both target a newer Lua than 5.1, and both run sandboxed — which is often what you want, and
+exactly what you can't use when the point is matching a 5.1 target or reaching the real OS.
+
+> **Note:** this is stock Lua 5.1.5 (PUC-Rio), not LuaJIT. Source-level and C API compatibility
+> with a LuaJIT target is fine, but **compiled bytecode is not interchangeable** between LuaJIT
+> and PUC-Rio Lua. If you exchange precompiled chunks with a LuaJIT runtime, this is not a drop-in
+> replacement.
+
 ## Installation
 
 ```
@@ -78,10 +110,12 @@ lua.Close();
 ## How it works
 
 Built on the [Lua 5.1 C API](https://www.lua.org/manual/5.1/manual.html) through
-[Node-API](https://nodejs.org/api/n-api.html), which is ABI-stable — a compiled build keeps working
-across future Node.js releases instead of breaking on each major version.
+[Node-API](https://nodejs.org/api/n-api.html). The API is low-level and maps closely onto the C
+API, and it is synchronous throughout — a long-running Lua script blocks the event loop.
 
-The API is low-level and maps closely onto the C API, and it is synchronous throughout.
+Node-API matters here beyond mere future-proofing: it is ABI-stable across Node.js **and Electron**
+versions, so a single build keeps working as the host updates. That is what makes this usable
+inside a VS Code extension, where the extension host's ABI changes with every release.
 
 Descended from [NodeLua](https://github.com/brettlangdon/NodeLua) and
 [node-luajit](https://github.com/whtiehack/node-luajit).
@@ -94,6 +128,9 @@ aborts the process rather than throwing a JavaScript exception. `SetField` and `
 against this; other methods do not. Keep track of what is on the stack — see
 [stack indices](https://github.com/mschmicking/node-lua-runner/blob/master/docs/api.md#stack-indices).
 
+Lua scripts get the full standard library, including `os.execute` and `io.open`. That is the
+point of this package, and it means **you should not run Lua you do not trust**.
+
 ## License
 
 ISC — see [LICENSE](LICENSE). The vendored Lua and LuaFileSystem sources are MIT; their notices are

package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-lua-runner",
   "version": "2.0.1",
-  "description": "Embed Lua 5.1 in Node.js. Lua and LuaFileSystem are compiled into the addon, so there is nothing to install on the system.",
+  "description": "Real Lua 5.1 in Node.js, for tooling that must interoperate with a Lua 5.1 runtime. A Node-API native addon with the genuine Lua 5.1.5 interpreter and LuaFileSystem compiled in.",
   "author": "Maurice Schmicking",
   "contributors": [
     "Medaeus245"
@@ -19,7 +19,10 @@
     "node-api",
     "napi",
     "embed",
-    "scripting"
+    "scripting",
+    "lua51",
+    "embedded",
+    "interop"
   ],
   "files": [
     "index.js",