1 files changed, 26 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3813efa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,26 @@
+# CLAUDE.md — worldgen
+
+Procedural world generator (H3 grid, tectonics → erosion → climate → hydrology → render). Terse everywhere.
+Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see `.gitignore`).
+
+## Layout
+- `mapgen.py` — CLI (new-world, build, check, era, compare; `--res`, `--final`, `--low-memory`, `--from/--stop <stage>`)
+- `mapgen/` — pipeline stages, order = `STAGES` in pipeline.py: grid sketch plates crust elevation erosion climate
+  hydrology seabed environment ice fields render; `mapgen/testing.py` + `mapgen/testdata/world.toml` = test fixtures
+  (also used by worldmap-viewer's tests: keep `small_world` / `built_world` stable)
+- `example/` — starter world; `tests/` — unittest. worldhistory reads `cells.npz`.
+
+## Build / test
+- Setup: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`; in a git worktree link the main
+  tree's `.venv` (`ln -sfn <main>/.venv .venv`; `.venv` is ignored without trailing slash: it may be a link).
+- Verify: `.venv/bin/python -m unittest discover -s tests -t .` (270 tests, ~2 min, multi-core).
+
+## Gotchas
+- System python lacks scipy/h3: always `.venv/bin/python`.
+- numba optional (not in requirements): JIT fast paths in graph.py / noise.py / render.py; `WORLDGEN_NO_JIT=1`
+  forces numpy paths; `WORLDGEN_THREADS` caps workers; test_sphere_noise skips without numba.
+- Outputs must stay byte-identical across `--low-memory` (test_low_memory) — memory work never changes results.
+- Real builds at r5 / `--final` are big (README Troubleshooting).
+
+## Git
+- Work in a git worktree on a branch (`.worktrees/<topic>`), not in the main tree; ff-merge when green.