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

sudo nixos-rebuild switch --flake '.?submodules=1#lauretta'
nix flake update                    # Update all inputs
nix flake lock --update-input X    # Update specific input

Dev Shell & REPL

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

Linting/Formatting

Uses alejandra:

nix fmt   # Format all Nix files
alejandra .

Testing

Manual VM testing:

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 in modules/home-manager/default.nix and modules/nixos/default.nix (alphabetical order)

Nix Module Template

{
  lib,
  config,
  pkgs,
  ...
}: let
  isEnabled =
    config.azos.<module-name>.enable;
in {
  options.azos.<module-name>.enable = lib.mkOption {
    default = 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)
• 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, ...
• Use ./relative/path.nix for local imports

Option Patterns

• Boolean enable: lib.mkOption { default = 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

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
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>