CLAUDE.md — worldhistory

History simulation on a worldgen world (races spread, adapt, split, fight, invent; eras and events). Terse everywhere. Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see .gitignore).

Layout

• history.py — CLI entry (→ worldhistory/cli.py: run, preview, compare, check-config)
• worldhistory/ — engine package (one step = phase_* in engine.py, README order); tests/ — unittest, synthetic worlds (tests/helpers.py: line_world / fields, 1-D, hand-checkable)
• docs/reference/ — research notes (canals)

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 . (whole suite ~3 s).

Gotchas

• System python lacks scipy: always .venv/bin/python.
• numba optional (not in requirements): state.py JIT fast paths; tests/test_fastpaths.py skips without it.
• Input = a worldgen build (cells.npz + eras/<era>/cells.npz). A full run on a large world is big (README: < 2 GB at r4 ≈ 290k cells). SmokeTest (test_engine.py) runs 100 years when WORLDHISTORY_SMOKE_WORLD + WORLDHISTORY_SMOKE_CONFIG are set.
• Config: unknown keys are errors (config.py _keys); history.py check-config <dir> [--world <build>] validates.

Git

• Work in a git worktree on a branch (.worktrees/<topic>), not in the main tree; ff-merge when green.