diff --git a/COLLABORATION_AGREEMENT.md b/COLLABORATION_AGREEMENT.md
index fc0be784f529af168ac777c57eeaa8b07c5891f7..bdc9bdf9e5aa3406e6eb6208ad31d481ba3c7c6b 100644
--- a/COLLABORATION_AGREEMENT.md
+++ b/COLLABORATION_AGREEMENT.md
@@ -13,7 +13,7 @@ examples of other big scientific software projects.
 
 The CORSIKA project consists of the contributions from the scientific
 community and individuals in a best effort to deliver the best
-possible computing performance and physics output. 
+possible performance and physics output. 
 The MCnet guidelines developed by [www.montecarlonet.org](www.montecarlonet.org) 
 are copied in [MCNET_GUIDELINES](MCNET_GUIDELINES) -- they provide a very good 
 additional scope that contributors should read and consider. 
@@ -27,78 +27,36 @@ The license adopted for the CORSIKA project is the explicit copyleft
 license GPLv3, as copied in full in the file
 [LICENSE](LICENSE). Each source file of the CORSIKA project contains a
 short statement of the copyright and this license. Each binary or
-source code release of CORSIKA must contain the file LICENSE. The
+source code release of CORSIKA contains the file LICENSE. The
 code, documentation and content in the folder [ThirdParty](ThirdParty)
 is not integral part of the CORSIKA project and can be based on, or
 include, other licenses, which must be compatible with GPLv3. Check the
 content of this folder for details and additional license information. It depends on the configuration of
 the build system to what extend this code is used to build CORSIKA.
 
-## Who is the "copyright holder"
-For legal reasons and the ability to maintain the CORSIKA project
-effectively over a very long lifespan of several decades, all
-contributors are required to transfer their copyright to the CORSIKA
-Project. Of course you will be duly credited and your name will appear
-on the contributors page and in the [AUTHORS](AUTHORS) file shipped
-with every binary and source distribution. The copyright transfer is
-necessary to be able to effectively defend the project in case of
-litigation. The copyright holder may change, if decided by the CORSIKA
-Project. The current copyright holder is the CORSIKA Project
-corsika-project@lists.kit.edu, with the current chair person 
-Ralf Ulrich (KIT) ralf.ulrich@kit.edu.
-
-## Definition of a "contributor"
-Contributor is a person of whom at least one merge request was
-accepted for the master branch of the CORSIKA project at
-[https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika).
-All contributors will be co-listed and credited as (software) authors
-of the CORSIKA project, as well as listed indefinitely in the
-[AUTHORS](AUTHORS) file. Contributors should add their name and
-contact data to the [AUTHORS](AUTHORS) file, as part of one of their
-merge requests. This file is always distributed together with all
-source and binary releases.  If you contribute to any non-master
-branch, you can add your name to the [AUTHORS](AUTHORS) file of this
-particular branch, but all official releases are normally performed
-via the master branch.
+
+## Contributing
 
 If you want to contribute, you need to read
 [the GUIDELINES](CONTRIBUTING.md) and comply with these rules, or help to
-improve them.
+improve them. 
 
 
-## The CORSIKA Project panel
-The CORSIKA Project panel makes all decisions for the CORSIKA
-Project. It can also change the
+## The CORSIKA Projects Maintainers
+The CORSIKA Project mainters make all decisions for the CORSIKA
+Project. They can also change the
 [COLLABORATION\_AGREEMENT](COLLABORATION\_AGREEMENT.md), the
 [GUIDELINES](CONTRIBUTING.md) or any other structure or document relevant for the CORSIKA Project.
 
-The CORSIKA Project *panel* consists (October 2018) of
-   
-  * Hans Dembinski (MPG)
-  * Ralph Engel (KIT)
-  * Dieter Heck (KIT)
-  * Tanguy Pierog (KIT)
-  * Maximilian Reininghaus (KIT)
-  * Felix Riehn (LIP)
-  * Ralf Ulrich (KIT)
-  * Darko Veberic (KIT)
-  
-and can be contacted via corsika-project@lists.kit.edu.  The chair
-person of the CORSIKA Project is Ralf Ulrich (KIT). Members of the
-CORSIKA Project *panel* can be *Maintainer* of the CORSIKA Project in
-gitlab at
-[https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika),
-and have special responsibilities also for this reason. 
+The current CORSIKA Project maintainers are listed in the file [MAINTAINERS](MAINTAINERS.md). 
 
