AGENTS.md: add hierarchical documentation for hosts, home, features, services

2025-12-29 18:55:52 +01:00
parent 460fc927ec
commit 6ac20b65f4
5 changed files with 284 additions and 6 deletions
--- a/home/AGENTS.md
+++ b/home/AGENTS.md
@@ -0,0 +1,51 @@
+# home/ - Home Manager Configurations
+
+User-level configurations managed by home-manager.
+
+## Structure
+
+```
+home/
+├── common/         # Shared home-manager config
+│   └── default.nix   # Overlays, nix-colors, allowUnfree
+├── features/       # Modular, toggle-able features
+│   ├── cli/          # Shell tools (see features/AGENTS.md)
+│   ├── coding/       # Dev tools
+│   └── desktop/      # GUI, Hyprland, theming
+└── m3tam3re/       # Per-host user configs
+    ├── home.nix      # Shared user config (git, ssh, packages)
+    └── m3-<host>.nix # Host-specific (imports features, monitor layouts)
+```
+
+## Per-Host Config Pattern
+
+Each `m3-<host>.nix`:
+1. Imports `../common`, `./home.nix`, and needed `../features/*`
+2. Enables specific features via `features.<category>.<name>.enable`
+3. Overrides host-specific settings (monitors, default apps)
+
+Example:
+```nix
+{
+  imports = [../common ./home.nix ../features/cli ../features/desktop];
+  
+  features.cli.nushell.enable = true;
+  features.desktop.hyprland.enable = true;
+  
+  wayland.windowManager.hyprland.settings.monitor = ["DP-1,2560x1440,0x0,1"];
+}
+```
+
+## Theming
+
+Uses nix-colors (Dracula scheme). Access colors:
+```nix
+"#${config.colorScheme.palette.base00}"  # Background
+"#${config.colorScheme.palette.base05}"  # Foreground
+```
+
+## Adding New User Config
+
+1. Create `m3tam3re/m3-<newhost>.nix`
+2. Import needed features
+3. Add to `flake.nix` homeConfigurations (standalone) or host's home-manager.users
--- a/home/features/AGENTS.md
+++ b/home/features/AGENTS.md
@@ -0,0 +1,64 @@
+# features/ - Modular Home Manager Features
+
+Toggle-able feature modules using `mkEnableOption` pattern.
+
+## Structure
+
+```
+features/
+├── cli/            # Shell & terminal tools
+│   ├── default.nix   # Always-on CLI tools (bat, eza, direnv, carapace)
+│   ├── nushell.nix   # features.cli.nushell.enable
+│   ├── fzf.nix       # features.cli.fzf.enable
+│   ├── starship.nix  # features.cli.starship.enable
+│   ├── zellij.nix    # Always-on zellij config
+│   └── secrets.nix   # features.cli.secrets.enable
+├── coding/         # Dev tools
+│   └── default.nix   # features.coding.* (zed, neovim)
+└── desktop/        # GUI applications
+    ├── default.nix   # Always-on (kitty, xdg, cursor)
+    ├── hyprland.nix  # features.desktop.hyprland.enable
+    ├── gaming.nix    # features.desktop.gaming.enable
+    ├── media.nix     # features.desktop.media.enable
+    └── ...
+```
+
+## Creating a New Feature
+
+1. Create `<category>/<feature>.nix`:
+```nix
+{config, lib, ...}:
+with lib; let
+  cfg = config.features.<category>.<feature>;
+in {
+  options.features.<category>.<feature>.enable = 
+    mkEnableOption "description";
+
+  config = mkIf cfg.enable {
+    # Configuration when enabled
+  };
+}
+```
+
+2. Import in `<category>/default.nix`
+3. Enable in user configs: `features.<category>.<feature>.enable = true;`
+
+## Feature Categories
+
+| Category | Purpose | Key features |
+|----------|---------|--------------|
+| cli | Shell tools | nushell, fzf, starship, nitch, secrets |
+| coding | Development | (in default.nix, no sub-features yet) |
+| desktop | GUI/WM | hyprland, gaming, media, office, crypto, fonts, rofi, wayland |
+
+## Always-On vs Toggle-able
+
+- **default.nix**: Configuration that applies when the category is imported (no enable flag)
+- **<feature>.nix**: Must be explicitly enabled via `features.*.enable = true`
+
+## Desktop Feature Details
+
+- `hyprland.nix`: Window manager config, keybinds, window rules (host overrides monitors/workspaces)
+- `gaming.nix`: Steam, gamemode, mangohud
+- `media.nix`: mpv, obs-studio, spotify
+- `wayland.nix`: Clipboard, screenshots, idle management