diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md
index 41edc66da..900f52387 100644
--- a/docs/admins/migrate.md
+++ b/docs/admins/migrate.md
@@ -1,164 +1,253 @@
-## **Migrating Existing NixOS Configuration Flake to Clan Core**
+# Migrating Existing NixOS Configuration Flake to Clan Core
 
-Transitioning your existing setup to Clan Core is straightforward with these detailed steps. Follow this guide to ensure a smooth migration.
+Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration.
 
+## 0. Prerequisites
 
-### Before You Begin
+### Backup Your Current Configuration
 
-1. **Backup Your Current Configuration**: Start by creating a backup of your existing NixOS configuration. This step is crucial as it ensures you have the option to revert to your original setup if necessary.
+Create a backup of your existing NixOS configuration.
+This step ensures you have the option to revert to your original setup if necessary.
 
-   ```shellSession
-   cp -r /etc/nixos ~/nixos-backup
-   ```
+```bash
+cp -r /etc/nixos ~/nixos-backup
+```
 
-2. **Initialize flake.nix**: If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory:
+## 1. Initialize a flake.nix
 
-   1. **Generate a Trivial flake.nix File**: This creates a basic `flake.nix` file that you can later customize for your project.
+If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory.
 
-      ```bash
-      cd /etc/nixos && nix flake init -t github:NixOS/templates#trivial
-      ```
+> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
 
-   2. **Initialize a Git Repository (if necessary)**: If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
+### Generate a Trivial flake.nix File
 
-      ```bash
-      git init
-      ```
+This creates a basic `flake.nix` file that you can later customize for your project.
+  
+Create a place for your system configuration if you don't have one already. We'll create `~/clans/empire`.
+In this example, we're setting up a directory named `empire` inside a `clans` folder in your home directory. This is just an example, and you can name and place your project directory as it suits your organizational preferences.
 
-   3. **Add Files to the Repository**: Add your project files to the Git repository. This step is essential for nix flakes as it will ignore files not inside the git repo. 
+```bash
+mkdir -p ~/clans/empire && cd ~/clans/empire 
+nix flake init -t github:NixOS/templates#trivial
+```
 
-      ```bash
-      git add .
-      ```
+This will initialize a `flake.nix` file that looks like this:
 
+```nix
+# flake.nix
+{
+  description = "A very basic flake";
 
-3. **Create Machines Directory**: Create a machines directory where you put all machine specific nix configs like the configuration.nix
-    1. Create the machines directory in your git root example: `/etc/nixos/machines/`
-        ```bash
-        mkdir machines
-        ```
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+  };
 
-    2. Inside the machines directory create a directory named after the hostname of the machine you want to manage with clan.
-        ```bash
-        mkdir machines/jons-desktop
-        ```
+  outputs = { self, nixpkgs }: {
 
-    3. Move your `configuration.nix` and included files into  `machines/jons-desktop`
-        ```bash
-        mv configuration.nix machines/jons-desktop/configuration.nix 
-        ```
+    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
 
-    4. Git add your new machines folder
-        ```bash
-        git add machines
-        ```
+    packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
 
-4. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
+  };
+}
+```
 
-   ```nix
-   inputs.clan-core = {
-     url = "git+https://git.clan.lol/clan/clan-core";
-     inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs unstable.
-   };
-   ```
+### Initialize a Git Repository (optional/recommended)
 
-   Ensure to replace the placeholder URL with the actual Git repository URL for Clan Core. The `inputs.nixpkgs.follows` line indicates that your flake should use the same `nixpkgs` input as your main flake configuration.
+If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
 
+```bash
+git init && git add .
+```
 
-5. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
+> Note: adding all files to the git index is essential for `nix flakes` as `flakes` ignores source files that are not part of the git index.
 
-   - Previously:
+Confirm your flake repository is working:
 
-     ```nix
-     outputs = { self, nixpkgs }: {
-      nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
-        system = "x86_64-linux";
-        modules = [ ./configuration.nix ];
-      };
-     };
-     ```
+```bash
+nix flake show
+```
 
