SCUMM-style web adventure engine v0.1

Headless, data-driven core (no DOM, no eval): loader with one-pass
validation, verb-coin interaction resolution, polygon walkables with
Dijkstra pathfinding, branching dialogue with mid-conversation saves,
declarative JSON conditions/effects, versioned JSON saves.

Thin integration layer: asset manifest with graceful placeholders,
WebAudio music loop points (midi-playlist convention), canvas renderer
(hotspot boxes drawn where hitTest clicks), HUD model.

Web harness (web/) + skeleton example game exercising every feature.
69 tests (node --test), tools/run_all.sh gate, docs/SPEC.md design spec.
Verified end-to-end in a real browser: intro scene, walking, look/take,
room exits, dialogue choices.

README.md

@@ -1,3 +1,38 @@
 # moonlit-engine
 
-SCUMM-style web adventure game engine. Data-driven game specs, verb coin interface, dialogue trees, walkable areas, save/load. Content-agnostic: engine only, assets and game ideas come later.
+A SCUMM-style, web-based adventure game engine. Data-driven: a game is a
+JSON spec, not code. Engine only — game ideas and asset generation come
+later.
+
+- Design spec: [docs/SPEC.md](docs/SPEC.md)
+
+## Quickstart
+
+```sh
+./tools/run_all.sh          # validate example spec + 68 tests — must be green
+node tools/validate_game.js example/game.json   # check any game spec
+python3 -m http.server 8080 # then open http://localhost:8080/web/index.html
+```
+
+The demo (`example/game.json` + `web/`) is a two-room skeleton — jetty,
+tavern, a suspicious mug, a barkeep, one branching dialogue — deliberately
+minimal: it exists to exercise every engine feature, not to be a game.
+It ships with the *Moonlit Mangrove Calypso* track and its loop points.
+
+## Layout
+
+```
+src/core/    headless engine (no DOM): loader, world, verbs, dialogue,
+             walkable, conditions, effects, save, events, engine
+src/render/  thin integration layer: asset manifest, audio (loop points),
+             canvas renderer, HUD model — all testable without a browser
+web/         browser harness: index.html + boot.js (~150 lines of glue)
+example/     the skeleton game spec
+tools/       validate_game.js, run_all.sh
+tests/       node --test suite, one file per module
+docs/        SPEC.md — the design spec
+```
+
+## Requirements
+
+Node 20+ for tests/tooling. Any modern browser for the demo. No dependencies.