docs: Copilot update all docs files

docs/INVENTORY.md

@@ -1,101 +1,272 @@
 # Host Inventory Configuration
 
-This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices.
+This document explains the `inventory.nix` file, which defines all hosts in your fleet.
 
 ## Table of Contents
 
-- [Understanding Inventory Structure](#understanding-inventory-structure)
-- [Hostname Generation Rules](#hostname-generation-rules)
-- [Adding Hosts](#adding-hosts)
-- [Device Configuration Options](#device-configuration-options)
+- [Overview](#overview)
+- [Structure](#structure)
+- [Hostname Generation](#hostname-generation)
+- [Configuration Methods](#configuration-methods)
+- [Options](#options)
 - [Examples](#examples)
 
-## Understanding Inventory Structure
+## Overview
 
-The `inventory.nix` file defines all hosts in the fleet using a flexible system. Top-level keys are always hostname **prefixes**, and actual hostnames are generated from device configurations.
+`inventory.nix` defines your fleet of hosts. Top-level keys are hostname **prefixes**, and actual hostnames are generated from device specifications. This allows you to manage large fleets with minimal repetition.
 
-## Hostname Generation Rules
+**Key concepts:**
+- Each top-level key generates one or more NixOS configurations
+- Host type defaults to the prefix name (can be overridden)
+- System architecture defaults to `x86_64-linux`
+- Common configuration can be applied to all devices in a group via `overrides`
 
-- **Numeric suffixes**: no dash (e.g., `nix-laptop1`, `nix-laptop2`)
-- **Non-numeric suffixes**: with dash (e.g., `nix-laptop-alpha`, `nix-laptop-beta`)  
-- **Custom hostnames**: Set `athenix.host.useHostPrefix = false` to use suffix as full hostname
-
-## Adding Hosts
-
-### Method 1: Quick Count (Simplest)
+## Structure
 
 ```nix
-nix-laptop = {
-  devices = 5;  # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
-};
+{
+  "prefix-name" = {
+    # Optional: Device count or explicit device map
+    devices = 5;           # or { "1" = { ... }; "alpha" = { ... }; }
+    
+    # Optional: Hardware type (defaults to prefix name)
+    type = "nix-desktop";
+    
+    # Optional: System architecture
+    system = "x86_64-linux";
+    
+    # Optional: Configuration applied to ALL devices in this group
+    overrides = {
+      athenix.users.student.enable = true;
+    };
+    
+    # Optional: Per-device configuration
+    "device-suffix" = { ... };
+  };
+}
 ```
 
-### Method 2: Explicit Count with Overrides
+## Hostname Generation
+
+Hostnames are generated automatically based on the device key:
+
+- **Numeric keys** (`"1"`, `"2"`, `"42"`) → no dash: `prefix1`, `prefix2`, `prefix42`
+- **Non-numeric keys** (`"alpha"`, `"special"`) → with dash: `prefix-alpha`, `prefix-special`
+- **Custom hostnames** → Set `athenix.host.useHostPrefix = false` to use the suffix as the full hostname (no prefix)
+
+**Examples:**
 
 ```nix
 nix-laptop = {
-  devices = 5;
-  overrides = {
-    # Applied to ALL nix-laptop hosts
-    athenix.users.student.enable = true;
-    athenix.sw.extraPackages = with pkgs; [ vim git ];
+  devices = 3;  # Generates: nix-laptop1, nix-laptop2, nix-laptop3
+};
+
+nix-surface = {
+  devices = {
+    "1" = { };  # → nix-surface1
+    "special" = { };  # → nix-surface-special
+  };
+};
+
+custom-machine = {
+  devices."lab-machine" = {
+    athenix.host.useHostPrefix = false;  # → lab-machine (not custom-machine-lab-machine)
   };
 };
 ```
 
-### Method 3: Individual Device Configuration
+## Configuration Methods
+
+### Method 1: Simple Count
+
+Create N identical hosts:
+
+```nix
+nix-laptop = {
+  devices = 5;
+};
+# Generates: nix-laptop1, nix-laptop2, nix-laptop3, nix-laptop4, nix-laptop5
+```
+
+### Method 2: Simple Count with Overrides
+
+Create N hosts with common configuration:
+
+```nix
+nix-desktop = {
+  devices = 3;
+  overrides = {
+    athenix.users.student.enable = true;
+    athenix.sw.extraPackages = with pkgs; [ vim git ];
+    services.openssh.enable = true;
+  };
+};
+# All three hosts get the overrides configuration
+```
+
+### Method 3: Explicit Device Map
+
+Configure each device individually:
 
 ```nix
 nix-surface = {
   devices = {
     "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
     "2".athenix.sw.kioskUrl = "https://dashboard2.example.com";
-    "3".athenix.sw.kioskUrl = "https://dashboard3.example.com";
+    "3" = {
+      athenix.sw.kioskUrl = "https://dashboard3.example.com";
+      services.openssh.enable = false;
+    };
   };
 };
 ```
 
-### Method 4: Mixed (Default Count + Custom Devices)
+### Method 4: External Module
+
+Reference a Git repository instead of inline configuration:
 
 ```nix
-nix-surface = {
-  defaultCount = 2;  # Creates nix-surface1, nix-surface2
+nix-lxc = {
+  devices."builder" = builtins.fetchGit {
+    url = "https://git.factory.uga.edu/org/builder-config";
+    rev = "abc123...";
+  };
+};
+```
+
+### Method 5: Mixed Approach
+
+Combine default count, custom devices, and overrides:
+
+```nix
+nix-lab = {
+  defaultCount = 5;  # Creates nix-lab1 through nix-lab5
   devices = {
-    "special" = {  # Creates nix-surface-special
-      athenix.sw.kioskUrl = "https://special-dashboard.example.com";
+    "special" = {
+      athenix.sw.extraPackages = with pkgs; [ special-software ];
     };
   };
   overrides = {
-    # Applied to all devices (including "special")
-    athenix.sw.kioskUrl = "https://default-dashboard.example.com";
+    # Applied to all devices (default count + custom)
+    athenix.users.lab-admin.enable = true;
   };
 };
 ```
 
-## Device Configuration Options
+## Options
 
-### Direct Configuration (Recommended)
+### Top-Level Device Options
 
-Use any NixOS or `athenix.*` option:
+#### `devices`
+
+Specify hosts to create. Can be:
+- **Number**: Create N hosts with keys `"1"`, `"2"`, ..., `"N"`
+- **Attribute set**: Map of device names to configurations
+
+**Type**: `int | attrs`
+
+**Examples:**
+```nix
+devices = 5;  # Creates 5 hosts
+
+devices = {
+  "1" = { };
+  "alpha" = { };
+};
+```
+
+#### `defaultCount`
+
+When using a device map, also create N numbered hosts.
+
+**Type**: `int` (optional)
+
+**Example:**
+```nix
+defaultCount = 3;  # Creates "1", "2", "3" in addition to devices map
+devices = {
+  "special" = { };
+};
+# Result: hosts "1", "2", "3", and "special"
+```
+
+#### `type`
+
+Hardware type module to use. Defaults to the prefix name (inferred from top-level key).
+
+**Type**: `string` (optional)
+
+**Options**: `nix-desktop`, `nix-laptop`, `nix-surface`, `nix-lxc`, `nix-wsl`, `nix-ephemeral`
+
+**Example:**
+```nix
+lab-machines = {
+  type = "nix-desktop";  # Use desktop hardware configuration
+  devices = 5;
+};
+```
+
+#### `system`
+
+System architecture. Defaults to `x86_64-linux`.
+
+**Type**: `string` (optional)
+
+**Example:**
+```nix
+arm-devices = {
+  system = "aarch64-linux";
+  devices = 2;
+};
+```
+
+#### `overrides`
+
+Configuration applied to all devices in this group. Useful for fleet-wide settings.
+
+**Type**: `attrs` (optional)
+
+**Example:**
+```nix
+nix-laptop = {
+  devices = 10;
+  overrides = {
+    # Applied to all 10 laptops
+    athenix.users.staff.enable = true;
+    services.openssh.enable = true;
+    boot.loader.timeout = 10;
+  };
+};
+```
+
+### Per-Device Options
+
+Any NixOS or `athenix.*` option can be set per-device:
 
 ```nix
-"1" = {
-  # Athenix options
-  athenix.users.myuser.enable = true;
-  athenix.host.filesystem.swapSize = "64G";
-  athenix.sw.extraPackages = with pkgs; [ docker ];
-  athenix.sw.kioskUrl = "https://example.com";
-  
-  # Standard NixOS options
-  networking.firewall.enable = false;
-  services.openssh.enable = true;
-  time.timeZone = "America/New_York";
+nix-surface = {
+  devices = {
+    "1" = {
+      # athenix.* namespace options
+      athenix.users.student.enable = true;
+      athenix.host.filesystem.device = "/dev/sda";
+      athenix.host.filesystem.swapSize = "16G";
+      athenix.sw.kioskUrl = "https://dashboard1.example.com";
+      athenix.sw.extraPackages = with pkgs; [ firefox ];
+      
+      # Standard NixOS options
+      networking.firewall.enable = false;
+      services.openssh.enable = true;
+      time.timeZone = "America/New_York";
+      boot.kernelPackages = pkgs.linuxPackages_latest;
+    };
+  };
 };
 ```
 
 ### Convenience: `athenix.forUser`
 
-Quick setup for single-user systems (especially WSL):
+Quick setup for single-user systems (especially WSL). This automatically enables a user and sets the WSL default user:
 
 ```nix
 nix-wsl = {