diff --git a/CLAUDE.md b/CLAUDE.md
index 07bd102..c1afc2f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,7 +1,56 @@
+# helm
+
 ## Using atgc
 
 When doing repo operations, always use the global install of `atgc`. `atgc agent` is compiled into the binary and provides an up-to-date view of the current version's capabilities.
 
+## Building in a worktree
+
+A fresh worktree has no `target/`, so its first build compiles the whole
+dependency tree before it can run a single test — and `rusqlite` builds a
+bundled libsqlite3, which is C and takes minutes on its own. Several agents
+doing that at once is what puts this machine under load.
+
+- Point cargo at one shared directory:
+  `export CARGO_TARGET_DIR="$HOME/.cache/lance-blue-target"`. The second
+  worktree onwards reuses the first one's artifacts. This cannot go in a
+  committed `.cargo/config.toml`: a relative `build.target-dir` resolves
+  inside each worktree, which is the thing being avoided.
+- Cargo takes a file lock on the target directory, so two builds sharing one
+  serialise rather than run together. That is the intended trade: waiting for
+  a warm build beats two cold ones competing for the same cores.
+- Sharing it has one quiet cost: two worktrees with identical manifests get
+  the same unit hash and are told apart on mtimes alone, so a `cargo test`
+  can be answered from *another* worktree's binary — it prints `Finished`,
+  passes, and tested code you did not write. Check for a `Compiling helm-bv`
+  line naming your path; `find crates -name '*.rs' -exec touch {} +` forces
+  one.
+- Always `-j 2`. A full-parallel build has taken this machine down.
+- A worktree keeps its `target/` after the branch merges and these run to
+  gigabytes — this one reached 3.8GB beside the main checkout's 2.2GB. Remove
+  the worktree when the branch lands, not just the branch.
+
+## Running the tests
+
+Most of the suite is ordinary `cargo test`. Three things are not:
+
+- The conformance and oracle tests are `#[ignore]`d and need a MegaMek install
+  and a bridge dump: `HELM_MEGAMEK=<install> HELM_BRIDGE=<dump> cargo test
+  -p helm-bv --test conformance -- --ignored`. `HELM_BV_BLESS=1` re-records
+  `conformance.txt`, and a commit that moves a figure should say why.
+- `tests/performance.rs` is **release only** — an unoptimised build has a
+  different shape, not just a different speed, and is printed rather than
+  checked. `HELM_PERF_BLESS=1` re-records `performance.txt`.
+- `crates/helm-wasm/smoke.mjs` drives the wasm boundary from Node, which is
+  the only thing that exercises the interface a browser calls through. Build
+  the module first:
+  `cargo build -p helm-wasm --target wasm32-unknown-unknown --release`.
+
+Never read test fixtures out of a MegaMek install's `logs/` directory. That
+is MegaMek's own scratch, rewritten by anything that starts it — including
+`bridge/dump.sh` — so a case covered today can vanish tomorrow with nothing
+in this repository changing.
+
 ## Feature branch workflow
 
 If asked to do work, unless directly instructed otherwise, do not make changes to the user's top-level git checkout. All of your work will be on feature branches and inside git worktrees.