-### Changing to a different license, for parts, or the complete project
+and can be contacted via corsika-project@lists.kit.edu.  The chair
+person of the CORSIKA Project is Ralf Ulrich (KIT). Maintainers have special 
+responsibilities for specific parts of the project. 
 
-The CORSIKA Project panel can change the license for parts or the entire project in general or for individual releases.
 
 ### Planning and performing releases
 
-The CORSIKA Project panel decides on releases of the software, and about the content of it. 
+The CORSIKA maintainers decide on releases of the software, and about the content of it. 
 
-### Changes to the Collaboration Agreement
 
-The CORSIKA Project panel decides on changes to the Collaboration
-agreement.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b1b83aea72024e3d0ae78004c4bc7e8593a3839a..000470412f22b17b22b1a38db5176fb2f776b207 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,6 +20,7 @@ change/improve them.
   - Proposed code to close one issue (located in a specific git
     branch) is reviewed, discussed, and eventually merged
     into the master branch to close the issue.
+  - all merge request will undergo a code review, and must be approved before merge, in order to ensure high code qualtiy: [Code Approval Procedure](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/-/wikis/Code-Approval-Procedure)
 
 
 ## Code formatting
@@ -46,35 +47,54 @@ e.g. [link1](https://clangformat.com/) or
 
 While `clang-format` does the structural formatting, we still need to agree on naming conventions:
 
-  - Classes and structs start with capital letters
-  - Class member variables start with "f"
-  - Any static variable has a "g" prefix. A static member variable starts with "fg"
-  - Class member functions start with capital letters
-  - Any class getter begins with "Get", and setter with "Set". Logical getters start with "Is" or "Has".
-  - enums should be "enum class" and start with a capital "E"
-  - Function parameter names start with "v"
+  - Classes and structs start with capital letters ```LikeThis```
+  - Class member variables start non-captial and have a trailing "_" ```likeThis_```
+  - Class member functions start with small letters ```LikeThis::doSomething(...)``` or ```LikeThis::do_something(...)```
+  - Any class setter begins with "set_" ```LikeThis::set_something(...)```
+  - Any class getter is named accoring to its property: ```LikeThis::something()```
+  - Logical getters may start with ```is_``` or ```has_```
+  - enums should be ```enum class``` 
+  - Named variables start with small letter ```likeThis```
+  - types in template definitions start with "T" ```TLikeThis```
+  
+  - use names that explain and document the code, thus for example
+  ``` 
+     TimeType TimeOfIntersection(Line const& line, Plane const& plane) {
+         auto const line_direction = line.GetDirection();     
+         auto const plane_normal = plane.GetNormal();     
+         return plane_normal.dot(plane.GetCenter()-line.GetPosition()) / plane_normal.dot(line_direction);     
+         }
+  ```
+    and not 
+  ```
+       TimeType TimeOfIntersection(Line const& l, Plane const& p) {
+         auto const d = p.GetCenter() - l.GetR0();     
+         auto const v = l.GetV0();     
+         auto const n = p.GetNormal();     
+         auto const c = n.dot(v);    
+         return n.dot(d) / c;     
+         }
+  ```
+    This actually is suffient to document the code, no further comments should be added in such cases. Only if further clarification is needed.  
 
   - We use namespaces to avoid clashes and to structure code
-    - *Everything* is part of the corsika namespace
+    - *Everything* is part of one of those namespaces:
+       - ```corsika::framework```, ```corsika::physics```, or ```corsika::process```
     - All classes and objects are encapsulated into suited sub-namespaces,
-      thus corsika::geometry, corsika::processes, corsika::units, etc.
+      thus ```corsika::framework::geometry```, ```corsika::physics::process```, ```corsika::physics::units```, etc.
     - Namespace names do not use capital letters.  
-    - Every header file is copied during build and install into
-      "include/corsika/[namespace]" which also means, each header file
-      can only provide definitions for a _single_ namespace. It is one
-      main purpose of namespaces to structure the location of header
-      files.
-    - Each header file uses an include protection that includes at
-      least the namespace name, and header file name, thus, `#ifndef
-      __include_geometry_Point_h__` or `#ifndef __geometry_Point_h__`,
-      or similar are acceptable.
-    - Header files should always be included with `<..>`, thus,
-      `#include <corsika/geometry/Point.h>` since the build system
-      will always provide the correct include directives (and files
-      anyway cannot be found in file-system paths, which generally do
-      not follow the namespace naming conventions outlined
-      here).
-
+  - Every header file is located in the source tree in ```include/corsika/[namespace]```, which also means that in almost all cases each header file
+    can only provide definitions for a _single_ namespace. It is one
+    main purpose of namespaces to structure the location of header
+    files.
+  - Each header file uses an include protection ```#pragma once```
+    immediately below the copyright statement.
+  - Header files should always be included with `<..>`, thus,
+    `#include <corsika/geometry/Point.h>` since the build system
+    will always provide the correct include directives (and files
+    anyway cannot be found in file-system paths, which generally do
+    not follow the namespace naming conventions outlined
+    here).
   - Header files are named after the main class (or object) they
     define. This also means each header file name starts with a
     capital letter.
@@ -82,20 +102,24 @@ While `clang-format` does the structural formatting, we still need to agree on n
 
 ## Coding rules
 
-  - Code may not introduce any compiler errors, or warnings (latter: on current CI runners)
-  - All unit tests must succeed at all times. If tests fail, code is not merged.
-  - We use C++17 concepts wherever useful and helpful
+  - Warnings should be fixed, when they appear on the system(s) currently used by the CI, by altering the code unless the warning originates from third-party code and cannot be fixed. In that case, the warning should be locally silenced with appropriate pragmas or by locally turning off warnings for that translation unit. 
+  - All unit tests must succeed on the specified systems/configurations on gitlab-ci. If tests fail, code is not merged.
+  - The unit test code coverage should not decrease due to a new merge request. 
+  - We use C++17 features wherever useful and helpful. 
   - On any major error or malfunction we throw an exception. This is needed and required for complex physics and shower debugging.
   - We never catch exceptions for error handling, there might be very few special exceptions from this. We need to discuss such cases.
-  - Everything that should not change should be `const`
+  - Everything that should not change should be ```const```
   - Everything that does not need to be visible to the outside of a class/struct should be `private` or `protected`
   - We prefer the use of references, wherever useful
-  - There cannot be any pointer in the interface of any class or object
-    exposed to outside users, there might be pointers for very special cases
+  - There cannot be any raw pointer in the interface of any class or object
+    exposed to outside users, there might be (technical) raw pointers for very special cases
     inside of classes.
+  - (member)functions that do something (are not just getters/setters), model actions or transformations, and should therefore be verbs. Classes are nouns.
   - When you contribute new code, or extend existing code, at the same time provide unit-tests for all functionality.
-  - When you contribute new physics algorithms, in addition you also need to provide a validation module
-  - Code must be documented with `doxygen` commands
+  - When you contribute new physics algorithms, in addition you also need to provide a validation module (this is still TBD what exactly this means)
+  - Code must be documented with `doxygen` commands extensively -> MAKE THIS INVESTMENT OF YOUR TIME EARLY, IT REALLY HELPS
+  - There should not be any useless comments in code, in particular absolutely avoid to commit commented-out debug remnants
+  - Add sufficient and meaningful comments to the code (only in English)
   
 ## CMAKE formatting
 
@@ -120,6 +144,8 @@ Since cmake itself lacks structure almost entirely:
   - add plenty of comments to all cmake code
   - use expressive variables and functions
 
+
+
 ## Release versioning scheme
 
 Releases of CORSIKA are thought to be the baseline for larger scale
diff --git a/MAINTAINERS b/MAINTAINERS.md
similarity index 93%
rename from MAINTAINERS
rename to MAINTAINERS.md
index 7abdfeb5062a5e3716cdf975087a81c1fa7d7ed7..85e3786be3061bba45a7e4814bd69c0ce765e300 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS.md
@@ -13,7 +13,7 @@ High performance, GPU:
 - Luisa Arrabito <arrabito@in2p3.fr>, Montpellier
 
 Electromagnetic models, and infrastructure: 
-- Jean-Marco Alameddine <gitlab@gitlab.ikp.kit.edu>, Dortmund
+- Jean-Marco Alameddine <jean-marco.alameddine@udo.edu>, Dortmund
 - Jan Soedingrekso <jan.soedingrekso@tu-dortmund.de>, Dortmund
 - Maximilian Sackel <maximilian.sackel@udo.edu>, Dortmund
 
diff --git a/README.md b/README.md
index 8611b3537851d04ec8f7009c8d297bb877db4bfe..497e4f2396504cae0f2e7f6ff8470bc5008ecd18 100644
--- a/README.md
+++ b/README.md
@@ -13,9 +13,7 @@ compiler optimization. Thus, the most fundamental configuration
 decision of the user must be performed at compile time. At run time
 only specific model parameters can still be changed.
 
-CORSIKA 8 is released under the GPLv3 license. This does not exclude
-that specific CORSIKA 8 versions can be released for specific purposes
-under different licensing. See [license
+CORSIKA 8 is by default released under the GPLv3 license. See [license
 file](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/LICENSE)
 which is part of every release and the source code.
 
@@ -23,7 +21,7 @@ If you use, or want to refer to, CORSIKA 8 please cite ["Towards a Next
 Generation of CORSIKA: A Framework for the Simulation of Particle
 Cascades in Astroparticle Physics", Comput.Softw.Big Sci. 3 (2019)
 2](https://doi.org/10.1007/s41781-018-0013-0). We kindly ask (and
-expect) any relevant improvement or addition to be offered or
+require) any relevant improvement or addition to be offered or
 contributed to the main CORSIKA 8 repository for the benefit of the
 whole community.
 
@@ -33,9 +31,7 @@ guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/CONT
 that fails the review by the CORSIKA author group must be improved
 before it can be merged in the official code base. After your code has
 been accepted and merged you become a contributor of the CORSIKA 8
-project and you should include yourself in the
-[AUTHORS](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/AUTHORS)
-file.
+project (code author). 
 
 IMPORTANT: Before you contribute, you need to read and agree to the
 [collaboration
@@ -48,21 +44,21 @@ which are very useful also for us.
 
 
 ## Get in contact
-  * Connect to https://gitlab.ikp.kit.edu; register yourself and join the "Air Shower Physics" group
+  * Connect to https://gitlab.ikp.kit.edu register yourself and join the "Air Shower Physics" group
   * Connect to corsika-devel@lists.kit.edu (self-register at
     https://www.lists.kit.edu/sympa/subscribe/corsika-devel) to get in
     touch with the project
 
 
-## Installation
+## Prerequisites
 
-CORSIKA 8 is tested regularly at least on gcc7.3.0 and clang-6.0.0.
-Additional software prerequisites: eigen3, boost, cmake, g++, git. 
-However, eigen3 is shipped in ThirdParty directory, so any installation 
-on the system is optional. 
-In case one wants to use Pythia 8 for particle decays or to simulate showers
-in a proton environment, Pythia has to be installed on your system and 
-switched ON in CMakeLists.txt. We test with Pythia version 8.235.
+CORSIKA 8 is tested regularly via gitlab-CI using recent gcc and clang
+versions.  Additional software prerequisites: cmake, g++, git.
+Furthermore, eigen3, boost, catch2, spdlog are shipped in the
+ThirdParty directory, so an installation on the system is optional.
+Also Pythia 8, CONEX and PROPOSAL are distributed in the ThirdParty
+folder. You may also install those packages on your system and use
+those; we test with Pythia version 8.235.
 
 On a bare Ubuntu 18.04, just add:
 ```
@@ -70,9 +66,18 @@ sudo apt install cmake g++ git
 ```
 add ```libeigen3-dev``` if you want to use system version of eigen3.
 
+If you work with FreeBSD, run:
+```
+pkg install git cmake python3 flang
+```
+or add ```boost-libs``` and ```eigen``` if you want to use the system versions. 
+
+## Installation
+
+
 Follow these steps to download and install CORSIKA 8 milestone2
 ```
-git clone https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
+git clone --recursive https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
 cd corsika
 mkdir ../corsika-build
 cd ../corsika-build
@@ -81,7 +86,8 @@ make -j8
 make install
 make test
 ```
-and if you want to see how the first simple hadron cascade develops, see `Documentation/Examples/cascade_example.cc` for a starting point. 
+and if you want to see how the first simple hadron cascade develops, 
+see `Documentation/Examples/cascade_example.cc` for a starting point. 
 
 Run the cascade_example with: 
 ```
@@ -95,6 +101,10 @@ bash share/tools/plot_tracks.sh tracks.dat
 firefox tracks.dat.gif 
 ```
 
+Or also consider the `vertical_eas` example in the same directory, which can 
+be configured with command line options. 
+
+
 ### Generating doxygen documentation
 
 To generate the documentation, you need doxygen and graphviz. On Ubuntu 18.04, do: