nix-config/AGENTS.md

# Agent Guide for nix-config

This document provides guidelines for AI coding agents working in this Nix configuration repository.

## Repository Overview

This is a flake-based Nix configuration managing multiple hosts:
- `dnsc-air` (nix-darwin, macOS)
- `dnsc-work` (nix-darwin, macOS)
- `dnsc-deck` (home-manager only, Steam Deck)
- `dnsc-server` (NixOS)
- `dnsc-vps-sm` (NixOS)

## Directory Structure

```
.
├── flake.nix              # Main flake configuration
├── Justfile               # Common build/deploy commands
├── hosts/                 # Host-specific configurations
│   ├── dnsc-air/
│   ├── dnsc-work/
│   ├── dnsc-server/
│   └── dnsc-vps-sm/
├── home/                  # Home-manager configurations
│   ├── darwin.nix
│   ├── darwin-work.nix
│   ├── linux.nix
│   ├── server.nix
│   └── deck.nix
├── modules/               # Reusable modules
│   ├── base/
│   ├── fish/
│   ├── git/
│   ├── nixvim/
│   └── [40+ other modules]
└── secrets/               # agenix encrypted secrets
```

## Build Commands

### Validation and Testing
```bash
# Check flake evaluates correctly
nix flake check

# Show flake metadata
nix flake show

# Update flake inputs
just up

# Update specific input
just upi i=home-manager
```

### Deployment

**macOS (darwin-rebuild):**
```bash
# Deploy to current macOS host
just mre

# Deploy with lock file recreation
just mup

# Manual deployment
darwin-rebuild switch --flake .
```

**NixOS (nixos-rebuild):**
```bash
# Deploy NixOS configuration
just deploy

# Deploy with debug output
just debug

# Manual deployment
nixos-rebuild switch --flake .
```

**Steam Deck (home-manager):**
```bash
# Deploy to Steam Deck
just dre

# Manual deployment
nix run home-manager/master -- switch --flake .#dnsc-deck
```

### Maintenance
```bash
# View system generation history
just history

# Clean old generations (>7 days)
just clean

# Run garbage collection
just gc

# Open Nix REPL
just repl
```

## Code Style Guidelines

### Nix Language Conventions

**File Structure:**
```nix
{
  config,
  inputs,
  outputs,
  lib,
  pkgs,
  ...
}:
{
  imports = [
    # List imports first
  ];

  # Configuration follows
}
```

**Formatting:**
- Use 2 spaces for indentation
- Opening braces on same line: `{ foo = "bar"; }`
- Function parameters use named pattern matching
- Multi-line lists: one item per line with trailing semicolons
- String interpolation: `"${variable}"` or `''${expression}''`

**Naming Conventions:**
- Module files: `default.nix` in subdirectories
- Descriptive attribute names: `services.syncthing.enable`
- Host configurations: `dnsc-<hostname>`
- Use kebab-case for file/directory names: `nixos-modules`
- Use camelCase for attribute names in Nix expressions

**Imports:**
```nix
# In flake.nix
inputs.home-manager.nixosModules.home-manager

# In configuration files
outputs.nixosModules.base
../../modules/docker
./hardware-configuration.nix
```

**Package Management:**
```nix
# System packages
environment.systemPackages = with pkgs; [
  git
  btop
  neovim
];

# Using lib.mkAfter for additions
environment.systemPackages = lib.mkAfter (
  with pkgs; [
    additional-package
  ]
);
```

**Module Structure:**
- Keep modules focused and reusable
- Place in `modules/<service-name>/default.nix`
- Use option declarations when creating configurable modules
- Include modules in host configs via `imports = [ ]`

### Configuration Patterns

**Home Manager Integration:**
```nix
home-manager = {
  extraSpecialArgs = { inherit inputs outputs; };
  useGlobalPkgs = true;
  backupFileExtension = "backup";
  users = {
    dennis = import ../../home/darwin.nix;
  };
};
```

**Service Configuration:**
```nix
services.syncthing = {
  enable = true;
  user = "dennis";
  configDir = "/home/dennis/.config/syncthing";
  # ... additional settings
};
```

**Secrets with agenix:**
```nix
age = {
  identityPaths = [ "${config.users.users.dennis.home}/.ssh/id_ed25519" ];
  secrets."restic/password".file = ../../secrets/restic/password.age;
};
```

### Fish Shell Functions

**Function Style:**
```nix
functions = {
  function_name = /* fish */ ''
    # Fish shell code here
    echo "example"
  '';
};
```

**Inline Comments:**
Use `/* fish */` or `/* bash */` before multi-line strings to indicate language

## Common Tasks

### Adding a New Module

1. Create `modules/<module-name>/default.nix`
2. Define module structure:
   ```nix
   { pkgs, ... }:
   {
     # Configuration here
   }
   ```
3. Export in `flake.nix` if needed:
   ```nix
   nixosModules.moduleName = import ./modules/module-name;
   ```
4. Import in host configuration:
   ```nix
   imports = [ ../../modules/module-name ];
   ```

### Adding a New Host

1. Create `hosts/<hostname>/default.nix`
2. Create `hosts/<hostname>/hardware-configuration.nix` (for NixOS)
3. Add configuration to `flake.nix`:
   ```nix
   nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
     system = "x86_64-linux";
     specialArgs = { inherit inputs outputs; };
     modules = [ ./hosts/hostname ];
   };
   ```

### Modifying Home Manager Config

1. Edit appropriate file in `home/`:
   - `darwin.nix` for dnsc-air
   - `darwin-work.nix` for dnsc-work
   - `server.nix` for servers
2. Changes take effect on next deployment
3. Home configs import modules from `modules/` directory

## Important Notes

- **Never commit secrets**: Use agenix for sensitive data
- **Test before deploying**: Run `nix flake check` before major changes
- **System state version**: Don't change `system.stateVersion` without migration
- **Flake inputs**: Keep inputs up-to-date with `just up`
- **Git ignore**: `.DS_Store` files are ignored globally (see `modules/git/default.nix`)
- **No traditional package.json**: This is a Nix project, not a Node.js project
- **Experimental features**: This config uses `nix-command` and `flakes` features