From 0a394ca5f32168dc8314614086af39ff3a73b988 Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Tue, 2 Jun 2026 16:18:01 +1000
Subject: [PATCH] Flesh out README with usage, tech, and limitations

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 709a384..3c7b460 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,51 @@
-# hidden-spectre
+# HIDDEN SPECTRE 👻
 
-AR ghost-hunting web app — an homage to the LEGO Hidden Side app. WebXR world tracking with camera+gyro fallback; roaming ghosts caught with a trap tool.
\ No newline at end of file
+An augmented-reality ghost-hunting web app — an homage to the LEGO® Hidden Side™ app, focused purely on the AR mechanics: ghosts roam your real-world space and you trap them with an aiming reticle.
+
+> Not affiliated with or endorsed by the LEGO Group. A fan-made tribute to the AR play concept.
+
+## What it does
+
+- **World-tracked AR** via WebXR (`immersive-ar`) on supported devices (Android Chrome, etc.).
+- **Graceful fallback** to a live camera feed + device-gyro look-around on devices without WebXR AR (e.g. most iOS Safari) — so it still works as a "point and turn" experience.
+- **Roaming ghosts** rendered as procedural glowing wisps in Three.js that drift, bob, and eventually flee.
+- **Trap tool**: aim the reticle at a ghost and *hold* the trap button to charge a capture. Fill the meter before it escapes.
+- HUD with live score, nearby count, off-screen direction hints, capture flash + haptics.
+
+## How to play
+
+1. Open on a phone over **HTTPS** (camera/WebXR require a secure context).
+2. Tap **Begin the Hunt** and grant camera + motion permissions.
+3. Pan slowly to map the area, then turn your body to find ghosts.
+4. Center a ghost in the reticle, **hold the trap button** until the green ring fills.
+
+## Tech
+
+- [Three.js](https://threejs.org/) (ES module via CDN import map)
+- WebXR Device API with camera + `DeviceOrientation` fallback
+- Vanilla JS, no build step — static files only
+
+## Files
+
+```
+index.html        markup + screens
+css/style.css     neon supernatural styling
+js/ar-engine.js   WebXR / camera+gyro abstraction
+js/ghost.js       procedural ghost mesh + behaviour
+js/main.js        game loop, aiming, trapping, scoring
+```
+
+## Running locally
+
+Any static server over HTTPS works. For quick local testing:
+
+```bash
+npx serve .
+# then open the https URL on your phone (use a tunnel like ngrok/cloudflared for device testing)
+```
+
+## Notes & limitations
+
+- iOS Safari does not support `immersive-ar`; it uses the camera+gyro fallback (look-around only, ghosts are world-locked relative to your starting orientation).
+- Motion permission on iOS must be triggered by a user gesture — handled on the Begin button tap.
+- Lighting and a steady camera improve the illusion, same as the original.