meta: add AI agent rules and skills

Create a modular, context-aware style guide for AI code assistants.

- Add nixos-architecture skill for .nix file generation and networking patterns
- Add dns-management rule to enforce Bind9 SOA serial increments
- Add cicd-networking rule for direct-IP runner authentication
- Add git-workflow rule to enforce conventional and atomic commits

.agent/rules/ci-cd-networking-constraints.md

@@ -0,0 +1,13 @@
+---
+name: cicd-networking
+description: Networking constraints for CI/CD workflow files (Gitea/GitHub Actions).
+globs: [".github/workflows/.yml", ".github/workflows/.yaml", ".gitea/workflows/.yml", ".gitea/workflows/.yaml"]
+---
+
+# Bos55 CI/CD Networking Constraints
+
+When generating or modifying CI/CD workflows, strictly follow these networking practices:
+
+1. **IP-Based Login for Reliability**
+   - When CI runners (like Gitea Actions) need to interact with internal services for authentication or deployment, always use direct IP addresses (e.g., `192.168.0.25`) for machine-to-machine login steps.
+   - **Why?** This bypasses potential DNS resolution issues or delays within the isolated runner environment, ensuring maximum robustness during automated CI/CD runs.

.agent/rules/dns-management.md

@@ -0,0 +1,14 @@
+---
+name: dns-management
+description: Hard constraints for modifying Bind9 DNS zone files.
+globs: ["db.", ".zone"]
+---
+
+# Bos55 DNS Management Constraints
+
+When modifying or generating Bind9 zone files, you MUST strictly adhere to the following rules:
+
+1. **Serial Increment (CRITICAL)**
+   - Every single time you modify a Bind9 zone file (e.g., `db.depeuter.dev`), you MUST increment the Serial number in the SOA record. Failure to do so will cause DNS propagation to fail.
+2. **Domain Name Specificity**
+   - Prefer a single, well-defined explicit domain (e.g., `nix-cache.depeuter.dev`) instead of creating multiple aliases or using magic values. Keep records clean and explicit.

.agent/rules/git-workflow.md

@@ -0,0 +1,21 @@
+---
+name: git-workflow
+description: Rules for generating Git commit messages and managing branch workflows.
+globs: ["COMMIT_EDITMSG", ".git/*"]
+---
+
+# Git Workflow Constraints
+
+When generating commit messages, reviewing code for a commit, or planning a branch workflow, strictly follow these standards:
+
+1. **Commit Formatting**
+   - **Conventional Commits**: You MUST format all commit messages using conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `ci:`, `meta:`.
+   - **Clarity**: Ensure the message clearly explains *what* changed and *why*.
+2. **Atomic Commits**
+   - Group changes by a single logical concern.
+   - NEVER mix documentation updates, core infrastructure code, and style guide changes in the same commit.
+   - Ensure that the generated commit is easily revertible without breaking unrelated features.
+3. **Branching Workflow**
+   - Always assume changes will be pushed to a feature branch to create a Pull Request.
+   - Do not suggest or generate commands that push directly to the main branch.
+

