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

nix eval .#nixosConfigurations.lauretta.config.system.build.toplevel
nix flake show

Building

# VM (with submodules for azos-core)
nix build '.?submodules=1#nixosConfigurations.vm.config.system.build.vm'

# Formatter
nix build .#formatter.x86_64-linux

Deploying

# Rebuild the azos environment for lauretta (this machine) — use this when asked to "rebuild"
sudo nixos-rebuild switch --flake '.?submodules=1#lauretta'
nix flake update --flake '.?submodules=1'                    # Update all inputs
nix flake lock --flake '.?submodules=1' --update-input X    # Update specific input

Note

: When the user asks to "rebuild", they mean rebuilding the lauretta environment with the command above — NOT building the VM.

Dev Shell & REPL

nix develop .#shells.x86_64-linux.default
nix repl
:lf .

Ad-hoc Commands

If an executable doesn't exist on the system, run it ad-hoc with:

nix shell nixpkgs#<package> --command <cmd> <args>

Linting/Formatting

Uses alejandra:

nix fmt   # Format all Nix files
alejandra .

Testing

Manual VM testing:

nix build '.?submodules=1#nixosConfigurations.vm.config.system.build.vm'
./result/bin/run-nixos-vm

Emacs Debugging

When adding or debugging Emacs functionality, you can interact with the running Emacs session via emacsclient (with user permission):

# Create and switch to a buffer
emacsclient -c -e '(switch-to-buffer (get-buffer-create "test"))'

# Evaluate arbitrary Elisp
emacsclient -e '(message "hello")'

Code Style Guidelines

File Organization

• Home-manager modules: modules/home-manager/<name>.nix
• NixOS modules: modules/nixos/<name>.nix
• Imports: All modules in modules/home-manager/default.nix and modules/nixos/default.nix (alphabetical order)
• Home config: home-manager/home.nix - main home-manager user config
• Custom packages: pkgs/ - custom package definitions
• Overlays: overlays/ - package overlays (addpkgs, modifications, unstable-packages)

Nix Module Template

{
  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; [ pkg1 pkg2 ];
  };
}

Naming Conventions

• Option paths: config.azos.<module-name>.<option>
• Enable option: enable (bool), default true
• Module names: kebab-case (libreoffice.nix, git-config.nix)
• Option names: may differ from filename (e.g., git.nix uses azos.git-config)
• Variables: kebab-case (isEnabled)

Formatting

• Indentation: 2 spaces
• Let bindings: multi-line with isEnabled on its own line
• Packages: Use with pkgs; [ ... ] syntax

Imports

• Always include {...} for module args
• Standard args: lib, config, pkgs, ...
• NixOS config args: inputs, outputs, lib, config, pkgs, ...
• Use ./relative/path.nix for local imports

Option Patterns

• Boolean enable: lib.mkOption { default = true; example = true; type = lib.types.bool; }
• Conditional config: lib.mkIf isEnabled { ... }
• User-overridable: lib.mkDefault
• Force value: lib.mkForce (sparingly)

Home-Manager vs NixOS

• Home-manager: home.packages, home.file, programs.<program>
• NixOS: config.services, environment.systemPackages

Suites System

Modules are organized into suites (defined in azos-core/):

• azos.suites.base - Base packages and config
• azos.suites.editor - Editor tools
• azos.suites.dev - Development tools
• azos.suites.station - Desktop applications
• azos.suites.exwm - EXWM window manager
• Enable in home-manager/home.nix with azos.suites.<name>.enable = true;

Specializations

NixOS supports specializations for alternative configurations:

specialisation = {
  hyprland = {
    configuration = {
      home-manager.users.aner = {pkgs, ...}: {
        azos.suites.exwm.enable = lib.mkForce false;
        azos.suites.hyprland.enable = true;
      };
    };
  };
};

Adding New Modules

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

Key Files

File	Purpose
flake.nix	Main flake, defines systems, overlays
modules/home-manager/default.nix	Home-manager imports
modules/nixos/default.nix	NixOS imports
home-manager/home.nix	User home-manager config, enables suites
nixos/configuration.nix	Lauretta laptop config
nixos/configuration-vm.nix	Test VM config
overlays/	Custom package overlays
pkgs/	Custom packages
azos-core/	Shared modules (submodule)

Common Tasks

Add system package: Edit NixOS module, add to environment.systemPackages = with pkgs; [ pkg ]

Add home-manager package: Edit module, add to home.packages = with pkgs; [ pkg ]

Add system service: Edit NixOS module, add under services.<service>

Add custom package: Create file in pkgs/, add to pkgs/default.nix, use via overlay

Access unstable packages: Use pkgs.unstable.<package> (via unstable-packages overlay)