notes
Edit on GitHubOne page per module, holding what used to live in its header block: why the module is the way it is, the measurements behind each number, and what was tried and rejected.
Why this folder exists
Rule 2 used to allow a header block "as long as it needs to be". Measured on 16/08/2026, that
had grown into 6062 comment lines out of 16634 across the tree, 36%, with one module
(modules/home/shell/claude-code.nix) carrying a 123-line header. A header that long stops being
documentation and becomes a wall you scroll past to reach the code. Worse, none of that
reasoning was reachable from docs/: to find out why Caddy has a jail, you had to already know
to open modules/nixos/services/caddy.nix.
So the reasoning moved here instead of being deleted. The module keeps a 2-line header that says what it is and points at its page. After the sweep the tree is at 1601 comment lines out of 13299, 12%, and no comment anywhere runs longer than 2 lines.
Nothing was deleted. Every measurement, every rejected alternative and every correction that was in a header is on one of these pages. If you find something here that the code no longer does, that is rule 16 and the page is the bug.
How it relates to the rest of docs/
| Folder | Question it answers |
|---|---|
../history/ | "What happened on that day, and what did I learn?" Chronological, append-only |
notes/ (here) | "Why is THIS module like this, right now?" One page per module, kept current |
../guides/ | "What do I type to redo this by hand?" Steps outside Nix's reach |
The history is a diary and keeps its entries even when they go stale, because a diary that gets edited stops being evidence. These notes are the opposite: they describe the CURRENT state, and rule 16 applies in full, so a note that stops being true is a bug.
Conventions
-
Grouped by SUBJECT, not by repo path. A mirror of the tree was measured and rejected: 30 of the 93 pages name files on both sides of the
modules/nixos/andmodules/home/boundary (arch-legacy, claude-code, monitors, theme, restic, vpn, fonts and others), and 58 name two or more modules. They cross because the ARTIFACT crosses, so a mirror would have to split a third of the pages or file them under a half-truth. The folder answers "where would I go looking", which is the question a reader actually has.The count is a module path written anywhere in the page (re-measured 13/10/2026; it was 16 of 51 on 16/08, the same third). Counting only the modules whose 2-line header points AT the page gives 13 of 74 instead, but it misses theme, vpn and fonts, which plainly span both sides.
-
The file name mirrors the module, so
modules/nixos/services/caddy.nixbecomesnetwork/caddy.md. When a page covers several modules it takes the name of the SUBJECT (desktop-plumbing.md,apps-and-mime.md). -
A page is created only when there is something to say. A module whose header compresses to 2 lines with nothing lost does not get a page.
-
The module points here, never the other way around. The pointer lives in the 2-line header, and
repo/link-checker.mdis what keeps those pointers honest: a broken one failsnix flake check.
The pages
boot-and-storage
| Page | What you would come here asking |
|---|---|
| boot | Limine, the Secure Boot trust chain, and what it does NOT protect |
| disko | the subvolume layout, and why the swapfile belongs to the host |
| btrfs | the scrub, the alarm, the reclaim, and why fstrim is off |
| btrbk | the local snapshots, which are NOT a backup |
| restic | why the backup is gone, the frozen repos, and ~/Drive |
| arch-legacy | the old Arch archive, permanently mounted, and --no-lock |
| disk-hygiene | the space alarm that names the biggest consumers |
| downloads-tidy | ~/Downloads as an inbox, sorted by type every 30 min |
| disk-insight | the size trend, the usage sampler, and why not atime |
| impermanence | the home persistence list written before the switch, and persist-diff |
| games-disk | one game install shared with Windows, and the force option that stays off |
| shutdown | why the machine takes that long to go down |
hardware
| Page | What you would come here asking |
|---|---|
| gpu | the Arc B580 on xe, and why the driver stack must NOT go unstable |
| gpu-rgb | the Steel Legend's LED, the bus everyone assumed wrong, and when to delete the patches |
| fans | the Arc's fan that was supposed to be uncontrollable, the PCODE path, and the firmware red herring |
| monitors | the connector SSOT, and why it lives on the system side |
| fonts | the UI font SSOT, and the fallback coverage |
| mouse | the MX Master, the boot race, and the gestures |
| razer | the DeathAdder's DPI OSD, and why openrazer does not build on 7.x |
| android | pairing the phone over wireless ADB, and why SFTP could not clean it |
| oom | earlyoom, and the three traps in its regex |
| power-and-memory-baseline | the 18/10/2026 audit: where the RAM goes, what was kept and why, what is still unmeasured |
| power | Balanced, Gaming and Eco: power-profiles-daemon, and GameMode's hold |
| webcam | the UVC -71, everything it is NOT, and the one test left |
network
| Page | What you would come here asking |
|---|---|
| network | the firewall by SOURCE, the DDNS that moved to the router, fail2ban, the FAI gateway |
| exposure | the house seen from outside: open ports and the sshd, weekly |
| router-log | the router's syslog kept here 30 days: who may send it, and why the order matters |
| vpn | FAI (nxBender) and UFSCar (openconnect), always split-tunnel |
| ssh | the exposed SSH, the hosts, and reaching the FAI workstation |
| sunshine | remote access, the black screen, and why dpms is forbidden |
| caddy | the reverse proxy, the auto-gate, client_ip vs remote_ip |
| tunnel | the Cloudflare Tunnel behind Access, the MCP portal, what is NOT in git |
| fai-workstation | the host SSOT, Wake-on-LAN, and the rclone mount |
| vps-mount | ~/VPS, the KingHost VPS' root over rclone SFTP |
desktop
| Page | What you would come here asking |
|---|---|
| desktop | Hyprland, the autologin trade, the portals, the keyring |
| hypr | the Lua config, the helper scripts, the remote-access safety net |
| keybinds | every bind, and why the cheatsheet is generated from them |
| quickshell | the shell in QML, and the 758 MiB XEmbed bridge |
| bar | the bar and its popovers, the VPN probe, the holiday table |
| hyprglass | the Liquid Glass plugin: the pinned build, the presets, turning it on and off |
| nixos-center | the logo's panel: notifications, do-not-disturb, the session, the toasts |
| dash | the glance band on the standing monitor: vitals, month, CI pages |
| glance-feed | the SQLite network cache: fetch only what changed, paint from disk at boot |
| lockscreen | the QML lock (Quickshell), hyprlock as its fallback, hypridle, and the hardware lessons |
| away | a black screen and dark LEDs while an agent works, and why not DDC or DPMS |
| weather | one source for the bar and the lock, and the icon-by-regex trap |
| theme | dark mode, Kvantum, the Win11 icons, the palette SSOT |
| autostart | what opens at login, and Spotify's 4145 restarts |
| hyprsunset | the blue light curve, and why 13 profiles |
| backlight | DDC/CI on both panels, the 10000 K that faked a broken filter |
| desktop-plumbing | the polkit agent, XDG associations, the wallpaper, the cheatsheet, clipboard-push |
| vicinae | the launcher, the clipboard history, the command palette |
| spellcheck | English and pt-BR in every app: one list, one layer per app family |
apps
| Page | What you would come here asking |
|---|---|
| dolphin | the ViewMode enum trap, and the Windows Explorer parity |
| recoll | searching by content, and why the index must never see a secret |
| dropbox | the tray icon's cost, and 10 days of syncing nothing |
| vscode | a versioned mirror and not an immutable source |
| claude-code | two accounts, one archive, and the rules every project inherits |
| codex | who owns config.toml, and why the settings option is left empty |
| antigravity-cli | why agy and not gemini-cli, and the symlink this one clobbers |
| basic-memory | two memory servers split at the FAI boundary, uv2nix, and why HTTP and not stdio |
| azure-mcp | the Azure MCP server, FAI only |
| flameshot | the v14 keyboard flow, and the duplicated bar |
| screenrec | recording a monitor or a region by keyboard, MP4 with GIF on demand, and why not the portal |
| curseforge | the repackaged AppImage, and why the schemes are declared |
| curseforge-fix-perms | the +x the app loses, and why ELF magic and not names |
| fai-meet | the FAI's meeting recorder: the pointer AppImage and its login scheme |
| hydralauncher | the game launcher on upstream's latest, its download sources declared, and its login scheme |
| bottles | the library declared without owning the prefix, and the name that is not the directory |
| mega | megatools, the quota, and why the loop waits |
| spotifast | the native Spotify client, why the release binary, and the theme that must be a real file |
| apps-and-mime | media, office, MangoHud, OpenAL, and the CANONICAL mimetype |
| zen | the launch guard, and the NSS check that had to be written backwards |
| crypto | Stack Wallet and Bisq 2, the threat model with no LUKS, and the first purchase |
| fastfetch | boxes drawn from the key, and a donut.c-style logo rendered at build time |
services
| Page | What you would come here asking |
|---|---|
| service-toggles | the optional-service list, and why it is centralized |
| jellyfin | the media library, the UMask override, DLNA on the TV |
| immich | the photo library, why it lives in /srv, and why it is not a backup |
| ollama | local models on the Arc through Vulkan |
| duo | the compose stack declared in Nix, and the three Docker traps |
| grad-radar | the stack at boot, and the monitor chain's order |
| credit-radar | why the most sensitive service never leaves the house |
| docker-prune | the 11 GB with no ceiling, and the two options that destroy data |
| phone-sync | why Syncthing for the phone's photos, and the Revert button that deletes |
| libvirt | the KVM sandbox, and the three wiki steps that are wrong on 26.05 |
| cockpit | start/stop from the browser, and stop versus toggle |
| beszel | the resource history Cockpit cannot keep, and the pairing step |
repo
| Page | What you would come here asking |
|---|---|
| flake | the inputs, the overlays, and the quality gate |
| core | Nix settings, the GC, locale, and why each ceiling is that number |
| packages | what is installed and why, per package |
| shell | zsh, the aliases, and the NH_FLAKE trap |
| secrets | sops-nix, Bitwarden, and the two recipients |
| version-bumps | the three-layer version strategy, and the four bump scripts |
| link-checker | what keeps these pointers from rotting |
| dead-config | what is declared and never used, and the seven checks |
| rules-index | every rule N points at a live rule, and which rules a check enforces |
| ownership | the long form of rules 11, 14 and 15: one source, one writer, one starter |
| hardening | the systemd sandbox baseline for this repo's own root services, with scores |
| router-ssot | the values the router repeats, and who guards them |
| prose-style | rule 17's bans, and what counts as a literal instead of prose |
| vm-boot | whether this config still boots on a machine that is not this one |
| site | how docs/ becomes a site, and why the tree did not move to match it |
| site-sources | which repo files each page is about, and what the site may publish of them |
| github-settings | what protects the repo on GitHub, outside git |
| eval-metrics | what evaluating the config costs, how big the code is, and the budgets |
| usage-audit | which apps show any sign of being used, and why it is not a gate |
| readme | the README's header, the stats counted at build, and the two diagrams |
| license | MIT for the code, CC BY 4.0 for the docs, and what neither covers |