a

home-manager/README.md

@@ -0,0 +1,79 @@
+# Home-Manager Configuration
+
+This directory contains a refactored, modular home-manager configuration organized by program/tool.
+
+## Directory Structure
+
+```
+home-manager/
+├── home.nix              # Main entry point with all imports
+├── common.nix            # Base configuration (overlays, minimal packages)
+│
+├── platform/             # Platform-specific configurations
+│   ├── darwin.nix        # macOS-specific settings
+│   └── linux.nix         # Linux-specific settings
+│
+└── modules/              # Modular configurations by program/tool
+    ├── git.nix           # Git configuration (unified from old common + development)
+    ├── shells.nix        # Bash, Zsh, Fish configurations
+    ├── cli-tools.nix     # Modern CLI tools (ripgrep, fd, bat, etc.)
+    ├── terminal-emulators.nix  # Terminal emulator configs (Alacritty)
+    ├── editors.nix       # Text editor configs (Neovim)
+    ├── multiplexers.nix  # Terminal multiplexers (tmux)
+    └── dev-tools.nix     # Development tools (gh, lazygit, direnv)
+```
+
+## What Changed?
+
+### Problems Solved
+
+1. **Git configuration conflict**: Previously, both `common.nix` and `development.nix` configured `programs.git`, causing conflicts. Now unified in `modules/git.nix`
+
+2. **Package duplication**: Tools like `ripgrep` and `fd` were listed in multiple files. Now centralized in `modules/cli-tools.nix`
+
+3. **Unclear module boundaries**: `development.nix` mixed version control, build tools, and editors without clear purpose. Now split into focused modules.
+
+4. **Mixed concerns**: `terminal.nix` contained terminal emulator + CLI tools + text editor + tmux. Now properly separated.
+
+### File Mapping
+
+| Old File | New Location |
+|----------|--------------|
+| `development.nix` | → Split into `modules/git.nix` and `modules/dev-tools.nix` |
+| `shell.nix` | → `modules/shells.nix` |
+| `terminal.nix` | → Split into `modules/terminal-emulators.nix`, `modules/editors.nix`, `modules/multiplexers.nix`, and `modules/cli-tools.nix` |
+| `common.nix` | → Simplified (git config moved to `modules/git.nix`, CLI tools to `modules/cli-tools.nix`) |
+| `darwin.nix` | → `platform/darwin.nix` |
+| `linux.nix` | → `platform/linux.nix` |
+
+## Benefits
+
+- **Clear separation of concerns**: Each module has a single, well-defined purpose
+- **No more conflicts**: Git is configured in one place
+- **No duplication**: Packages appear once
+- **Easy to find things**: Need to configure git? Check `modules/git.nix`
+- **Easy to disable features**: Comment out imports in `home.nix`
+- **Platform-specific code isolated**: macOS and Linux configs clearly separated
+
+## Usage
+
+To disable a feature, simply comment out its import in `home.nix`:
+
+```nix
+imports = [
+  ./common.nix
+  ./platform/darwin.nix
+  ./platform/linux.nix
+  ./modules/git.nix
+  ./modules/shells.nix
+  # ./modules/multiplexers.nix  # Disable tmux
+  # ...
+];
+```
+
+## Next Steps
+
+1. Configure your git identity in `modules/git.nix` (lines 11-13)
+2. Enable/disable optional packages in each module as needed
+3. Add new modules following the same pattern (one file per program/tool category)
+