diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..6839d3ea
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+musrfit is a C++ data analysis package for time-differential μSR (muon spin rotation/relaxation)
+and β-NMR data. It provides a fitting engine (`musrfit`), a viewer (`musrview`), Fourier transform
+tools, run-management utilities, and a set of Qt-based GUI applications (musredit, musrWiz,
+musrStep, mupp). It builds on CERN ROOT (Minuit2 for minimization) and depends on Boost, GSL,
+FFTW3, and LibXml2.
+
+## Build
+
+Out-of-source CMake build only (in-source builds are refused). `ROOTSYS` must be set/sourced
+before configuring (`. $ROOTSYS/bin/thisroot.sh` or equivalent).
+
+```
+mkdir build && cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=$ROOTSYS
+cmake --build . --clean-first
+cmake --install .          # installs binaries + writes ~/.musrfit XML config
+```
+
+An existing `build/` tree from a prior configure already lives at `build/` in this checkout
+(git-ignored). Reconfigure with `cmake ..` inside it rather than creating a second build dir.
+
+Key CMake options (`-D<option>=1` to enable):
+- `nexus` — NeXus (HDF4/HDF5) file format support (needed for ISIS data)
+- `BMWlibs`, `ASlibs`, `BNMRlibs` — optional external theory-function libraries
+- `DummyUserFcn` — build the example/template user function
+- `qt_based_tools` (default ON) — build musredit/musrWiz/musrStep/mupp; auto-detects Qt6 → Qt5 → Qt4 → Qt3
+- `qt_version` — force a specific Qt major version instead of auto-detect
+- `try_OpenMP` (default ON) — use OpenMP if available
+
+Requires ROOT >= 6.18, C++17. On macOS see `macos26_build_issues.txt` for two known local
+workarounds (AGL framework must be dropped from Qt6 app linking; mupp needs a `mupp-1.1.0 -> mupp`
+symlink under `MacOS`).
+
+## Testing
+
+Tests are registered with CTest from the top-level `tests/` directory (separate from the
+developer sandbox in `src/tests/`, which is example/scratch code, not part of the test suite).
+
+```
+cd build
+ctest                       # run everything
+ctest -N                    # list tests without running
+ctest -R test-histo-MusrRoot   # run a single test by name (regex match)
+ctest -R '^musrview-'          # run just the musrview rendering tests
+```
+
+Two test families, both driven by Python wrapper scripts against `.msr` files in `doc/examples/`:
+- `maxLH_check` (`tests/maxLH_check/`) — runs `musrfit` on an `.msr` file and asserts the final
+  max-log-likelihood/χ² value matches an expected value to 1e-4 (registered in
+  `tests/maxLH_check/CMakeLists.txt`).
+- `musrview_check` (`tests/musrview_check/`) — runs `musrview` (optionally with `-f`/`-a` for
+  Fourier/averaged-Fourier) and compares rendered PNG output against references in
+  `tests/musrview_check/ref/`.
+
+When adding a new example/regression case: drop the `.msr` (and data file) into `doc/examples/`,
+then add a corresponding `add_maxLH_test(...)` / `add_musrview_test(...)` line in the relevant
+`tests/*/CMakeLists.txt`.
+
+## Documentation
+
+The user documentation for setting it up, as well as for its usage can be find either under
+../musrfit-docu (sphinx)
+or under 
+https://lmu.pages.psi.ch/musrfit-docu/
+
+## Architecture
+
+### Core fitting pipeline
+
+The central data model and control flow (all in `src/classes/` with headers in `src/include/`):
+
+- **`PMsrHandler`** parses/writes the `.msr` fit-definition file format (theory block, parameters,
+  run blocks, Fourier/plot options) — the human-editable input driving every fit.
+- **`PRunDataHandler`** loads raw histogram data from the various supported file formats
+  (MusrRoot/HDF5, PSI-BIN, PSI-MDU, ROOT (LEM), MUD (TRIUMF), NeXus, WKM-deprecated).
+- **`PRunBase`** is the abstract base for all fit types; concrete subclasses implement
+  format/analysis-specific `PrepareData()`/theory-evaluation logic:
+  `PRunSingleHisto`, `PRunAsymmetry`, `PRunSingleHistoRRF`, `PRunAsymmetryRRF`,
+  `PRunAsymmetryBNMR`, `PRunMuMinus`, `PRunNonMusr`. The run type is selected by the
+  `PRUN_*` constants in `PMusr.h`.
+- **`PRunListCollection`** aggregates all runs of a fit for global/simultaneous fitting.
+- **`PTheory`** parses the algebraic theory expression from the msr file into a tree of built-in
+  functions (~34 of them) and evaluates it per bin.
+- **`PFunction`** / `PFunctionHandler` / `PFunctionGrammar` / `PFunctionAst` implement a small
+  Boost.Spirit-based expression grammar used for user-defined parameter functions (FUNCTIONS block
+  in the msr file).
+- **`PFitterFcn`** wraps the χ²/max-log-likelihood objective for ROOT's Minuit2; **`PFitter`**
+  drives the minimization and post-fit error analysis.
+- **`PMusrCanvas`** / **`PFourier`** / **`PFourierCanvas`** / **`PPrepFourier`** handle plotting
+  and Fourier-transform display, used by `musrview`/`musrFT`.
+- **`PMsr2Data`** implements `msr2data`'s logic for generating follow-up/global msr files from a
+  template across a run list.
+
+Executables in `src/*.cpp` are thin drivers over these classes: `musrfit.cpp` (fitter),
+`musrview.cpp` (viewer), `musrFT.cpp` (Fourier tool), `musrt0.cpp` (t0 determination),
+`msr2data.cpp` / `msr2msr.cpp` (msr file generation/conversion), `addRun.cpp` (run summation),
+`any2many.cpp` / `dump_header.cpp` / `write_musrRoot_runHeader.cpp` (format conversion/inspection),
+`musrRootValidation.cpp`.
+
+### Extending with user functions (plugins)
+
+Beyond the built-in theory functions, custom physics models are added as `PUserFcnBase` subclasses
+compiled into standalone shared libraries and loaded dynamically at runtime via ROOT's plugin
+mechanism — no core rebuild needed. See the doc comment in `src/include/PUserFcnBase.h` for the
+full header/impl/LinkDef pattern. Existing examples of this pattern live under `src/external/`
+(`libFitPofB`, `libGbGLF`, `libLFRelaxation`, `libZFRelaxation`, `libSpinValve`, `libGapIntegrals`,
+`libPhotoMeissner`, `libCalcMeanFieldsLEM`, `libCuba`, `LF_GL`, `Nonlocal`, `MagProximity`,
+`DepthProfile`, `BMWtools`, `libBNMR`, `DummyUserFcn` as a minimal template). Each has its own
+CMake option gate (`ASlibs`, `BMWlibs`, `BNMRlibs`, `DummyUserFcn`) or is built unconditionally.
+
+### Third-party/vendored format support (`src/external/`)
+
+`mud` (TRIUMF MUD format), `MusrRoot` (ROOT/HDF5-based format + its LaTeX definition doc),
+`TLemRunHeader` (LEM ROOT files), `MuSR_software/Class_MuSR_PSI` (PSI-BIN/PSI-MDU), `nexus`
+(NeXus/HDF4/HDF5, only built when `-Dnexus=1`) are vendored client libraries for reading each
+raw data format; `PRunDataHandler` dispatches to the appropriate one based on file
+extension/content.
+
+### GUI tools (`src/musredit_qt6/`, with `_qt5`/legacy `musredit`/`musrgui` siblings)
+
+Qt6 is the primary target; CMake auto-falls-back to Qt5 → Qt4 → Qt3 equivalents if Qt6 isn't
+found (`qt_based_tools`/`qt_version` options above). Four independent Qt apps:
+- `musredit` — msr-file editor/front-end for running `musrfit`.
+- `musrWiz` — wizard for constructing new msr files from instrument/function templates
+  (`func_defs/`, `instrument_defs/`).
+- `musrStep` — step-through/interactive fit tool.
+- `mupp` — μSR parameter plotter (plots fit results extracted across multiple msr files).
+
+### Runtime configuration
+
+Installed binaries read an XML startup config from `~/.musrfit` (written at `cmake --install`
+time), not from the source tree — check that location when debugging why an installed binary
+behaves differently from a locally-built one in `build/`.
+
+## Notes
+
+- Version is tracked in `CMakeLists.txt` (`project(musrfit VERSION x.y.z ...)`); the current
+  branch (`root6`) is mid-refactor targeting ROOT 6-only support (`PMsrHandler` C++17 tokenizer
+  rewrite, `PMsrHighlighter` renamed to CERN/ROOT naming scheme — see `ChangeLog`).
+- Full user documentation lives externally at https://lmu.pages.psi.ch/musrfit-docu/index.html,
+  not in this repo; `doc/` here holds Doxygen configs (`doc/*.dox`, `doc/*_dox.cfg`) and the
+  example/regression `.msr` files consumed by the test suite.