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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
nix repl
:lf .
# Then explore with:
inputs.nixpkgs.lib
```

### Dev Shell
```bash
nix develop .#shells.x86_64-linux.debugTexShell
```

### Garbage Collection
```bash
sudo nix-collect-garbage --delete-old
```

## Linting/Formatting

This project uses [alejandra](https://github.comkamadorama/alejandra) as the formatter.

```bash
# Format all Nix files
nix fmt

# Or use alejandra directly
alejandra .
```

There are no automated tests in this repository. VM testing is manual:
```bash
# 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:

```nix
{
  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
  ```nix
  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`