Update docs. Add cmtc install/cmta new command reference doc

docs/reference-cmta.md

@@ -14,6 +14,7 @@ The available commands and their function is as follows:
 - [`delinearize            `](#cmta-delinearize): reflect the changes made in a linearized artifact back into the corresponding main repository
 - [`renumber-exercises     `](#cmta-renumber-exercises): renumber exercises in a main repository
 - [`duplicate-insert-before`](#cmta-duplicate-insert-before): duplicate a selected exercise in a main repository and insert it before that exercise
+- [`new                    `](#cmta-new): create a new main repository from a Github template
 
 The remainder of this section describes these commands in further detail.
 
@@ -171,4 +172,55 @@ The following options are available:
 
     **-c**: Specify an alternative CMT configuration file.
 
+    **-h**: Print command-specific help.
+
+### cmta new
+
+#### Synopsys
+
+`   cmta new [-h] -t <template repository reference>`
+
+#### Description
+
+Create a main CMT repository from a given template repository on Github. The template repository can be
+any regular main CMT repository on Github.
+
+The template repository reference is composed of the name of the repository and the Github organisation.
+
+Following is an example of an invocation of the `cmta new` command that is creating a new CMT main repo
+based on the [lunatech-scala-2-to-scala3-course](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course) Github repository:
+
+```bash
+$ cmta new -t lunatech-labs/lunatech-scala-2-to-scala3-course
+Cloning into 'lunatech-scala-2-to-scala3-course'...
+Project:
+   lunatech-labs/lunatech-scala-2-to-scala3-course/3.0.0-v1
+successfully installed to:
+   /Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/lunatech-scala-2-to-scala3-course
+```
+
+It is also possible to create a new repo from a specific, existing release:
+
+```bash
+$ cmta new -t lunatech-labs/lunatech-scala-2-to-scala3-course/0.27.0-RC1-v0
+Cloning into 'lunatech-scala-2-to-scala3-course'...
+Project:
+   lunatech-labs/lunatech-scala-2-to-scala3-course/0.27.0-RC1-v0
+successfully installed to:
+   /Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/lunatech-scala-2-to-scala3-course-2
+```
+
+When a project is passed without specifying a Github organisation, the project name will be prepended with `cmt-template-` and the most recent version of the project will be fetched from the `lunatech-labs` github organisation. To illustrate this, the following example launches the `cmta new` command passing `scala` as the template name. As a result the newest version (`1.0.0`) of the `lunatech-labs/cmt-template-scala` repo will be used to create a new course.
+
+```bash
+$ cmta new -t scala
+Cloning into 'cmt-template-scala'...
+Project:
+   lunatech-labs/cmt-template-scala/1.0.0
+successfully installed to:
+   /Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/scala
+```
+
+The following options are available:
+
 &nbsp;&nbsp;&nbsp;&nbsp;**-h**: Print command-specific help.

docs/reference-cmtc.md

@@ -28,6 +28,7 @@ The available commands and their function is as follows:
 - [`save-state`](#cmtc-save-state): save the state of th current exercise
 - [`list-saved-states`](#cmtc-list-saved-states) : list all previously saved exercise states
 - [`restore-state`](#cmtc-restore-state) : restore a previously saved state
+- [`install`](#cmtc-install) : restore a previously saved state
 
 The remainder of this section describes these commands in further detail.
 
@@ -318,3 +319,90 @@ the use-case for this command, read the section of [`cmtc pull-solution`](#cmtc-
 The following option is available:
 
     **-h**: Print command-specific help.
+
+### cmtc install
+
+#### Synopsys
+
+`cmtc install [-h] -s <studentified repo reference>`
+
+#### Description
+
+Installs a course from a studentified artifact and set it as the default course for subsequent
+`cmtc` command invocations. The studentified repo reference can one of three different forms:
+
+- A zipped version of a studentified course.
+- A folder containing the studentified course.
+- A published [studentified] release of a course.
+
+In the first two cases, the user (student) already has a local, zipped or unzipped copy of a
+studentified course.
+For the third case, the author of the course has published a release in a Github repository,
+most likely via some form of automation (eg. CI using Github Actions), and following a specific
+naming convention for the zipped studentified course artifact.
+
+Following are examples of invocations of the `cmtc install` command for each of the above
+cases:
+
+##### Install from zip archive
+
+```
+$ ls -l ~/Downloads/lunatech-scala-2-to-scala3-course-student.zip
+-rw-r--r--@ 1 ericloots  staff  696763  7 Jul 09:56 /Users/ericloots/Downloads/lunatech-scala-2-to-scala3-course-student.zip
+
+$ (cd ~/Downloads;cmtc install -s lunatech-scala-2-to-scala3-course-student.zip)
+Unzipped 'lunatech-scala-2-to-scala3-course-student.zip' to '/Users/ericloots/Library/Caches/com.lunatech.cmt/Courses'
+Current course set to '/Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/LSL-P-lightbend-scala-language-professional'
+
+Exercises in repository:
+  1.  *   exercise_000_initial_state
+  2.      exercise_001_define_a_class
+  3.      exercise_002_define_class_parameters
+  4.      exercise_003_promote_class_parameters
+  5.      exercise_004_define_a_field
+  6.      exercise_005_define_a_method
+  <elided>
+
+```
+
+##### Install from a folder
+
+```
+$ ls -ld ~/Downloads/lunatech-scala-2-to-scala3-course
+drwxr-xr-x@ 7 ericloots  staff  224 11 Mar 19:08 /Users/ericloots/Downloads/lunatech-scala-2-to-scala3-course
+
+$ (cd ~/Downloads;cmtc install -s lunatech-scala-2-to-scala3-course)
+$ cmtc install -s LSL-P-lightbend-scala-language-professional
+Current course set to '/Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/LSL-P-lightbend-scala-language-professional'
+
+Exercises in repository:
+  1.  *   exercise_000_initial_state
+  2.      exercise_001_define_a_class
+  3.      exercise_002_define_class_parameters
+  4.      exercise_003_promote_class_parameters
+  5.      exercise_004_define_a_field
+  6.      exercise_005_define_a_method
+  <elided>
+```
+
+##### Install from a published release on Github
+
+```bash
+$ cmtc install -s lunatech-labs/lunatech-scala-2-to-scala3-course
+downloading studentified course from 'https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course/releases/download/3.0.0-v1/lunatech-scala-2-to-scala3-course-student.zip' to courses directory
+lunatech-scala-2-to-scala3-course (3.0.0-v1) successfully installed to /Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/lunatech-scala-2-to-scala3-course
+Current course set to '/Users/ericloots/Library/Caches/com.lunatech.cmt/Courses/LSL-P-lightbend-scala-language-professional'
+
+Exercises in repository:
+  1.  *   exercise_000_initial_state
+  2.      exercise_001_define_a_class
+  3.      exercise_002_define_class_parameters
+  4.      exercise_003_promote_class_parameters
+  5.      exercise_004_define_a_field
+  6.      exercise_005_define_a_method
+  <elided>
+```
+
+The following option is available:
+
+&nbsp;&nbsp;&nbsp;&nbsp;**-h**: Print command-specific help.