Update README with comprehensive repo overview and setup guides

README.md

@@ -1,62 +1,79 @@
 # Nix Config
 
-This is my interpretation of the perfect nix flake, this powers my desktops, vms, containers, and all aspects of my computers.
+This is my interpretation of the perfect nix flake, this powers my desktops, laptops, servers, vms, containers, and all aspects of my computers.
 
 ## Features
 
-- Automated Persistence through TempFS, or snapshotting with BTRFS, with persistable components using [Impermanence]
-- Secret management in [NixOS] ([sops-nix]) and [home-manager] ([sops-nix] with [sops])
-- Automated Flake dependency updates through Github Actions using [Update-flake-lock]
+- **Automated Discovery**: Hosts and users are automatically configured from filesystem structure
+- **Automated Persistence**: TempFS with persistable components using [Impermanence] or BTRFS snapshotting
+- **Secret Management**: Encrypted secrets in [NixOS] ([sops-nix]) and [home-manager] ([sops-nix] with [sops])
+- **Automated Updates**: Flake dependency updates through Github Actions using [Update-flake-lock]
+- **Hardware Acceleration**: Automatic hardware acceleration support detection and configuration
+- **Modular Architecture**: Custom modules and overlays for extensibility
 
 ## Supported Configurations
 
-- [NixOS]-managed
-  - Desktops
-    - [nixmi] (Personal Desktop)
-  - Servers
-    - [nixai] (Locally hosted AI)
-    - [nixcloud] (Replacing usage of external cloud services)
-    - [nixdev] (Development)
-    - [nixio] (Interface between the web & internal services)
-    - [nixmon] (Monitoring)
-    - [nixserv] (Nix Cache & Build System)
+- [NixOS]-managed systems with automatic configuration discovery:
+  - **Desktops** - Personal workstations and development environments
+  - **Servers** - Infrastructure services and automation
+  - **Laptops** - Portable systems with power management
 
 ## Repository Structure
 
+The repository uses an **automatic discovery system** that scans the filesystem to build configurations:
+
 ```
 .
-├─ home          # Root for all user homes
-├─── shared      #
-├─ hosts         # Root for all hosts
-├─── shared      # Auto-Imported modules for all hosts
-├─── desktop     # Desktop NixOS systems
-├───── shared    # Auto-Imported modules for desktops
-├─── laptop      # Laptop NixOS Systems
-├───── shared    # Auto-Imported modules for laptops
-├─── server      # Server NixOS Systems
-├───── shared    # Auto-Imported modules for servers
-├─ lib           # Extension to the nixpkgs lib
-├─ modules       # Custom NixOS and home-manager modules
-├─ overlays      # NixPkgs overlays
-└─ pkgs          # Custom Packages
+├─ home              # Root for all user homes (auto-discovered)
+│  ├─── {username}   # User-specific configurations
+│  └─── shared       # Shared home-manager modules
+├─ hosts             # Root for all hosts (auto-discovered by device type)
+│  ├─── shared       # Auto-imported modules for all hosts
+│  │    ├─── global  # Core system configuration (locale, networking, etc.)
+│  │    └─── optional# Optional modules for specific use cases
+│  ├─── desktop      # Desktop NixOS systems
+│  │    ├─── shared  # Auto-imported modules for desktops
+│  │    └─── {host}  # Individual desktop host configurations
+│  ├─── laptop       # Laptop NixOS Systems  
+│  │    ├─── shared  # Auto-imported modules for laptops
+│  │    └─── {host}  # Individual laptop host configurations
+│  └─── server       # Server NixOS Systems
+│       ├─── shared  # Auto-imported modules for servers
+│       └─── {host}  # Individual server host configurations
+├─ lib               # Extensions to nixpkgs lib and custom builders
+│  └─── builders     # System and home-manager configuration builders
+├─ modules           # Custom NixOS and home-manager modules
+├─ overlays          # NixPkgs overlays for package modifications
+├─ pkgs              # Custom packages not in nixpkgs
+└─ docs              # Additional documentation
 ```
 
+### Auto-Discovery Mechanism
+
+The flake automatically discovers:
+- **Hosts**: By scanning `hosts/{device-type}/` directories (excluding `shared/`)
+- **Users**: By scanning `home/` directories and matching with existing hosts
+- **Hardware Acceleration**: Support based on predefined host lists
+
+## Getting Started
+
+- **[Creating New Hosts](./docs/Creating-Hosts.md)** - Step-by-step guide to add new hosts to your configuration
+- **[Creating New Users](./docs/Creating-Users.md)** - Instructions for adding new user configurations
+- **[Installation Guide](./docs/Installation.md)** - Complete installation and setup instructions
+
 ## Things on the TODO
 
 > These probably won't happen honestly
 
-- Cosmic Desktop once stabalised
+- Cosmic Desktop once stabilized
+- Declarative disk management with disko for all hosts
+- Automated backup strategies for persistent data
+
+## Links
 
 [home-manager]: https://github.com/nix-community/home-manager
 [impermanence]: https://github.com/nix-community/impermanence
