1. Introduction
+1. Introduction
1.1. What do you get?
+1.1. What do you get?
This repository delivers a reproducible foundation built on NixOS, Home-Manager, and Flakes. It assumes a clean NixOS installation as a starting point, preferably minimal or headless, onto which the configuration is applied. @@ -403,9 +415,480 @@ Core packages are installed as part of the base configuration. Additional softwa
1.2. Base packages
-2. what you don't get
++This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress. +
+2.1. What Is a Literate System in the Context of NixOS?
++A literate system combines documentation and implementation into a single, coherent source. +In this repository, that source is: +
+ +README.org ++
+Everything originates from this file: +
+ +-
+
- Architectural explanations +
- Design decisions +
- NixOS modules +
- Home-Manager modules +
- Generated documentation +
+There is no separation between “docs” and “code”. +The documentation explains the intent. +The source blocks define the system. +Org-mode turns that narrative into both executable configuration and readable documentation. +
+ ++The README is not describing the system. +The README is the system. +
+ ++— +
+2.2. Two Types of Code Blocks
++This literate system uses two different kinds of source blocks. +
+ ++1. Documentation Blocks +
+ ++These blocks exist purely for documentation purposes. +They generate visible code blocks in the exported documentation, but they do not create files. +
+ ++Example: +
+ +<tekst> ++
+These are used to show commands, examples, or explanatory snippets in the generated documentation. +
+ ++They are never tangled into the filesystem. +
+ ++— +
+ ++2. File-Generating Blocks +
+ ++These blocks generate real `.nix` files and insert the same code into the documentation. +
+ ++Example structure: +
+2.3. install_packages.nix
++<tekst> +
+ +<tekst> ++
+Explanation: +
+ +-
+
- The headline `=installpackages.nix=` becomes a documentation chapter. +
- The paragraph `<tekst>` explains what the module does. +
+The source block generates the file: +
+ ++configuration/apps/installpackages.nix +
+
+- The same source block is rendered as a code block in the documentation. +
+This means: +
+ +-
+
- The explanation and the implementation live side-by-side. +
- The documentation cannot drift away from the code. +
- The generated `.nix` file is always derived from the canonical explanation. +
+— +
+2.4. The Two Core Commands
++There are exactly two commands that matter. +
+ ++1. Generate all `.nix` files +
+ +emacs README.org --batch -f org-babel-tangle ++
+This command: +
+ +-
+
- Regenerates `./configuration` +
- Regenerates `./home` +
- Overwrites previously generated modules +
- Ensures the system matches the README +
+— +
+ ++2. Generate documentation +
+ +emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill ++
+This command exports the same README into HTML documentation. +
+ ++— +
+ ++In practice you usually combine them: +
+ +emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill ++
+First the system is generated. +Then the documentation is generated. +Both come from the same source. +
+ ++— +
+2.5. Editing Generated Files
++The directories: +
+ +-
+
- `./configuration` +
- `./home` +
+are fully generated by: +
+ +emacs README.org --batch -f org-babel-tangle ++
+Editing these files directly is allowed only temporarily, for experimentation or testing. +
+ ++Structural or permanent changes must always be implemented in the corresponding section inside `README.org`. +
+ ++If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle. +
+ ++Generated directories are output, not source. +
+ ++— +
+2.6. Recommended Workflow
++This workflow allows safe experimentation while preserving literate structure. +
+ +-
+
- Change any existing file in `./assets`, `./home` or `./configuration` +
- Commit your experimental change +
- Test the configuration +
- If satisfied, migrate the change into `README.org` +
- Regenerate system and documentation +
- Commit again +
- Test again +
+Commands: +
+ +git add . +git commit -m "experiment: local change" + +sudo nixos-rebuild test --flake .#your_hostname ++
+After confirming the change: +
+ +emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill + +git add . +git commit -m "literate: structural update" + +sudo nixos-rebuild test --flake .#your_hostname ++
+If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly. +
+ ++— +
+2.7. Folder Structure Explained
++The repository separates generated system code from non-generated supporting files. +
+ ++**./assets** +
+ ++Contains non-generated assisting files such as: +
+ +-
+
- Icons +
- Themes +
- Static configuration files +
+These files are safe to edit directly. +
+ ++— +
+ ++*./assets/configuration** +
+ ++Contains non-generated assisting configuration files that influence several aspects of builds. +
+ ++Users are expected to modify these when needed. +
+ ++— +
+ ++*./configuration** +
+ ++Fully (re)generated by `README.org`. +
+ ++Contains: +
+ +-
+
- All NixOS modules +
- Service definitions +
- System-level configuration +
+This directory is output. +
+ ++— +
+ ++*./hardware** +
+ ++Contains non-generated `hardware.nix` files detailing hardware-specific details. +
+ ++This directory will likely be deprecated in the future. +
+ ++— +
+ ++*./home** +
+ ++Fully (re)generated by `README.org`. +
+ ++Contains: +
+ +-
+
- All Home-Manager modules +
- User-level configuration +
- Shell and desktop configuration +
+This directory is generated output. +
+ ++— +
+ ++*./machines** +
+ ++Contains one folder per machine you want to configure. +
+ ++Each machine folder contains non-generated files detailing specifics for that machine: +
+ +-
+
- Host-specific overrides +
- Hardware references +
- Host definitions +
+These determine how shared modules apply to each system. +
+ ++— +
+2.8. Final Principle
++A literate NixOS system guarantees: +
+ +-
+
- Single source of truth +
- No divergence between documentation and configuration +
- Reproducible system builds +
- Clear architectural reasoning +
- Controlled experimentation +
+You are not maintaining configuration files. +
+ ++You are maintaining a structured narrative that builds an operating system. +
+2.9. Base packages
+The baseline package set is defined explicitly within the repository to ensure reproducibility:
@@ -477,9 +960,9 @@ The baseline package set is defined explicitly within the repository to ensure r1.3. Additional packages
-2.10. Additional packages
+Additional software can be installed by extending the dedicated configuration files that define system and Flatpak packages:
@@ -506,7 +989,7 @@ Available Flatpak identifiers can be discovered using:-or by browsing: https://flathub.org/. +or by browsing: https://flathub.org/.(manually)
@@ -518,9 +1001,9 @@ This separation maintains clarity between system-level packages and user-facing
1.4. What you do not get
-2.11. What you do not get
+This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution.
@@ -543,13 +1026,13 @@ In short, this repository provides a coherent and extensible base, not a finishe2. Setting up your system manually
-3. Setting up your system manually
+2.1. Pre-requisites to build this setup
-3.1. Pre-requisites to build this setup
+- a NIXOS system installed with a user with sudo rights. - an internet connection @@ -558,9 +1041,9 @@ In short, this repository provides a coherent and extensible base, not a finishe
2.2. Setup when Emacs not (yet) available
-3.2. Setup when Emacs not (yet) available
+- Copy the folder henrovnix to your machine
@@ -628,9 +1111,9 @@ Run the build command to set up the system for the first time
3. Testing and generating builds
-4. Testing and generating builds
+At this stage, you should have a functional and reproducible system that can be edited, rebuilt, and extended according to your needs. The foundational structure is now in place, and further customization can occur incrementally through the modular configuration files.
@@ -692,47 +1175,47 @@ Other important files:4. flake.lock for pinning input versions.
+5. flake.lock for pinning input versions.
5. assets/* for non-Nix-managed artifacts such as images and wallpapers.
-6. assets/* for non-Nix-managed artifacts such as images and wallpapers.
+Generated outputs should not be edited directly. A CI workflow can tangle and commit generated outputs when they differ.
5.1. Emacs + Org + Tangle
+6.1. Emacs + Org + Tangle
6. [Emacs](https://www.gnu.org/software/emacs/][Emacs) is used as the editor and execution environment for this literate configuration.
+7. [Emacs](https://www.gnu.org/software/emacs/][Emacs) is used as the editor and execution environment for this literate configuration.
7. [Org](https://orgmode.org/][Org) mode provides the document structure and the source block execution model used here.
+8. [Org](https://orgmode.org/][Org) mode provides the document structure and the source block execution model used here.
8. Tangling exports source blocks from this Org document into the corresponding configuration files.
-9. Tangling exports source blocks from this Org document into the corresponding configuration files.
+- References of the form
<<code-id>>are noweb placeholders that are expanded from other blocks during tangling.
8.1. Nix & NixOS
+9.1. Nix & NixOS
9. [Nix](https://nix.dev/][Nix) is used to define packages, environments, and configuration as pure expressions.
+10. [Nix](https://nix.dev/][Nix) is used to define packages, environments, and configuration as pure expressions.
10. [NixOS](https://nixos.org/][NixOS) evaluates Nix expressions into a complete system configuration that can be applied by rebuild operations.
-11. [NixOS](https://nixos.org/][NixOS) evaluates Nix expressions into a complete system configuration that can be applied by rebuild operations.
+10.1. Repository layout and folder conventions
-11.1. Repository layout and folder conventions
+<p> This repository contains system modules, user modules, and configuration fragments. The following directories are treated as separate layers: @@ -744,9 +1227,9 @@ Generated outputs should not be edited directly. A CI workflow can tangle and co
10.2. Shared domain folders
-11.2. Shared domain folders
+<ul> <li><code>core/</code> – base settings and common infrastructure</li> @@ -759,9 +1242,9 @@ Generated outputs should not be edited directly. A CI workflow can tangle and co
10.3. Full tree (including unchanged parts)
-11.3. Full tree (including unchanged parts)
+The tree below shows the full repository layout, with the standardized internal structure applied only inside
@@ -876,9 +1359,9 @@ The tree below shows the full repository layout, with the standardized internal10.4. Notes
-11.4. Notes
+<ul> <li>Only the internal layout of <code>configuration/</code>, <code>home/</code>, and <code>assets/conf/</code> is standardized; all other paths remain as currently organized.</li> @@ -910,9 +1393,9 @@ This prevents unwanted and surprise updates when rebuilding without changing the
11. TLDR App List
-12. TLDR App List
+12. Configuration Variables
-13. Configuration Variables
+
I have a bunch of constant strings that I would rather put in a file. Thats what user.nix is.
The values are imported at the beginning and are available to almost all the functions being called to configure the system.
@@ -1008,9 +1491,9 @@ The values are imported at the beginning and are available to almost all the fun
13. Flake Inputs
-14. Flake Inputs
+The inputs for my system's configuration are very simple
@@ -1050,16 +1533,16 @@ Sometimes pinned to a specific commit because unstable broke something and the f14. Flake Output
-15. Flake Output
+
Now that the inputs are ready, the outputs define what the system will actually look like. I also define the machines that this configuration specifies early on. Finally, I iterate over the machines list and pull files from /.machines/${name} subdirectory. This allows me to have configuration that has machine specific configuration limited to those files while also keeping a modular reusable base.
We also add a devshell that makes editing this repository easier in emacs.
outputs = inputs@{
+outputs = inputs@{
nixpkgs,
home-manager,
emacs-overlay,
@@ -1120,7 +1603,7 @@ Overlays are a special nix way to override existing packages within a repository
-({ ... }: {
+({ ... }: {
nixpkgs.overlays = [ emacs-overlay.overlays.default ];
})
@@ -1130,7 +1613,7 @@ Overlays are a special nix way to override existing packages within a repository
Then the machine specific configuration, in this case, just "machine1".
-./machines/${machine}/configuration.nix
+./machines/${machine}/configuration.nix
@@ -1140,7 +1623,7 @@ This can be initialized and managed on its own but I'd rather use the nixo
-home-manager.nixosModules.home-manager
+home-manager.nixosModules.home-manager
{
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
@@ -1183,9 +1666,9 @@ Finally I pull in the machine specific home configuration. Along with the overri
-
-14.1. Envrc + Direnv
-
+
+15.1. Envrc + Direnv
+
Editing this file will be much nicer if we have the dev environment configured.
That is done in the devshells section. But to auto load this dev shell, we need a .envrc file.
@@ -1205,14 +1688,14 @@ fi
-
-15. Machines
-
+
+16. Machines
+
The individual machines subdirectory is configured as follows :-
-+--machine
++--machine
| +--configuration.nix
| +--home.nix
| +--hardware-configuration.nix
@@ -1233,13 +1716,13 @@ This imported object (or function result) is just trivially merged into a common
We can take a look at that the common hardware options I have for all my machines.
-
-15.0.1. Other Utils
-
+
+16.0.1. Other Utils
+
-- Updates
-
+- Updates
+
To update the computer, I just need to update the flake.lock file to have references to the latest repository. This is done with :-
@@ -1252,9 +1735,9 @@ To update the computer, I just need to update the flake.lock file t
-
-16. Hardware
-
+
+17. Hardware
+
I'll let the code comments explain the file here.
@@ -1287,9 +1770,9 @@ I'll let the code comments explain the file here.
-
-17. Configuration
-
+
+18. Configuration
+
This section describes the main system configuration for the computers that I have. Nix will look for a default.nix file if you give it a path to a folder to import. And default.nix looks as follows :-
@@ -1331,17 +1814,17 @@ This section describes the main system configuration for the computers that I ha
-
-17.1. Apps section
-
+
+18.1. Apps section
+
This section describes a way of installing packages, either through nixpkgs orr flatpak. What apps to instal is decided in the files ./assets/conf/apps/packages.conf and flatpaks.conf
-
-17.2. install_packages.nix
-
+
+18.2. install_packages.nix
+
{ config, lib, pkgs, flakeRoot, inputs, ... }:
@@ -1400,9 +1883,9 @@ in
-
-17.3. install_flatpaks.nix
-
+
+18.3. install_flatpaks.nix
+
{ config, pkgs, lib, flakeRoot, ... }:
@@ -1512,9 +1995,9 @@ in
-
-17.4. Nix Settings
-
+
+18.4. Nix Settings
+
These are global nix settings that configure the settings for the actual tool.
@@ -1562,9 +2045,9 @@ These are global nix settings that configure the settings for the actual tool.
-
-17.5. Boot
-
+
+18.5. Boot
+
This file has most of the settings the control how the computer boots up.
@@ -1601,17 +2084,17 @@ This file has most of the settings the control how the computer boots up.
-
-17.6. Login
-
+
+18.6. Login
+
Here we control what the login screen would look like. In configuration/default.nix you can choose whether to use tuigreet (very minimalistic) or LightDM (nicer, themeable)
-
-17.7. Tuigreet
-
+
+18.7. Tuigreet
+
Doesn't match the rest of the aesthetic of the system (with hyprland), but I like its simplicity.
@@ -1635,9 +2118,9 @@ Doesn't match the rest of the aesthetic of the system (with hyprland), but I lik
-
-17.8. LightDM
-
+
+18.8. LightDM
+
{ config, pkgs, lib, ... }:
@@ -1783,9 +2266,9 @@ in
-
-17.9. Terminal (default system)
-
+
+18.9. Terminal (default system)
+
This is the initial system level configuration for the terminal that I use on this machine. Its just zsh.
@@ -1803,9 +2286,9 @@ This is the initial system level configuration for the terminal that I use on th
-
-17.10. Files
-
+
+18.10. Files
+
I use Thunar as the file explorer. Also setup a few plugins for Thunar in this config.
Along with that, a few other utilities like zip and enabling services to automount usb drives.
@@ -1845,9 +2328,9 @@ Along with that, a few other utilities like zip and enabling services to automou
-
-17.11. Locale
-
+
+18.11. Locale
+
I live in Netherlands and would like all my locale and timezone settings to match. Except my default locale.
@@ -1880,9 +2363,9 @@ in
-
-17.12. Networking
-
+
+18.12. Networking
+
Not much to see here. I want networking to be enabled. I want firewall as well.
@@ -1912,9 +2395,9 @@ Not much to see here. I want networking to be enabled. I want firewall as well.
-
-17.13. Hyprland
-
+
+18.13. Hyprland
+
This is a big one because the DE needs so much configuration. This section mostly installs Hyprland.
The configuration is done in the home manager section.
@@ -1984,9 +2467,9 @@ The configuration is done in the home manager section.
-
-17.14. Services
-
+
+18.14. Services
+
These are some of the services that I enable at the system level. Explanation in the comments.
@@ -2018,9 +2501,9 @@ These are some of the services that I enable at the system level. Explanation in
-
-17.15. Audio
-
+
+18.15. Audio
+
{ config, pkgs, lib, ... }:
@@ -2097,11 +2580,11 @@ These are some of the services that I enable at the system level. Explanation in
-
-17.16. Miscellaneous Packages and Programs
-
+
+18.16. Miscellaneous Packages and Programs
+
-environment.systemPackages = with pkgs; [
+environment.systemPackages = with pkgs; [
wget # fetch utility
curl # more fetch utility
binutils # executable utilities, like ld
@@ -2129,7 +2612,7 @@ programs.gdk-pixbuf.modulePackages = [ pkgs.librsvg ];
-programs = {
+programs = {
nix-ld.enable = true; # helps with linking troubles with dynamic libraries
appimage.enable = true; # allow appimage installations
dconf.enable = true; # to save user settings
@@ -2145,14 +2628,14 @@ programs.gdk-pixbuf.modulePackages = [ pkgs.librsvg ];
-
-17.17. Fonts
-
+
+18.17. Fonts
+
Nothing much to see here. I love Aporetic, and I use it everywhere.
-fonts.packages = with pkgs; [
+fonts.packages = with pkgs; [
aporetic
nerd-fonts.iosevka
];
@@ -2160,14 +2643,14 @@ Nothing much to see here. I love
-17.18. User Config
-
+
+18.18. User Config
+
This creates the user profile that I login with. Initially created during install.
-users.users.${user.username} = {
+users.users.${user.username} = {
isNormalUser = true;
description = "<defaultUser>";
extraGroups = [
@@ -2182,18 +2665,18 @@ This creates the user profile that I login with. Initially created during instal
-
-18. Home
-
+
+19. Home
+
I use home-manager to manage my user level dotfiles and configurations.
Most of the "theme" of the system is decided here.
I also use it to install programs that are okay with being installed at the user level instead of the system.
-
-18.1. default.nix
-
+
+19.1. default.nix
+
This module will import all necessities.
@@ -2228,9 +2711,9 @@ This module will import all necessities.
-
-18.2. Wallpaper
-
+
+19.2. Wallpaper
+
wallpaper.nix installs wpaperd and deploys your wallpaper files from the repo (./assets/conf/desktop/wallpaper/pictures/) into ~/conf/desktop/wallpaper/pictures. It also deploys the default wallpaper configuration from assets/conf/desktop/wallpaper/wallpaper.conf into ~/conf/desktop/wallpaper/wallpaper.conf, which is the file you can edit as a user override.
Finally, it creates a systemd user service (wpaperd.service) that automatically starts wpaperd at login and keeps it running, using your override config so wallpapers rotate according to your settings.
@@ -2283,11 +2766,11 @@ in
-
-18.3. Waybar
-
+
+19.3. Waybar
+
-
+
@@ -2324,9 +2807,9 @@ in
-
-18.4. Lock Screen
-
+
-
-18.5. Idle Screen
-
+
+19.5. Idle Screen
+
<henro: needs instruction>
@@ -2366,9 +2849,9 @@ in
-
-18.6. Hyprshell
-
+
+19.6. Hyprshell
+
For nice task-starting and -switching
@@ -2407,9 +2890,9 @@ in
-
-18.7. Hyprland
-
+
+19.7. Hyprland
+
This configures the desktop environment along with the peripherals. The comments should explain whats happening.
@@ -2458,9 +2941,9 @@ in
-
-18.8. Walker
-
+
+19.8. Walker
+
This is how I launch applications. It is bound to Win+Space in the ./asstes/conf/desktop/hypr/bindings.conf.
@@ -2560,9 +3043,9 @@ in
-
-18.9. Theme
-
+
+19.9. Theme
+
I use the Catppuccin almost everywhere. The nix module integrates almost automatically everywhere (except gtk).
You'll notice the color values in multiple places outside this as well.
@@ -2594,9 +3077,9 @@ You'll notice the color values in multiple places outside this as well.
-
-18.10. Default-apps
-
+
+19.10. Default-apps
+
This is where you can set defaults
@@ -2614,9 +3097,9 @@ This is where you can set defaults
-
-18.11. Hyperexpo
-
+
+19.11. Hyperexpo
+
hyprexpo gets installed and configured
@@ -2655,9 +3138,9 @@ hyprexpo gets installed and configured
-
-18.12. Alacritty
-
+
+19.12. Alacritty
+
Alacritty gets installed and configured
@@ -2678,9 +3161,9 @@ in
-
-18.13. Dev Tools
-
+
+19.13. Dev Tools
+
All the miscellaneous dev tools on this computer.
@@ -2738,9 +3221,9 @@ All the miscellaneous dev tools on this computer.
-
-18.14. Kitty
-
+
+19.14. Kitty
+
Kitty gets installed and configured
@@ -2763,9 +3246,9 @@ in
-
-18.15. Shells
-
+
+19.15. Shells
+
The aliases mentioned in ./assets/conf/dev/terminal/shells.conf will be added to enabled shells
@@ -2987,9 +3470,9 @@ EOF
-
-18.16. Zsh
-
+
+19.16. Zsh
+
Zsh gets installed and configured
@@ -3031,9 +3514,9 @@ in
-
-18.17. Starship
-
+
+19.17. Starship
+
The configuration mentioned in ./assets/conf/dev/terminal/starship.toml will be added to enabled shells
@@ -3064,18 +3547,18 @@ in
-
-18.18. Other Settings
-
+
+19.18. Other Settings
+
Some repeated info from the configuration.
-
-18.18.1. Home User
-
+
+19.18.1. Home User
+
-home.username = "${user.username}";
+home.username = "${user.username}";
home.homeDirectory = pkgs.lib.mkDefault "/home/${user.username}";
home.stateVersion = user.stateVersion;
@@ -3084,9 +3567,9 @@ home.stateVersion = user.stateVersion;
-
-19. Emacs
-
+
+20. Emacs
+
I practically live inside emacs. The configuration for it is a mix between init.el and the nix configuration.
Nix allows me to install emacs packages as part of the configuration which is most of the following file.
@@ -3164,9 +3647,9 @@ Comments describe the emacs package and what it does.
-
-19.1. Early Initialization
-
+
+20.1. Early Initialization
+
There are some emacs settings that can be configured before the gui shows up.
And some of them help increase performance and let the gui show up that much faster.
@@ -3270,9 +3753,9 @@ These are listed here.
-
-19.2. Initialization
-
+
+20.2. Initialization
+
Now starts the main emacs configuration.
@@ -3683,23 +4166,23 @@ ting a file within such a
-
-20. Machines
-
+
+21. Machines
+
Only a few more things left. Specifically the machine level extra settings.
-
-20.1. Traveldroid
-
+
+21.1. Traveldroid
+
The configuration for the laptop does not change much. Most changes are because the hardware is different.
-
-20.1.1. System Level
-
+
+21.1.1. System Level
+
Nothing specific for the laptop.
@@ -3716,9 +4199,9 @@ Nothing specific for the laptop.
-
-20.1.2. Hardware
-
+
+21.1.2. Hardware
+
This is the most different. Mostly taken from hardware-configuration.nix setup at first install.
@@ -3766,9 +4249,9 @@ hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistr
-
-20.1.3. Home
-
+
+21.1.3. Home
+
This is mostly about configuring the monitor. And laptop specific utilities.
@@ -3794,18 +4277,18 @@ This is mostly about configuring the monitor. And laptop specific utilities.
-
-21. README Utils
-
+
+22. README Utils
+
-
-21.0.1. Headers
-
+
+22.0.1. Headers
+
This script adds a DO NOT MODIFY header to all the generated nix files.
-(progn
+(progn
(defun add-tangle-headers ()
(message "running in %s" (buffer-file-name))
(when (string= (file-name-extension (buffer-file-name)) "nix")
@@ -3822,7 +4305,7 @@ This script adds a DO NOT MODIFY header to all the generated nix fi
diff --git a/henrovnix/README.org b/henrovnix/README.org
index 32dd1c094..a0517d2f9 100755
--- a/henrovnix/README.org
+++ b/henrovnix/README.org
@@ -51,6 +51,278 @@ The system provides a predefined baseline configuration that installs and enable
Core packages are installed as part of the base configuration. Additional software can be incorporated in a controlled and modular manner by extending configuration files.
+* what you don't get
+
+This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress.
+
+** What Is a Literate System in the Context of NixOS?
+
+A literate system combines documentation and implementation into a single, coherent source.
+In this repository, that source is:
+
+#+begin_src bash :tangle no block
+README.org
+#+end_src
+
+Everything originates from this file:
+
+- Architectural explanations
+- Design decisions
+- NixOS modules
+- Home-Manager modules
+- Generated documentation
+
+There is no separation between “docs” and “code”.
+The documentation explains the intent.
+The source blocks define the system.
+Org-mode turns that narrative into both executable configuration and readable documentation.
+
+The README is not describing the system.
+The README *is* the system.
+
+---
+
+** Two Types of Code Blocks
+
+This literate system uses two different kinds of source blocks.
+
+**1. Documentation Blocks**
+
+These blocks exist purely for documentation purposes.
+They generate visible code blocks in the exported documentation, but they do not create files.
+
+Example:
+
+#+begin_src bash :tangle no
+
+#+end_src
+
+These are used to show commands, examples, or explanatory snippets in the generated documentation.
+
+They are never tangled into the filesystem.
+
+---
+
+**2. File-Generating Blocks**
+
+These blocks generate real `.nix` files and insert the same code into the documentation.
+
+Example structure:
+
+** =install_packages.nix=
+
+
+
+#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
+
+#+end_src
+
+Explanation:
+
+- The headline `=install_packages.nix=` becomes a documentation chapter.
+- The paragraph `` explains what the module does.
+- The source block generates the file:
+
+ configuration/apps/install_packages.nix
+
+- The same source block is rendered as a code block in the documentation.
+
+This means:
+
+- The explanation and the implementation live side-by-side.
+- The documentation cannot drift away from the code.
+- The generated `.nix` file is always derived from the canonical explanation.
+
+---
+
+** The Two Core Commands
+
+There are exactly two commands that matter.
+
+**1. Generate all `.nix` files**
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle
+#+end_src
+
+This command:
+
+- Regenerates `./configuration`
+- Regenerates `./home`
+- Overwrites previously generated modules
+- Ensures the system matches the README
+
+---
+
+**2. Generate documentation**
+
+#+begin_src bash :tangle no block
+emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+#+end_src
+
+This command exports the same README into HTML documentation.
+
+---
+
+In practice you usually combine them:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+#+end_src
+
+First the system is generated.
+Then the documentation is generated.
+Both come from the same source.
+
+---
+
+** Editing Generated Files
+
+The directories:
+
+- `./configuration`
+- `./home`
+
+are fully generated by:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle
+#+end_src
+
+Editing these files directly is allowed only temporarily, for experimentation or testing.
+
+Structural or permanent changes must always be implemented in the corresponding section inside `README.org`.
+
+If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle.
+
+Generated directories are output, not source.
+
+---
+
+** Recommended Workflow
+
+This workflow allows safe experimentation while preserving literate structure.
+
+1. Change any existing file in `./assets`, `./home` or `./configuration`
+2. Commit your experimental change
+3. Test the configuration
+4. If satisfied, migrate the change into `README.org`
+5. Regenerate system and documentation
+6. Commit again
+7. Test again
+
+Commands:
+
+#+begin_src bash :tangle no block
+git add .
+git commit -m "experiment: local change"
+
+sudo nixos-rebuild test --flake .#your_hostname
+#+end_src
+
+After confirming the change:
+
+#+begin_src bash :tangle no block
+emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
+
+git add .
+git commit -m "literate: structural update"
+
+sudo nixos-rebuild test --flake .#your_hostname
+#+end_src
+
+If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly.
+
+---
+
+** Folder Structure Explained
+
+The repository separates generated system code from non-generated supporting files.
+
+****./assets**
+
+Contains non-generated assisting files such as:
+
+- Icons
+- Themes
+- Static configuration files
+
+These files are safe to edit directly.
+
+---
+
+***./assets/configuration**
+
+Contains non-generated assisting configuration files that influence several aspects of builds.
+
+Users are expected to modify these when needed.
+
+---
+
+***./configuration**
+
+Fully (re)generated by `README.org`.
+
+Contains:
+
+- All NixOS modules
+- Service definitions
+- System-level configuration
+
+This directory is output.
+
+---
+
+***./hardware**
+
+Contains non-generated `hardware.nix` files detailing hardware-specific details.
+
+This directory will likely be deprecated in the future.
+
+---
+
+***./home**
+
+Fully (re)generated by `README.org`.
+
+Contains:
+
+- All Home-Manager modules
+- User-level configuration
+- Shell and desktop configuration
+
+This directory is generated output.
+
+---
+
+***./machines**
+
+Contains one folder per machine you want to configure.
+
+Each machine folder contains non-generated files detailing specifics for that machine:
+
+- Host-specific overrides
+- Hardware references
+- Host definitions
+
+These determine how shared modules apply to each system.
+
+---
+
+** Final Principle
+
+A literate NixOS system guarantees:
+
+- Single source of truth
+- No divergence between documentation and configuration
+- Reproducible system builds
+- Clear architectural reasoning
+- Controlled experimentation
+
+You are not maintaining configuration files.
+
+You are maintaining a structured narrative that builds an operating system.
+
** Base packages
The baseline package set is defined explicitly within the repository to ensure reproducibility:
@@ -137,7 +409,7 @@ Available Flatpak identifiers can be discovered using:
flatpak search
#+end_src
-or by browsing: https://flathub.org/.
+or by browsing: https://flathub.org/.(manually)
The behavior and integration of Flatpak installation within the system are defined in =install_flatpaks.nix=, which reads the corresponding configuration files and ensures declarative installation.