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