feat(flake): expose examples as packages + eval checks

Each entry in the `examples` attrset is materialised three ways:
`nixosConfigurations.example-<name>` (the full system), `packages.<system>.<name>`
(the qemu-runnable VM, so `nix run .#<name>`), and `checks.<system>.example-<name>`
(eval-only, so option-name drift fails CI without paying for a full VM test).

Author: kmein

README.md

@@ -91,6 +91,18 @@ live in the per-pairing README:
   service-account bootstrap flow and the operator-supplied client
   override.
 
+### Runnable examples
+
+Each entry under [`examples/`](examples/) is a complete NixOS
+configuration with its own walkthrough. `nix run .#<example>` builds
+and boots the example as a QEMU VM (host ports forwarded so you can
+hit the services from a browser).
+
+- [`keycloak-forgejo`](examples/keycloak-forgejo/README.md) — both
+  pairings together, a custom Keycloak login theme, SSO from Forgejo
+  into Keycloak, a private internal repo, and per-user avatars served
+  over a side nginx. `nix run .#keycloak-forgejo`.
+
 ### Secrets
 
 Secrets should never enter the world-readable Nix store. The admin token and
@@ -103,7 +115,7 @@ path — prefer it over the literal for any real secret.
 ## Repository layout
 
 ```
-flake.nix              # outputs: nixosModules, checks, formatter
+flake.nix              # outputs: nixosModules, packages (examples), checks, formatter
 treefmt.nix            # treefmt + nixfmt config
 modules/
   default.nix          # aggregates per-pairing modules into nixosModules.default
@@ -120,6 +132,8 @@ services/              # one directory per service<->provider pairing
     lib.nix            #   ~95 typed resourceTypes + the value-tree renderer
     checks.nix         #   1 VM + 4 nspawn-container tests, one per resource family
     README.md          #   usage docs
+examples/              # runnable demos; one configuration.nix + README per example
+  keycloak-forgejo/    #   both pairings together with theme, SSO, avatar
 ```
 
 ## Development

flake.nix

@@ -28,6 +28,21 @@
           }
         );
       treefmtEval = forAllSystems ({ pkgs, ... }: treefmt-nix.lib.evalModule pkgs ./treefmt.nix);
+      # runnable examples (see ./examples/<name>/README.md). each `name`
+      # surfaces as `nix run .#<name>` (the qemu vm) and as an eval-only
+      # check, so option-name drift fails CI without paying for a full vm test.
+      examples = {
+        keycloak-forgejo = ./examples/keycloak-forgejo/configuration.nix;
+      };
+      exampleSystem =
+        system: cfg:
+        nixpkgs.lib.nixosSystem {
+          inherit system;
+          modules = [
+            self.nixosModules.default
+            cfg
+          ];
+        };
     in
     {
       # NixOS module entrypoint: enables a Nixpkgs service and reconciles its
@@ -36,11 +51,24 @@
       nixosModules.forgejo = ./services/forgejo/module.nix;
       nixosModules.keycloak = ./services/keycloak/module.nix;
 
+      nixosConfigurations = nixpkgs.lib.mapAttrs' (
+        name: cfg: nixpkgs.lib.nameValuePair "example-${name}" (exampleSystem "x86_64-linux" cfg)
+      ) examples;
+
+      packages = forAllSystems (
+        { system, ... }:
+        nixpkgs.lib.mapAttrs (name: cfg: (exampleSystem system cfg).config.system.build.vm) examples
+      );
+
       checks = forAllSystems (
         { pkgs, system }:
         # Per-service checks (one attrset per pairing under ./services/<svc>).
         (import ./services/forgejo/checks.nix { inherit pkgs self; })
         // (import ./services/keycloak/checks.nix { inherit pkgs self; })
+        // (nixpkgs.lib.mapAttrs' (
+          name: cfg:
+          nixpkgs.lib.nameValuePair "example-${name}" (exampleSystem system cfg).config.system.build.toplevel
+        ) examples)
         // {
           formatting = treefmtEval.${system}.config.build.check self;
         }