Add package documentation for AI agents

docs/quick-start.md

@@ -0,0 +1,100 @@
+# Quick start
+
+This package embeds manifest-driven Lua game packages in Flutter apps.
+
+## Add dependency
+
+For private Git usage, prefer a pinned tag:
+
+```yaml
+dependencies:
+  flame_lua_runtime:
+    git:
+      url: https://gitea.sdws.shop/xim/flutter_lua_runtime.git
+      ref: v0.1.0
+```
+
+For local development:
+
+```yaml
+dependencies:
+  flame_lua_runtime:
+    path: ../flame_lua_runtime
+```
+
+## Add game assets to the host app
+
+A minimal host app should provide one game package:
+
+```text
+assets/games/template/manifest.json
+assets/games/template/scripts/main.lua
+assets/games/template/scripts/state.lua
+assets/games/template/scripts/ui.lua
+```
+
+Declare assets in the host app `pubspec.yaml`:
+
+```yaml
+flutter:
+  assets:
+    - assets/games/template/manifest.json
+    - assets/games/template/scripts/
+    - assets/games/template/assets/
+```
+
+The runtime package itself provides shared Runtime Lua helpers from:
+
+```text
+packages/flame_lua_runtime/assets/runtime/lua/
+```
+
+## Embed in Flutter
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flame_lua_runtime/flame_lua_runtime.dart';
+
+class GameScreen extends StatelessWidget {
+  const GameScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const LuaGameWidget(
+      gameId: 'template',
+      runtimeOptions: RuntimeOptions(
+        runtimeLuaRoot: 'packages/flame_lua_runtime/assets/runtime/lua',
+      ),
+    );
+  }
+}
+```
+
+## Run the package example
+
+```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
+```
+
+## Minimal manifest
+
+```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"
+  }
+}
+```