AGENTS.md

ALWAYS Read @CONTRIBUTING.md when making changes.

For any Nix code or module task, use the writing-nix skill before making edits.

Core Principles

1. Home-First: Prefer Home Manager (modules/home) for user-space configs (dotfiles, programs) over system modules.
2. Namespace Scoping: Always place options under khanelinix.*.
3. Explicit Imports: Single-line with lib; and with pkgs; are acceptable. Avoid block-level with lib;. Use inherit (lib) ... or explicit lib.<fn> for larger scopes.
4. Modular & Composable: Split large modules (>200 lines) into sub-modules in a directory.
5. Skill Usage (Nix Work): For any Nix code or module task, use the writing-nix skill before making edits.

Coding Style & Patterns

• Naming: camelCase for Nix variables/options, kebab-case for files and directories.
• Option Path: khanelinix.{category}.{subcategory}.{name}.
• Home Manager + System Access: HM modules use osConfig ? {} to access the host system's configuration.
• Conditionals: Prefer lib.mkIf for entire configuration blocks.
• PATH vs Store Paths: Prefer adding required tools to home.packages / environment.systemPackages so configs can use plain command names, instead of inlining store paths with lib.getExe/getExe' in shell aliases or config strings (unless a fixed store path is explicitly needed).
• Secrets: Use sops-nix. Never commit secrets in plaintext. Use lib.getFile "secrets/..." helpers.
• Custom Helpers: Check lib.khanelinix for common helpers like enabled and disabled.

Git Workflow

• In sandboxed agent environments, set PRE_COMMIT_HOME=/tmp/pre-commit before git commit if pre-commit cannot write to ~/.local/cache/pre-commit.

Module Template

{ config, lib, pkgs, osConfig ? {}, ... }:
let
  inherit (lib) mkIf mkEnableOption;
  cfg = config.khanelinix.category.name;
in {
  options.khanelinix.category.name.enable = mkEnableOption "Description";
  config = mkIf cfg.enable {
    # implementation
  };
}