.agent/skills/nixos-architecture/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: bos55-nix-architecture
+description: Implementation patterns for NixOS configurations, networking, and service modules.
+globs: [".nix", "hosts/**/", "modules//*", "secrets//*"]
+---
+
+# NixOS Architecture Skill
+
+When generating or modifying NixOS configuration files for the Bos55 project, strictly adhere to the following architectural patterns:
+
+## 1. Minimal Hardcoding & Dynamic Discovery
+
+- **Local IP Ownership**: Define IPv4/IPv6 addresses **only** within their respective host configuration files (e.g., `hosts/<HostName>/default.nix`). Do not use global IP mapping modules.
+- **Inter-Host Discovery**: Resolve a host's IP or port by evaluating its configuration at build time. Never hardcode another host's IP.
+  **Pattern Example**:
+  ```
+  let
+    bcConfig = inputs.self.nixosConfigurations.BinaryCache.config;
+    bcIp = (pkgs.lib.head bcConfig.networking.interfaces.ens18.ipv4.addresses).address;
+  in "http://${bcIp}:8080"
+  ```
+- **Unified Variables**: Use local variables (e.g., `let dbName = "attic"; in ...`) for shared values between host services and containers to ensure consistency.
+
+## 2. Modular Service Encapsulation
+
+- **Self-Contained Modules**: Service modules (`modules/services/<service>/default.nix`) must manage their own configurations. Prefer `lib.mkOption` over hardcoded strings for domains, ports, and credentials.
+- **Firewall Responsibility**: Open ports (e.g., TCP 8080, SSH 22) directly within the service module based on its own options. Do not open service ports manually in host files.
+- **Remote Builders**: Define `nix.settings.trusted-users`, `builder` user, and SSH rules directly within the service module if it supports remote building (e.g., Attic).
+
+## 3. Networking & Connectivity
+
+- **Container-to-Host**: Host services must connect to companion containers using the container name, not the bridge IP or `localhost`.
+- **Host Resolution**: Map the container name to `127.0.0.1` using `networking.extraHosts` in the host service module to route traffic seamlessly.
+- **Domain Deferral**: Client modules must defer their default domain settings to the server module's defined domain option.
+
+## 4. Secrets Management
+
+- **Sops-Nix Exclusivity**: Manage all secrets via `sops-nix`.
+- **Centralized Config**: Rely on `modules/common/default.nix` for fleet-wide settings like `defaultSopsFile` and `age.keyFile`.
+- **References**: Always reference credentials dynamically using `config.sops.secrets."path/to/secret".path`.
+
+## 5. Security & Documentation
+
+- **Supply Chain Protection**: Always verify and lock Nix flake inputs. Use fixed-output derivations for external resource downloads.
+- **Assumptions Documentation**: Clearly document environment assumptions (e.g., Proxmox virtualization, Tailscale networking, and specific IP ranges) in host or service READMEs.
+- **Project Structure**: Maintain the strict separation of `hosts/`, `modules/`, `users/`, and `secrets/` to ensure clear ownership and security boundaries.
+

.github/workflows/build.yml

@@ -0,0 +1,43 @@
+name: "Build"
+on:
+  pull_request:
+  push:
+
+jobs:
+  determine-hosts:
+    name: "Determining hosts to build"
+    runs-on: ubuntu-latest
+    container: catthehacker/ubuntu:act-24.04
+    outputs:
+      hosts: ${{ steps.hosts.outputs.hostnames }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: https://github.com/cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+      - name: "Determine hosts"
+        id: hosts
+        run: |
+          hostnames="$(nix eval .#nixosConfigurations --apply builtins.attrNames --json)"
+          printf "hostnames=%s\n" "${hostnames}" >> "${GITHUB_OUTPUT}"
+
+  build:
+    runs-on: ubuntu-latest
+    container: catthehacker/ubuntu:act-24.04
+    needs: determine-hosts
+    strategy:
+      matrix:
+        hostname: [
+          Development,
+          Testing
+        ]
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: https://github.com/cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+      - name: "Build host"
+        run: |
+          nix build ".#nixosConfigurations.${{ matrix.hostname }}.config.system.build.toplevel" --verbose
+

.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: "Test"
+on:
+  pull_request:
+  push:
+jobs:
+  tests:
+    if: false
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+    - uses: actions/checkout@v5
+    - uses: https://github.com/cachix/install-nix-action@v31
+      with:
+        nix_path: nixpkgs=channel:nixos-unstable
+    - name: "My custom step"
+      run: nix run nixpkgs#hello

.gitignore

@@ -1 +1,2 @@
 .idea
+result

flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1760524057,
-        "narHash": "sha256-EVAqOteLBFmd7pKkb0+FIUyzTF61VKi7YmvP1tw4nEw=",
+        "lastModified": 1772624091,
+        "narHash": "sha256-QKyJ0QGWBn6r0invrMAK8dmJoBYWoOWy7lN+UHzW1jc=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "544961dfcce86422ba200ed9a0b00dd4b1486ec5",
+        "rev": "80bdc1e5ce51f56b19791b52b2901187931f5353",
         "type": "github"
       },
       "original": {
@@ -48,11 +48,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1760393368,
-        "narHash": "sha256-8mN3kqyqa2PKY0wwZ2UmMEYMcxvNTwLaOrrDsw6Qi4E=",
+        "lastModified": 1772495394,
+        "narHash": "sha256-hmIvE/slLKEFKNEJz27IZ8BKlAaZDcjIHmkZ7GCEjfw=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "ab8d56e85b8be14cff9d93735951e30c3e86a437",
+        "rev": "1d9b98a29a45abe9c4d3174bd36de9f28755e3ff",
         "type": "github"
       },
       "original": {

hosts/Development/default.nix

@@ -11,7 +11,6 @@
         };
         traefik.enable = true;
         plex.enable = true;
