Many changes by GLM

AGENTS.md

@@ -28,7 +28,7 @@ nix flake lock --update-input X    # Update specific input
 
 ### Dev Shell & REPL
 ```bash
-nix develop .#shells.x86_64-linux.debugTexShell
+nix develop .#shells.x86_64-linux.default
 nix repl
 :lf .
 ```
@@ -45,7 +45,7 @@ alejandra .
 
 Manual VM testing:
 ```bash
-nix build .#nixosConfigurations.vm.config.system.build.vm
+nix build '.?submodules=1#nixosConfigurations.vm.config.system.build.vm'
 ./result/bin/run-nixos-vm
 ```
 
@@ -55,6 +55,9 @@ nix build .#nixosConfigurations.vm.config.system.build.vm
 - **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
 
@@ -70,6 +73,7 @@ nix build .#nixosConfigurations.vm.config.system.build.vm
 in {
   options.azos.<module-name>.enable = lib.mkOption {
     default = true;
+    example = true;
     type = lib.types.bool;
   };
 
@@ -83,6 +87,7 @@ in {
 - 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
@@ -93,10 +98,11 @@ in {
 ### 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; type = lib.types.bool; }`
+- 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)
@@ -105,6 +111,30 @@ in {
 - 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/`
@@ -119,6 +149,7 @@ in {
 | `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 |
@@ -131,4 +162,8 @@ in {
 
 **Add home-manager package**: Edit module, add to `home.packages = with pkgs; [ pkg ]`
 
-**Add system service**: Edit NixOS module, add under `services.<service>`
+**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)