diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..14300e7
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,99 @@
+# FrankieSDK v1
+
+> Include this in your arcade game to talk to Frankie OS.
+
+
+## Game Structure
+
+Your game must be packaged as a `.zip` containing:
+
+my-game.zip  
+├── frankie-game.json    ← Erforderliches Manifest (Format siehe unten)  
+├── index.html           ← Erforderlicher Einstiegspunkt  
+└── assets/              ← Optional: JS, CSS, Bilder, Audio, etc.  
+
+## frankie-game.json Format
+
+```json
+{
+  "id":          "my-game",          // slug: lowercase letters, digits, hyphens (1-64 chars)
+  "version":     "1.0.0",            // your game version
+  "title":       "My Game",          // shown on the cartridge
+  "tagline":     "A one-line pitch", // shown under the title
+  "icon":        "🎮",               // emoji shown on the cartridge
+  "kind":        "ARCADE",           // badge: ARCADE | VS | LLM | PET
+  "author":      "Your Name",        // shown in the admin panel
+  "order":       50,                 // sort position in the arcade grid (lower = first)
+  "sdk_version": 1                   // must be 1; future versions may be incompatible
+}
+```
+
+Lifecycle Hooks (Events Received FROM Frankie)
+```javascript
+sdk.on('init', ({ userId, username, gameId, theme }) => { ... })
+```
+Called once after the iframe loads. Initialize your game here.
+You MUST call sdk.emit('ready') when your game has finished loading.
+```javascript
+sdk.on('pause', () => { ... })
+```
+Called when the arcade overlay loses focus (e.g. user switches tab).
+Pause timers, animations, and any ongoing audio.
+
+```javascript
+sdk.on('resume', () => { ... })
+```
+Called when the overlay regains focus. Resume paused state.
+
+Events Emitted TO Frankie
+```javascript
+sdk.emit('ready')
+```
+
+Tell Frankie your game is loaded and ready. Required after 'init'.
+```javascript
+sdk.emit('xp', { amount: number, reason: string })
+```
+
+Award XP to the player. reason is a short label shown in toasts.
+```javascript
+sdk.emit('win')
+```
+
+Record a win for this game (increments win counter and awards XP).
+```javascript
+sdk.emit('score', { value: number })
+```
+
+Submit a high score. Frankie keeps the all-time best per game.
+
+```javascript
+sdk.emit('close')
+```
+
+Close the game and return to the arcade grid.
+
+LLM Access (for kind: "LLM" games)
+```javascript
+const reply = await sdk.llm([
+  { role: 'system', content: 'You are a trivia host.' },
+  { role: 'user',   content: 'Ask me a question.' }
+])
+console.log(reply) // string — the model's response text
+Example (Vanilla JS)
+import sdk from './frankie-sdk.js'
+
+sdk.on('init', ({ username }) => {
+  document.querySelector('#welcome').textContent = `Hello, ${username}!`
+  sdk.emit('ready')
+})
+
+sdk.on('pause', () => clearInterval(gameLoop))
+sdk.on('resume', () => { gameLoop = setInterval(tick, 16) })
+
+function onPlayerWin() {
+  sdk.emit('win')
+  sdk.emit('xp', { amount: 50, reason: 'Victory' })
+  sdk.emit('score', { value: playerScore })
+}
+```
\ No newline at end of file