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