docs: comprehensive README with architecture, identity system, feature flags, work profile

2026-05-02 10:54:33 +02:00
parent 4acf4a12c0
commit 55661c12d4
1 changed files with 229 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -1,38 +1,253 @@
-# m3ta-home — Portable User Profiles
+# m3ta-home — Portable User Profiles for NixOS

-Centralized home-manager configurations for NixOS systems.
-Separates user identity, preferences, and feature sets for portable deployment.
+Centralized, portable Home-Manager configurations. Manages user identities, preferences, feature sets, and assets across multiple NixOS hosts — from desktops and laptops to headless servers.

-## Structure
+One repo, all your machines. Change once, deploy everywhere.
+
+## Architecture

 ```
 m3ta-home/
-├── lib/           ← mkHome, mkDevShell
-├── modules/       ← Home-Manager module exports
-├── profiles/      ← base, contexts, sets
-├── users/         ← identity, preferences, secrets
-└── secrets/       ← Agenix-encrypted user secrets
+├── flake.nix              ← Entry point: inputs, lib, homeManagerModules
+├── lib/
+│   ├── default.nix        ← Re-exports mkHome
+│   └── mkHome.nix         ← Composition engine (WHO + WHERE + WHAT)
+├── modules/
+│   ├── default.nix        ← Module aggregation for flake export
+│   └── paths.nix          ← "m3ta-home".paths.srcRoot (pure eval compatibility)
+├── profiles/
+│   ├── base/              ← Always loaded: shell, CLI tools, secrets, nix settings
+│   ├── contexts/
+│   │   ├── desktop/       ← GUI host: WM, apps, theme, terminal, XDG
+│   │   └── server/        ← Headless: minimal
+│   └── sets/              ← Optional feature bundles
+│       ├── coding/        ← core, editors, languages, LSP, agents
+│       ├── gaming/        ← Steam, Gamescope, GPU tools
+│       └── media/         ← OBS, ffmpeg, kdenlive, yt-dlp
+├── users/
+│   └── m3tam3re/
+│       ├── identities/
+│       │   ├── private.nix ← Personal: git (m3tm3re), SSH, JJ
+│       │   └── work.nix   ← Work: git (sascha.koenig), SSH, JJ
+│       └── preferences/   ← Identity-independent: cliphist, difftastic
+└── assets/
+    └── wallpapers/        ← Wallpaper collection (referenced via srcRoot)
 ```

-## Usage in nixos-config
+## The Three Dimensions
+
+`mkHome` composes a complete Home-Manager configuration from three axes:
+
+| Dimension | Options | Description |
+|-----------|---------|-------------|
+| **WHO** | `user` + `identity` | Which user, which identity (private/work) |
+| **WHERE** | `context` | `desktop` or `server` — mutually exclusive |
+| **WHAT** | `sets` | `coding`, `gaming`, `media` — freely combinable |
+
+```nix
+mkHome {
+  user = "m3tam3re";
+  identity = "private";     # ← "private" or "work"
+  context = "desktop";      # ← "desktop" or "server"
+  sets = ["coding" "gaming" "media"];
+}
+```
+
+### How it Works
+
+1. **Base** is always imported (shell, CLI tools, nix settings, nix-colors/dracula theme)
+2. **Context** is loaded based on `context` — exactly one of `desktop` or `server`
+3. **Sets** are loaded on top — any combination of `coding`, `gaming`, `media`
+4. **Identity** overrides git username/email, SSH match blocks, and Jujutsu config
+5. **Feature flags** in the consuming host selectively enable/disable individual modules
+
+### Assertions
+
+- `gaming` and `media` sets require `desktop` context (enforced via Nix assertions)
+- `coding` works in both `desktop` and `server` contexts
+
+## Usage
+
+### In nixos-config (flake.nix)

 ```nix
 inputs.m3ta-home = {
-  url = "git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home.git";
+  url = "git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home";
  inputs.nixpkgs.follows = "nixpkgs";
 };
 ```

+### Per-Host Configuration
+
+The consuming repo (`nixos-config`) maps hosts to profiles:
+
 ```nix
 # hosts/common/users/m3tam3re.nix
+hostProfiles = {
+  m3-kratos = { context = "desktop"; sets = ["coding" "gaming" "media"]; };
+  m3-atlas  = { context = "server";  sets = ["coding"]; };
+  m3-helios = { context = "server";  sets = []; };
+};
+```
+
+Then enables specific feature flags per host:
+
+```nix
 home-manager.users.m3tam3re = {
  imports = [
-    (inputs.m3ta-home.lib.mkHome {
+    (m3ta-lib.mkHome {
      user = "m3tam3re";
      identity = "private";
-      context = "desktop";
-      sets = [ "coding" "gaming" "media" ];
+      inherit (profile) context sets;
    })
+    hostFlags  # ← per-host enable/disable of individual modules
  ];
 };
 ```
