docs: an overview page - what a rugnux run does, in order

The page that did not exist: one paragraph per stage from opening the file to
the written reflections, each linking into the data-analysis reference part
that carries the depth, with the stills differences at the end. First entry
after the landing page, and the landing page says to read it first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EFEJG6WBQv8th4UJFNe53N

docs/RUGNUX.md

@@ -113,6 +113,8 @@ A few things worth knowing before reaching for more flags:
 
 One page per job, so the answer needed is near the top of a short page:
 
+- [What a rugnux run does](RUGNUX_OVERVIEW.md) — the pipeline from images to merged reflections,
+  in order. Read this one first.
 - [Installing rugnux](RUGNUX_INSTALL.md) — packages, the release archive, GPU drivers, building
   from source, hardware.
 - [What rugnux reads](RUGNUX_FORMATS.md) — will it open your data: NXmx / EIGER masters, PILATUS

docs/RUGNUX_OVERVIEW.md

@@ -0,0 +1,63 @@
+# What a rugnux run does
+
+The map of a run, in the order it happens — one paragraph per stage, each linking into the
+[data-analysis reference](CPU_DATA_ANALYSIS.md) where the algorithm lives. The walk-through is a
+rotation run with the defaults; stills differences are at the end.
+
+**Open the dataset.** The geometry, wavelength and goniometer come from the file
+([What rugnux reads](RUGNUX_FORMATS.md)). A goniometer axis makes it a rotation run, none makes it
+serial stills — nothing is asked of the user.
+
+**Pre-scan.** A projection of the first frames (60 by default) finds the beam-stop shadow and masks
+it ([§1.5](CPU_DATA_ANALYSIS_IMAGE.md)), measures the beam centre from the isotropy of the
+scattered background and compares it with the file's ([§1.4](CPU_DATA_ANALYSIS_IMAGE.md)), and
+reads how wide this crystal's spots are, which sets the integration radius
+([§9.5](CPU_DATA_ANALYSIS_INTEGRATION.md)).
+
+**Spots.** Every image is decoded — on the GPU straight from the compressed chunk
+([§0](CPU_DATA_ANALYSIS_IMAGE.md)) — and one fused pass computes the azimuthal profile and finds
+the spots against each image's own per-resolution-ring noise
+([§2–§3](CPU_DATA_ANALYSIS_IMAGE.md)). The ice-ring score is read off the same profile.
+
+**Indexing.** The spots of a sample of frames are rotated back to a common crystal frame and the
+FFT search looks for periodicity over thousands of directions; candidate cells are
+Niggli-reduced, classified by Bravais lattice, refined both constrained and triclinic, and decided
+on how many validation frames each actually indexes
+([§4–§7](CPU_DATA_ANALYSIS_INDEXING.md)). A failed pass triggers the discrete rescues — the
+rotation-axis sign, the beam-centre search — before anything is given up on.
+
+**First integration pass.** At the geometry in the file, every frame is predicted
+([§8](CPU_DATA_ANALYSIS_INTEGRATION.md)) and profile-fit integrated
+([§9](CPU_DATA_ANALYSIS_INTEGRATION.md)); partials are combined into fulls, scaled and merged
+([§10](CPU_DATA_ANALYSIS_INTEGRATION.md)).
+
+**Geometry post-refinement.** From those reflections the detector distance, beam centre and the
+cell scale / rotation axis are refined over all frames at once, each step committed only if it
+improves a held-out residual ([§7.5](CPU_DATA_ANALYSIS_INDEXING.md)).
+
+**Second pass.** The sweep is re-indexed de novo and re-integrated at the refined geometry; this
+pass is the canonical output, and a guard compares the two passes and keeps the better one
+(reported as `PASS=` / `PASS_DECISION=` in [the report](RUGNUX_REPORT.md)).
+
+**Space group.** On the P1 merge of the final pass, the point group is scored operator by operator
+on resolution-normalised intensities and the screw axes and centring are read from the systematic
+absences ([§13.1](CPU_DATA_ANALYSIS_DECISIONS.md)); twinning is checked beside it
+([§13.2](CPU_DATA_ANALYSIS_DECISIONS.md)). `CANNOT_DETERMINE` and an enantiomorphic pair are real
+answers here, not evasions.
+
+**Scale and merge.** In the determined group: per-frame scales, the cross-validated correction
+surfaces (decay, absorption, modulation), the error model and ISa, outlier rejection, the
+CC½-based resolution cut, the anisotropy description, French–Wilson amplitudes and the R-free
+flags ([§10](CPU_DATA_ANALYSIS_INTEGRATION.md),
+[§13.3–§13.5](CPU_DATA_ANALYSIS_DECISIONS.md)).
+
+**Write.** The merged `.mtz` / `.cif` / `.hkl`, the unmerged MTZ, the P1 cross-check and the
+results report land next to each other ([Output files](RUGNUX_TUTORIAL.md#output-files)); with
+`--model`, validation runs first and the maps are written too
+([§14](CPU_DATA_ANALYSIS_DECISIONS.md)).
+
+**Stills instead.** Serial data skip the two-pass machinery: each image is indexed independently
+(with the known-cell `ffbidx` indexer where a cell is given), partiality comes from a per-crystal
+orientation-tilt post-refinement rather than a rocking curve, and a merohedral indexing ambiguity
+has to be broken per image, at integration time, against a reference or a model
+([Advanced ▸ the indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity)).

docs/index.rst

@@ -19,6 +19,7 @@ Jungfraujoch is distributed under the GPLv3 license.
    :caption: rugnux — data processing
 
    RUGNUX
+   RUGNUX_OVERVIEW
    RUGNUX_INSTALL
    RUGNUX_FORMATS
    RUGNUX_TUTORIAL