# 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
```bash
nix eval .#nixosConfigurations.lauretta.config.system.build.toplevel
nix flake show
```

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

# Formatter
nix build .#formatter.x86_64-linux
```

### Deploying
```bash
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
```bash
nix develop .#shells.x86_64-linux.default
nix repl
:lf .
```

## Linting/Formatting

Uses [alejandra](https://github.com/kamadorama/alejandra):
```bash
nix fmt   # Format all Nix files
alejandra .
```

## Testing

Manual VM testing:
```bash
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):

```bash
# 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

```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; [ 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:
```nix
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)