Add package documentation for AI agents

docs/protocol.md

@@ -0,0 +1,93 @@
+# Runtime protocol
+
+The runtime protocol is the stable boundary between Lua and Dart.
+
+```text
+RuntimeEvent -> Lua -> GameDiff / RuntimeCommand -> Flame
+```
+
+## RuntimeEvent
+
+Dart sends white-listed events to Lua. Events represent input, lifecycle, command/resource outcomes, and host/runtime notifications.
+
+Lua should treat events as data and return explicit state changes.
+
+## GameDiff
+
+A `GameDiff` describes desired changes to the runtime render tree.
+
+Typical operations include creating, updating, and removing runtime nodes. Dart validates node fields before applying them to Flame components.
+
+## RuntimeNode
+
+Runtime nodes are generic render descriptions. They are not Flame objects.
+
+Supported node concepts include:
+
+- Containers/panels.
+- Text.
+- Sprites/images.
+- Buttons.
+- List views.
+- Particles.
+- Spine nodes.
+
+Lua may compose higher-level widgets, but those widgets must normalize into supported runtime nodes.
+
+## RuntimeCommand
+
+Runtime commands request generic side effects owned by Dart/Flame.
+
+Examples:
+
+- `move_path`
+- `move_to`
+- `fade_to`
+- `scale_to`
+- `rotate_to`
+- `remove_node`
+- `sequence`
+- `parallel`
+- `delay`
+- `toast`
+- `play_sound`
+- `play_bgm`
+- `pause_bgm`
+- `resume_bgm`
+- `stop_bgm`
+- `preload_resources`
+- `evict_resources`
+- `cancel_commands`
+- `play_spine_animation`
+- `copy_text`
+
+Commands must remain generic. Do not add commands like `roll_ludo_dice` or `move_airplane_piece`; those belong in Lua game logic.
+
+## Validation expectations
+
+- Unknown protocol fields should not become implicit behavior.
+- Required fields should fail clearly when absent.
+- Helper-only aliases must be normalized before Dart protocol validation.
+- Runtime code should not silently convert invalid game state into fake success.
+
+## Where to change protocol code
+
+```text
+lib/runtime/models/          Data models
+lib/runtime/protocol/        Protocol validation
+lib/runtime/commands/        Command validation/execution
+lib/runtime/rendering/       Runtime node to Flame component mapping
+assets/runtime/lua/          Lua helper constructors/aliases
+```
+
+When protocol changes affect Lua authoring, update:
+
+```text
+tool/lua_runtime_defs_common.lua
+```
+
+Then run:
+
+```bash
+dart run tool/generate_lua_runtime_defs.dart
+```