1 files changed, 26 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..519ea94
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,26 @@
+# 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.