gammasim · GernotMaier · Jan 21, 2026 · Jan 20, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/docs/changes/1991.doc.md b/docs/changes/1991.doc.md
@@ -0,0 +1 @@
+Improve documentation for CORSIKA and related container images.
diff --git a/docs/source/components/corsika.md b/docs/source/components/corsika.md
@@ -1,8 +1,46 @@
 # Air shower simulations with CORSIKA
 
-- [CORSIKA 7](https://www.iap.kit.edu/corsika/): Simulates extensive air showers.
-- [corsika-opt-patches](https://gitlab.cta-observatory.org/cta-computing/dpps/simpipe/corsika-opt-patches): Vectorized performance-optimized patches for Cherenkov light generation in propagation in CORSIKA.
+simtools uses CORSIKA 7, a detailed Monte Carlo simulation framework for extensive air showers initiated by high-energy cosmic rays. This includes the generation and propagation of Cherenkov light.
 
-```{warning}
-Incomplete documentation - missing references
+References:
+
+- [CORSIKA 7 homepage at (KIT)](https://www.iap.kit.edu/corsika/)
+- [CORSIKA 7 gitlab (KIT)](https://gitlab.iap.kit.edu/AirShowerPhysics/corsika-legacy/corsika7) (access restricted)
+- [Heck, D. et al, CORSIKA: A Monte Carlo code to simulate extensive air showers, FZKA 6019 (1998)](https://www.iap.kit.edu/corsika/).
+
+## Building CORSIKA for simtools
+
+CORSIKA 7 is built using the CORSIKA `coconut` build system:
+
+```bash
+./coconut --expert --without-root \
+    --without-COASTUSERLIB --without-conex < /dev/null; \
 ```
+
+Build configurations are provided by the [CTAO corsika7-config](https://gitlab.cta-observatory.org/cta-computing/dpps/simpipe/simulation_software/corsika7-config) repository.
+Each supported CORSIKA release has dedicated configuration files, including variants for flat and curved atmospheric geometries.
+
+### CPU vectorization
+
+Patches to CORSIKA to make use of CPU vectorization for Cherenkov light generation are available from the [CTAO corsika-opt-patches](https://gitlab.cta-observatory.org/cta-computing/dpps/simpipe/simulation_software/corsika-opt-patches) repository.
+Patches are version-specific and currently available only for flat-atmosphere configurations.
+
+References:
+
+- [Arrabito, L. et al, Optimizing Cherenkov photons generation and propagation in CORSIKA for CTA Monte-Carlo simulations, arXiv:2006.14927](https://arxiv.org/abs/2006.14927)
+
+## CORSIKA interaction tables
+
+CORSIKA requires precomputed interaction tables for the supported physics models, including:
+
+- EGS4 (electromagnetic)
+- URQMD (low-energy hadronic)
+- EPOS (low-/high-energy hadronic)
+- QGSJET-II/III (high-energy hadronic)
+- further models will be added as needed in future releases
+
+For efficiency, interaction tables are distributed separately from the executables and must be installed manually.
+
+Tables are provided by the CTAO repository: [CTAO corsika7-interaction-tables repository](https://gitlab.cta-observatory.org/cta-computing/dpps/simpipe/simulation_software/corsika7-interaction-tables).
+
+The environment variable `$SIMTOOLS_CORSIKA_INTERACTION_TABLE_PATH` must point to the interaction-tables subdirectory. Follow the repository instructions for download and installation.
diff --git a/docs/source/user-guide/container_images.md b/docs/source/user-guide/container_images.md
@@ -41,6 +41,10 @@ Images are compatible with ARM and x86_64 CPUs.
 
 The `generic` image is compatible with ARM and x86_64 CPUs, all other images are for x86_64 CPUs only.
 
+```{important}
+Container images do not include the interaction tables required by CORSIKA. Follow the instructions in the [CORSIKA documentation](../components/corsika.md#corsika-interaction-tables) to download and install the interaction tables.
+```
+
 ### sim_telarray Images
 
 - registry page: [sim_telarray](https://github.com/gammasim/simtools/pkgs/container/sim_telarray)

diff --git a/docs/source/user-guide/getting_started.md b/docs/source/user-guide/getting_started.md
@@ -17,9 +17,7 @@ simtools can be installed using one of the following methods:
 OCI-compatible container images are available for simtools users and support both application and development use cases.  Any runtime such as [Docker](https://www.docker.com/products/docker-desktop), [Podman](https://podman.io/), or [Apptainer](https://apptainer.org/) can be used.
 These images eliminate all manual installation steps and allow direct execution of simtools applications.
 
-The most important types of images are:
-
-### Pre-built Images
+The most important types of images are list below; for a complete overview, see the [Container Images](container-images) documentation.
 
 - **Simtools Production images** ([simtools-prod](https://github.com/gammasim/simtools/pkgs/container/simtools-sim-telarray-250903-corsika-78010-bernlohr-1.70-prod6-baseline-qgs3-no_opt)): Include CORSIKA, sim_telarray, and simtools applications. Variants are available with:
   - Different CORSIKA/sim_telarray versions
@@ -30,6 +28,10 @@ The most important types of images are:
 Pre-built images are hosted on the [simtools package registry](https://github.com/orgs/gammasim/packages?repo_name=simtools). Authentication may be required; follow [GitHub's guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) to configure access (`docker login`).
 
 
+```{important}
+Container images do not include the interaction tables required by CORSIKA. Follow the instructions in the [CORSIKA documentation](../components/corsika.md#corsika-interaction-tables) to download and install the interaction tables.
+```
+
 ### Running a simtools Production Image
 
 **Prerequisite**: Configure [simulation model database access](model-database-access).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Improve documentation for CORSIKA and related container images.