Add package documentation for AI agents

docs/validation.md

@@ -0,0 +1,82 @@
+# Validation and release checks
+
+Run validation from the package root unless noted otherwise.
+
+## Package checks
+
+```bash
+flutter pub get
+flutter analyze
+flutter test test
+dart run tool/generate_lua_runtime_defs.dart --check
+```
+
+## Example checks
+
+```bash
+cd example
+flutter pub get
+flutter analyze
+flutter test
+```
+
+## Publish dry run
+
+```bash
+flutter pub publish --dry-run
+```
+
+A warning about missing `homepage` or `repository` is acceptable until real public metadata is configured. Do not add fake metadata.
+
+## Manual smoke runs
+
+```bash
+cd example
+flutter run --dart-define=LUA_GAME_ID=showcase
+flutter run --dart-define=LUA_GAME_ID=template
+flutter run --dart-define=LUA_GAME_ID=ludo
+flutter run --dart-define=LUA_GAME_ID=flight
+```
+
+## Lua static checks
+
+Lua static checks require `lua-language-server`.
+
+If available, run the host/static-check workflow that points at game packages and `.luarc.json`.
+
+If unavailable, state explicitly that LuaLS is not installed instead of claiming static verification passed.
+
+## Windows builds
+
+Flutter Windows builds must be run on a Windows host.
+
+Example:
+
+```powershell
+fvm flutter build windows --debug --dart-define=LUA_GAME_ID=template
+```
+
+If CMake has stale target names after project renames, delete the Windows build cache first:
+
+```powershell
+Remove-Item -Recurse -Force build\windows -ErrorAction SilentlyContinue
+```
+
+## Git release flow
+
+For private Git dependency usage, prefer tags over `main`:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Consumers can depend on:
+
+```yaml
+dependencies:
+  flame_lua_runtime:
+    git:
+      url: https://gitea.sdws.shop/xim/flutter_lua_runtime.git
+      ref: v0.1.0
+```