agents.md

agents.md

@@ -0,0 +1,159 @@
+# 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