diff --git a/crates/geormerge-demo/README.md b/crates/geormerge-demo/README.md
new file mode 100644
index 0000000..91e2125
--- /dev/null
+++ b/crates/geormerge-demo/README.md
@@ -0,0 +1,27 @@
+## Geomerge Demo
+
+This crate demonstrates storing and reading data with the `geomerge` submodule.
+
+The demo
+1. loads the compiled `paths.json` schema
+2. creates a Geomerge store
+3. inserts a small graph dataset in one transaction
+4. reads the inserted edge back
+5. persists the store to bytes
+6. reloads it and checks that the restored store matches the original.
+
+### Run
+
+```sh
+cargo run -p geormerge-demo
+```
+
+Expected output includes table and law counts, stored graph row counts, edge endpoints, and persisted byte size.
+
+### Test
+
+```sh
+cargo test -p geormerge-demo
+```
+
+The tests cover the successful store, read, and persistence round trip, plus a rejected invalid edge insert that must leave the store unchanged.