dev/configs/nixos/AGENTS.md

NixOS configuration instructions

Desktop

• When adding a graphical application, register its workspace icon in registry.window-icon. The workspace indicator uses this mapping to show an application icon instead of the generic default glyph. Match the mapping on the window class. Store the icon as the rendered string. 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, records the imported closure as the target system profile, and activates it. 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.
• Configure the Chaotic Nyx cache only on hosts that select linuxPackages_cachyos (currently Neogaia and Zeus), not in the generic host module.
• Module-relative paths resolve from the module file. Update them when moving a module into a subdirectory.
• On Pikachu, uptime does not support -s. Use who -b to report the boot time.
• Evaluating a NixOS guest's inner config.services.nginx can force incomplete ACME values. Evaluate the parent host's config.system.build.toplevel to validate an ACME-enabled guest.
• pkgs.systemd does not set meta.mainProgram. Use lib.getExe' pkgs.systemd "systemctl" instead of lib.getExe pkgs.systemd.