-        solidtime.enable = true;
       };
       virtualisation.guest.enable = true;
     };

modules/apps/default.nix

@@ -9,7 +9,6 @@
     ./homepage
     ./jellyfin
     ./plex
-    ./solidtime
     ./speedtest
     ./technitium-dns
     ./traefik

modules/apps/solidtime/default.nix

@@ -1,278 +0,0 @@
-{ config, lib, pkgs, ... }:
-
-let
-  cfg = config.homelab.apps.solidtime;
-
-  networkName = "solidtime";
-  internalNetworkName = "solidtime-internal";
-  proxyNet = config.homelab.apps.traefiik.sharedNetworkName;
-
-  user = "1000:1000";
-
-  # dbExternalPort = ...;
-  dbInternalPort = 5432;
-
-  gotenbergPort = 3000;
-
-  inherit (config.virtualisation.oci-containers) containers;
-
-  solidtimeImageName = "solidtime/solidtime";
-  version = "0.10.0";
-  solidtimeImage = "${solidtimeImageName}:${version}";
-  solidtimeImageFile = pkgs.dockerTools.pullImage {
-    imageName = solidtimeImageName;
-    finalImageTag = version;
-    imageDigest = "sha256:817d3a366ecc39f0473d7154372afa82dd4e6e50c66d70be45804892c8421cbb";
-    sha256 = "sha256-h5aCKaquUF/EVsOHaLOHrn1HAoXZYPhAbJ+e4cmjSA8=";
-  };
-
-  volumes = [
-    "solidtime-storage:/var/www/html/storage"
-    "solidtime-logs:/var/www/html/storage/logs"
-    "solidtime-app:/var/www/html/storage/app"
-  ];
-
-  # laravel.env
-  laravelEnv = {
-    APP_NAME = "Solidtime";
-    VITE_APP_NAME = laravelEnv.APP_NAME;
-    APP_ENV = "production";
-    APP_DEBUG = "false";
-    APP_URL = "http://localhost:${toString cfg.port}";
-    APP_FORCE_HTTPS = "false";
-    APP_ENABLE_REGISTRATION = "false";
-    TRUSTED_PROXIES = "0.0.0.0/0,2000:0:0:0:0:0:0:0/3";
-
-    # Logging
-    LOG_CHANNEL = "stderr_daily";
-    LOG_LEVEL = "debug";
-
-    # Database
-    DB_CONNECTION = "pgsql";
-    DB_HOST = containers.solidtimeDb.hostname;
-    DB_PORT = toString dbInternalPort;
-    DB_SSL_MODE = "require";
-    DB_DATABASE = "solidtime";
-    DB_USERNAME = "solidtime";
-    DB_PASSWORD = "ChangeMe";
-
-    # Mail
-    #MAIL_MAILER = "smtp";
-    #MAIL_HOST = "smtp.gmail.com";
-    #MAIL_PORT = "465";
-    #MAIL_ENCRYPTION = "tls";
-    #MAIL_FROM_ADDRESS = "no-reply@time.depeuter.dev";
-    MAIL_FROM_NAME = laravelEnv.APP_NAME;
-    #MAIL_USERNAME = "kmtl.hugo@gmail.com";
-    #MAIL_PASSWORD = "fhfxoequhhqidrhd";
-
-    # Queue
-    QUEUE_CONNECTION = "database";
-
-    # File storage
-    FILESYSTEM_DISK = "local";
-    PUBLIC_FILESYSTEM_DISK = "public";
-
-    # Services
-    GOTENBERG_URL = "http://${containers.solidtimeGotenberg.hostname}:${toString gotenbergPort}";
-  };
-
-in {
-  options.homelab.apps.solidtime = {
-    enable = lib.mkEnableOption "Solidtime time tracker using Docker";
-    port = lib.mkOption {
-      type = lib.types.int;
-      default = 8000;
-      description = "Solidtime WebUI port";
-    };
-    exposePort = lib.mkEnableOption "Expose Soldtime port";
-  };
-
-  config = lib.mkIf cfg.enable {
-    homelab.virtualisation.containers.enable = true;
-
-    # Make sure the Docker network exists.
-    systemd.services = {
-      "docker-${networkName}-create-network" = {
-        description = "Create Docker network for ${networkName}";
-        requiredBy = [
-          "${containers.solidtime.serviceName}.service"
-        ];
-        serviceConfig = {
-          Type = "oneshot";
-          RemainAfterExit = true;
-        };
-        script = ''
-          if ! ${pkgs.docker}/bin/docker network ls | grep -q ${networkName}; then
-            ${pkgs.docker}/bin/docker network create ${networkName}
-          fi
-        '';
-      };
-      "docker-${internalNetworkName}-create-network" = {
-        description = "Create Docker network for ${internalNetworkName}";
-        requiredBy = [
-          "${containers.solidtime.serviceName}.service"
-          "${containers.solidtimeScheduler.serviceName}.service"
-          "${containers.solidtimeQueue.serviceName}.service"
-          "${containers.solidtimeDb.serviceName}.service"
-          "${containers.solidtimeGotenberg.serviceName}.service"
-        ];
-        serviceConfig = {
-          Type = "oneshot";
-          RemainAfterExit = true;
-        };
-        script = ''
-          if ! ${pkgs.docker}/bin/docker network ls | grep -q ${internalNetworkName}; then
-            ${pkgs.docker}/bin/docker network create ${internalNetworkName}
-          fi
-        '';
-      };
-    };
-    
-    virtualisation.oci-containers.containers = {
-      solidtime = {
-        hostname = "solidtime";
-        image = solidtimeImage;
-        imageFile = solidtimeImageFile;
-        inherit user;
-        autoStart = true;
-        dependsOn = [
-          "solidtimeDb"
-        ];
-        ports = [
-          # Open ports if you don't use Traefik
-          "${toString cfg.port}:8000"
-        ];
-        networks = [
-          networkName
-          internalNetworkName
-        ];
-        extraOptions = [
-          # Healthecks
-          # test: [ "CMD", "curl", "--fail", "http://localhost:8000/health-check/up" ]
-          ''--health-cmd=curl --fail http://localhost:8000/health-check/up''
-        ];
-        inherit volumes;
-        labels = {
-          "traefik.enable" = "true";
-          "traefik.http.routers.solidtime.rule" = "Host(`time.${config.networking.hostName}.depeuter.dev`)";
-          "traefik.http.services.solidtime.loadbalancer.server.port" = toString cfg.port;
-        };
-        environmentFiles = [
-          "/home/admin/.solidtime.env"
-        ];
-        environment = laravelEnv // {
-          CONTAINER_MODE = "http";
-        };
-      };
-      solidtimeScheduler = {
-        hostname = "scheduler";
-        image = solidtimeImage;
-        imageFile = solidtimeImageFile;
-        inherit user;
-        autoStart = true;
-        dependsOn = [
-          "solidtimeDb"
-        ];
-        networks = [
-          internalNetworkName
-        ];
-        extraOptions = [
-          # Healthchecks
-          # test: [ "CMD", "healthcheck" ]
-          ''--health-cmd="healthcheck"''
-        ];
-        inherit volumes;
-        environmentFiles = [
-          "/home/admin/.solidtime.env"
-        ];
-        environment = laravelEnv // {
-          CONTAINER_MODE = "scheduler";
-        };
-      };
-      solidtimeQueue = {
-        hostname = "queue";
-        image = solidtimeImage;
-        imageFile = solidtimeImageFile;
-        inherit user;
-        autoStart = true;
-        networks = [
-          internalNetworkName
-        ];
-        extraOptions = [
-          # Healthchecks
-          # test: [ "CMD", "healthcheck" ]
-          ''--health-cmd="healthcheck"''
-        ];
-        inherit volumes;
-        dependsOn = [
-          "solidtimeDb"
-        ];
-        environmentFiles = [
-          "/home/admin/.solidtime.env"
-        ];
-        environment = laravelEnv // {
-          CONTAINER_MODE = "worker";
-          WORKER_COMMAND = "php /var/www/html/artisan queue:work";
-        };
-      };
-      solidtimeDb = let
-        imageName = "postgres";
-        finalImageTag = "15";
-      in {
-        hostname = "database";
-        image = "${imageName}:${finalImageTag}";
-        imageFile = pkgs.dockerTools.pullImage {
-          inherit imageName finalImageTag;
-          imageDigest = "sha256:98fe06b500b5eb29e45bf8c073eb0ca399790ce17b1d586448edc4203627d342";
-          sha256 = "sha256-AZ4VkOlROX+nR/MjDjsA4xdHzmtKjiBAtsp2Q6IdOvg=";
-        };
-        autoStart = true;
-        ports = [
-          # "${toString dbExternalPort}:${toString dbInternalPort}"
-        ];
-        networks = [
-          internalNetworkName
-        ];
-        extraOptions = [
-          # Healthchecks
-          # test: - CMD - pg_isready - '-q' - '-d' - '${DB_DATABASE}' - '-U' - '${DB_USERNAME}' retries: 3 timeout: 5s
-          ''--health-cmd="pg_isready -q -d ${laravelEnv.DB_DATABASE} -U ${laravelEnv.DB_USERNAME}"''
-          "--health-retries=3"
-          "--health-timeout=5s"
-        ];
-        volumes = [
-          "solidtime-db:/var/lib/postgresql/data"
-        ];
-        environment = {
-          PGPASSWORD = laravelEnv.DB_PASSWORD;
-          POSTGRES_DB = laravelEnv.DB_DATABASE;
-          POSTGRES_USER = laravelEnv.DB_USERNAME;
-          POSTGRES_PASSWORD = laravelEnv.DB_PASSWORD;
-        };
-      };
-      solidtimeGotenberg = let
-        imageName = "gotenberg/gotenberg";
-        finalImageTag = "8.26.0";
-      in {
-        hostname = "gotenberg";
-        image = "${imageName}:${finalImageTag}";
-        imageFile = pkgs.dockerTools.pullImage {
-          inherit imageName finalImageTag;
-          imageDigest = "sha256:328551506b3dec3ff6381dd47e5cd72a44def97506908269e201a8fbfa1c12c0";
-          sha256 = "sha256-1zz4xDAgXxHUnkCVIfjHTgXb82EFEx+5am6Cu9+eZj4=";
-        };
-        autoStart = true;
-        networks = [
-          internalNetworkName
-        ];
-        extraOptions = [
-          # Healthchecks
-          # test: [ "CMD", "curl", "--silent", "--fail", "http://localhost:3000/health" ]
-          ''--health-cmd="curl --silent --fail http://localhost:${toString gotenbergPort}/health"''
-        ];
-      };
-    };
-  };
-}
-

modules/apps/vaultwarden/default.nix

@@ -13,12 +13,12 @@ in {
       description = "Vaultwarden WebUI port";
     };
     domain = lib.mkOption {
-      type = lib.types.string;
+      type = lib.types.str;
       example = "https://vault.depeuter.dev";
       description = "Domain to configure Vaultwarden on";
     };
     name = lib.mkOption {
-      type = lib.types.string;
+      type = lib.types.str;
       example = "Hugo's Vault";
       description = "Service name to use for invitations and mail";
     };
@@ -77,7 +77,7 @@ in {
         dataDir = "/data";
       in {
         hostname = "vaultwarden";
-        image = "vaultwarden/server:1.34.3-alpine";
+        image = "vaultwarden/server:1.35.4-alpine";
         autoStart = true;
         ports = [
           "${toString cfg.port}:80/tcp"