docs: improve template & secrets

clanModules/root-password.nix

@@ -12,7 +12,7 @@
       mkpasswd
     ];
     generator.script = ''
-      xkcdpass -c 3 -d -  > $secrets/password
+      xkcdpass --numwords 3 --delimiter - --count 1 > $secrets/password
       cat $secrets/password | mkpasswd -s -m sha-512 > $secrets/passwordHash
     '';
   };

docs/admins/01-quickstart.md

@@ -114,7 +114,7 @@ On the remote execute:
 Ready to expand? Explore how to install a new machine with the helpful documentation [here](./02-machines.md).
 Ready to explore more?
 
-- **Adding New Machines to your setup**. [Following our template](/templates/new-clan/flake.nix)
+- **Adding New Machines to your setup**. [Following our templates](./99-templates.md)
 
 - **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how] (./02-machines.md).
 

docs/admins/02-machines.md

@@ -2,29 +2,30 @@
 
 Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations.
 
-We'll walk you through adding a new computer to your Clan using a special tool that works through a USB stick.
+We'll walk you through adding a new computer to your Clan.
 
 ## Installing a New Machine
 
 Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.
+
 This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
 
 ### Step 0. Prerequisites
 
-Boot the target machine using our [Installer](./03-Installer.md). Recommended for the most efficient workflow.
+Boot the target machine using our [Clan Installer](./03-Installer.md). Which is recommended for ensuring most efficient workflows.
 
 Alternatively you can use any linux machine if it is reachable via SSH and supports `kexec`.
 
-Confirm the machine is reachable via SSH from your main computer.
+Confirm the machine is reachable via SSH from your setup computer.
 
 ```bash
 ssh root@<your_target_machine_ip>
 ```
 
