From 52f015e8e27037c0fed342938972b240d0f340ed Mon Sep 17 00:00:00 2001
From: Aelith <aelith@sweeney.fyi>
Date: Tue, 16 Jun 2026 13:52:55 -0400
Subject: [PATCH] Add comprehensive README with project status, roadmap, and
 infrastructure docs

---
 README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..be5612b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,150 @@
+# Nerdhalla Valheim World Map
+
+**Vanilla Valheim community server tools** — no mods, no BepInEx. Everything runs off the world save file.
+
+## 🌐 Live Sites
+
+| Site | URL | Purpose |
+|---|---|---|
+| **Nerdhalla Community** | https://nerdhalla.nerdcade.cc | Map viewer, POI browser, server status |
+| **Forgejo (source)** | https://git.sweeney.fyi/aelith/valheim-map | Git repo for all code |
+
+## 🗺️ What's Here
+
+### Data Pipeline
+
+| Step | Script | Output |
+|---|---|---|
+| Decode tiles | `decode_valheim_tiles.py` | 16 × 1024×1024 PNGs (composite, biome, height) |
+| Stitch tiles | `valheim_decode_tiles.py` | 4096×4096 world images |
+| Build POI DB | `build_db.py` | SQLite DB with 11,309 locations |
+| Build viewer | `build_viewer.py` | Leaflet HTML with 3 map layers |
+| Parse .db | `parse_valheim_db.py` | ZPackage → JSON conversion |
+
+### Web Viewer (`index.html`)
+
+- Leaflet map with 3 layers: composite, biome, height
+- 11,309 POI markers with category icons (boss, dungeon, resource, etc.)
+- Coordinate display on hover
+- POI browser with search + category filter
+- Server status indicator (checks Nerdcade via SSH)
+
+### API Server (`api_server.py`)
+
+- `GET /api/status` — Nerdcade server online/offline check
+- `GET /api/pois?limit=N&search=X&category=Y` — POI queries
+
+### Infrastructure
+
+- **Caddy** — reverse proxy with auto-TLS for nerdhalla.nerdcade.cc + git.sweeney.fyi
+- **Forgejo** — bare metal (migrated from Docker), git.sweeney.fyi:3000
+- **nerdhalla-api** — systemd service, port 8081
+
+## 📊 World Stats
+
+| Property | Value |
+|---|---|
+| Seed | `yzZ5fr2tGa` |
+| Map Size | ~10 km × 10 km (4096 × 4096 px) |
+| Biomes | Meadows, Black Forest, Swamp, Mountain, Plains, Ocean, Mistlands |
+| Total POIs | 11,309 |
+| Best Tar Pit | (1210, -4159) — 5 tar pits within 200m |
+
+## 🚧 Roadmap
+
+### Phase 1 — POI Database ✅
+- [x] Decode 16 map tiles from world save
+- [x] Stitch into 4096×4096 composite/biome/height images
+- [x] Build SQLite DB from `locations.json` (11,309 POIs)
+- [x] Spatial queries for base location hunting
+
+### Phase 2 — Web Viewer ✅
+- [x] Leaflet map with 3 tile layers
+- [x] POI markers with category icons
+- [x] Search + category filter
+- [x] Coordinate display
+- [x] Server status indicator
+- [x] TLS via Caddy
+- [x] API backend for POI queries
+
+### Phase 3 — Fog-of-War ⏳
+- [ ] **Blocked:** Need player `.fch` files from local machines
+- [ ] Extract explored/unexplored bitmap per player
+- [ ] Overlay on map viewer
+- [ ] Merge multiple players' exploration data
+
+### Phase 4 — Cartography Sync 🔮
+- [ ] **Undecided approach:**
+  - Option 1: ServerSideMap mod (requires BepInEx — some players don't want this)
+  - Option 2: Periodic merge script (pull `.fch` files, merge explored data)
+  - Option 3: Cartography table automation (in-game solution)
+
+### Phase 5 — Automation 🔮
+- [ ] Cron job to periodically pull `Nerdhalla.db` from Nerdcade
+- [ ] Auto-regenerate map tiles on world update
+- [ ] Push updated data to site
+
+## 🛠️ Infrastructure
+
+### Services on Boston-VPS
+
+| Service | Type | Port | Notes |
+|---|---|---|---|
+| Caddy | Bare metal | 80/443 | Reverse proxy, auto-TLS |
+| Forgejo | Bare metal | 3000 | Git server, git.sweeney.fyi |
+| nerdhalla-api | Bare metal | 8081 | Python API server |
+| Hermes Gateway | Bare metal | 8642/8644 | Fleet COO agent |
+
+### Docker Cleanup (June 2026)
+- Forgejo migrated from Docker to bare metal (saved ~450 MB virtual overhead)
+- Dead containers removed: `hermes-fa98be67` (exited), `vllm-compression` (never started)
+- 9.2 GB reclaimed from unused images
+- Docker still installed but only used if needed
+
+## 🔧 Quick Commands
+
+```bash
+# Restart API
+sudo systemctl restart nerdhalla-api
+
+# Restart Forgejo
+sudo systemctl restart forgejo
+
+# Restart Caddy
+sudo systemctl reload caddy
+
+# View logs
+sudo journalctl -u nerdhalla-api -n 50 --no-pager
+sudo journalctl -u forgejo -n 50 --no-pager
+sudo tail -f /var/log/caddy/nerdhalla.log
+```
+
+## 📁 File Layout
+
+```
+/var/www/nerdhalla/          # Site root
+├── index.html               # Main site
+├── api_server.py            # Python API
+├── world_composite.png      # 4096×4096 map images
+├── world_biome.png
+├── world_height.png
+├── 00-00_*.png              # Individual tile images (16 tiles × 3 layers)
+└── ...
+
+/srv/forgejo/                # Forgejo data
+└── data/
+    ├── gitea/               # Config, DB, attachments
+    └── git/repositories/    # Git repos
+
+/etc/caddy/
+├── Caddyfile                # Main config (imports sites-enabled/)
+└── sites-enabled/
+    ├── nerdhalla.conf       # nerdhalla.nerdcade.cc
+    └── git.conf             # git.sweeney.fyi
+```
+
+## 🔗 Related
+
+- **Nerdcade server:** `aelith@100.86.206.39:46129`
+- **World saves:** `/home/amp/.ampdata/instances/Valheim/.config/unity3d/IronGate/Valheim/worlds_local/`
+- **Forgejo API token:** stored in Hermes memory