feat: Added agents.md

AGENTS.md

@@ -0,0 +1,337 @@
+# Agent Guidelines for NixOS/nix-darwin Dotfiles
+
+This repository contains NixOS, nix-darwin, and Home Manager configurations written in the Nix language. This document provides essential information for AI coding agents working in this codebase.
+
+## Identity
+
+You are a sysadmin that manages server configurations and deployments in NixOS/nix-darwin using the Nix language.
+
+## Build, Test, and Deployment Commands
+
+### Building Configurations
+
+**Linux (NixOS):**
+```bash
+# Build configuration
+nixos-rebuild build --flake . --show-trace
+just build
+
+# Apply configuration
+sudo nixos-rebuild switch --flake . --builders '' --max-jobs 1 --cores 32
+just install cores='32'
+
+# Test configuration (no activation)
+sudo nixos-rebuild test --fast --flake .
+```
+
+**macOS (nix-darwin):**
+```bash
+# Build configuration
+nix run nix-darwin -- build --flake . --show-trace
+just build
+
+# Apply configuration
+nix run nix-darwin -- switch --flake .
+just install
+```
+
+**Home Manager:**
+```bash
+nix --extra-experimental-features "nix-command flakes" run home-manager/master -- switch --flake . --show-trace
+just home
+```
+
+### Deployment to Remote Machines
+
+```bash
+# Deploy to specific machine (uses deploy-rs)
+deploy -s .#ryu      # Desktop (x86_64-linux)
+deploy -s .#tako     # Server (x86_64-linux)
+deploy -s .#tsuba    # Raspberry Pi (aarch64-linux)
+deploy -s .#kuro     # MacBook M4 Pro (aarch64-darwin)
+deploy -s .#shiro    # Mac Mini M4 (aarch64-darwin)
+```
+
+### Validation and Checking
+
+```bash
+# Check flake for errors
+nix flake check
+
+# Check deployment configuration
+nix flake check --show-trace
+
+# Validate specific output
+nix eval .#nixosConfigurations.ryu.config.system.build.toplevel
+```
+
+### Formatting
+
+```bash
+# Format Nix files with alejandra
+alejandra fmt <file>.nix
+
+# Format all files in directory
+alejandra fmt .
+```
+
+## Directory Structure
+
+```
+.
+├── flake.nix                 # Main flake entry point
+├── overlays.nix              # Package overlays
+├── deploy.nix                # deploy-rs configuration
+├── sops.nix                  # Secrets management
+├── stylix.nix                # Styling configuration
+├── nixos/                    # NixOS configurations
+│   ├── default.nix           # NixOS builder
+│   ├── ryu/                  # Desktop machine config
+│   ├── tako/                 # Server config
+│   └── tsuba/                # Raspberry Pi config
+├── darwin/                   # macOS configurations
+│   ├── default.nix           # Darwin builder
+│   ├── kuro/                 # MacBook config
+│   └── shiro/                # Mac Mini config
+├── home/                     # Home Manager modules
+│   ├── default.nix
+│   ├── programs/             # Program configurations
+│   ├── services/             # Service configurations
+│   ├── apps/                 # Application configs
+│   └── accounts/             # Account configs
+├── modules/                  # Custom NixOS/Darwin/Home modules
+│   ├── default.nix
+│   ├── nixos/                # NixOS-specific modules
+│   ├── darwin/               # Darwin-specific modules
+│   └── home/                 # Home Manager modules
+├── builders/                 # Machine builder definitions
+├── packages/                 # Custom packages
+├── scripts/                  # Helper scripts
+├── secrets/                  # SOPS secrets (encrypted)
+└── patches/                  # Package patches
+```
+
+## Code Style Guidelines
+
+### Nix Language Conventions
+
+**File Structure:**
+```nix
+{
+  inputs,
+  config,
+  pkgs,
+  lib,
+  device,
+  ...
+}: {
+  # Configuration here
+}
+```
+
+**Imports:**
+- List all parameter imports at the top
+- Order: `inputs`, `config`, `pkgs`, `lib`, `device`, custom params, `...`
+- Use set destructuring for clarity
+
+**Formatting:**
+- Use `alejandra` formatter (maintained in the repo)
+- 2-space indentation
+- Keep lines under 100 characters when reasonable
+- Use trailing commas in lists and attribute sets
+
+**Naming Conventions:**
+- Files: lowercase with hyphens (e.g., `my-module.nix`)
+- Attributes: camelCase (e.g., `enableMyFeature`)
+- Functions: camelCase (e.g., `mkDevice`)
+- Constants: UPPER_SNAKE_CASE (e.g., `API_KEY`)
+- Device names: lowercase (e.g., `ryu`, `tako`, `kuro`)
+
+**Let Expressions:**
+```nix
+with lib; let
+  cfg = config.programs.myProgram;
+  myHelper = x: y: x + y;
+in {
+  options = { ... };
+  config = mkIf cfg.enable { ... };
+}
+```
+
+**Options:**
+```nix
+options = {
+  programs.myProgram = {
+    enable = mkEnableOption "my program";
+    package = mkPackageOption pkgs "myProgram" {};
+    
+    settings = mkOption {
+      type = types.attrs;
+      default = {};
+      description = "Configuration settings";
+    };
+  };
+};
+```
+
+**Conditionals:**
+- Use `mkIf` for config options
+- Use `lib.optionalAttrs` for attribute sets
+- Use `lib.optionals` for lists
+- Prefer inline `if-then-else` for simple expressions
+
+**String Interpolation:**
+```nix
+# Good
+"${pkgs.package}/bin/command"
+"${config.home.homeDirectory}/.config"
+
+# Avoid unnecessary interpolation
+"simple string"  # not "${''simple string''}"
+```
+
+**Comments:**
+```nix
+# Single-line comments for brief explanations
+# Use above the line being explained
+
+/* Multi-line comments
+   for longer explanations
+   or documentation blocks */
+```
+
+### Module Patterns
+
+**Simple Package Module:**
+```nix
+{pkgs, ...}: {
+  home.packages = [pkgs.myPackage];
+}
+```
+
+**Program Configuration Module:**
+```nix
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+with lib; let
+  cfg = config.programs.myProgram;
+in {
+  options.programs.myProgram = {
+    enable = mkEnableOption "myProgram";
+  };
+  
+  config = mkIf cfg.enable {
+    home.packages = [pkgs.myProgram];
+  };
+}
+```
+
+**Service Module:**
+```nix
+{
+  config,
+  lib,
+  ...
+}: {
+  services.myService = {
+    enable = true;
+    settings = {
+      # Configuration here
+    };
+  };
+}
+```
+
+### Device-Specific Logic
+
+```nix
+# Check device properties
+home.packages = lib.optionals device.isLinux [
+  pkgs.linuxPackage
+] ++ lib.optionals device.isDarwin [
+  pkgs.macPackage
+];
+
+# Or use conditionals
+sessionVariables = {
+  BROWSER = if device.isDarwin then "open" else "xdg-open";
+};
+```
+
+## Important Rules
+
+1. **NEVER create new markdown files** unless explicitly requested
+2. **DO NOT add helper scripts or shell scripts** - use Nix expressions
+3. **DO NOT add example snippets or sample code files**
+4. **All configurations must use Nix expressions** when possible
+5. **Follow existing naming conventions** and directory structure
+6. **Ensure new files match the structure** of existing similar files
+
+## Secrets Management
+
+- Secrets are managed with SOPS (Secrets OPerationS)
+- Encrypted secrets in `secrets/` directory
+- Configuration in `.sops.yaml`
+- Access secrets via `config.sops.secrets."path/to/secret".path`
+
+## Common Patterns
+
+### Adding a New Program
+
+```bash
+# Use the justfile recipe
+just add program myprogram
+
+# This creates home/programs/myprogram.nix and adds import
+```
+
+### Creating a Module
+
+1. Determine location: `modules/nixos/`, `modules/darwin/`, or `modules/home/`
+2. Create file with proper structure
+3. Add to `modules/default.nix` imports
+4. Use the module in appropriate device configuration
+
+### Device Configuration
+
+Devices are defined in `flake.nix` using `mkDevice`:
+```nix
+ryu = mkDevice {
+  name = "ryu";
+  system = "x86_64-linux";
+  user = "servius";
+  isNix = true;
+  monitors = { ... };
+};
+```
+
+Properties available:
+- `device.isLinux`, `device.isDarwin`
+- `device.isServer`, `device.hasGui`
+- `device.isDesktopLinux`
+- `device.name`, `device.user`, `device.home`
+
+## Error Handling
+
+- Use `mkIf` to conditionally enable configurations
+- Check for required options before using them
+- Validate paths and files exist when referencing external resources
+- Handle both Linux and macOS cases when adding cross-platform features
+
+## Testing Changes
+
+1. Build the configuration first: `just build` or `nixos-rebuild build --flake .`
+2. Check for errors with `--show-trace` flag
+3. Test on non-production systems first
+4. Use `sudo nixos-rebuild test` for temporary activation on Linux
+
+## Version Information
+
+- Nix Version: 2.32+
+- Flakes: Enabled (required)
+- Formatter: alejandra
+- State Version: 23.11+ (varies by machine)

builders/mirai.nix

@@ -1,7 +0,0 @@
-# {
-#   hostName = "mirai.darksailor.dev";
-#   sshUser = "remotebuilder";
-#   systems = ["x86_64-linux" "aarch64-linux"];
-#   protocol = "ssh-ng";
-#   supportedFeatures = ["nixos-test" "benchmark" "big-parallel" "kvm"];
-# }

home/programs/blobdrop.nix

@@ -1 +1,8 @@
-{pkgs, ...}: {home.packages = [pkgs.blobdrop];}
+{
+  pkgs,
+  device,
+  lib,
+  ...
+}: {
+  home.packages = lib.optionals (device.name != "shiro") [pkgs.blobdrop];
+}

home/programs/fzf.nix

@@ -1 +1 @@
-{pkgs, ...}: { home.packages = [pkgs.fzf];}
+{pkgs, ...}: {home.packages = [pkgs.fzf];}