# NixOS Configuration Repository - AI Agent Guidelines

This file contains project-specific rules and guidelines for AI agents working with this NixOS configuration repository. Follow these rules to ensure consistent, secure, and maintainable configurations.

## Core Principles

### 1. Declarative Configuration
- All system state must be defined in Nix expressions
- Never use imperative commands for permanent changes
- Every configuration change should be reproducible

### 2. Modular Architecture
- Maintain separation between hardware, software, and user configurations
- Use existing modules before creating new ones
- Follow the established directory structure strictly

### 3. Security First
- Never expose sensitive data (passwords, private keys, API tokens)
- Use proper user privilege separation
- Validate all external inputs and configurations

## File Structure Rules

### Module Placement
```
desktop/           # Desktop environment configurations
  ├── dev.nix     # Development tools and languages
  ├── gaming.nix  # Games and gaming platforms
  ├── media.nix   # Audio/video software
  └── *.nix       # Other desktop applications

systems/           # Hardware-specific configurations
  ├── common.nix  # Shared system settings
  ├── framework.nix  # Framework laptop
  └── hostname.nix  # Other hardware configs

users/             # User configurations with Home Manager
  ├── jsutter.nix  # Primary user
  └── username.nix # Additional users

servers/           # Server-specific configurations
  ├── common.nix  # Base server settings
  └── service.nix # Specific services
```

### File Naming Conventions
- Use lowercase with hyphens: `vpn-config.nix`, `development-tools.nix`
- System configurations must match hostname: `framework.nix`, `aurora.nix`
- User configurations must match username: `jsutter.nix`, `isutter.nix`

## Nix/NixOS Specific Guidelines

### Function Parameters
Always include these parameters in configuration modules:
```nix
{ config, pkgs, pkgs-unstable, lib, ... }:  # For modules using unstable packages
{ config, pkgs, lib, ... }:                  # For stable-only modules
```

### Package Management Rules

#### Stable vs Unstable Packages
```nix
# PREFERRED: Use stable packages by default
environment.systemPackages = with pkgs; [
  firefox
  git
  vim
];

# ACCEPTABLE: Use unstable when necessary
# Add comments explaining why unstable is needed
environment.systemPackages = with pkgs; [
  firefox
  pkgs-unstable.windsurf  # Latest features not in stable
];
```

#### Package Selection Criteria
1. **Use stable unless**: Package doesn't exist OR needs newer version
2. **Document reasons**: Always comment why unstable is used
3. **Test thoroughly**: Unstable packages may have issues
4. **Review regularly**: Check if unstable packages can move to stable

### Module Organization Patterns

#### System Configuration Pattern
```nix
{ config, lib, pkgs, ... }:
{
  # Always include hostname first
  networking.hostName = "system-name";
  
  # Hardware configuration
  fileSystems."/" = { ... };
  fileSystems."/boot" = { ... };
  
  # System-specific settings
  # Group related configurations together
}
```

#### User Configuration Pattern
```nix
{ config, pkgs, pkgs-unstable, home-manager, ... }:
{
  # System user definition
  users.users.username = {
    shell = pkgs.zsh;
    isNormalUser = true;
    description = "User Description";
    extraGroups = [ "networkmanager" "wheel" ];  # Only essential groups
  };

  # Home Manager configuration
  home-manager.users.username = {
    home.username = "username";
    home.homeDirectory = "/home/username";
    home.stateVersion = "25.05";
    
    # User configurations
  };
}
```

## Security Rules

### Sensitive Data Handling
- **NEVER** commit plaintext passwords
- **NEVER** commit private SSH keys
- **NEVER** commit API tokens or secrets
- **ALWAYS** use hashed passwords: `hashedPassword = "$6$..."`
- **CONSIDER** using sops-nix for advanced secret management

### User Privilege Management
```nix
# GOOD: Minimal necessary groups
extraGroups = [ "networkmanager" "wheel" "audio" ];

# BAD: Over-privileged users
extraGroups = [ "networkmanager" "wheel" "audio" "video" "input" "disk" "lp" "scanner" ];
```

### SSH Key Management
```nix
# GOOD: Use authorizedKeys for SSH access
openssh.authorizedKeys.keys = [
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBNVUh+RrcOSMRV6qysnsdPs5AyK8dSm4QhhnwgpikyI user@domain"
];

# FORBIDDEN: Never include private keys
```

