dev/configs/nixos/AGENTS.md

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.

Firefox

• 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.

Neovim

• 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.

AI tooling

• 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.

Gotchas

• configs/nixos/registry/stable-uid.nix receives library functions through lib. Qualify its library calls with lib..
• 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.
• deploy-to builds from the source checkout and activates an imported closure on the target. Do not rely on a target-local monorepo checkout for remote deployment.
• On Pikachu, nix copy --to ssh://pikachu accepted a small nix store add-file probe, but rejected locally built system paths that lacked trusted signatures. Use a sudo nix-store --import path for unsigned deploy closures.
• Public DNS entries are not managed through the NixOS configuration. Do not describe NixOS route choices as public-DNS management.
• 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.