docs: update CLAUDE.md with comprehensive git commit guidelines and heavy run instructions

## Git Commit Guidelines

When creating commits:

- **Python environment**: Use the environment `/dati/pyenvs/pyaetnaEnv`

- **Commit often**: Small, focused commits are easier to review and understand. Ask for confirmation before committing

- **Pre-commit tests**: Run all pre-commit hooks before committing, recipes are in `.pre-commit-config.yaml` (black, ruff, mypy)

- **Repository test suite**: Run the repository test suite before committing, using `pytest -v --maxfail=1 --disable-warnings`. Fix all failures, also the ones not related to your changes, before committing.

- **Format**: Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:)

- **Subject line**: Maximum 100 characters, no period

- **Body**: Only if truly necessary; omit if the subject says enough

- **Example**: 

  - `fix: handle NaN in RV uncertainties`

  - `feat: add Bayesian model comparison for exoplanet candidates`

  - `refactor: simplify posterior sampling loop`

Do NOT include lengthy explanations unless the change warrants it. One-line commits are preferred.

Whenever you send me messages, report the current date and time in local time, compact format, boldface, and in parentheses. For example: **(2024-06-05 14:30)**. This will help me keep track of the timeline of our discussion.

# PyAETNA: instructions for the code and the benchmarks (the software paper: `paper/CLAUDE.md`)

## Working with the author

- The author is an exoplanet astronomer, not a software developer. Make the standard technical choices yourself

  and explain the outcome in plain language; do not ask them to write code or to choose between technical options.

  Still ask before committing, unless they said to go ahead for that piece of work.

- Never print or propagate access tokens (e.g. the token file in `/dati/software/pyLib/`).

## Git commits

- **Python environment**: use `/dati/pyenvs/pyaetnaEnv`.

- **Commit often**: small, focused commits are easier to review and understand. Ask for confirmation before

  committing.

- **Pre-commit tests**: run all pre-commit hooks before committing; recipes are in `.pre-commit-config.yaml`

  (black, ruff, mypy).

- **Repository test suite**: run it before committing, with `pytest -v --maxfail=1 --disable-warnings`. Fix all

  failures, including those unrelated to your changes, before committing.

- **Format**: Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:).

- **Subject line**: at most 100 characters, no period.

- **Body**: only if truly necessary; omit it if the subject says enough. No lengthy explanations unless the change

  warrants them.

- **Examples**: `fix: handle NaN in RV uncertainties`; `feat: add Bayesian model comparison for exoplanet

  candidates`; `refactor: simplify posterior sampling loop`.

- **Not committed**: `prompt.md`, the author's own edits to `.gitignore` and `CLAUDE.md` unless asked, and large

  outputs. Checkpoints (`.pckl`) and the posterior chains of ensemble-MCMC runs stay out of git

  (`paper_benchmarks/.gitignore`); their summaries are kept.

## Heavy runs

- **One heavy job at a time** on each machine: a GPU or CPU PyAETNA run, the full pytest suite and benchmark

  scripts never overlap. Only light commands (grep, git, lint, single small tests) may run alongside. On the laptop,

  check `nvidia-smi` and `free -g` first. On the server, every queue takes the lock `heavy.lock`.

- **Laptop timings** only in the `performance` power profile, on mains, with uncapped CPU clocks. A reboot brings

  back the quiet profile, and a suspend/resume caps every core at 2 GHz until the next reboot. Check all three

  before each timed run; each run records them in `power_profile.txt`. Ask the author before long laptop runs.

- **Server** (ExoREC-Ganymede, `ssh ganymede-cuda13`, workspace `/DATA/ExoREC/pyaetna_bench`): if unreachable,

  activate the OACT VPN (`nmcli connection up OACT`). GitHub clones fail there, so copy sources from the laptop.

- **Nothing that must survive goes in `/tmp`** or the session scratchpad (a tmpfs wiped at reboot). Environments,

  sources, run folders and queue logs go in `/dati/software/pyLib/PyAETNA_bench_work/`. Copy results into the

  repository as soon as a run ends.

- When timing a JAX computation, wait for it to finish (`jax.block_until_ready`): JAX returns before the work is

  done.

- Whenever a long job is not required to run on the laptop, run it on the server

## Paper benchmarks

`paper_benchmarks/` reproduces every result of the PyAETNA software paper (the LaTeX draft is local-only in `paper/`,

synced to Overleaf). Before changing anything there, read the **Reproducibility policy** in

`paper_benchmarks/README.md`:

- runs record their provenance (commit, dirty flag, package versions);

`paper_benchmarks/` (public, in this repository) reproduces every result of the software paper. A benchmark folder

`paper_benchmarks/<case>/` holds `data/`, `configs/`, `runs/` and `results/summary.json`. Before changing anything

there, read the **Reproducibility policy** in `paper_benchmarks/README.md`:

- runs record their provenance (commit, dirty flag, package versions), and each `results/*.json` records the

  hardware, software versions, wall-clock time and settings;

- outputs are kept as portable `.npz`/`.json`, not pickles;

- the paper cites a release tag made at submission, from clean reruns (`./rerun_all.sh`);

- the tagged release is archived on Zenodo at acceptance.

- the tagged release is archived on Zenodo, with a DOI, at acceptance.

Numbers in the paper come only from `*/results/*.json`, through the generated tables or by reading the JSON. If a

result changes, rerun the generators; never retype numbers.

**Fair comparisons with other codes.**

- Same machine; each code at its own best number of CPUs (from a scan); one BLAS thread per worker. Timings from

  other machines are not quoted.

- Samplers and models as close as possible: if the reference code runs an ensemble MCMC, run PyAETNA with the same

  MCMC (moves, walkers, steps, start) in direct mode, without its warmup. If the reference code offers a closed-form

  model equivalent to PyAETNA's, compare with that one.

- Remaining large differences go in the paper constructively: strengths and weaknesses of each approach, and

  guidance on which code to choose. Every case where PyAETNA is slower is tracked, with its cause and possible

  improvements, in `localDocs/performance/PYAETNA_SLOWER_CASES.md`.

## The software paper

Numbers in the paper come only from `*/results/summary.json`.

The paper is in `paper/`, its own repository (synced with Overleaf; ignored here). Everything about writing and

revising it (scope, language and style, layout, conventions, building, the live documents and the revision log) is in

`paper/CLAUDE.md`. The paper takes its numbers only from `paper_benchmarks/*/results/*.json`, through the generated

tables and figures: if a result changes, rerun the generators; never retype numbers.