aner
e6188adc0d
- Simplify escape sequences in bind commands (M, Z keys) - Add c.session.default_name = '' and c.session.store_size = 0 - Update AGENTS.md (trimmed to 150 lines) - Update flake.lock with latest dependencies
134 lines
3.4 KiB
Markdown
134 lines
3.4 KiB
Markdown
# 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.debugTexShell
|
|
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 .#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
|
|
|
|
```nix
|
|
{
|
|
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>` |