## Configuration Best Practices

### Code Style
- Use 2-space indentation
- Align attribute lists consistently
- Add comments for non-obvious configurations
- Group related configurations together

### Module Dependencies
- Avoid circular dependencies between modules
- Use proper imports for shared utilities
- Document module dependencies in comments

### Resource Management
```nix
# GOOD: Enable services only when needed
services.openssh.enable = true;
services.printing.enable = false;

# GOOD: Configure sensible defaults
boot.kernelPackages = pkgs.linuxPackages_latest;

# GOOD: Enable garbage collection
nix.gc = {
  automatic = true;
  dates = "weekly";
  options = "--delete-older-than 7d";
};
```

## Testing and Validation

### Pre-commit Testing
ALWAYS run these commands before submitting changes:

```bash
# 1. Syntax check
nix flake check

# 2. Dry run for affected systems
sudo nixos-rebuild dry-run --flake .#framework
sudo nixos-rebuild dry-run --flake .#aurora
sudo nixos-rebuild dry-run --flake .#labrizor

# 3. Check flake outputs
nix flake show
```

### Build Verification
- Test on at least one system before merging
- Verify all services start correctly
- Check for package conflicts
- Validate hardware-specific configurations

### Rollback Planning
- Always know how to rollback changes
- Keep previous generation available
- Document critical system dependencies

## Common Workflows

### Adding New Packages
1. **Determine appropriate module** (desktop/, systems/, users/)
2. **Check if package exists** in stable channel
3. **Use unstable only if necessary** with documentation
4. **Test with dry-run** before applying
5. **Update relevant documentation**

### Creating New Modules
1. **Follow existing patterns** in similar modules
2. **Include proper function parameters**
3. **Add descriptive comments**
4. **Test module independently**
5. **Update flake.nix** if needed

### System Modifications
1. **Identify correct system file** in `systems/`
2. **Backup current configuration**
3. **Make minimal, focused changes**
4. **Test thoroughly on target system**
5. **Document hardware-specific requirements**

## Forbidden Patterns

### NEVER DO THESE:
- **Hardcode paths**: Use Nix store paths or derivations
- **Ignore errors**: All configuration errors must be resolved
- **Skip testing**: Always validate changes before applying
- **Mix concerns**: Don't put desktop configs in system files
- **Use mutable state**: Avoid commands that modify /etc directly

### INSTEAD DO THESE:
- **Use proper Nix expressions** for all configurations
- **Handle errors explicitly** with appropriate error messages
- **Test before deploying** with dry-run and build tests
- **Maintain separation** between hardware, software, users
- **Use declarative approach** for all system changes

## Documentation Requirements

### Code Comments
- Explain non-obvious configurations
- Document reasons for unstable package usage
- Note hardware-specific requirements
- Reference external dependencies

### Commit Messages
- Use clear, descriptive commit messages
- Reference affected systems/modules
- Explain reasoning for significant changes
- Include testing steps when applicable

## Emergency Procedures

### System Recovery
If a system fails to boot after changes:
1. Boot from installation media
2. Mount root filesystem: `mount /dev/disk/by-partlabel/primary /mnt`
3. Roll back: `sudo nixos-rebuild switch --rollback`
4. Identify and fix configuration issues
5. Test before rebooting

### Configuration Rollback
```bash
# List available generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous working generation
sudo nixos-rebuild switch --profile-name generation-123

# Or use rollback shortcut
sudo nixos-rebuild switch --rollback
```

## Agent-Specific Rules

### Before Making Changes
1. **Read existing documentation** in docs/
2. **Understand current configuration** patterns
3. **Identify impact scope** of proposed changes
4. **Plan testing strategy** for affected systems

### During Development
1. **Follow established patterns** exactly
2. **Add appropriate comments** explaining changes
3. **Test incrementally** with dry-run checks
4. **Document new patterns** if introducing changes

### After Changes
1. **Run complete test suite**
2. **Update relevant documentation**
3. **Verify all systems** build successfully
4. **Commit with clear message** describing changes

---

These rules ensure consistent, secure, and maintainable NixOS configurations. Follow them strictly, and ask for clarification when unsure about any requirement.