+
+### Host-Specific Overrides
+
+Monitor layouts, window rules, and XDG/MIME settings stay in `nixos-config`:
+- `hosts/m3-kratos/home.nix` — dual DP monitors, Hyprland workspaces
+- `hosts/m3-ares/home.nix` — laptop eDP + HDMI, tuxedo-backlight
+- Server hosts need no `home.nix` (no desktop config)
+
+## Identity System: Private vs. Work
+
+The identity system allows switching between personal and work contexts on any machine — same dotfiles, different git identity, SSH config, and Jujutsu settings.
+
+### How Identities Work
+
+| | **Private** | **Work** |
+|---|---|---|
+| **Git user** | m3tm3re | sascha.koenig |
+| **Git email** | p@m3ta.dev | sascha.koenig@azintec.com |
+| **JJ email** | m@m3tam3re.com | sascha.koenig@azintec.com |
+| **SSH hosts** | code.m3ta.dev, github.com, private infra | git.az-gruppe.com, AZ servers |
+
+### Use Case: Work Laptop
+
+If you bring a work NixOS machine into your fleet, you can use the same `m3ta-home` repo with a different identity:
+
+```nix
+# On the work machine's nixos-config:
+(m3ta-lib.mkHome {
+  user = "m3tam3re";
+  identity = "work";       # ← switches git, SSH, JJ to work profile
+  context = "desktop";
+  sets = ["coding"];
+})
+```
+
+This gives you:
+- Your familiar shell setup (fish, starship, nushell)
+- Your CLI tools (fzf, bat, eza, zoxide, etc.)
+- Your editor configs (neovim, zed)
+- Work git identity and SSH configuration automatically
+- No gaming, media, or personal apps
+
+### Adding a New Identity
+
+1. Create `users/<username>/identities/<identity>.nix`
+2. Define git, SSH, and JJ settings for that identity
+3. Reference it via `identity = "<identity>"` in mkHome
+
+## Feature Flags
+
+Every module in m3ta-home has an `enable` option. Base modules default to `true`, everything else defaults to `false`. Flags are set per-host in the consuming repo.
+
+### Available Flags
+
+```
+base.shell.fish.enable          # Fish shell
+base.shell.nushell.enable       # Nushell
+base.shell.starship.enable      # Starship prompt
+base.cliTools.fzf.enable        # Fuzzy finder
+base.cliTools.bat.enable        # Cat replacement
+base.cliTools.eza.enable        # Ls replacement
+base.cliTools.zellij.enable     # Terminal multiplexer
+base.cliTools.zoxide.enable     # Smarter cd
+base.cliTools.direnv.enable     # Directory-based env
+base.cliTools.television.enable # TV fuzzy finder
+base.cliTools.nitch.enable      # System info
+base.secrets.enable             # pass-wayland, pinentry
+
+desktop.wm.hyprland.enable      # Hyprland window manager
+desktop.wm.rofi.enable          # Rofi launcher
+desktop.wm.wayland.enable       # Wayland tools (grim, slurp, etc.)
+desktop.apps.obsidian.enable    # Obsidian
+desktop.apps.office.enable      # LibreOffice
+desktop.apps.crypto.enable      # Bisq2, Monero, Trezor
+desktop.theme.fonts.enable      # Desktop fonts
+desktop.theme.wallpapers.enable # Wallpaper collection
+
+coding.editors.neovim.enable    # Neovim
+coding.editors.zed.enable       # Zed editor (desktop only)
+coding.lsp.enable               # Language servers
+coding.packages.enable          # Bruno, Insomnia
+coding.languages.python.enable
+coding.languages.javascript.enable
+coding.languages.typescript.enable
+coding.languages.rustToolchain.enable
+coding.languages.go.enable
+
+profiles.gaming.steam.enable
+profiles.gaming.gamescope.enable
+profiles.gaming.gpu.enable
+
+profiles.media.obs.enable
+profiles.media.ffmpeg.enable
+profiles.media.kdenlive.enable
+profiles.media.ytDlp.enable
+profiles.media.handbrake.enable
+```
+
+## Adding a New Module
+
+1. Create the `.nix` file in the appropriate directory under `profiles/`
+2. Define an `options` block with `mkEnableOption`
+3. Define a `config` block with `mkIf cfg.enable`
+4. Add the import to the parent `default.nix`
+
+Example:
+
+```nix
+# profiles/sets/coding/languages/elixir.nix
+{ config, lib, pkgs, ... }:
+with lib; let
+  cfg = config.coding.languages.elixir;
+in {
+  options.coding.languages.elixir.enable = mkEnableOption "Elixir language support";
+
+  config = mkIf cfg.enable {
+    home.packages = with pkgs; [ elixir ];
+  };
+}
+```
+
+Then add `./elixir` to `profiles/sets/coding/languages/default.nix`.
+
+## Assets
+
+Static assets (wallpapers, etc.) live in `assets/`. They are referenced via the `"m3ta-home".paths.srcRoot` option, which points to the flake source root and works in pure evaluation mode:
+
+```nix
+source = "${config."m3ta-home".paths.srcRoot}/assets/wallpapers";
+```
+
+## Dependencies
+
+| Input | Purpose |
+|-------|---------|
+| `nixpkgs` | Package set (follows nixos-config's nixpkgs) |
+| `home-manager` | Home-Manager modules |
+| `nix-colors` | Dracula theme palette (used everywhere) |
+| `m3ta-nixpkgs` | Custom packages (zellij-ps, rofi-project-opener) and HM modules |
+| `agenix` | Secret management |
+| `NUR` | Additional packages |
+
+## Important Notes
+
+- **Overlays** are managed at the NixOS level in `nixos-config`, not here. `home-manager.useGlobalPkgs = true` ensures HM sees them.
+- **Host-specific config** (monitor layouts, window rules, XDG/MIME) belongs in `nixos-config/hosts/<name>/home.nix`, not here.
+- **Pure evaluation**: All file references use `"m3ta-home".paths.srcRoot` instead of relative `../..` paths.