-- [x] Two Computers: You'll need the computer you're setting up and another one to control the setup process. Both should be able to connect over the network using SSH. This is usually already done if you're working with servers from providers like Hetzner.
-- [x] A clan machine configuration you want to deploy. [Check out our templates](/templates/new-clan/flake.nix)
-- [x] Initialized secrets: See [secrets](./06-secrets.md) for how to generate your secrets.
-- [x] (Optional) USB Flash Drive with our [Installer](./03-Installer.md)
+- [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
+- [x] **Machine configuration**: You want to deploy. [Check out our templates](./99-templates.md)
+- [x] Initialized secrets: See [secrets](./06-secrets.md) for how to initialize your secrets.
+- [x] (Optional) USB Flash Drive with the [Clan Installer](./03-Installer.md)
 
 ### Step 1. Identify Target Disk-ID
 

docs/admins/06-secrets.md

@@ -2,81 +2,53 @@
 
 Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
 
-This documentation will guide you through managing secrets with the Clan CLI,
-which utilizes the [sops](https://github.com/getsops/sops) format and
-integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
+Clan utilizes the [sops](https://github.com/getsops/sops) format and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
 
-## 1. Generating Keys and Creating Secrets
+This documentation will guide you through managing secrets with the Clan CLI
 
-To begin, generate a key pair:
+## 1. Initializing Secrets
 
-```shellSession
-$ clan secrets key generate
+### Create Your Master Keypair
+
+To get started, you'll need to create **Your master keypair**.
+
+Don't worry — if you've already made one before, this step won't change or overwrite it.
+
+```bash
+clan secrets key generate
 ```
 
 **Output**:
 
-```
+```bash
 Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7
-Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user.
+
 Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets.
 Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
 ```
 
-⚠️ **Important**: Backup the generated private key securely, or risk losing access to your secrets.
+⚠️ **Important**: Make sure to keep a safe backup of the private key you've just created.
+If it's lost, you won't be able to get to your secrets anymore because they all need the master key to be unlocked.
 
-> Note: All generated secrets that the `clan CLI` places in your repository are safe to be commit into version control (i.e. with `git`).
+> Note: It's safe to add any secrets created by the clan CLI and placed in your repository to version control systems like `git`.
 
-Next, add your public key to the Clan flake repository:
+### Add Your Public Key
 
-```shellSession
-$ clan secrets users add <your_username> <your_public_key>
+```bash
+clan secrets users add <your_username> <your_public_key>
 ```
 
-Doing so creates this structure in your Clan flake:
+⚠️ **Important**: Choose the username same username as on your Setup/Source Machine that you use to control the deployment with.
 
-```
+Once run this will create the following files:
+
+```bash
 sops/
 └── users/
     └── <your_username>/
         └── key.json
 ```
 
-Now, to set your first secret:
-
-```shellSession
-$ clan secrets set mysecret
-Paste your secret:
-```
-
-Note: As you type your secret, keypresses won't be displayed. Press Enter to save the secret.
-
-Retrieve the stored secret:
-
-```shellSession
-$ clan secrets get mysecret
-```
-
-And list all secrets like this:
-
-```shellSession
-$ clan secrets list
-```
-
-Secrets in the repository follow this structure:
-
-```
-sops/
-├── secrets/
-│   └── <secret_name>/
-│       ├── secret
-│       └── users/
-│           └── <your_username>/
-```
-
-The content of the secret is stored encrypted inside the `secret` file under `mysecret`.
-By default, secrets are encrypted with your key to ensure readability.
-
 ## 2. Adding Machine Keys
 
 New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
@@ -91,6 +63,8 @@ For existing machines, add their keys:
 $ clan secrets machines add <machine_name> <age_key>
 ```
 
+### Advanced
+
 To fetch an age key from an SSH host key:
 
 ```shellSession
@@ -111,9 +85,36 @@ You can add machines/users to existing secrets without modifying the secret:
 $ clan secrets machines add-secret <machine_name> <secret_name>
 ```
 
-## 4. Utilizing Groups
+## 4. Adding Secrets
 
-For convenience, Clan CLI allows group creation to simplify access management. Here's how:
+```shellSession
+$ clan secrets set mysecret
+Paste your secret: 
+```
+
+> Note: As you type - your secret won't be displayed. Press Enter to save the secret.
+
+## 5. Retrieving Stored Secrets
+
+```shellSession
+$ clan secrets get mysecret
+```
+
+### List all Secrets
+
+```shellSession
+$ clan secrets list
+```
+
+## 6. Groups
+
+Clan CLI makes it easy to manage access by allowing you to create groups.
+
+All users within a group inherit access to all secrets of the group.
+
+This feature eases the process of handling permissions for multiple users.
+
+Here's how to get started:
 
 1. **Creating Groups**:
 
@@ -135,7 +136,24 @@ For convenience, Clan CLI allows group creation to simplify access management. H
    $ clan secrets groups add-secret <group_name> <secret_name>
    ```
 
-# NixOS integration
+## Further
+
+Secrets in the repository follow this structure:
+
+```bash
+sops/
+├── secrets/
+│   └── <secret_name>/
+│       ├── secret
+│       └── users/
+│           └── <your_username>/
+```
+
+The content of the secret is stored encrypted inside the `secret` file under `mysecret`.
+
+By default, secrets are encrypted with your key to ensure readability.
+
+### NixOS integration
 
 A NixOS machine will automatically import all secrets that are encrypted for the
 current machine. At runtime it will use the host key to decrypt all secrets into
@@ -157,7 +175,7 @@ can get a path to secrets like this `config.sops.secrets.<name>.path`. Example:
 See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more
 examples.
 
-# Importing existing sops-based keys / sops-nix
+### Migration: Importing existing sops-based keys / sops-nix
 
 `clan secrets` stores each secrets in a single file, whereas [sops](https://github.com/Mic92/sops-nix)
 commonly allows to put all secrets in a yaml or json documents.

docs/admins/99-templates.md

@@ -0,0 +1,13 @@
+# 99 Templates
+
+We provide some starting templates you can easily use one of those via `nix flakes`.
+
+They showcase best practices and guide you through setting up and using Clan's modules
+
+To use the `new-clan` template run the following command:
+
+`nix flake init -t git+https://git.clan.lol/clan/clan-core#new-clan`.
+
+## Available Templates
+
+- **new-clan**:  Perfect for beginners, this template shows you how to link two machines in a basic setup.