-[nixai]: ./hosts/server/nixai/
-[nixcloud]: ./hosts/server/nixcloud/
-[nixdev]: ./hosts/server/nixdev/
-[nixio]: ./hosts/server/nixio/
-[nixmi]: ./hosts/desktop/nixmi/
-[nixmon]: ./hosts/server/nixmon/
 [nixos]: https://nixos.org/
-[nixserv]: ./hosts/server/nixserv/
 [sops]: https://github.com/mozilla/sops
 [sops-nix]: https://github.com/Mic92/sops-nix
 [update-flake-lock]: https://github.com/DeterminateSystems/update-flake-lock

docs/Creating-Hosts.md

@@ -0,0 +1,95 @@
+# Creating New Hosts
+
+To add a new host to your configuration:
+
+## 1. Create Host Directory Structure
+```bash
+# For a new desktop host named "mydesktop"
+mkdir -p hosts/desktop/mydesktop
+
+# For a new server host named "myserver"  
+mkdir -p hosts/server/myserver
+
+# For a new laptop host named "mylaptop"
+mkdir -p hosts/laptop/mylaptop
+```
+
+## 2. Create Required Configuration Files
+
+Create `hosts/{device-type}/{hostname}/default.nix`:
+```nix
+{ self, pkgs, ... }:
+{
+  imports = [
+    # Hardware configuration (required)
+    ./hardware.nix
+
+    # Optional: device-specific modules
+    # "${self}/hosts/shared/optional/containers.nix"
+    # "${self}/modules/nixos/custom-module.nix"
+  ];
+
+  # Host-specific configuration
+  host = {
+    device.isHeadless = false; # Set to true for servers
+  };
+
+  # Add your system configuration here
+  # networking.hostName is automatically set from directory name
+}
+```
+
+Create `hosts/{device-type}/{hostname}/hardware.nix`:
+```nix
+{ inputs, ... }:
+{
+  imports = [
+    # Include relevant hardware modules
+    inputs.nixos-hardware.nixosModules.common-cpu-amd
+    inputs.nixos-hardware.nixosModules.common-pc-ssd
+
+    # For laptops, also include:
+    # inputs.nixos-hardware.nixosModules.common-pc-laptop
+  ];
+
+  # Boot configuration
+  boot.loader = {
+    systemd-boot.enable = true;
+    efi.canTouchEfiVariables = true;
+  };
+
+  # Filesystem configuration (use disko for declarative disk setup)
+  fileSystems."/" = {
+    device = "/dev/disk/by-label/nixos";
+    fsType = "ext4";
+  };
+
+  # Add hardware-specific configuration
+}
+```
+
+## 3. Add Hardware Acceleration (Optional)
+
+If your host supports hardware acceleration, add it to the acceleration lists in `flake.nix`:
+```nix
+accelerationHosts = {
+  cuda = [
+    "your-new-host"  # Add here for CUDA support
+  ];
+  rocm = [
+    "your-amd-host"  # Add here for ROCm support
+  ];
+};
+```
+
+## 4. Build and Test
+```bash
+# Build the configuration (don't switch yet)
+sudo nixos-rebuild build --flake .#your-new-host
+
+# Test the configuration 
+sudo nixos-rebuild test --flake .#your-new-host
+
+# Switch to the new configuration
+sudo nixos-rebuild switch --flake .#your-new-host
+```

docs/Creating-Users.md

@@ -0,0 +1,57 @@
+# Creating New Users
+
+To add a new user configuration:
+
+## 1. Create User Directory
+```bash
+mkdir -p home/newuser
+```
+
+## 2. Create User Configuration Files
+
+Create host-specific configurations in `home/newuser/{hostname}.nix`:
+```nix
+{ pkgs, lib, ... }:
+{
+  imports = [
+    # Import shared configurations
+    ./features/cli              # Common CLI tools
+    ./features/desktop/common   # Desktop environment basics
+  ];
+
+  # User-specific configuration
+  home = {
+    username = "newuser";
+    homeDirectory = "/home/newuser";
+    stateVersion = "25.05";
+  };
+
+  # Add user-specific packages and configuration
+  programs = {
+    git = {
+      userName = "Your Name";
+      userEmail = "your.email@domain.com";
+    };
+  };
+}
+```
+
+Create feature modules in `home/newuser/features/`:
+```bash
+mkdir -p home/newuser/features/{cli,desktop,development}
+```
+
+## 3. Link User to Hosts
+
+The auto-discovery system will automatically link users to hosts if:
+- A file `home/{username}/{hostname}.nix` exists
+- The hostname matches an existing host configuration
+
+## 4. Test User Configuration
+```bash
+# Build home-manager configuration
+home-manager build --flake .#newuser@hostname
+
+# Switch to new configuration  
+home-manager switch --flake .#newuser@hostname
+```