@@ -39,7 +39,19 @@ Particles that were already decayed by the generator, or that are not flagged fo
 | `EventDecayer.g4ParticleTable` | empty | optional Geant4 particle table, written by `o2-sim-g4-particle-table`, to report particles unknown to Geant4 |
 | `EventDecayer.verbose`, `showChanged` | `false` | Pythia8 printout |
 
-Which species are decayed, and through which channels, is set in Pythia8's own terms: `id:mayDecay`, `id:onMode`, `id:oneChannel`, `id:addChannel` and so on. `base.cfg` keeps K0S, Λ, Σ±, Ξ and Ω (and other species Geant4 must transport) stable. A request that wants to decay, say, charm baryons switches them on, for example with `4232:mayDecay = on`.
+## Which particles are decayed
+
+The step decays a particle only if it is flagged for transport, Pythia8 may decay it (`id:mayDecay = on`), its `tau0` is at most `EventDecayer.tau0Max`, and it is not listed in `EventDecayer.skipPdg`. Everything else reaches Geant4 unchanged. The channels are set in Pythia8's own terms (`id:onMode`, `id:oneChannel`, `id:addChannel`, ...), so a request's forced-decay config works for the step as it does for the external decayer.
+
+Long-lived particles such as K0S, Λ, Σ±, Ξ and Ω are never decayed by the step, for two independent reasons. `base.cfg`, which is read first, sets `mayDecay off` for them, and the default `tau0Max` of 10 mm/c excludes them anyway (cτ is about 27 mm for K0S, 79 mm for Λ, 49 mm for Ξ⁻ and 24 mm for Ω⁻). They are therefore transported by Geant4 as before, with their hits, their bending in the field and their interactions with the material, which strangeness tracking and efficiency studies need. A request does not need to add `ParticleDecays:limitTau0` or `tau0Max` to its own config; a positive `EventDecayer.tau0Max` takes precedence over a `tau0Max` in a config file.
+
+The same keys also allow decaying such particles in the generator, by setting `mayDecay on` and raising or disabling `tau0Max`. Do this only for generator-level studies without transport (`o2-sim --noGeant`). With transport it is wrong, because the step places the decay point on a straight line from the production vertex and knows nothing about the detector: the particle would leave no hits, would not bend or interact, and its daughters would become generator primaries, which changes their physical-primary classification.
+
+`base.cfg` also keeps the weakly decaying charm baryons stable, because the external decayer receives them from Geant4 one at a time. A request that wants the step to decay them switches them on. For Ξc⁰, Ξc⁺ and Ωc⁰ the O2DPG file `MC/config/PWGHF/pythia8/decayer/eventdecayer_charmbaryon.cfg` ([O2DPG PR 2518](https://github.com/AliceO2Group/O2DPG/pull/2518)) does this, next to the usual forced channels:
+
+```bash
+--configKeyValues "DecayerPythia8.config[1]=${O2DPG_MC_CONFIG_ROOT}/MC/config/PWGHF/pythia8/decayer/force_hadronic_charmbaryon.cfg;EventDecayer.enable=true;EventDecayer.config[2]=${O2DPG_MC_CONFIG_ROOT}/MC/config/PWGHF/pythia8/decayer/eventdecayer_charmbaryon.cfg"
+```
 
 The default `skipPdg` holds the resonances for which O2 defines its own Geant4 decay modes (`115 225 335 10221 10331 20223 20333 102132 102134 9010221`, among them Λ(1520) and f0(980)). They are kept in the MC truth but decayed by Geant4. A request that wants Pythia8 to decay them overrides the list.
 
@@ -48,6 +60,7 @@ At the end of the run the step prints a summary: decayed and failed decays per s
 ## Things to know
 
 - Pythia8's vertex-limit settings `ParticleDecays:limitTau`, `limitRadius` and `limitCylinder` are refused; only the species-level `limitTau0`/`tau0Max` is supported.
-- A decay that would produce partons (e.g. some quarkonium decays) is not performed; the particle is left to Geant4 as before.
+- No parton is ever handed to the transport. A decay into partons (e.g. some quarkonium decays) is either hadronised by Pythia8 itself (recent Pythia8 versions) or, if partons remain, not performed, and the particle is left to Geant4 as before.
+- To check in an AOD who decayed a particle, use the `producedByGenerator()` accessor of `McParticles`: products of the step are generator particles, while the daughters of particles decayed by Geant4 are not. Reading the raw `fFlags` column (e.g. with `RDataFrame`) can return it as a boolean and is not reliable for this.
 - The decay products are primaries, so all their transport secondaries are stored. For an HF event pool this made the Kine files about 0.6% larger.
 - The lifetimes of several charm and beauty hadrons in Pythia8's defaults are older measurements; `base.cfg` sets the PDG values for them.