docs: add AGENTS.md with contributor and agent guidance

[mschmicking]

Guidance for AI agents and new contributors, covering what is not discoverable by reading the code.

Conventions in src/

• vendor/ is a verbatim upstream copy and must not be patched — that is what keeps a Lua upgrade a file copy rather than a merge
• Argument validation goes through CheckArgs; Lua errors through ThrowLuaError, which owns the lua_pop that is easy to forget
• Relative stack indices must be resolved with abs_index before pushing — this was a real bug, where SetField(-1, ...) assigned into the value it had just pushed
• Unprotected Lua errors abort the process rather than throwing, so types must be guarded first
• No C++ exceptions through Lua frames: Lua unwinds with longjmp, which skips destructors

Workflow rules that caused real friction here

• Branch from the default branch, never stack. Merges are squash-only, so a squashed parent leaves duplicate commits and guaranteed conflicts. This cost two rebases during the recent work.
• DIRTY and BEHIND are different. One is a conflict, the other just needs "Update branch".
• Read CodeQL results from a default-branch analysis. PR analyses only report alerts new relative to the base, so results=0 on a PR reads as clean when the branch has open alerts. That misled this repo once already.
• Rebuild after changing src/ — npm test runs against the last compiled binary and will pass on stale output.

Verified

• No personal information: scanned for emails, names and account handles — none present
• All local links resolve
• Every factual claim checked against the repo: 287 tab-indented lines and 0 space-indented, NAPI_DISABLE_CPP_EXCEPTIONS present in binding.gyp, all five helper names exist, 29 vendored Lua sources, files allowlist present

🤖 Generated with Claude Code