From 39837999b3b30427bcace594f44b4668d5064e46 Mon Sep 17 00:00:00 2001
From: Collin Williams <96917990+bluedragon1221@users.noreply.github.com>
Date: Wed, 14 Jan 2026 13:34:25 -0600
Subject: README update

---
 README.md                  | 80 ++++++++++++++++++++++--------------------
 docs/homogenous_modules.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+), 37 deletions(-)
 create mode 100644 docs/homogenous_modules.md

diff --git a/README.md b/README.md
index 52714f9..ce0fd49 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,43 @@
-```sh
-nixos-rebuild build-vm --flake .#collinux
-```
-
-
-A host config has many parts
-- user environment config (home-manager)
-- system config
-- hardware config (facter)
-  - disks config (disko or manual)
-
-## Dream hosts/config.nix
-```nix
-collinux = {
-  user = {
-    fullName = "";
-    name = "";
-    email = "";
-    password = "";
-  };
-
-  theme = "";
-
-  desktop = {
-    programs = {};
-  };
-
-  terminal = {
-    programs = {};
-  };
-
-  boot = {};
-
-  extraNixosModules = [];
-  extraHomeModules = [];
-};
-```
+# `bluedragon1221/nixos`
+Cool things:
+1. Using [hjem](https://github.com/feel-co/hjem) over [home-manager](https://github.com/nix-community/home-manager)
+2. Features an [awesome tmux configuration](https://github.com/bluedragon1221/tmux-tsunami)
+3. Deployments over ssh using [deploy-rs](https://github.com/serokell/deploy-rs)
+4. Automatic secret decryption with ssh keys using [agenix](https://github.com/ryantm/agenix)
+5. Fully declarative self-hosted services, including:
+  - [Headscale](./modules/services/nixos/selfhost/headscale.nix)
+  - [AdGuard Home](./modules/services/nixos/selfhost/adguard.nix)
+  - [Forgejo](./modules/services/nixos/selfhost/forgejo.nix)
+  - [Navidrome](./modules/services/nixos/selfhost/navidrome.nix)
+  - ... all with configurable [caddy-tailscale](https://github.com/tailscale/caddy-tailscale) integration
+6. [Homogenous modules](./docs/homogenous_modules.md)
+
+# Hosts
+## [Mercury](./hosts/mercury)
+- Device: Lenovo Thinkpad X1 Carbon Gen 6
+- OS: NixOS
+- DE/Compositor: Sway (or Niri, I can't decide)
+Goes everywhere with me. Used for programming, school, and browsing the web
+
+## [Jupiter](./hosts/jupiter)
+- Device: HP ENVY Desktop
+- OS: NixOS (dual booted with Windows 11 LTSC IoT Enterprise)
+- DE/Compositor: GNOME
+Used for heavier tasks, like gaming and music production
+
+## [Ganymede](./hosts/ganymede)
+- Device: Lenovo Yoga 730 (broken screen)
+- OS: NixOS
+- DE/Compositor: none
+Hosts my family's webserver, personal Headscale instance, and a few other self-hosted services over my tailnet
+
+## Terra
+- Device: Samsung S20 Ultra
+- OS: Android
+My phone. Used for communication, reading Hacker News, and whatever else.
+
+## Io
+- Device: Raspberry PI Zero 2 W
+- OS: Alpine Linux
+- DE/Compositor: none
+Low-power device used as a Forgejo actions builder
diff --git a/docs/homogenous_modules.md b/docs/homogenous_modules.md
new file mode 100644
index 0000000..aa2cbda
--- /dev/null
+++ b/docs/homogenous_modules.md
@@ -0,0 +1,87 @@
+# Homogenous Nix Modules: Why and How
+In the creation of my nixos configuration, I came to a (possibly unique) issue:
+many services that I wanted to configure required a "system" piece, and a "home" piece.
+
+For example, in configuring a shell, it makes sense to configure that shell as the default shell for the user in the same place.
+However, in standard nixos configuration, you configure the actual shell with home-manager, and the default-ness with nixos.
+
+My solution to this was to create a new way of managing my nixos modules, which I coined "Homogenous Modules."
+
+The idea is as follows: each module contains three parts:
+1. a shared `options.nix` file,
+2. a nixos part, and
+3. a home-manager part (or [Hjem](github.com/feel-co/hjem), in my case).
+
+The `options.nix` file contains _only_ the `options` section of a module.
+The nixos part contains the `config` section of the module, as if it was a nixos module.
+The home-manager part contains the `config` section of the module, as if it was a home-manager module.
+
+Now, `{imports = [./options.nix ./nixos.nix];}` is a valid nixos module, and
+`{imports = [./options.nix ./home.nix];}` is a valid home-manager module.
+
+## Example
+Let's implement that shell example from the start, from scratch.
+We'll start with with the `options.nix`:
+```nix
+{lib, ...}: let
+  inherit (lib) mkOption mkEnableOption;
+in {
+  options = {
+    collinux.shells = {
+      zsh = {
+        enable = mkEnableOption "the zsh shell and customizations to it";
+        default = mkEnableOption "make zsh the default shell";
+      };
+      bash = {
+        enable = mkEnableOption "the bash shell and customizations to it";
+        default = mkEnableOption "make bash the default shell";
+      };
+    };
+  };
+  config.assertions = [
+    {
+      assertion = with collinux.shells; !(zsh.default && bash.default);
+      message = "You can only have one default shell!";
+    }
+  ];
+}
+```
+
+Here, we define a simple configuration.
+
+In the nixos part, we'll set the default shell:
+```nix
+{pkgs, config, lib, ...}: let
+  cfg = config.collinux.shells;
+in {
+  users.users."collin".shell =
+    if config.zsh.enable
+    then pkgs.zsh
+    else if config.bash.enable
+    then pkgs.bash
+    else null;
+}
+```
+
+And in the home-manager part, we'll set some customization options:
+```nix
+{pkgs, config, lib, ...}: let
+  cfg = config.collinux.shells;
+
+  shellAliases = {
+    ll = "ls -l";
+    update = "home-manager switch";
+  };
+in {
+  programs.zsh = {
+    enable = cfg.zsh.enable;
+    syntaxHighlighting.enable = true;
+    inherit shellAliases;
+  };
+
+  programs.bash = {
+    enable = cfg.bash.enable;
+    inherit shellAliases;
+  };
+}
+```
-- 
cgit v1.3.1