1 files changed, 24 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c795ad4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,24 @@
+# CLAUDE.md — worldmap-viewer
+
+Map server + browser viewer for worldgen worlds (globe and flat views, tiles, deep zoom, pins, regions, export).
+Terse everywhere. Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see
+`.gitignore`). Overview, CLI table and layout: `README.md`.
+
+## Layout
+- Python server: `serve.py` (HTTP API, `env_defaults` = `WORLDMAP_<OPTION>`), `tiles.py`, `refine.py`, `rivers.py`,
+  `seafloor.py`, `servecache.py`, `export.py`, `h3par.py`, `mapview.py` (CLI), `worldgen_path.py` (finds `mapgen`)
+- Deploy: `deploy.py`, `dedupe.py`, `tilecap.py`, `deploy/` (Containerfile, server README)
+- `viewer/` — browser app (`js/`, `tests/` node unit tests, `tools/smoke/` headless browser smoke, `vendor/` three.js:
+  never edit); `tests/` — Python unittest (`tests/helpers.py`: small in-process mapgen grid, no world folder)
+
+## Build / test
+- Needs worldgen (the `mapgen` package): `$WORLDGEN`, `../worldgen` or `./worldgen`. Python deps (numpy, scipy, h3,
+  pillow) are not in system python: a `.venv` with them (worldgen's works: `ln -sfn ../worldgen/.venv .venv`).
+  In a git worktree link the main tree's `.venv` and `worldgen` (`.venv` and `/worldgen` are ignored without
+  trailing slash: they may be links).
+- Verify: `.venv/bin/python -m unittest discover -s tests -t .` (≈ 4 min; slow: test_tiles, test_serve,
+  test_export) and `cd viewer && node --test tests/*.test.mjs` (≈ 3 s).
+- Browser smoke: `WORLD=<world dir> PYTHON=.venv/bin/python viewer/tools/smoke.sh viewer/tools/smoke/core.mjs`.
+
+## Git
+- Work in a git worktree on a branch (`.worktrees/<topic>`), not in the main tree; ff-merge when green.