docs: clarify OpenResty LuaJIT runtime scope in README

[membphis]

Background

lua-qjson is primarily intended for OpenResty LuaJIT workloads. Despite the package name, the project is not currently a general-purpose standard Lua JSON library: the Lua surface loads the Rust native library through LuaJIT FFI, and the main production target is OpenResty's LuaJIT runtime.

The current README mentions LuaJIT and includes caveats around pairs / ipairs / #, but the project scope is still easy to misread as "works with Lua 5.x generally." The install instructions also use a bare luarocks install lua-qjson, which can target the user's default LuaRocks tree instead of the Lua 5.1 / LuaJIT tree expected by the rockspec.

Problem

Readers can currently draw a few incorrect conclusions:

• lua-qjson supports standard PUC Lua 5.1/5.2/5.3/5.4.
• luarocks install lua-qjson is enough regardless of the default Lua version configured in LuaRocks.
• Stock LuaJIT has the same lazy-table ergonomics as OpenResty LuaJIT for native pairs, ipairs, and #.
• LuaJIT is merely optional runtime context rather than a real requirement caused by the FFI loader.

These misunderstandings can lead to failed installs, failed require("qjson"), or surprising behavior when code uses native table traversal on qjson lazy proxies.

Goals

• State clearly near the top of the README that OpenResty LuaJIT is the primary supported runtime.
• Clarify that standard Lua is not currently supported because qjson depends on LuaJIT FFI.
• Make the LuaRocks install command explicitly target the Lua 5.1 / LuaJIT tree.
• Separate build-time requirements from runtime requirements:
  • Build/install: Rust/Cargo plus LuaRocks targeting Lua 5.1 / LuaJIT.
  • Runtime: OpenResty LuaJIT / LuaJIT with access to the installed native library.
• Keep the existing stock-LuaJIT caveat for lazy proxies, but frame OpenResty as the intended environment.

Non-goals

• Add support for standard PUC Lua.
• Claim regression coverage for Lua 5.2+ or non-LuaJIT runtimes.
• Change the FFI loader or lazy table implementation.
• Change benchmark claims.

Proposed README changes

Add a short runtime-support section near the top, before installation/build details, with wording along these lines:

## Runtime support

`lua-qjson` is designed for OpenResty LuaJIT workloads. It loads the Rust native
library through LuaJIT FFI, so standard Lua 5.1/5.2/5.3/5.4 is not a supported
runtime today.

Stock LuaJIT may work for direct `qjson.parse` / cursor access, but the lazy
`qjson.decode` table API is most ergonomic on OpenResty LuaJIT, which enables
Lua 5.2 compatibility by default. On LuaJIT builds without
`LUAJIT_ENABLE_LUA52COMPAT`, use `qjson.pairs`, `qjson.ipairs`, and `qjson.len`
instead of native `pairs`, `ipairs`, and `#` on lazy proxies.

Update the install command:

luarocks --lua-version=5.1 install lua-qjson

Then adjust the install text to avoid implying that standard Lua is supported:

The rock builds the Rust native library during installation, so Rust/Cargo must
be available in the build environment. Install it into a Lua 5.1 / LuaJIT
LuaRocks tree. Runtime use requires LuaJIT FFI; OpenResty LuaJIT is the primary
supported target.

Optionally soften any "drop-in replacement" wording around qjson.encode to
"cjson-shaped encoder" or "replacement for common cjson.encode call sites,"
since the migration guide already documents unsupported lua-cjson knobs.

Acceptance criteria

• The README first screen makes the OpenResty LuaJIT target explicit.
• The README no longer implies standard Lua support.
• LuaRocks installation examples consistently target Lua 5.1 / LuaJIT.
• Build-time and runtime dependencies are described separately and accurately.
• The stock-LuaJIT pairs / ipairs / # caveat remains discoverable.
• This can be completed as a docs-only PR.

[coderabbitai]

🔗 Related PRs

#45 - feat: release v0.1.0 [merged]
#54 - perf: Lua encode + cache + scanner + validation stack optimizations [merged]
#58 - docs: fix install instructions and qualify ARM64 performance claims [merged]
#92 - docs: add no-Rust runtime deployment guide [merged]
#99 - ci: test qjson against OpenResty runtimes [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!