NixOS configuration instructions

Desktop

TODO: Verify this path after the NixOS configuration is migrated. When adding a graphical application, add a window-rewrite icon mapping in modules/desktop/session/waybar.nix. The workspace indicator uses this mapping to show an application icon instead of the generic default glyph. Match the mapping on the window class. Run hyprctl clients -j | jq -r '.[].class' | sort -u to list classes in the running session.
TODO: Verify this path after the NixOS configuration is migrated. Set Hyprland session environment variables in modules/desktop/session/hyprland/default.nix with env = KEY,VALUE. home.sessionVariables do not reach the Hyprland session because UWSM does not source hm-session-vars.sh. Source cursor values from config.stylix.cursor. Set XCURSOR_* and HYPRCURSOR_* to the same theme for Bibata.

Manage Firefox search engines through programs.firefox.search with force = true. Hide built-in engines with <engine>.metaData.hidden = true because omission does not remove them. Use current engine ids, such as default = "ddg" instead of "DuckDuckGo". Decode the built search.json.mozlz4 with mozlz4a -d <search.json.mozlz4> to check the result.
Avoid Home Manager Firefox extension settings unless the whole profile can use the legacy extension-storage backend. Any non-empty profiles.<name>.extensions.settings.<id>.settings sets extensions.webextensions.ExtensionStorageIDB.enabled = false for the whole profile.

Nixvim's flake input follows the root nixpkgs source, but its Home Manager module does not reuse the host's pkgs instance. Keep programs.nixvim.nixpkgs.useGlobalPackages = true. That setting makes Nixvim use the shared package set without warning that its source default changed.

Use produced literals for Herdr key names that include shifted punctuation. For example, use prefix+< instead of prefix+shift+comma.
Put monorepo Pi extension sources in .pi/extensions/. Pi discovers them from subdirectories through the local ancestor-resource patch.
Treat Home Manager-managed Pi settings as generated output. Do not edit them except for throwaway development or local experiments. Promote finished settings into the NixOS configuration before treating them as deployed.

Guest modules are host-agnostic wiring, while host files own deployment-specific service configuration such as served volumes and host paths. For example, guests/copyparty.nix should expose options and translate them into guest mounts/service settings, while hosts/pikachu/default.nix chooses /inbox, /media, and their backing paths. Guest addresses and routes are host-level configuration because a guest module can be used on multiple hosts.
sops.secrets.<name>.owner must name a user known on the decrypting host. Do not set the owner to a guest-only service user unless the host also declares that user. Use a host-visible owner plus a shared group mode when the guest service can read the decrypted secret file through its group.
A read-only guest bind mount cannot contain nested writable bind mounts unless their mount-point directories already exist inside the read-only source. For aggregate Copyparty volumes such as /srv with nested /srv/inbox, keep the guest bind mount writable and enforce read-only behavior through Copyparty access plus service ReadWritePaths.
Pikachu deploys from the monorepo checkout copied to ~/dev. Do not use the old ~/wrk/dotfiles path for remote rebuild commands.
Do not hand-author hardware-configuration.nix for a host that has not been generated on that machine. Generate it on the target system or live ISO, then stage it before evaluating the flake.