nixos/agents.md

Quick Start Guide for NixOS Configuration Repository

This guide provides essential information for agents to quickly understand and work with this NixOS configuration repository.

Repository at a Glance

• Type: Flake-based NixOS configuration
• Base: NixOS 25.05 stable with selective unstable packages
• Systems: framework (laptop), aurora (desktop), labrizor (desktop)
• Desktop: KDE Plasma with modular application sets
• Users: jsutter (primary), isutter, aksutter

Essential Commands

Testing Configuration

# Check flake syntax and outputs
nix flake check

# Dry run for specific system
sudo nixos-rebuild dry-run --flake .#systemname

# Show flake outputs
nix flake show

Applying Changes

# Apply to specific system
sudo nixos-rebuild switch --flake .#systemname

# Build only (don't switch)
sudo nixos-rebuild build --flake .#systemname

# Test (current generation rollback on reboot)
sudo nixos-rebuild test --flake .#systemname

Updates

# Update all flake inputs
nix flake update

# Update only unstable packages
nix flake lock --update-input nixpkgs-unstable

File Locations

What you want to do	Where to edit
Add system packages	systems/common.nix
Add development tools	desktop/dev.nix
Add desktop apps	desktop/[category].nix
Modify user settings	users/[username].nix
System-specific settings	systems/[hostname].nix
Add new system	Edit flake.nix + create systems/[hostname].nix

Adding Packages: Quick Reference

# In appropriate .nix file
{ config, pkgs, pkgs-unstable, ... }:  # Add pkgs-unstable if needed

{
  # Use stable packages
  environment.systemPackages = with pkgs; [
    firefox
    git
    new-package
  ];
  
  # Use unstable when necessary
  environment.systemPackages = with pkgs; [
    pkgs-unstable.latest-tool  # Comment why unstable is needed
  ];
}

System Status

framework (Laptop)

• Hardware: Framework AMD AI 300 series
• Special: AMD GPU optimization, power management
• Users: jsutter

aurora (Desktop)

• Hardware: Generic desktop
• Special: 3D/2D printing, multiple users
• Users: jsutter, isutter, aksutter

labrizor (Desktop)

• Hardware: Generic desktop
• Special: 3D printing
• Users: jsutter

Module Structure

Common Desktop Modules (applied to all desktop systems)

• systems/common.nix - Base system config
• desktop/plasma.nix - KDE Plasma
• desktop/dev.nix - Development tools
• desktop/office.nix - Office applications
• desktop/gaming.nix - Gaming platforms
• desktop/media.nix - Audio/video software
• desktop/virtualization.nix - VM/container support
• desktop/tailscale.nix - VPN for internet archive
• desktop/3dprinting.nix - 3D printing tools
• desktop/2dprinting.nix - 2D printing tools

Critical Rules

1. Always test before applying: Use dry-run first
2. Use stable packages unless necessary: Document unstable usage
3. Follow file placement rules: Put configs in correct directories
4. Maintain security: Never commit secrets or private keys

Emergency Recovery

If system fails to boot:

# Boot from installation media
mount /dev/disk/by-partlabel/primary /mnt
cd /mnt/root/nixos
sudo nixos-rebuild switch --rollback

Common Patterns

Add New Package

1. Choose appropriate file (see table above)
2. Add to environment.systemPackages
3. Test: sudo nixos-rebuild dry-run --flake .#system-name
4. Apply: sudo nixos-rebuild switch --flake .#system-name

Add New User

1. Create users/newuser.nix following existing pattern
2. Add to desired system in flake.nix
3. Test and apply

Add New System

1. Create systems/hostname.nix with hardware config
2. Add to flake.nix following existing pattern
3. Test and apply

Documentation

• Project Guide: docs/PROJECT_GUIDE.md - Comprehensive documentation
• File Structure: docs/FILE_STRUCTURE.md - Detailed file reference
• Workflows: docs/WORKFLOW.md - Step-by-step procedures
• Rules: .clinerules - Agent-specific guidelines

Get Help

1. Check existing patterns in similar files
2. Read docs/PROJECT_GUIDE.md for detailed information
3. Follow .clinerules for best practices
4. Test thoroughly before applying changes