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