docs: Copilot update all docs files

docs/NAMESPACE.md

@@ -1,53 +1,69 @@
 # Configuration Namespace Reference
 
-All UGA Innovation Factory-specific options are under the `athenix` namespace to avoid conflicts with standard NixOS options.
+All UGA Innovation Factory-specific options are in the `athenix` namespace to avoid conflicts with standard NixOS options.
 
 ## Table of Contents
 
 - [Host Configuration (`athenix.host`)](#host-configuration-athenixhost)
 - [Software Configuration (`athenix.sw`)](#software-configuration-athenixsw)
 - [User Management (`athenix.users`)](#user-management-athenixusers)
-- [System Configuration (`athenix.system`)](#system-configuration-athenixsystem)
 - [Convenience Options](#convenience-options)
 
 ## Host Configuration (`athenix.host`)
 
-Hardware and host-specific settings.
+Hardware and boot-related settings.
 
-### `athenix.host.filesystem`
+### `athenix.host.filesystem.device`
 
-Disk and storage configuration.
+Boot disk device path.
 
-**Options:**
-- `athenix.host.filesystem.device` - Boot disk device (default: `/dev/sda`)
-- `athenix.host.filesystem.swapSize` - Swap file size (default: `"32G"`)
+**Type:** String
+
+**Default:** `"/dev/sda"`
 
 **Example:**
 ```nix
-athenix.host.filesystem = {
-  device = "/dev/nvme0n1";
-  swapSize = "64G";
-};
+athenix.host.filesystem.device = "/dev/nvme0n1";
+```
+
+### `athenix.host.filesystem.swapSize`
+
+Swap partition size.
+
+**Type:** String (size with unit, e.g., `"32G"`, `"2G"`)
+
+**Default:** `"32G"`
+
+**Example:**
+```nix
+athenix.host.filesystem.swapSize = "64G";
 ```
 
 ### `athenix.host.buildMethods`
 
-List of supported build artifact types for this host.
+Artifact types to build for this host.
 
 **Type:** List of strings
 
 **Options:** `"installer-iso"`, `"iso"`, `"ipxe"`, `"lxc"`, `"proxmox"`
 
-**Default:** `["installer-iso"]`
+**Default:** `[ "installer-iso" ]`
+
+**Description:**
+- `"installer-iso"` - Installer ISO with auto-install
+- `"iso"` - Live ISO (boot without installation)
+- `"ipxe"` - iPXE netboot artifacts
+- `"lxc"` - LXC container tarball
+- `"proxmox"` - Proxmox VMA template
 
 **Example:**
 ```nix
-athenix.host.buildMethods = [ "lxc" "proxmox" ];
+athenix.host.buildMethods = [ "installer-iso" "lxc" ];
 ```
 
 ### `athenix.host.useHostPrefix`
 
-Whether to prepend the host type prefix to the hostname (used in inventory generation).
+Whether to prepend the host type prefix to the generated hostname.
 
 **Type:** Boolean
 
@@ -55,15 +71,19 @@ Whether to prepend the host type prefix to the hostname (used in inventory gener
 
 **Example:**
 ```nix
-athenix.host.useHostPrefix = false;  # "builder" instead of "nix-lxc-builder"
+# With useHostPrefix = true (default)
+# Device "1" under "nix-laptop" → "nix-laptop1"
+
+# With useHostPrefix = false
+# Device "builder" under "nix-lxc" → "builder" (not "nix-lxc-builder")
+athenix.host.useHostPrefix = false;
 ```
 
-### `athenix.host.wsl`
+### `athenix.host.wsl.user`
 
-WSL-specific configuration options.
+Default WSL user account (only for `nix-wsl` type).
 
-**Options:**
-- `athenix.host.wsl.user` - Default WSL user for this instance
+**Type:** String (username)
 
 **Example:**
 ```nix
@@ -72,11 +92,11 @@ athenix.host.wsl.user = "myusername";
 
 ## Software Configuration (`athenix.sw`)
 
-System software and application configuration.
+System type, packages, and application configuration.
 
 ### `athenix.sw.enable`
 
-Enable the software configuration module.
+Enable software configuration.
 
 **Type:** Boolean
 
@@ -84,28 +104,32 @@ Enable the software configuration module.
 
 ### `athenix.sw.type`
 
-System type that determines the software profile.
+System profile/type. Determines which software packages and services are installed.
 
-**Type:** Enum
+**Type:** String or list of strings
 
 **Options:**
-- `"desktop"` - Full desktop environment (GNOME)
-- `"tablet-kiosk"` - Surface tablets with kiosk mode browser
-- `"stateless-kiosk"` - Diskless PXE boot kiosks
+- `"desktop"` - Full GNOME desktop environment with development tools
+- `"tablet-kiosk"` - Surface tablets with Firefox kiosk browser
+- `"stateless-kiosk"` - Diskless PXE-booted ephemeral systems
 - `"headless"` - Servers and containers without GUI
+- `"builders"` - Build servers with build dependencies
 
 **Default:** `"desktop"`
 
 **Example:**
 ```nix
-athenix.sw.type = "headless";
+athenix.sw.type = "desktop";
+
+# Multiple types supported
+athenix.sw.type = [ "desktop" "headless" ];
 ```
 
 ### `athenix.sw.kioskUrl`
 
-URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` types).
+URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types).
 
-**Type:** String
+**Type:** String (URL)
 
 **Default:** `"https://ha.factory.uga.edu"`
 
@@ -114,12 +138,13 @@ URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk`
 athenix.sw.kioskUrl = "https://dashboard.example.com";
 ```
 
-### `athenix.sw.python`
+### `athenix.sw.python.enable`
 
-Python development tools configuration.
+Enable Python development tools (pixi, uv, etc.).
 
-**Options:**
-- `athenix.sw.python.enable` - Enable Python tools (pixi, uv) (default: `true`)
+**Type:** Boolean
+
+**Default:** `true`
 
 **Example:**
 ```nix
@@ -128,11 +153,13 @@ athenix.sw.python.enable = true;
 
 ### `athenix.sw.remoteBuild`
 
-Remote build server configuration for offloading builds.
+Configure remote build servers for offloading builds.
+
+**Type:** Attribute set
 
 **Options:**
-- `athenix.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets)
-- `athenix.sw.remoteBuild.hosts` - List of build server hostnames
+- `enable` - Enable remote builders (Boolean, default: `true` for tablets)
+- `hosts` - List of remote builder hostnames (List of strings)
 
 **Example:**
 ```nix
@@ -144,104 +171,187 @@ athenix.sw.remoteBuild = {
 
 ### `athenix.sw.extraPackages`
 
-Additional system packages to install beyond the type defaults.
+Additional system packages beyond the type defaults.
 
 **Type:** List of packages
 
-**Default:** `[]`
+**Default:** `[ ]`
 
 **Example:**
 ```nix
 athenix.sw.extraPackages = with pkgs; [
   vim
-  htop
   docker
+  htop
+  ripgrep
 ];
 ```
 
 ### `athenix.sw.excludePackages`
 
-Packages to exclude from the default list for this system type.
+Packages to remove from the default list for this system type.
 
 **Type:** List of packages
 
-**Default:** `[]`
+**Default:** `[ ]`
 
 **Example:**
 ```nix
 athenix.sw.excludePackages = with pkgs; [
-  firefox  # Remove Firefox from default desktop packages
+  firefox  # Don't install Firefox on this system
 ];
 ```
 
 ## User Management (`athenix.users`)
 
-User account configuration and management.
+User account configuration and access control.
 
 ### `athenix.users.<username>.enable`
 
-Enable a specific user account on this system.
+Enable a user account on this system.
 
 **Type:** Boolean
 
-**Default:** `false` (except `root` and `engr-ugaif` which default to `true`)
+**Default:** `false` (except `root` and `engr-ugaif` which are `true`)
 
 **Example:**
 ```nix
-athenix.users = {
-  myuser.enable = true;
-  student.enable = true;
+# In inventory.nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
 };
 ```
 
-### User Account Options
+### User Account Options (in `users.nix`)
 
-Each user in `users.nix` can be configured with:
+Define user accounts in `users.nix` with these options:
+
+#### `description`
+
+Full name or description of the user.
+
+**Type:** String
 
 ```nix
-# Option 1: Define inline in users.nix
-athenix.users.myuser = {
-  description = "Full Name";
-  isNormalUser = true;                    # Default: true
-  extraGroups = [ "wheel" "docker" ];     # Additional groups
-  shell = pkgs.zsh;                       # Login shell
-  hashedPassword = "$6$...";              # Hashed password
-  opensshKeys = [ "ssh-ed25519 ..." ];    # SSH public keys
-  useZshTheme = true;                     # Use system Zsh theme
-  useNvimPlugins = true;                  # Use system Neovim config
-  
-  enable = false;  # Enable per-system in inventory.nix
-};
+athenix.users.myuser.description = "John Doe";
+```
 
-# Option 2: Use external configuration (recommended)
-# The external user.nix can set athenix.users.myuser options directly
-athenix.users.anotheruser.external = builtins.fetchGit {
+#### `extraGroups`
+
+Additional Unix groups for the user.
+
+**Type:** List of strings
+
+**Common groups:**
+- `"wheel"` - Sudo access
+- `"networkmanager"` - Network configuration
+- `"docker"` - Docker access
+- `"video"` - Video device access
+- `"audio"` - Audio device access
+- `"input"` - Input device access (keyboards, mice)
+
+```nix
+athenix.users.myuser.extraGroups = [ "wheel" "docker" "networkmanager" ];
+```
+
+#### `shell`
+
+Login shell for the user.
+
+**Type:** Package
+
+**Default:** `pkgs.bash`
+
+```nix
+athenix.users.myuser.shell = pkgs.zsh;
+```
+
+#### `hashedPassword`
+
+Password hash for the user.
+
+**Type:** String (SHA-512 hash)
+
+**Generation:**
+```bash
+mkpasswd -m sha-512
+```
+
+```nix
+athenix.users.myuser.hashedPassword = "$6$...";
+```
+
+#### `opensshKeys`
+
+SSH public keys for this user.
+
+**Type:** List of strings
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@host"
+  "ssh-rsa AAAA... user@other"
+];
+```
+
+#### `useZshTheme`
+
+Apply system Zsh theme configuration to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useZshTheme = true;
+```
+
+#### `useNvimPlugins`
+
+Apply system Neovim configuration to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useNvimPlugins = true;
+```
+
+#### `external`
+
+Reference external user configuration (dotfiles, home-manager).
+
+**Type:** Path or Git reference
+
+**Example:**
+```nix
+athenix.users.myuser.external = builtins.fetchGit {
   url = "https://git.factory.uga.edu/username/dotfiles";
   rev = "abc123...";
 };
 ```
 
-## System Configuration (`athenix.system`)
+See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) for detailed external module usage.
 
-System-wide settings and services.
+### Enabling Users on Systems
 
-### `athenix.system.gc`
+Users defined in `users.nix` are **not enabled by default**. Enable them in `inventory.nix`:
 
-Automatic garbage collection configuration.
-
-**Options:**
-- `athenix.system.gc.enable` - Enable automatic garbage collection (default: `true`)
-- `athenix.system.gc.frequency` - How often to run (default: `"weekly"`)
-- `athenix.system.gc.retentionDays` - Days to keep old generations (default: `30`)
-- `athenix.system.gc.optimise` - Optimize Nix store automatically (default: `true`)
-
-**Example:**
 ```nix
-athenix.system.gc = {
-  enable = true;
-  frequency = "daily";
-  retentionDays = 14;
-  optimise = true;
+# Option 1: Enable on all devices in a group
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.student.enable = true;
+};
+
+# Option 2: Enable on specific devices
+nix-surface = {
+  devices = {
+    "1".athenix.users.admin.enable = true;
+    "2".athenix.users.admin.enable = true;
+  };
 };
 ```
 
@@ -249,7 +359,7 @@ athenix.system.gc = {
 
 ### `athenix.forUser`
 
-Quick setup option that enables a user account in one line.
+Quick setup for single-user systems. Automatically enables a user and sets it as the default.
 
 **Type:** String (username) or null
 
@@ -257,11 +367,7 @@ Quick setup option that enables a user account in one line.
 
 **Example:**
 ```nix
-athenix.forUser = "myusername";  # Equivalent to athenix.users.myusername.enable = true
-```
-
-**Usage in inventory.nix:**
-```nix
+# In inventory.nix - enables the user automatically
 nix-wsl = {
   devices = {
     "alice".athenix.forUser = "alice-uga";
@@ -269,9 +375,17 @@ nix-wsl = {
 };
 ```
 
+Equivalent to:
+```nix
+"alice" = {
+  athenix.users.alice-uga.enable = true;
+  athenix.host.wsl.user = "alice-uga";
+};
+```
+
 ## See Also
 
-- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
-- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
-- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
+- [INVENTORY.md](INVENTORY.md) - Host configuration examples
+- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management guide
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module integration
 - [README.md](../README.md) - Main documentation