diff --git a/README.md b/README.md
index 494c1d6..3a365b9 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,39 @@
-# hidden-side-footprints
+# Hidden Side Set Footprints
 
-LEGO Hidden Side set footprint presets for the Newbury Exhibit layout editor (fan/tribute; not affiliated with the LEGO Group)
\ No newline at end of file
+Footprint presets for the Newbury Exhibit layout editor. Each preset is the top-down
+table footprint (width × depth in cm, 1 unit = 1 cm) of a LEGO Hidden Side set.
+
+Fan/tribute project — not affiliated with or endorsed by the LEGO Group. Dimensions
+derived from Brickset-published model sizes.
+
+## Files
+- `set-footprints.json` — data only, for the server/editor to load.
+- `setFootprints.js` — ES module: preset array + `getFootprint`, `footprintLabel`,
+  `makeFootprintOutline(THREE, fp)`, `makeFootprintPlane(THREE, fp)`.
+
+## Editor integration sketch
+```js
+import { SET_FOOTPRINTS, getFootprint, footprintLabel, makeFootprintOutline } from './setFootprints.js';
+
+// populate a dropdown
+for (const fp of SET_FOOTPRINTS) {
+  const opt = document.createElement('option');
+  opt.value = fp.setNumber;
+  opt.textContent = footprintLabel(fp);
+  select.appendChild(opt);
+}
+
+// on import, drop a footprint outline at the cursor / origin
+const fp = getFootprint(select.value);
+const outline = makeFootprintOutline(THREE, fp);
+scene.add(outline); // then reposition with TransformControls
+```
+
+## Notes on the numbers
+Brickset lists three dimensions as W × D × H. Footprint uses the two horizontal axes:
+- **70421 Stunt Truck** — the 17 cm figure is height (ramp/tower), so footprint is 10 × 10.
+- **70424 Ghost Train** — 61 cm long; footprint 14 × 61 (the 15 is car height).
+- **70437 Mystery Castle** — hinges open; both closed (34 × 31) and open (45.5 × 26) variants included.
+
+Sets without published dimensions (70419 Wrecked Shrimp Boat, 70423 Paranormal Intercept
+Bus 3000, 70436 Phantom Fire Truck 3000) are omitted — add manually if you measure them.