# Agent Guidelines for NixOS Configuration

## Project Overview
This repository contains a NixOS configuration managed with Nix Flakes. It defines system configurations for one or more hosts (currently `cryodev-main` and `cryodev-pi`), custom packages, modules, overlays, and templates.

## Environment & Build Commands

### Prerequisites
-   **Nix** with Flakes enabled.
-   **Git**

### Core Commands
-   **Build Host Configuration**:
    ```bash
    nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
    # Examples:
    nix build .#nixosConfigurations.cryodev-main.config.system.build.toplevel
    nix build .#nixosConfigurations.cryodev-pi.config.system.build.toplevel
    ```
-   **Format Code**:
    ```bash
    nix fmt
    ```
    This uses the formatter defined in `flake.nix` (typically `nixfmt` via `pre-commit-hooks`).
-   **Run Checks (Lint/Test)**:
    ```bash
    nix flake check
    ```
    This validates the flake outputs and runs configured checks (including formatting checks and deploy-rs checks).
-   **Update Flake Inputs**:
    ```bash
    nix flake update
    ```

### Development Shell
You can enter a development shell with necessary tools (if configured in `devShells`):
```bash
nix develop
```

## Code Style & Conventions

### General Nix Style
-   **Formatting**: Strictly adhere to `nixfmt` style. Run `nix fmt` before committing.
-   **Indentation**: Use 2 spaces for indentation.
-   **Lines**: Limit lines to 80-100 characters where possible, but follow the formatter's lead.
-   **Comments**: Use `#` for single-line comments. Avoid block comments `/* ... */` unless necessary for large blocks of text.

### Module Structure
-   **Function Header**: Always use the standard module arguments pattern:
    ```nix
    { config, lib, pkgs, inputs, outputs, constants, ... }:
    ```
    -   Include `inputs`, `outputs`, and `constants` if you need access to flake inputs, the flake's own outputs, or the central constants.
-   **Option Definitions**:
    -   Define options in `options = { ... };`.
    -   Implement configuration in `config = { ... };`.
    -   Use `mkEnableOption` for boolean flags.
    -   Use `mkOption` with types (e.g., `types.str`, `types.bool`) and descriptions.
-   **Imports**:
    -   Use relative paths for local modules: `imports = [ ./module.nix ];`.
    -   Use `inputs` or `outputs` for external/shared modules: `imports = [ outputs.nixosModules.common ];`.

### Naming Conventions
-   **Files**: `kebab-case.nix` (e.g., `hardware-configuration.nix`).
-   **Options**: `camelCase` (e.g., `services.myService.enable`).
-   **Variables**: `camelCase` in `let ... in` blocks.

### Flake Specifics
-   **Inputs**: Defined in `flake.nix`.
    -   `nixpkgs`: Main package set (typically following a stable release).
    -   `nixpkgs-unstable`: Unstable channel for latest packages.
-   **Outputs**:
    -   `nixosConfigurations`: Host definitions.
    -   `nixosModules`: Reusable modules exported by this flake.
    -   `packages`: Custom packages exported by this flake.
    -   `overlays`: Overlays to modify `nixpkgs`.
    -   `templates`: Project templates for creating new hosts.

### Error Handling
-   Use `assert` for critical configuration invariants.
-   Use `warnings` or `trace` for deprecation or non-critical issues during evaluation.
-   Example:
    ```nix
    config = lib.mkIf cfg.enable {
      assertions = [
        { assertion = cfg.port > 1024; message = "Port must be non-privileged"; }
      ];
    };
    ```

## Directory Structure
-   `flake.nix`: Entry point, defines inputs and outputs.
-   `hosts/`: Specific host configurations.
    -   `<hostname>/default.nix`: Host entry point.
-   `modules/`: Reusable NixOS modules.
    -   `nixos/`: Modules specific to NixOS (e.g. `nixvim`, `comin`, `forgejo`).
-   `pkgs/`: Custom package definitions.
-   `overlays/`: Nixpkgs overlays.
-   `templates/`: Templates for bootstrapping new hosts (`raspberry-pi`, `generic-server`).
-   `scripts/`: Helper scripts (e.g., `install.sh` for bootstrapping).
-   `constants.nix`: Central configuration for domains, IPs, and ports.
-   `INSTRUCTIONS.md`: Setup and deployment instructions (DNS, SOPS, bootstrap).
-   `README.md`: General project documentation and architecture overview.

## Deployment Workflows
-   **cryodev-main**: Push-based deployment via Forgejo Actions using `deploy-rs`.
-   **cryodev-pi**: Pull-based deployment using `comin` (polling the repository).

## Working with Agents
-   **Context**: When asking for changes, specify if it's for a specific host (`hosts/cryodev-main`) or a shared module (`modules/`).
-   **Verification**: Always run `nix flake check` after changes to ensure validity.
-   **Refactoring**: When moving code, update `imports` carefully.
-   **Constants**: Use `constants.nix` for values like domains, IPs, and ports instead of hardcoding them in modules.