Update flake to unstable, add chromium/opencode modules, update emacs config

2026-03-15 01:27:58 +02:00
parent 68d2c50721
commit 07fb5656f2
12 changed files with 299 additions and 71 deletions
@@ -0,0 +1,200 @@
+# 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`