Document how to combine a CAD module with built-in detectors

Detectors/CADSupport/README.md

@@ -188,6 +188,11 @@ volume; `barrel` sits at (0, −30, 0) in the cave. `placement` is given in cm a
 anchor's frame. Several modules, each from its own `geom.C`, can be listed together: the loader compiles
 each macro into its own namespace, so their identical function names do not collide.
 
+A custom `--detectorList` replaces the official list. To combine a CAD module with built-in
+detectors, list them all in the same file, for example
+`{ "EXTCAD": ["A3IP", "TRK", "FT3", "TF3", "EOS"] }`, and do not pass `-m`. Entries can be copied from
+`$O2_ROOT/share/config/o2simdefaultdetectorlist.json`.
+
 ## Sensitive external detectors
 
 Use an `externalDetectors` array. It takes the same fields as a module, plus `detID` and at least

Detectors/CADSupport/doc/tutorial/docs/limits.md

@@ -9,6 +9,7 @@ rediscover in a result.
 | One `geom.C` per hooked thing | The macro exports a single builder hook, and that hook is what the JSON refers to. | Run the converter once per subsystem, into its own folder. They coexist happily in one JSON. |
 | Media, cuts and field default to zero | A CAD file carries a material, never a medium, and the emitter uses a three-argument `TGeoMedium` which zeroes every parameter. | Pass `--in-field`. Accept transport defaults for step control, and treat production cuts as unset until you write a real detector. |
 | The anchor volume must already exist | Placement is expressed inside the frame of an existing O2 volume. | Use `barrel` unless you have a reason not to, and remember it sits at cave `(0, -30, 0)`. |
+| A custom detector list does not extend an official one | `--detectorList NAME:file.json` takes the modules from that file alone, and `-m` can only select from it. | Copy the built-in entries you want into the same list as your CAD module, see [Add passive geometry](passive.md#combine-it-with-the-built-in-detectors). |
 | Free-form surfaces stay tessellated | Genuine B-spline *surfaces* are not supported by the exact tier at all. | Check the surface report. Recognition already recovers quadrics written as NURBS, which is the large majority of them. |
 | Illegal overlaps in the CAD model | Engineering assemblies are not drawn as legal transport worlds, and parts routinely interpenetrate. | Read `CheckOverlaps`, then fix in CAD or clip the offending region. |
 | Degenerate facets at coarse precision | `O2Tessellated` drops triangles that collapse to a line. | Treat it as a mesh-quality signal: lower `--mesh-prec`, or move the part onto an exact tier. |

Detectors/CADSupport/doc/tutorial/docs/passive.md

@@ -56,3 +56,30 @@ Setting special cuts for passive module EXCV
 
 Those three lines mean your CAD geometry is in the simulation and particles are being transported
 through it. You can list as many modules in the same array as you like.
+
+## Combine it with the built-in detectors
+
+A custom `--detectorList` replaces the official list, it does not extend it. `o2-sim` takes the
+module set from the one list you name, and `-m` may only select from that set. To simulate your CAD
+module together with, say, the ALICE 3 detectors, put all of them in the same list:
+
+`detectorlist.json`
+
+```json
+{ "EXTCAD": ["A3IP", "TRK", "FT3", "TF3", "EOS"] }
+```
+
+```bash
+o2-sim-serial-run5 -n 1 -g boxgen \
+    --detectorList EXTCAD:detectorlist.json \
+    --extGeomFile externalGeometry.json
+```
+
+Here `EOS` is the `name` of the module in `externalGeometry.json`. Leave `-m` out, so that every
+module in the list is active. If you pass `-m A3IP TRK` together with a list that does not contain
+them, you get `Modules specified that are not present in detector list`.
+
+- Copy the entries of the official list you want from `$O2_ROOT/share/config/o2simdefaultdetectorlist.json`.
+- Use `o2-sim-serial-run5` (or `o2-sim-run5`) for ALICE 3 modules, and `o2-sim-serial` for Run 3 ones.
+- Switch a module off by removing it from the list, or with `--skipModules`.
+- The cave is always built, so `barrel` stays a valid anchor.