docs: Copilot update all docs files

docs/BUILDING.md

@@ -1,11 +1,13 @@
-# Building Installation Media
+# Building Installation Media and Artifacts
 
-This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake.
+Guide to building installer ISOs, live images, and container artifacts.
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
 - [Available Artifacts](#available-artifacts)
+- [Building Locally](#building-locally)
+- [Building from Remote](#building-from-remote)
 - [Installer ISOs](#installer-isos)
 - [Live ISOs](#live-isos)
 - [Container Images](#container-images)
@@ -15,116 +17,194 @@ This guide covers building installer ISOs, live images, and container artifacts
 ## Quick Start
 
 ```bash
-# Build an installer ISO for a specific host
-nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
+# List all available artifacts
+nix flake show
 
-# Result will be in result/iso/
+# Build installer ISO for a specific host
+nix build .#installer-iso-nix-laptop1
+
+# Result is in result/iso/
 ls -lh result/iso/
 ```
 
 ## Available Artifacts
 
-List all available build outputs:
+Athenix can build multiple artifact types for deployment:
 
-```bash
-nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
+| Type | Description | Location | Use Case |
+|------|-------------|----------|----------|
+| `installer-iso-*` | Auto-install ISO | `result/iso/` | Install NixOS to disk |
+| `iso-*` | Live ISO | `result/iso/` | Boot without installing |
+| `ipxe-*` | PXE netboot | `result/` | Diskless netboot systems |
+| `lxc-*` | LXC container | `result/tarball/` | LXC/Proxmox containers |
+| `proxmox-*` | Proxmox VMA | `result/` | Proxmox VM templates |
+
+Set artifact types per-host via `athenix.host.buildMethods` in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.host.buildMethods = [ "installer-iso" ];
+};
+
+nix-lxc = {
+  devices.builder = {
+    athenix.host.buildMethods = [ "lxc" "proxmox" ];
+  };
+};
 ```
 
-Common artifact types:
+## Building Locally
 
-| Artifact Type | Description | Example |
-|--------------|-------------|---------|
-| `installer-iso-*` | Auto-install ISO that installs configuration to disk | `installer-iso-nix-laptop1` |
-| `iso-*` | Live ISO (bootable without installation) | `iso-nix-ephemeral1` |
-| `ipxe-*` | iPXE netboot artifacts (kernel, initrd, script) | `ipxe-nix-ephemeral1` |
-| `lxc-*` | LXC container tarball | `lxc-nix-builder` |
-| `proxmox-*` | Proxmox VMA archive | `proxmox-nix-builder` |
-
-## Installer ISOs
-
-Installer ISOs automatically install the NixOS configuration to disk on first boot.
-
-### Building Locally
+Build artifacts on your local machine:
 
 ```bash
-# Build installer for a specific host
+# Build installer ISO
 nix build .#installer-iso-nix-laptop1
 
-# Result location
-ls -lh result/iso/nixos-*.iso
-
-# Copy to USB drive (replace /dev/sdX with your USB device)
-sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress
-```
-
-### Building from Gitea
-
-```bash
-nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
-```
-
-### Using the Installer
-
-1. Boot from the ISO
-2. The system will automatically partition the disk and install NixOS
-3. After installation completes, remove the USB drive and reboot
-4. Log in with the configured user credentials
-
-**Note:** The installer will **erase all data** on the target disk specified in `athenix.host.filesystem.device`.
-
-## Live ISOs
-
-Live ISOs boot into a temporary system without installing to disk. Useful for:
-- Testing configurations
-- Recovery operations
-- Ephemeral/stateless systems
-
-### Building Live ISOs
-
-```bash
 # Build live ISO
 nix build .#iso-nix-ephemeral1
 
-# Result location
-ls -lh result/iso/nixos-*.iso
+# Build LXC container
+nix build .#lxc-nix-builder
+
+# Build all available outputs
+nix build .#
 ```
 
-### Stateless Kiosk Systems
+**Result locations:**
+- ISOs: `result/iso/nixos-*.iso`
+- LXC: `result/tarball/nixos-*.tar.xz`
+- Proxmox: `result/`
+- iPXE: `result/` (kernel, initrd, script)
 
-For PXE netboot kiosks, use the `ipxe-*` artifacts:
+### Build Specific Host
 
 ```bash
-# Build iPXE artifacts
-nix build .#ipxe-nix-ephemeral1
+# Get list of all hosts
+nix eval .#nixosConfigurations --apply builtins.attrNames
 
-# Result contains:
-# - bzImage (kernel)
-# - initrd (initial ramdisk)
-# - netboot.ipxe (iPXE script)
-ls -lh result/
+# Build specific host
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
+```
+
+## Building from Remote
+
+Build from the Gitea repository without cloning:
+
+```bash
+# Build installer ISO
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
+
+# Build LXC container
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#lxc-nix-builder
+
+# Use specific branch or revision
+nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git?ref=develop#installer-iso-nix-laptop1
+```
+
+## Installer ISOs
+
+Installer ISOs automatically partition and install NixOS on first boot.
+
+### Building
+
+```bash
+nix build .#installer-iso-nix-laptop1
+ls -lh result/iso/
+```
+
+### Burning to USB
+
+```bash
+# Find USB device (be careful!)
+lsblk
+
+# Burn ISO to USB (replace sdX with your device)
+sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress
+
+# Sync and eject
+sudo sync && sudo eject /dev/sdX
+```
+
+### Installation Process
+
+1. Boot from the USB drive
+2. System automatically boots into installer
+3. Installer partitions disk according to `athenix.host.filesystem`
+4. NixOS is installed and configured
+5. System reboots automatically
+6. Log in with configured user
+
+**Note:** Installer will erase all data on the target disk specified in `athenix.host.filesystem.device`.
+
+### Installer Configuration
+
+Customize installer via host configuration:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides = {
+    athenix.host.filesystem.device = "/dev/nvme0n1";
+    athenix.host.filesystem.swapSize = "32G";
+    athenix.host.buildMethods = [ "installer-iso" ];
+  };
+};
+```
+
+## Live ISOs
+
+Live ISOs boot into a temporary system without installing to disk.
+
+### Building
+
+```bash
+nix build .#iso-nix-ephemeral1
+```
+
+### Usage
+
+Live ISOs are useful for:
+- Testing configurations before installation
+- Recovery operations
+- Ephemeral/stateless systems
+- Booting in kiosk mode
+
+### Customizing Live ISO
+
+```nix
+nix-ephemeral = {
+  devices.live = {
+    athenix.sw.type = "stateless-kiosk";
+    athenix.sw.kioskUrl = "https://dashboard.example.com";
+    athenix.host.buildMethods = [ "iso" ];
+  };
+};
 ```
 
 ## Container Images
 
 ### LXC Containers
 
-Build LXC container tarballs for Proxmox or other LXC hosts:
+Build LXC container tarballs for Proxmox or standalone LXC:
 
 ```bash
-# Build LXC tarball
 nix build .#lxc-nix-builder
-
-# Result location
-ls -lh result/tarball/nixos-*.tar.xz
+ls -lh result/tarball/
 ```
 
-**Importing to Proxmox:**
+#### Importing to Proxmox
+
+1. Copy tarball to Proxmox host:
 
 ```bash
-# Copy tarball to Proxmox host
 scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/
+```
 
-# Create container from Proxmox CLI
+2. Create container:
+
+```bash
 pct create 100 local:vztmpl/nixos-*.tar.xz \
   --hostname nix-builder \
   --memory 4096 \
@@ -132,25 +212,59 @@ pct create 100 local:vztmpl/nixos-*.tar.xz \
   --net0 name=eth0,bridge=vmbr0,ip=dhcp
 ```
 
-See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions.
+3. Start and log in:
+
+```bash
+pct start 100
+pct shell 100
+```
+
+#### Proxmox Integration
+
+For detailed Proxmox deployment instructions, see [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md).
 
 ### Proxmox VMA
 
 Build Proxmox-specific VMA archives:
 
 ```bash
-# Build Proxmox VMA
 nix build .#proxmox-nix-builder
-
-# Result location
 ls -lh result/
 ```
 
+VMA files can be imported directly into Proxmox for rapid VM creation.
+
+## iPXE / Network Boot
+
+Build iPXE artifacts for diskless PXE boot systems:
+
+```bash
+nix build .#ipxe-nix-ephemeral1
+ls -lh result/
+```
+
+Artifacts include:
+- `bzImage` - Linux kernel
+- `initrd` - Initial ramdisk
+- `netboot.ipxe` - iPXE boot script
+
+### iPXE Setup
+
+Configure your PXE server to boot from these artifacts:
+
+```ipxe
+kernel tftp://server/bzImage
+initrd tftp://server/initrd
+boot
+```
+
+See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed network boot setup.
+
 ## Remote Builders
 
 Speed up builds by offloading to build servers.
 
-### One-Time Remote Build
+### One-Time Build
 
 ```bash
 nix build .#installer-iso-nix-laptop1 \
@@ -159,7 +273,7 @@ nix build .#installer-iso-nix-laptop1 \
 
 ### Persistent Configuration
 
-Add to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:
+Add to `~/.config/nix/nix.conf`:
 
 ```conf
 builders = ssh://engr-ugaif@nix-builder x86_64-linux
@@ -171,12 +285,12 @@ Then build normally:
 nix build .#installer-iso-nix-laptop1
 ```
 
-### SSH Key Setup
+### SSH Setup
 
-For remote builders, ensure SSH keys are configured:
+Ensure SSH is configured for the builder:
 
 ```bash
-# Generate SSH key if needed
+# Generate key if needed
 ssh-keygen -t ed25519
 
 # Copy to builder
@@ -188,77 +302,86 @@ ssh engr-ugaif@nix-builder
 
 ### Multiple Builders
 
-Configure multiple build servers:
-
 ```conf
-builders = ssh://engr-ugaif@nix-builder x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux
+builders = ssh://engr-ugaif@nix-builder1 x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux
 ```
 
+### Automatic Remote Build (Tablets)
+
+Surface tablets are configured to automatically use remote builders:
+
+```nix
+athenix.sw.remoteBuild = {
+  enable = true;
+  hosts = [ "nix-builder" ];
+};
+```
+
+This speeds up builds on resource-constrained devices.
+
 ## Troubleshooting
 
 ### Build Errors
 
-**Check configuration validity:**
+Get detailed error information:
+
 ```bash
+# Verbose error traces
+nix build .#installer-iso-nix-laptop1 --show-trace
+
+# Check all configurations first
 nix flake check --show-trace
 ```
 
-**Test specific host build:**
-```bash
-nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
-```
-
-### Remote Builder Issues
-
-**Test SSH access:**
-```bash
-ssh engr-ugaif@nix-builder
-```
-
-**Check builder disk space:**
-```bash
-ssh engr-ugaif@nix-builder df -h
-```
-
-**Temporarily disable remote builds:**
-
-In `inventory.nix`:
-```nix
-athenix.sw.remoteBuild.enable = false;
-```
-
 ### Out of Disk Space
 
-**Clean up Nix store:**
 ```bash
+# Clean up Nix store
 nix-collect-garbage -d
+
+# Optimize store
 nix store optimise
 ```
 
-**Check space:**
+### Build Hangs
+
 ```bash
-df -h /nix
+# List processes
+ps aux | grep nix
+
+# Cancel build
+Ctrl+C
 ```
 
-### ISO Won't Boot
+### Finding Artifact Outputs
 
-**Verify ISO integrity:**
 ```bash
-sha256sum result/iso/nixos-*.iso
+# List all buildable outputs
+nix flake show
+
+# Check specific output exists
+nix flake show | grep installer-iso-nix-laptop1
+
+# Get path to output
+nix build .#installer-iso-nix-laptop1 --no-link
 ```
 
-**Check USB write:**
-```bash
-# Use correct block size and sync
-sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress && sync
-```
+### Build Not Creating Expected File
 
-**Try alternative boot mode:**
-- UEFI systems: Try legacy BIOS mode
-- Legacy BIOS: Try UEFI mode
+```bash
+# Check build log
+nix build .#installer-iso-nix-laptop1 -L
+
+# Check what's in result
+ls -la result/
+
+# Inspect NixOS build structure
+nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
+```
 
 ## See Also
 
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Development workflow
+- [INVENTORY.md](INVENTORY.md) - Host configuration
+- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment
 - [README.md](../README.md) - Main documentation
-- [INVENTORY.md](INVENTORY.md) - Host configuration guide
-- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment guide