garandos/cheatsheets/project-guide.md

Project Guide — ZaneyOS

Scope

• A reproducible NixOS flake tailored for desktop systems with per-host overrides, GPU/VM profiles, and an integrated Home Manager layer (Hyprland, Waybar, shells, scripts).
• Repo location is expected at ~/zaneyos. If you place it elsewhere, update modules/core/nh.nix (programs.nh.flake) to the new path.

Quick commands

• Build and switch (preferred: nh/zcli)
  • fr → nh os switch --hostname # alias provided by zsh/bash modules
  • fu → nh os switch --hostname --update
  • zcli rebuild
  • zcli update
• Build for next boot (safer for larger changes)
  • zcli rebuild-boot
  • or: sudo nixos-rebuild boot --flake .#
• Direct NixOS (if you prefer without nh/zcli)
  • sudo nixos-rebuild switch --flake .#
• Validate the flake
  • nix flake check
• Format Nix files (nixfmt-rfc-style is included)
  • find . -name "*.nix" -print0 | xargs -0 nixfmt
• Host management
  • zcli update-host [hostname] [profile] # edits flake.nix host/profile
  • zcli add-host [profile] # copies hosts/default and guides hardware.nix
• Diagnostics and maintenance
  • zcli diag # writes ~/diag.txt
  • zcli cleanup # prunes older generations (prompts for retention)

zcli advanced options (for rebuild/update)

• --dry (-n) preview only
• --ask (-a) confirm before proceeding
• --cores N cap build CPU usage
• --verbose (-v) more logs
• --no-nom disable nix-output-monitor

Profiles and when to use them

• amd, intel, nvidia, nvidia-laptop (hybrid), vm
• Choose with the argument in nh/nixos-rebuild commands (e.g., .#vm)

High-level architecture

• flake.nix
  • Inputs: nixpkgs 25.05, home-manager 25.05, stylix, nvf, nix-flatpak
  • Local constants: system, host, profile, username
  • nixosConfigurations: one per GPU/VM profile via mkNixosConfig
    • Each configuration imports profiles/
• profiles//default.nix
  • Imports the active host and the system module stacks:
    • ../../hosts/${host}
    • ../../modules/drivers
    • ../../modules/core
  • Flips toggles: drivers.*.enable and vm.guest-services.enable
  • Hybrid laptops: profiles/nvidia-laptop pulls intel/nvidia Bus IDs from the host’s variables.nix and wires nvidia-prime
• hosts//
  • default.nix imports hardware.nix and host-packages.nix
  • variables.nix is the control panel for UX + feature toggles:
    • displayManager (greetd vs sddm)
    • terminal/browser defaults (enable per-terminal via flags)
    • waybarChoice, animChoice, stylixImage
    • 24h clock, thunarEnable, printEnable, NFS
    • intelID/nvidiaID for Prime offload
• modules/core
  • default.nix composes focused NixOS modules: boot, flatpak, fonts, hardware, network, nfs, nh, packages, printing, display manager (conditional greetd/sddm), security, services (PipeWire, SSH, Bluetooth, fstrim; smartd conditional on profile), steam, stylix, syncthing, system (nix settings, locales, env vars), thunar, user (Home Manager), virtualisation, xserver
  • user.nix integrates Home Manager and creates users.${username}; passes extraSpecialArgs { inputs, username, host, profile } to the home layer
  • nh.nix enables nh, configures GC, and pins programs.nh.flake = /home/${username}/zaneyos
• modules/drivers
  • Aggregates AMD, Intel, NVIDIA, NVIDIA Prime, and VM guest services
  • nvidia-prime-drivers.nix exposes options.drivers.nvidia-prime.{enable,intelBusID,nvidiaBusID} consumed by the nvidia-laptop profile
  • vm-guest-services.nix enables qemu-guest, spice agents when vm.guest-services.enable = true
• modules/home
  • default.nix composes the user environment (Hyprland, Waybar via waybarChoice, Rofi, Yazi, Kitty/WezTerm/Ghostty/Alacritty toggles, Zsh/Bash config, Git, NVF/Neovim, OBS, swaync, scripts, Stylix, optional Doom Emacs/VSCodium/Helix)
  • scripts/default.nix installs user-space tools including zcli; zcli wraps rebuild/update/boot builds, cleanup, diagnostics, host management, and Doom Emacs lifecycle

Where to change what

• flake.nix: set username, host, profile; add inputs; wire outputs
• hosts//{variables.nix,hardware.nix,host-packages.nix}: per-machine behavior, theming, and hardware
• modules/core/*: system-level settings, services, packages
• modules/home/*: user apps, shell, window manager, UI

Common workflows

• Small UX tweaks: edit hosts//variables.nix → fr
• Theme swap: edit stylixImage/waybarChoice in variables.nix → fr (or zcli rebuild-boot)
• GPU/VM switch: choose nixos-rebuild/nh profile (e.g., nh os switch --hostname vm) and optionally update host/profile constants with zcli update-host

Validation and troubleshooting

• nix flake check for a quick sanity test
• zcli diag to produce a detailed hardware/system report
• If the repo is not under ~/zaneyos, update modules/core/nh.nix so zcli/nh operate on the correct path

Documentation pointers

• README.md: requirements, first-time install methods, upgrade overview
• zcli.md: full CLI documentation, commands, options, and examples
• cheatsheets/: quick-reference guides for Hyprland, terminals, editors, etc.