agents.md

2025-11-27 12:57:50 -08:00 · 2025-11-27 12:57:50 -08:00 · 63b66fb98a
commit 63b66fb98a
parent 26cf1cd241
2 changed files with 469 additions and 0 deletions
--- a/.clinerules
+++ b/.clinerules
@ -0,0 +1,310 @@
+# 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.
--- a/agents.md
+++ b/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