Add readme (#42)

Author: FaustXVI

example/README.md

@@ -0,0 +1,15 @@
+# Exploitation repository for [O.R.CA](https://github.com/eove/orca)
+
+This repository uses [O.R.CA unstable](https://eove.github.io/orca/unstable) as written in the [flake.nix](./flake.nix) file
+
+The documentation is present in the `docs` folder as markdown files.
+
+You can open it locally in a web browser on your machine by running the following command:
+```bash
+nix develop --command mdbook build --open
+```
+
+> [!Note]  
+> The nix shell provided in the flake besides this readme automatically makes `mdbook` available to you
+
+That documentation will guide you on how to use this repository and O.R.CA.

example/docs/offline_vault_ceremony.md

@@ -50,17 +50,17 @@ The 📢`organiser` should communicate to all 👥`team members` the list of ope
 
 #### Configuring the ceremony
 
-The 📢`organiser` should know which environment will be worked on (`prod`/`preprod`), modify the value of `orca.environment-target` in [orca-config.nix](../../orca-config.nix) accordingly, and notify this environment to all 👥`team members`.
+The 📢`organiser` should know which environment will be worked on (`prod`/`preprod`), modify the value of `orca.environment-target` in orca-config.nix accordingly, and notify this environment to all 👥`team members`.
 
-The 📢`organiser` should get the value of the *C<sub>vault</sub>* present in the last report and set the value of `orca.latest_cvault` in [orca-config.nix](../../orca-config.nix) accordingly. If the ceremony is the first one for this environment, then `null` should be set. It is recommended that the 📢`organiser` verifies the validity of the report in the same way the 👥`team members` [will do during the verification phase](#verification-of-the-last-ceremonys-report).
+The 📢`organiser` should get the value of the *C<sub>vault</sub>* present in the last report and set the value of `orca.latest_cvault` in orca-config.nix accordingly. If the ceremony is the first one for this environment, then `null` should be set. It is recommended that the 📢`organiser` verifies the validity of the report in the same way the 👥`team members` [will do during the verification phase](#verification-of-the-last-ceremonys-report).
 
-The 📢`organiser` should know what will be done during the ceremony and set the values of `orca.actions_in_order` and `orca.rotate_keys` in [orca-config.nix](../../orca-config.nix) accordingly.
+The 📢`organiser` should know what will be done during the ceremony and set the values of `orca.actions_in_order` and `orca.rotate_keys` in orca-config.nix accordingly.
 
 #### Updating the version of the offline vault
 
 The software we are using to run the *ephemeral vault* should not be obsolete (to allow for smooth migration of data, and avoid any unpatched security weakness).
 
-Check if there is any new stable release that is more recent than what is specified in the exploitation repository's [flake.nix](../../../flake.nix)'s `inputs.nixpkgs.url` and `inputs.orca.url` . If so, we should upgrade to the lastest stable release.
+Check if there is any new stable release that is more recent than what is specified in the exploitation repository's flake.nix's `inputs.nixpkgs.url` and `inputs.orca.url` . If so, we should upgrade to the lastest stable release.
 
 Otherwise update the `flake.lock` to the most up-to-date packages by running:
 ```bash

example/docs/periodical_checks.md

@@ -87,7 +87,7 @@ Where:
 * `[email protected]` is the email address of the owner of this hardware token
 * `serial` is the serial number of the hardware token (as displayed, for example using `gpg --card-status`)
 
-Once all relevant GPG keys have been renewed and their public key commited to the repository, a key rotation should be run in a ceremony for the offline vault. This is done by setting `rotate_keys` to `true` in [the orca config file](../../orca-config.nix).
+Once all relevant GPG keys have been renewed and their public key commited to the repository, a key rotation should be run in a ceremony for the offline vault. This is done by setting `rotate_keys` to `true` in the orca-config.nix file.
 
 An unseal share rotation should be run also on the online vault.
 

flake.nix

@@ -94,6 +94,7 @@
             done
             sed -i s@github:eove/orca@github:eove/orca/$VERSION@g example/flake.nix
             sed -i s@github:eove/orca@github:eove/orca/$VERSION@g docs/README.md
+            sed -i "[email protected] [email protected] ''${VERSION}@g" example/README.md
             '';
           html-to-pdf = pkgs.writeShellScriptBin "html-to-pdf" ''
               if [ "$#" -lt 2 ]; then