Add package documentation for AI agents

AGENTS.md

@@ -0,0 +1,150 @@
+# flame_lua_runtime Agent Guide
+
+This file is the first-stop guide for AI agents and maintainers working in this package.
+
+## What this package is
+
+`flame_lua_runtime` is a reusable Flutter + Flame + Lua 2D game runtime.
+
+The stable runtime boundary is:
+
+```text
+RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame
+```
+
+Flutter/Flame owns runtime infrastructure, rendering, resources, events, commands, diagnostics, and package lifecycle. Lua owns game logic, UI layout, event handling, and construction of diff/command tables.
+
+## Hard boundaries
+
+Do not add game-specific logic to Dart runtime code.
+
+Do not let Lua directly hold or mutate Flutter, Flame, Spine, Particle, or native objects.
+
+Do not expose unrestricted Lua APIs:
+
+- `require`
+- `package`
+- `dofile`
+- `loadfile`
+- `os`
+
+Lua modularization must go through:
+
+```lua
+runtime.import(moduleName)
+```
+
+Modules must be declared in the game manifest.
+
+## Runtime Lua assets
+
+Shared Lua helper modules live here:
+
+```text
+assets/runtime/lua/
+```
+
+Supported shared modules currently include:
+
+```text
+runtime_ui.lua
+runtime_widgets.lua
+runtime_commands.lua
+layout.lua
+```
+
+Game manifests may reference them with restricted `runtime:` paths:
+
+```json
+{
+  "modules": {
+    "runtime_ui": "runtime:runtime_ui.lua"
+  }
+}
+```
+
+`runtime:` paths must remain narrow: only `runtime:*.lua`, no `/`, no `..`, and no empty path.
+
+Package-local Lua modules remain under:
+
+```text
+scripts/*.lua
+```
+
+## Public API surface
+
+The public barrel is:
+
+```text
+lib/flame_lua_runtime.dart
+```
+
+Keep this API intentionally small. Add exports only when host apps need them.
+
+Current primary API:
+
+- `LuaGameWidget`
+- `FlameLuaGame`
+- `RuntimeOptions`
+- `RuntimeLocaleResolver`
+- `GamePackageRepository`
+- `AssetGamePackageRepository`
+- `RemoteGamePackageRepository`
+- `ScriptEngine`
+- `LuaDardoScriptEngine`
+
+## Repository layout
+
+```text
+assets/runtime/lua/       Shared Lua framework modules
+lib/runtime/              Dart runtime implementation
+lib/flame_lua_runtime.dart Public API barrel
+test/                     Runtime and public API tests
+tool/                     Runtime helper/check scripts
+example/                  Runnable Flutter showcase app
+```
+
+## Validation commands
+
+Run these before committing package changes:
+
+```bash
+flutter analyze
+flutter test test
+dart run tool/generate_lua_runtime_defs.dart --check
+```
+
+For the example app:
+
+```bash
+cd example
+flutter analyze
+flutter test
+```
+
+For publish readiness:
+
+```bash
+flutter pub publish --dry-run
+```
+
+A warning about missing `homepage` / `repository` is acceptable until real public metadata is configured.
+
+## Development rules
+
+- Keep protocol fields white-listed and explicit.
+- Prefer simple data models over implicit behavior.
+- Runtime commands must be generic, not game-specific.
+- Lua helper aliases are allowed only if normalized before protocol validation.
+- Tests should cover protocol parsing, package validation, script loading, command execution, and public API exports.
+- If adding Lua helper APIs, update generated defs through `tool/generate_lua_runtime_defs.dart`.
+
+## More docs
+
+Read these docs before larger changes:
+
+- `docs/quick-start.md`
+- `docs/architecture.md`
+- `docs/lua-package-format.md`
+- `docs/protocol.md`
+- `docs/validation.md`