-   - With Clan Core:
+```bash
+warning: creating lock file flake.lock'
+path: <some/hash> 
+└───packages
+    └───x86_64-linux
+        ├───default: package 'hello-2.12.1'
+        └───hello: package 'hello-2.12.1'
+```
 
-     ```nix
-     outputs = { self, nixpkgs, clan-core }:
-      let clan = clan-core.lib.buildClan {
-        specialArgs = { }; # Add arguments to every nix import in here
-        directory = self; # Point this to the repository root.
-        clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
-        machines = {
-          jons-desktop = {
-            nixpkgs.hostPlatform = "x86_64-linux";
-            imports = [
-              clan-core.clanModules.sshd # Add openssh server for clan management
-              ./machines/jons-desktop/configuration.nix
-            ];
-          };
+## 2. Create your first Machine
+
+Create a directory where you put **all machine specific configs** like the `configuration.nix` or `hardware-configuration.nix`
+
+> Following this structure will allow you nicely organize all your different machines and allows the cLan-CLI to automatically detect and manage your machines.
+
+```bash
+mkdir -p machines/jons-desktop
+```
+
+> In this case `jons-desktop` is the hostname of the machine you want to manage with cLan.
+
+Move your `configuration.nix` and included files into `machines/jons-desktop`
+
+```bash
+mv configuration.nix machines/jons-desktop/configuration.nix 
+```
+
+Git add all new files/folders
+
+```bash
+git add machines
+```
+
+### Migrate to flakes and `buildClan`
+
+Add `Clan Core` as a new input to your `flake.nix`:
+
+```nix
+# flake.nix
+inputs.clan-core = {
+  url = "git+https://git.clan.lol/clan/clan-core";
+  inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+}
+```
+
+Your flake should now look something like this.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    # Change ref to your liking
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+
+    clan-core = {
+      url = "git+https://git.clan.lol/clan/clan-core";
+      inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+    };
+  };
+
+  outputs = { self, nixpkgs, clan-core }: {
+  # ...
+  };
+}
+```
+
+> Note: `inputs.nixpkgs.follows` ensures that `clan-core` uses the same `nixpkgs` version as the rest of your flake.
+
+### Use `clan-core.lib.buildClan` for declaring your machines
+
+If you used flakes already you might use `lib.nixosSystem`
+
+```nix
+# OLD
+
+# flake.nix
+outputs = { self, nixpkgs }: {
+  nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
+    system = "x86_64-linux";
+    modules = [ ./configuration.nix ];
+  };
+}
+```
+
+We explain how to setup `buildClan`
+
+```nix
+# flake.nix
+outputs = { self, nixpkgs, clan-core }:
+  let 
+    clan = clan-core.lib.buildClan {
+      ## Clan wide settings. (Required)
+      clanName = "__CHANGE_ME__"; # Ensure to choose a unique name.
+      directory = self; # Point this to the repository root.
+
+      specialArgs = { }; # Add arguments to every nix import in here
+      machines = {
+        jons-desktop = {
+          nixpkgs.hostPlatform = "x86_64-linux";
+          imports = [
+            ./machines/jons-desktop/configuration.nix
+            clan-core.clanModules.sshd # Add openssh server forcLanmanagement
+          ];
         };
       };
-     in { inherit (clan) nixosConfigurations clanInternals; };
-     ```
+    };
+  in
+  { 
+    inherit (clan) nixosConfigurations clanInternals; 
+  };
+```
 
+## Rebuild and Switch
 
+Apply your updated configuration
 
-6. **Rebuild and Switch**: Apply your updated configuration:
+Before we can rebuild the system we should replace the source of your system ( folder `/etc/nixos`) with a symlink to the `repo`
 
-   ```shellSession
-   sudo nixos-rebuild switch --flake /etc/nixos
-   ```
+```bash
+sudo ls -s ~/clans/empire /etc/nixos
+```
 
-   This rebuilds your system configuration and switches to it. The `--flake /etc/nixos` argument specifies that the `/etc/nixos` directory's flake should be used.
+```bash
+sudo nixos-rebuild switch
+```
 
-7. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+This rebuilds your system configuration and switches to it.
 
-8. **Reboot**: If the build is successful and no issues are detected, reboot your system:
+> Note: nixos-rebuild switch uses /etc/nixos by default.
 
-   ```shellSession
-   sudo reboot
-   ```
+## Finish installation
 
-9. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
+- **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+- **Reboot**: If the build is successful and no issues are detected, reboot your system:
 
+  ```shellSession
+  sudo reboot
+  ```
 
-# TODO:
-* How do I use clan machines install to setup my current machine?
-* I probably need the clan-core sshd module for that?
-* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
-
-
-## What's next
-
-After creating your clan checkout [managing machines](./machines.md)
+- **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
 
 ---
 
+## What's next?
 
-## Integrating Clan with Flakes using Flake-Parts
+After creating your cLan see [managing machines](./machines.md)
+
+Or continue with **flake-parts integration**
+
+## Integrating Clan with Flakes using `flake-parts``
+
+Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
 
