128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# AGENTS.md - NixOS Configuration Repository
|
|
|
|
This file provides guidance for AI coding assistants working on this NixOS configuration.
|
|
|
|
## Repository Overview
|
|
|
|
This is a NixOS system configuration for a desktop named "atlas". It uses flakes, modular organization, and includes customizations for gaming, development, and daily desktop use.
|
|
|
|
## Build/Validation Commands
|
|
|
|
```bash
|
|
# Validate Nix syntax and build configuration
|
|
nix flake check
|
|
|
|
# Build the configuration (dry-run, doesn't activate)
|
|
nixos-rebuild dry-build --flake .
|
|
|
|
# Format all .nix files with nixfmt
|
|
nixfmt **/*.nix
|
|
|
|
# Check for common issues
|
|
nixos-rebuild dry-activate --flake .
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### File Organization
|
|
- Entry point: `configuration.nix`
|
|
- Flake definition: `flake.nix`
|
|
- Modular structure under `modules/` organized by category:
|
|
- `core/` - Boot, system, networking, users, localization
|
|
- `hardware/` - GPU, audio, storage, power management
|
|
- `desktop/` - Window manager, apps, theming, portals
|
|
- `services/` - System services (avahi, printing, navidrome)
|
|
- `dev/` - Development tools, docker, shells
|
|
- `gaming/` - Steam, wine, gamemode
|
|
|
|
### Module Pattern
|
|
Each module follows this structure:
|
|
```nix
|
|
# modules/<category>/<name>.nix
|
|
# Brief description of what this module configures
|
|
{
|
|
config,
|
|
pkgs,
|
|
lib,
|
|
inputs, # Only if using flake inputs
|
|
username, # Custom arg passed from flake
|
|
...
|
|
}:
|
|
|
|
{
|
|
# Configuration options here
|
|
}
|
|
```
|
|
|
|
### Imports Pattern
|
|
`default.nix` files should only contain imports:
|
|
```nix
|
|
# modules/<category>/default.nix
|
|
{
|
|
imports = [
|
|
./boot.nix
|
|
./system.nix
|
|
];
|
|
}
|
|
```
|
|
|
|
### Formatting Rules
|
|
- Use 2-space indentation
|
|
- No tabs
|
|
- Keep lines under 100 characters when possible
|
|
- Add blank lines between logical sections
|
|
- Use descriptive comments with `# Description` format
|
|
|
|
### Naming Conventions
|
|
- Module files: descriptive lowercase with hyphens (e.g., `gpu-amd.nix`)
|
|
- Use `username` variable from flake for user-specific paths
|
|
- Use `lib.mkIf` for conditional configuration
|
|
- Use `lib.mkDefault` for values that can be overridden
|
|
|
|
### Input Handling
|
|
- Pass `inputs` from flake when accessing external packages
|
|
- Access input packages via: `inputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.default`
|
|
- Use `pkgs.stdenv.hostPlatform.system` for system-specific packages
|
|
|
|
### Special Files
|
|
- `hardware-configuration.nix` - Generated by nixos-generate-config, DO NOT EDIT
|
|
- Scripts in `scripts/` are bash installers (not part of NixOS config)
|
|
- Overlays contain patched Python scripts
|
|
|
|
### Security Notes
|
|
- Never commit secrets, API keys, or tokens
|
|
- Sensitive files are in `.gitignore`
|
|
- Use proper LUKS encryption for swap and root partitions
|
|
- Secure Boot is enabled with custom Limine patches
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Module
|
|
1. Create file in appropriate `modules/<category>/` subdirectory
|
|
2. Add to the category's `default.nix` imports
|
|
3. Follow existing module structure and formatting
|
|
4. Add brief header comment describing purpose
|
|
|
|
### Adding a Package
|
|
- System packages: add to `environment.systemPackages` in appropriate module
|
|
- User packages: prefer adding to system packages for shared use
|
|
- Flake packages: access via inputs with proper system attribute
|
|
|
|
### Testing Changes
|
|
```bash
|
|
# Before committing, always verify syntax
|
|
nix flake check
|
|
|
|
# Build to catch evaluation errors
|
|
nixos-rebuild dry-build --flake .
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
External flake inputs:
|
|
- `nixpkgs` - Main NixOS packages (nixos-unstable)
|
|
- `noctalia` - Desktop shell
|
|
- `nix-cachyos-kernel` - CachyOS kernel with optimizations
|
|
- `zen-browser` - Zen browser
|
|
- `opencode` - AI coding assistant
|