Phase 1 README: roster data + seed overview

README.md

@@ -1,3 +1,54 @@
-# newbury-nights-ghost-data
+# Newbury Nights — Ghost Roster (Phase 1 Data)
 
-Phase 1 ghost-roster data + SQLite seed for the Newbury Nights AR ghost-hunting loop. Decoded roster (111 ghosts, 36 abilities), name-slug IDs, separate seed DB.
+Standalone ghost-roster data + seed for the AR ghost-hunting loop. This is the
+**data foundation** — no hunt logic yet. It builds a separate SQLite DB so it
+doesn't touch the live app DB (the Free Hunt pool) until you choose to merge.
+
+## Contents
+
+| File | What it is |
+|------|------------|
+| `ghosts.json` | 111 ghosts: name, slug `id`, colour, rarity, pip stats, health/damage, `abilityId`, plus null placeholders for asset paths + AR stats |
+| `abilities.json` | 36 abilities (17 Common + 19 Boss): charges, cooldown, effect |
+| `locations.json` | AR-anchor stub (one generic plane). Extend with real sets in Phase 2/3 |
+| `seed-ghosts.js` | `better-sqlite3` seed → builds `ghost-roster.db` |
+| `verify.js` | Quick read-back / integrity check |
+
+## Run
+
+```bash
+npm install better-sqlite3        # needs build-essential (already on hal-blackpearl)
+node seed-ghosts.js               # writes ./ghost-roster.db
+node verify.js                    # prints counts + sample joins
+```
+
+Re-runnable — the seed drops and rebuilds the `roster_*` tables each time.
+
+## Schema (roster_* tables, namespaced)
+
+- `roster_ghosts` — one row per ghost. PK = name slug (`nagging-nathan`).
+- `roster_abilities` — PK = ability slug. `roster_ghosts.ability_id` → FK.
+- `roster_locations` — AR anchors (plane / image-target / qr).
+- `roster_ghost_locations` — many-to-many spawn affinity (wired in Phase 3).
+
+## Decoded mapping (source of truth)
+
+- **Rarity** ← `GhostRarity` enum: Common=1, Rare=2, Epic=3, Legendary=4.
+- **Colour** ← `GhostColor` enum: Red, Blue, Yellow — drives the colour-wheel lure.
+- **Pips** ← `UISpeedPips` / `UIRangePips` / `UIChargePips` (int 0–5).
+- **health_max / damage_max** ← Digital Game stats (from the roster wiki).
+
+## Placeholders to fill later
+
+Per-ghost fields left `null`, filled from asset/data-table exports:
+
+- `faceSprite`, `fullbodySprite`, `webmPath`, `webpPath` — **Phase 2** asset pipeline.
+- `arHealth`, `hauntValue`, `isBoss` — from the **`ARGhostData` TextAsset** export.
+- `locations[]` — from **`MetaGhostData.LocationsArray`**, set in Phase 3.
+
+## Asset rights
+
+Ghost assets/stats used under direct permission from the rights holder; app
+delivery is original (web). LEGO and Hidden Side **logos are excluded**. Sets
+used only as generic AR anchors/backdrops. See `PERMISSIONS.md` once the grant
+doc is digitised. Not legal advice.