-Clan supports integration with the Nix ecosystem through its flake module, making it compatible with [flake.parts](https://flake.parts/),
-a tool for modular Nix flakes composition.
 Here's how to set up Clan using flakes and flake-parts.
 
 ### 1. Update Your Flake Inputs
 
-To begin, you'll need to add `clan-core` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
-
-
+To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
 
 ```nix
-  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
-  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
-  inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+# flake.nix
+inputs = {
+  nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
 
-  # Newly added
-  inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
-  inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
-  inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
+  # New flake-parts input
+  flake-parts.url = "github:hercules-ci/flake-parts";
+  flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+  
+  clan-core = {
+    url = "git+https://git.clan.lol/clan/clan-core";
+    inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+    # New
+    inputs.flake-parts.follows = "flake-parts";
+  };
+}
 ```
 
 ### 2. Import Clan-Core Flake Module
 
-After updating your flake inputs, the next step is to import the `clan-core` flake module into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
+After updating your flake inputs, the next step is to import the `clan-core` flake module. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`.
 
 ```nix
   outputs =
@@ -174,9 +263,9 @@ After updating your flake inputs, the next step is to import the `clan-core` fla
 
 ### 3. Configure Clan Settings and Define Machines
 
-Lastly, define your Clan configuration settings, including a unique clan name and the machines you want to manage with Clan.
-This is where you specify the characteristics of each machine,
-such as the platform and specific Nix configurations. Update your `flake.nix` like this:
+Configure your clan settings and define machine configurations.
+
+Below is a guide on how to structure this in your flake.nix:
 
 ```nix
   outputs =
@@ -187,14 +276,17 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
           inputs.clan-core.flakeModules.default
         ];
         clan = {
+          ## Clan wide settings. (Required)
+          clanName = "__CHANGE_ME__"; # Ensure to choose a unique name.
+          directory = self; # Point this to the repository root.
+
           specialArgs = { }; # Add arguments to every nix import in here
-          clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
-          directory = inputs.self;
+          
           machines = {
             jons-desktop = {
               nixpkgs.hostPlatform = "x86_64-linux";
               imports = [
-                clan-core.clanModules.sshd # Add openssh server for clan management
+                clan-core.clanModules.sshd # Add openssh server for cLan management
                 ./configuration.nix
               ];
             };
@@ -207,7 +299,14 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
 For detailed information about configuring `flake-parts` and the available options within Clan,
 refer to the Clan module documentation located [here](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).
 
-### **Next Steps**
+### Next Steps
+
 With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
 
----
\ No newline at end of file
+---
+
+## TODO
+
+* How do I use cLan machines install to setup my current machine?
+* I probably need the clan-core sshd module for that?
+* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
\ No newline at end of file