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/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,23 @@
 # AGENTS.md - NixOS Configuration Repository

-This document provides guidelines for AI agents working on this NixOS flake configuration.
-
-## Repository Overview
+**Generated:** 2025-12-29 | **Branch:** master | **Commit:** 460fc92

 Multi-host NixOS flake managing servers and workstations with home-manager integration.
- **Hosts**: m3-aether, m3-ares, m3-atlas, m3-helios, m3-kratos
- **User**: m3tam3re
- **Key inputs**: nixpkgs (unstable), home-manager, agenix, disko, nix-colors
+
+## Host Inventory
+
+| Host | Type | Purpose | Key Services |
+|------|------|---------|--------------|
+| m3-atlas | VPS | Main server | Traefik, containers (n8n, ghost, baserow, vaultwarden, paperless, gitea) |
+| m3-helios | VPS | DNS/Dashboard | AdGuard Home, Homarr, Traefik |
+| m3-ares | Workstation | Desktop | WireGuard VPN, Tailscale, sound, podman |
+| m3-kratos | Workstation | Desktop | WireGuard VPN, Tailscale, Hyprland, gaming |
+| m3-aether | VM | Cloud-init | Minimal config |
+| m3-daedalus | - | Home-manager only | Desktop environment (no NixOS config) |
+
+## Key Inputs
+
+nixpkgs (unstable), nixpkgs-stable (25.05), home-manager, agenix, disko, nix-colors, m3ta-nixpkgs (private fork)

 ## Build/Rebuild Commands

@@ -245,3 +255,29 @@ Short, descriptive messages:
 - `+package` - Adding new package
 - `service-name: description` - Service changes
 - `host: description` - Host-specific changes
+
+## Container IP Registry (m3-atlas)
+
+Network: `10.89.0.0/24`, Gateway: `10.89.0.1` (postgres host)
+
+| Service | IP | Port |
+|---------|-----|------|
+| baserow | 10.89.0.4 | 3001 |
+| ghost | 10.89.0.10 | 3002 |
+| slash | 10.89.0.11 | 3010 |
+| littlelink | 10.89.0.13 | 3004 |
+| n8n | 10.89.0.14 | 5678 |
+| restreamer | 10.89.0.15 | 3006 |
+| kestra | 10.89.0.17 | 3018 |
+| pangolin | 10.89.0.20 | 3020 |
+
+**Next available IP**: 10.89.0.22
+
+## Feature Flags
+
+Home-manager features use `mkEnableOption` pattern:
+- `features.cli.*` - Shell tools (nushell, fzf, nitch, starship, secrets)
+- `features.desktop.*` - GUI apps (crypto, coding, gaming, hyprland, media, office, rofi, fonts, wayland)
+- `extraServices.*` - NixOS services (ollama, podman, flatpak, virtualisation)
+
+Enable in per-host configs: `features.cli.nushell.enable = true;`
--- 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
--- a/hosts/AGENTS.md
+++ b/hosts/AGENTS.md
@@ -0,0 +1,64 @@
+# hosts/ - NixOS Host Configurations
+
+Host-specific NixOS system configurations. Each `m3-*` directory is a complete host.
+
+## Structure
+
+```
+hosts/
+├── common/           # Shared by ALL hosts
+│   ├── extraServices/  # Toggle-able services (ollama, podman, flatpak)
+│   ├── users/          # User definitions
+│   ├── ports.nix       # Central port registry
+│   └── default.nix     # Overlays, nix settings, home-manager integration
+└── m3-*/             # Per-host configurations
+    ├── default.nix       # Entry point (imports common + enables extraServices)
+    ├── configuration.nix # Core system (boot, networking, stateVersion)
+    ├── hardware-configuration.nix
+    ├── programs.nix      # Host-specific packages
+    ├── secrets.nix       # Agenix secret declarations
+    └── services/         # Service configs
+        └── containers/   # OCI container definitions (m3-atlas only has many)
+```
+
+## Adding a New Host
+
+1. Create `hosts/m3-<name>/` with required files
+2. Add to `flake.nix` nixosConfigurations
+3. Create matching `home/m3tam3re/m3-<name>.nix`
+
+## Host Quick Reference
+
+| Host | extraServices | Has disko | Key services/ files |
+|------|---------------|-----------|---------------------|
+| m3-atlas | podman | Yes | traefik, postgres, gitea, containers/* |
+| m3-helios | - | Yes | adguard, traefik, containers/homarr |
+| m3-ares | podman | No | wireguard, tailscale, sound |
+| m3-kratos | podman, ollama | No | wireguard, tailscale, sound |
+| m3-aether | - | Yes | cloud-init (minimal) |
+
+## extraServices Pattern
+
+Enable in host's `default.nix`:
+```nix
+extraServices = {
+  podman.enable = true;
+  ollama.enable = true;
+  flatpak.enable = false;
+  virtualisation.enable = false;
+};
+```
+
+## Port Allocation
+
+ALWAYS check `common/ports.nix` before adding new services. Register new ports there.
+
+## Secrets Declaration
+
+Each host's `secrets.nix` declares only secrets it needs:
+```nix
+age.secrets.service-name = {
+  file = ../../secrets/service-name.age;
+  owner = "optional-user";
+};
+```
--- a/hosts/m3-atlas/services/AGENTS.md
+++ b/hosts/m3-atlas/services/AGENTS.md
@@ -0,0 +1,63 @@
+# services/ - m3-atlas Service Configurations
+
+Main server services including Traefik reverse proxy and containerized apps.
+
+## Container Network
+
+- **Network**: `web` (podman network)
+- **Subnet**: `10.89.0.0/24`
+- **Gateway/Postgres**: `10.89.0.1`
+- **DNS Challenge**: GoDaddy via Traefik
+
+## Adding a New Container
+
+1. Pick next available IP from registry (currently: `10.89.0.22`)
+2. Register port in `hosts/common/ports.nix`
+3. Create `containers/<service>.nix`:
+
+```nix
+{config, ...}: {
+  virtualisation.oci-containers.containers."service" = {
+    image = "registry/image:tag";
+    environmentFiles = [config.age.secrets.service-env.path];
+    ports = ["127.0.0.1:PORT:PORT"];
+    volumes = ["service_data:/data"];
+    extraOptions = [
+      "--add-host=postgres:10.89.0.1"
+      "--ip=10.89.0.XX"
+      "--network=web"
+    ];
+  };
+
+  services.traefik.dynamicConfigOptions.http = {
+    services.service.loadBalancer.servers = [{ url = "http://localhost:PORT/"; }];
+    routers.service = {
+      rule = "Host(`service.domain.com`)";
+      tls.certResolver = "godaddy";
+      service = "service";
+      entrypoints = "websecure";
+    };
+  };
+}
+```
+
+4. Import in `containers/default.nix`
+5. Add secret to `secrets.nix` and root `secrets.nix`
+6. Update IP registry in root AGENTS.md
+
+## Service Files (non-container)
+
+| File | Purpose |
+|------|---------|
+| traefik.nix | Reverse proxy, TLS, entrypoints |
+| postgres.nix | Native PostgreSQL for containers |
+| tailscale.nix | Mesh VPN |
+| gitea.nix | Native Gitea (not containerized) |
+| minio.nix | S3-compatible storage |
+
+## Traefik Patterns
+
+- HTTP redirect to HTTPS: automatic via `web` entrypoint
+- TLS: `certResolver = "godaddy"` (DNS challenge)
+- Auth middleware: `middlewares = ["auth"]` (basic auth)
+- Domain redirects: See `traefik.nix` middlewares