agents.md
This commit is contained in:
Julian Sutter
parent
26cf1cd241
commit
63b66fb98a
2 changed files with 469 additions and 0 deletions
310
.clinerules
Normal file
310
.clinerules
Normal file
|
|
@ -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.
|
||||||
159
agents.md
Normal file
159
agents.md
Normal file
|
|
@ -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
|
||||||
Loading…
Add table
Add a link
Reference in a new issue