azos/AGENTS.md

AGENTS.md - Guidelines for Agentic Coding in Azos

This is a NixOS/Nix flake-based configuration repository using home-manager for dotfiles and system configuration.

Build Commands

Evaluating Configuration

# Evaluate system config (Lauretta laptop)
nix eval .#nixosConfigurations.lauretta.config.system.build.toplevel

# Evaluate flake info
nix flake show

# Evaluate all outputs
nix eval . --apply 'x: x'

Building

# Build VM
nix build .#nixosConfigurations.vm.config.system.build.vm
# Or with submodules
nix build '.?submodules=1#nixosConfigurations.vm.config.system.build.vm'

# Build formatter (alejandra)
nix build .#formatter.x86_64-linux

Deploying

# Switch to new config (Lauretta)
sudo nixos-rebuild switch --flake '.?submodules=1#lauretta'

# Update flake inputs
nix flake update

# Update specific input
nix flake lock --update-input azos-core

Nix REPL

nix repl
:lf .
# Then explore with:
inputs.nixpkgs.lib

Dev Shell

nix develop .#shells.x86_64-linux.debugTexShell

Garbage Collection

sudo nix-collect-garbage --delete-old

Linting/Formatting

This project uses alejandra as the formatter.

# Format all Nix files
nix fmt

# Or use alejandra directly
alejandra .

There are no automated tests in this repository. VM testing is manual:

# Build and run VM
nix build .#nixosConfigurations.vm.config.system.build.vm
./result/bin/run-nixos-vm

Code Style Guidelines

File Organization

• Home-manager modules: modules/home-manager/<name>.nix
• NixOS modules: modules/nixos/<name>.nix
• Imports: All modules are imported in modules/home-manager/default.nix and modules/nixos/default.nix
• Import sorting: Alphabetical order in default.nix files

Nix Module Structure

Follow this template for home-manager modules:

{
  lib,
  config,
  pkgs,
  ...
}: let
  isEnabled =
    config.azos.<module-name>.enable;
in {
  options.azos.<module-name>.enable = lib.mkOption {
    default = true;
    example = true;
    type = lib.types.bool;
  };

  config = lib.mkIf isEnabled {
    home.packages = with pkgs; [
      <package1>
      <package2>
    ];
  };
}

Naming Conventions

• Option paths: config.azos.<module-name>.<option>
• Enable option: Always enable (bool), default true
• Module names: kebab-case (e.g., libreoffice.nix, git-config.nix)
• Variable names: kebab-case in let bindings (e.g., isEnabled)

Formatting Rules

• Indentation: 2 spaces
• Let bindings: Multi-line format with isEnabled on its own line

  let
    isEnabled =
      config.azos.module.enable;
  in
  

• Imports: Sorted alphabetically in default.nix
• Packages: Use with pkgs; block for package lists

Imports

• Always include {...} for module args even if unused
• Standard module args: lib, config, pkgs, ...
• Use ./relative/path.nix for local imports

Adding New Modules

1. Create file in appropriate directory (modules/home-manager/ or modules/nixos/)
2. Add import to modules/<type>/default.nix in alphabetical order
3. Use the standard module template above
4. Run nix fmt to format

Option Patterns

• Boolean enable: Always use lib.mkOption with default = true, type = lib.types.bool
• Conditional config: Always use lib.mkIf isEnabled wrapper
• Package lists: Use with pkgs; [ ... ] syntax

Error Handling

• Use lib.mkIf for conditional configuration rather than if-then-else
• Use lib.mkDefault for values that can be overridden by users
• Use lib.mkForce sparingly for values that must not be overridden

Home-Manager Specific

• Config goes under home attribute (e.g., home.packages, home.file, home.sessionVariables)
• Use programs.<program> for program configurations
• Use services.<service> for system services

NixOS Specific

• Config goes under config directly (e.g., services, environment.systemPackages)
• Use environment.systemPackages for system-wide packages
• Use users.users.<name> for user configuration

Key Files

• flake.nix: Main flake definition, defines systems, overlays, modules
• modules/home-manager/default.nix: Home-manager module imports
• modules/nixos/default.nix: NixOS module imports
• nixos/configuration.nix: Lauretta laptop configuration
• nixos/configuration-vm.nix: Test VM configuration
• overlays/: Custom package overlays
• pkgs/: Custom packages

Common Tasks

Add new package to system

1. Create or edit module in modules/nixos/
2. Add to environment.systemPackages = with pkgs; [ pkg ]

Add new home-manager package

1. Create or edit module in modules/home-manager/
2. Add to home.packages = with pkgs; [ pkg ]

Add new system service

1. Edit appropriate NixOS module
2. Add service config under services.<service>

Test changes locally

1. Build VM: nix build .#nixosConfigurations.vm.config.system.build.vm
2. Run VM: ./result/bin/run-nixos-vm