# 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
```bash
# 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
```bash
# 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
```bash
# 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

```nix
# 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:
```bash
# 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