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