diff --git a/README.md b/README.md
index 323e14f..eabe825 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,42 @@
 # airship-phaser
 
-Top-down Phaser.js airship combat prototype
\ No newline at end of file
+Top-down Phaser.js airship combat prototype.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run dev
+```
+
+Production builds run the regression suite before Vite:
+
+```bash
+npm run build
+```
+
+## Runtime diagnostics
+
+The browser keeps the latest 300 structured events in memory.
+
+In Chrome DevTools:
+
+```js
+airshipDebug.getLogs()
+airshipDebug.snapshot()
+airshipDebug.clearLogs()
+```
+
+Useful events include:
+
+- `scene:init`, `scene:create`, `scene:heartbeat`, `scene:shutdown`
+- `combat:broadside-fired`
+- `combat:player-hit-queued`
+- `combat:player-hit-processed`
+- `combat:pirate-hit`
+- `game:finish`
+- `hud:image-error`, `hud:helm-frame-error`, `hud:helm-knob-error`
+- `runtime:error`, `runtime:unhandled-rejection`
+
+If gameplay appears frozen, inspect `airshipDebug.snapshot()` first, then the tail of `airshipDebug.getLogs()`.