docs: expand AGENTS.md with comprehensive patterns and add HM module docs

modules/home-manager/AGENTS.md

@@ -0,0 +1,74 @@
+# Home Manager Modules
+
+User-level configuration modules organized by functional category.
+
+## Structure
+
+```
+home-manager/
+├── default.nix      # Aggregator: imports all categories + ports.nix
+├── ports.nix        # Port management (HM-specific: generateEnvVars)
+├── cli/             # Terminal/CLI tools
+│   ├── default.nix  # Category aggregator
+│   └── zellij-ps.nix
+└── coding/          # Development tools
+    ├── default.nix  # Category aggregator
+    └── editors.nix  # Neovim + Zed configs
+```
+
+## Where to Look
+
+| Task | Location |
+|------|----------|
+| Add CLI module | `cli/<name>.nix`, import in `cli/default.nix` |
+| Add coding module | `coding/<name>.nix`, import in `coding/default.nix` |
+| Add new category | Create `<category>/default.nix`, import in root `default.nix` |
+| Module with host ports | Import `../../lib/ports.nix`, use `mkPortHelpers` |
+
+## Option Namespaces
+
+- `cli.*` - CLI tools (e.g., `cli.zellij-ps.enable`)
+- `coding.editors.*` - Editor configs (e.g., `coding.editors.neovim.enable`)
+- `m3ta.ports.*` - Port management (shared with NixOS)
+
+## Patterns
+
+**Category aggregator** (`cli/default.nix`):
+```nix
+{
+  imports = [
+    ./zellij-ps.nix
+    # Add new modules here
+  ];
+}
+```
+
+**Simple module** (zellij-ps):
+```nix
+options.cli.zellij-ps = {
+  enable = mkEnableOption "...";
+  projectFolders = mkOption { type = types.listOf types.path; ... };
+};
+config = mkIf cfg.enable {
+  home.packages = [ pkgs.zellij-ps ];
+  home.sessionVariables.PROJECT_FOLDERS = ...;
+};
+```
+
+**Multi-config module** (editors.nix):
+```nix
+config = mkMerge [
+  (mkIf cfg.neovim.enable { programs.neovim = {...}; })
+  (mkIf cfg.zed.enable { programs.zed-editor = {...}; })
+  (mkIf (cfg.neovim.enable || cfg.zed.enable) { home.packages = [...]; })
+];
+```
+
+## HM vs NixOS Differences
+
+| Feature | Home Manager | NixOS |
+|---------|--------------|-------|
+| `currentHost` default | `null` (must set) | `config.networking.hostName` |
+| `generateEnvVars` | Available | Not available |
+| Output file | `~/.config/m3ta/ports.json` | `/etc/m3ta/ports.json` |
+| Package access | `pkgs.*` via overlay | `pkgs.*` via overlay |