Post Step 4 Completion

README.md

@@ -1,4 +1,71 @@
-# Labyricorn Project Template
+# XZBT-NGN Exhibit Engine
+
+A minimal, single-exhibit engineering host for XZBT Exhibit Contract 5.2.
+It discovers controls from `describe`, tracks the exhibit's reported state,
+and exposes set/invoke operations, events, sessions, and protocol errors.
+
+## Run locally
+
+Requires Node.js 22 or later. No npm dependencies or build step are needed.
+
+```powershell
+npm start
+```
+
+Open `http://127.0.0.1:4173`. Enter a same-origin exhibit path and select
+**Load exhibit**. The host negotiates a real session, calls `describe` and
+`state.get`, then renders the discovered catalog. **Reconnect** establishes
+a new session without reloading the exhibit; **Refresh state** requests a
+new authoritative snapshot. **Disconnect** removes the exhibit frame.
+
+Included test fixture paths:
+
+```text
+/test-fixtures/reference-exhibits/aquarium/index.html
+/test-fixtures/reference-exhibits/planetarium/index.html
+/test-fixtures/reference-exhibits/haunted-house/index.html
+```
+
+These copied fixtures have documented compatibility corrections; see
+[fixture provenance](test-fixtures/PROVENANCE.md). They are not NGN product
+logic. Additional trusted HTML exhibits can be placed in a directory under
+`public/` and loaded by their same-origin URL. The server exposes only
+`public/`, `src/`, and `test-fixtures/`, and binds to `127.0.0.1`.
+Set the `PORT` environment variable to change the default port.
+
+## Verification
+
+```powershell
+npm test
+python devlog_editor.py --validate
+git diff --check
+```
+
+With the server running, open
+`http://127.0.0.1:4173/test-fixtures/host-verification.html` and select
+**Run verification** for repeatable real-browser transport tests against all
+three exhibits. Manual admin UI and native exhibit gesture checks are recorded
+in [the Step 4 report](STEP4-MVP-REPORT.md).
+
+## Implementation boundaries
+
+- `src/host.js`: session/request correlation, catalog, state cache, events,
+  synchronization, and control operations.
+- `src/validation.js`: descriptor, value, and clarified argument validation.
+- `src/transport/post-message.js`: same-origin frame transport only.
+- `src/ui.js` and `public/`: descriptor-driven engineering interface.
+- `server/serve.js`: loopback static server with explicit served directories.
+- `tests/`: focused automated host and server tests.
+- `test-fixtures/`: copied reference exhibits and real-browser verification.
+
+The state display is a cache of exhibit reports. Events update reported values;
+editable fields are drafts and are submitted only when Set/Invoke is selected.
+Draft fields start from the first snapshot and do not overwrite themselves on
+each incoming event. Registry/capability rediscovery rebuilds the controls.
+Logs retain the latest 200 entries in memory. The interface intentionally has
+no persistence, accounts, MIDI, scenarios, webhooks, packaging, or orchestration.
+
+## Template and publishing records
 
 A starter template and baseline structure for projects compatible with
 [Labyricorn](https://www.labyricorn.com).
@@ -210,4 +277,4 @@ applicable `AGENTS.md` before making changes.
 
 ## License
 
-This template is released into the public domain under the [Unlicense](LICENSE).
+This template is released into the public domain under the [Unlicense](LICENSE).