Add package documentation for AI agents

docs/lua-package-format.md

@@ -0,0 +1,110 @@
+# Lua game package format
+
+A game package is a manifest plus Lua scripts and optional assets.
+
+Typical structure:
+
+```text
+assets/games/<gameId>/
+  manifest.json
+  scripts/
+    main.lua
+    state.lua
+    ui.lua
+    runtime_defs.lua
+  assets/
+    image.png
+  audio/
+    click.wav
+```
+
+## Manifest modules
+
+Lua modules must be declared in `manifest.json`.
+
+```json
+{
+  "id": "template",
+  "version": "0.1.0",
+  "entry": "main",
+  "modules": {
+    "main": "scripts/main.lua",
+    "state": "scripts/state.lua",
+    "ui": "scripts/ui.lua",
+    "runtime_ui": "runtime:runtime_ui.lua",
+    "runtime_widgets": "runtime:runtime_widgets.lua",
+    "runtime_commands": "runtime:runtime_commands.lua",
+    "layout": "runtime:layout.lua"
+  }
+}
+```
+
+Lua imports by module name:
+
+```lua
+local ui = runtime.import("ui")
+local widgets = runtime.import("runtime_widgets")
+```
+
+Do not use `require`, `package`, `dofile`, `loadfile`, or `os`.
+
+## Path rules
+
+Package-local module paths:
+
+```text
+scripts/*.lua
+```
+
+Runtime shared module paths:
+
+```text
+runtime:*.lua
+```
+
+`runtime:` paths must not contain `/`, `..`, or an empty filename.
+
+## Entry module
+
+The manifest `entry` module should expose lifecycle/event functions expected by the script engine. Keep game-specific state in Lua modules and return runtime diffs/commands through the approved protocol.
+
+## Runtime helper modules
+
+Shared helpers are provided by the runtime package:
+
+```text
+assets/runtime/lua/runtime_ui.lua
+assets/runtime/lua/runtime_widgets.lua
+assets/runtime/lua/runtime_commands.lua
+assets/runtime/lua/layout.lua
+```
+
+Use helpers for authoring convenience, but remember helpers must normalize into supported Runtime protocol nodes/commands before Dart validation.
+
+## Generated Lua definitions
+
+`runtime_defs.lua` files are generated from common definitions. After changing helper APIs, run:
+
+```bash
+dart run tool/generate_lua_runtime_defs.dart
+```
+
+Check without rewriting:
+
+```bash
+dart run tool/generate_lua_runtime_defs.dart --check
+```
+
+## Package validation
+
+A host repository can validate a game package with:
+
+```bash
+dart run tool/check_runtime_package.dart assets/games/template packages/flame_lua_runtime/assets/runtime/lua
+```
+
+Within this package repo, example game packages live under:
+
+```text
+example/assets/games/
+```