# 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.