docs: reposition around Lua 5.1 interop rather than general scripting (#12)

The README led with 'embed Lua 5.1 in your Node.js programs', which invites a
comparison against wasmoon and fengari that this package loses: both need no
C++ toolchain, and requiring one is a real barrier.

That comparison is also the wrong one. The reason to reach for this is that you
need Lua 5.1 *exactly* -- to interoperate with a runtime you do not control,
such as firmware, Redis scripting or OpenResty -- or that you need real
filesystem and process access rather than a sandbox. No no-compile alternative
can offer either, because they target a different Lua version and run
sandboxed.

Adds an honest 'is this the right package?' section that names those
alternatives and says plainly when to prefer them. Sending the wrong users away
costs nothing; the right ones can now recognise their problem.

Also documents that this is stock PUC-Rio Lua 5.1.5 and not LuaJIT, so
precompiled bytecode is not interchangeable with a LuaJIT target -- source and
C API compatibility are unaffected. And records that Node-API is ABI-stable
across Electron as well as Node, which is what makes the addon usable inside a
VS Code extension without rebuilding per host release.

npm description and keywords updated to match, since that is what appears in
search results.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: mschmicking

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",