chore: initial commit

README.md

@@ -0,0 +1,73 @@
+# NixOS + home-manager flake
+
+A flake-based NixOS and home-manager configuration: a set of **reusable modules** plus a
+**ready-to-run example host** that assembles them. Use it either way:
+
+- as a **starting template** — clone, swap in your hardware, rebuild; or
+- as **modules** — import them into your own (private) flake.
+
+## Quick start (template)
+
+```sh
+nix flake init -t github:<owner>/<repo>        # or: git clone …
+# generate hardware config for THIS machine (the one file you must replace):
+sudo nixos-generate-config --show-hardware-config > hosts/example/hardware-configuration.nix
+# set your hostName + username in hosts/example/default.nix, then:
+sudo nixos-rebuild switch --flake .#example
+```
+
+`nixosConfigurations.example` is a real, buildable machine assembled from the modules in
+`modules/`. It doubles as living documentation: it shows exactly how the modules wire
+together, so there's nothing to reverse-engineer. The only genuinely machine-specific file
+is `hardware-configuration.nix` (NixOS generates it); everything else works from defaults
+you can tweak.
+
+## Import the modules into your own flake
+
+Add this repo as a flake input and import its modules from your own configuration:
+
+```nix
+{
+  inputs.config.url = "github:<owner>/<repo>";
+  # …
+  outputs = { nixpkgs, config, home-manager, ... }: {
+    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+      modules = [
+        config.nixosModules.default
+        ./hosts/myhost                 # your hardware + hostname
+        home-manager.nixosModules.home-manager
+        { home-manager.users.me.imports = [ config.homeModules.default ]; }
+      ];
+    };
+  };
+}
+```
+
+Your machine list, hostnames, and any private specifics stay in *your* flake — you pull
+only the generic modules from here.
+
+## Architecture: three layers
+
+Kept apart on purpose. When adding config, decide which layer it belongs to:
+
+1. **Modules — generic, public (this repo).** Reusable building blocks under `modules/`,
+   exposed as `nixosModules.*` / `homeModules.*`. Anything machine- or user-specific is a
+   module **option with a sane default** — never hard-code personal values into a module.
+2. **Inventory — topology, private (your flake).** The actual machines:
+   `nixosConfigurations.<host>`, per-host `hosts/<host>/` (hardware, hostname), and
+   topology-revealing config (SSH hosts, Syncthing peers, internal IPs). This is what you
+   deploy from; it imports the modules above. Publish the modules, keep the inventory in a
+   private repo. The `example` host here is a placeholder-filled stand-in for it.
+3. **Secrets — neither repo.** Private keys, tokens, passwords never enter *any* repo.
+   Provide them as runtime files (`0600`, out-of-band) or via a secrets manager that
+   decrypts to a runtime path; nix references only the path.
+
+## Layout
+
+```
+flake.nix            # inputs + outputs (nixosModules, homeModules, example host, devShells)
+modules/             # the reusable library
+hosts/example/       # the template host (placeholder hardware-configuration.nix)
+```
+
+Shared `*.nix` / `*.lock` live at the top level; per-host files under `hosts/<host>/`.