From 63b66fb98a583af7b23f44d8b1cc6ec35a90ec19 Mon Sep 17 00:00:00 2001 From: Julian Sutter Date: Thu, 27 Nov 2025 12:57:50 -0800 Subject: [PATCH] agents.md --- .clinerules | 310 ++++++++++++++++++++++++++++++++++++++++++++++++++++ agents.md | 159 +++++++++++++++++++++++++++ 2 files changed, 469 insertions(+) create mode 100644 .clinerules create mode 100644 agents.md diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..860f381 --- /dev/null +++ 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. diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..acee33e --- /dev/null +++ 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