From ae67ad2ffafdb070440795efec5b34c85a58d920 Mon Sep 17 00:00:00 2001
From: Parley Hatch <parley.hatch@numencore.com>
Date: Tue, 2 Jun 2026 22:16:49 -0600
Subject: [PATCH] =?UTF-8?q?docs:=20add=20root=20README=20=E2=80=94=20sandb?=
 =?UTF-8?q?ox=20model=20+=20folder-per-experiment=20convention?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

reikhelm is now framed as an open-ended sandbox: each game-system experiment
lives in its own top-level folder, loosely coupled, glue code as needed. README
documents the convention and maps the current contents (dungeon procgen / web
playground + explorer / AI-render pixel-art pipeline).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..005c38e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# reikhelm
+
+A sandbox for game-system experiments. No single end goal — each idea is its
+own self-contained system, built to learn and to see something cool run. The
+best ones might get blended into an actual game someday; until then it's just
+shipping for fun.
+
+## How this repo works
+
+- **One experiment per top-level folder.** Each is meant to stand on its own.
+- **Mix and match freely.** When two systems are worth mashing up, write glue
+  code between them. It doesn't have to be pretty.
+- **Rust or Python**, whatever fits the idea. Rust experiments can be standalone
+  Cargo projects or join the workspace below for easy path-dependency glue.
+
+## What's here so far
+
+### Procedural dungeon generator (Rust)
+A deterministic 2D map generator built from small composable **passes** over a
+shared context (BSP → rooms → caves → connect → corridors → doors → pools →
+pillars → entities). Towns/dungeons are different **recipes** drawn from one
+primitive vocabulary (Partitioner / Shaper / Connector / Placer / Decorator).
+
+- `reikhelm-core/` — pure generation library, no rendering deps (the `Map`
+  struct is the contract; renderers own all art).
+- `reikhelm-wasm/` — `wasm-bindgen` bridge that compiles core to wasm32.
+- `reikhelm-viz/` — original macroquad renderer (**frozen** — kept, not maintained).
+
+### Browser playground & first-person explorer (JS + Canvas)
+- `reikhelm-web/` — live procgen playground (reroll / seed / config sliders /
+  per-pass scrubber) in an atmospheric torch-lit style, plus a top-down and a
+  first-person (Eye-of-the-Beholder style) renderer and a walkable explorer.
+
+### AI-render → pixel-art pipeline (Python)
+- `tools/` — depth map → local diffusion render (Z-Image on the LAN
+  workstation) → Floyd–Steinberg dither through a 256-color palette → signature
+  pixel art. See `tools/README.md`.
+
+## Building
+
+```sh
+# Rust workspace (host-native crates)
+cargo build            # builds reikhelm-core + reikhelm-viz
+cargo test
+
+# Browser playground (wasm)
+wasm-pack build reikhelm-wasm --dev --target web \
+  --out-dir ../reikhelm-web/pkg --out-name reikhelm_wasm
+python3 -m http.server 8011 --directory reikhelm-web
+```
+
+`~/.cargo/bin` may not be on the non-interactive shell PATH — prepend
+`export PATH="$HOME/.cargo/bin:$PATH"` to cargo commands if they're not found.