Nomarchy/docs/OPTIONS.md

# Nomarchy Options Reference

Every option Nomarchy exposes for downstream flakes. Paths under `nomarchy.system.*` are NixOS options (set in `system.nix`); paths under `nomarchy.*` (no `system` segment) are Home Manager options (set in `home.nix`). `nomarchy.hardware.*` is NixOS.

The installer-generated configuration writes a few of these for you (timezone, formFactor, hardware vendor flags, keymap, locale). Anything not listed there is opt-in — set it yourself.

To see the live default for any option:

```bash
nix eval .#nixosConfigurations.<host>.config.nomarchy.system.<path>
nix eval .#homeConfigurations.<user>.config.nomarchy.<path>
```

---

## NixOS options (`system.nix`)

### `nomarchy.system.dns`

DNS provider. One of `"DHCP"` (default), `"Cloudflare"`, `"Google"`, `"Custom"`. With `"Custom"`, set `nomarchy.system.customDns` to a list of nameservers. Anything other than `"DHCP"` also enables `services.resolved` with DNSSEC and DNS-over-TLS.

Defined in `core/system/options.nix`; wired in `core/system/network.nix`.

### `nomarchy.system.customDns`

`listOf str`, default `[]`. Nameservers used when `dns = "Custom"`.

### `nomarchy.system.wifi.powersave`

`bool`, default `true`. Sets `networking.networkmanager.wifi.powersave`. Turn off if you see drops on idle Wi-Fi.

### `nomarchy.system.timezone`

`str`, default `"UTC"`. The installer writes `time.timeZone` directly, so this option is informational unless you wire it into your own modules.

### `nomarchy.system.formFactor`

`enum [ "laptop" "desktop" ]`, default `"laptop"`. Drives UI affordances and the laptop power preset. The installer auto-detects via `/sys/class/power_supply/BAT*`. The default is `"laptop"` because the battery widget renders empty when no battery is present — safe on a desktop, useful on a laptop.

Wired in `features/desktop/waybar/default.nix` (filters the battery widget out on desktop), `features/scripts/battery-monitor.nix` (skips the timer on desktop), and `nomarchy.system.laptop.enable` (defaults true when this is `"laptop"`).

### `nomarchy.system.theme`

`str`, default `"summer-night"`. Theme name. Mirror of the home-side `nomarchy.theme`. Set both if you also want NixOS-side modules (e.g. SDDM theming) to follow.

### `nomarchy.system.features.fingerprint`

`bool`, default `false`. Enables `services.fprintd.enable`.

### `nomarchy.system.features.fido2`

`bool`, default `false`. Enables `security.pam.u2f` (sufficient, with cue).

### `nomarchy.system.features.hybridGPU`

`bool`, default `false`. NVIDIA-hybrid laptop support. Wires:

- `services.supergfxd.enable` for runtime mode switching (`Integrated` / `Hybrid` / `Vfio` / `AsusEgpu`), driven by `nomarchy-toggle-hybrid-gpu`.
- The NVIDIA driver stack (`services.xserver.videoDrivers = ["nvidia"]`, `hardware.graphics.{enable,enable32Bit}`, `hardware.nvidia.{modesetting,powerManagement}.enable`, `boot.kernelParams = ["nvidia-drm.modeset=1"]`).

All driver knobs use `lib.mkDefault`, so a downstream `system.nix` can pin a beta driver or flip to the open kernel module without forking the module.

**You still have to add bus IDs** — they're per-machine and can't be derived from any flag. Find them with `lspci -D | grep -E 'VGA|3D'`, then in your `/etc/nixos/system.nix`:

```nix
hardware.nvidia.prime = {
  offload.enable = true;
  offload.enableOffloadCmd = true;
  intelBusId  = "PCI:0:2:0";   # or `amdgpuBusId` for AMD iGPU
  nvidiaBusId = "PCI:1:0:0";
};
```

Without prime config, supergfxd still switches modes but render-offload via `nvidia-offload <cmd>` is unavailable.

### `nomarchy.system.snapper.enable`

`bool`, default `false`. BTRFS timeline snapshots of `/`. Auto-disables when `/` isn't BTRFS. Includes a `nixos-rebuild-snap` wrapper that takes a "Pre-rebuild" snapshot before each switch.

### `nomarchy.system.hibernation.enable`

`bool`, default `false`. Suspend-then-hibernate on lid close, idle, and power button. Requires a disk swap device or swapfile sized to at least RAM — zRAM alone is not enough.

### `nomarchy.system.hibernation.idleMinutes`

`int`, default `30`. Idle minutes before suspend-then-hibernate fires.

### `nomarchy.system.laptop.enable`

`bool`, default `nomarchy.system.formFactor == "laptop"`. Laptop power preset: TLP (with sane AC/battery governors and ThinkPad-style 75/80 charge thresholds), `services.upower`, `services.thermald` (gated by `laptop.thermald`), and a brightnessctl udev rule so the existing `nomarchy-brightness-{display,keyboard}` scripts run without root. Force-disables `services.power-profiles-daemon` (mutually exclusive with TLP) — to use PPD instead, set `laptop.enable = false` and wire it yourself. Lid-close action defers to `nomarchy.system.hibernation.enable`: `suspend-then-hibernate` when on, `suspend` otherwise. Charge thresholds are only honored on supported hardware (ThinkPad, some ASUS); harmless warning elsewhere.

### `nomarchy.system.laptop.thermald`

`bool`, default `true` on x86_64. Enables `services.thermald` (Intel thermal daemon). Harmless no-op on AMD; gated off on aarch64.

### `nomarchy.system.desktop.enable`

`bool`, default `nomarchy.system.formFactor == "desktop"`. Desktop preset: pins `powerManagement.cpuFreqGovernor` to `"performance"` (via `mkDefault`) and enables `services.zfs.autoScrub` + `services.zfs.trim` so a future ZFS pool gets sensible maintenance without further config. The ZFS knobs are no-ops until you add `boot.supportedFilesystems = [ "zfs" ]` (plus `networking.hostId`) and a pool. Battery-widget filtering is handled by `formFactor` itself, so this preset doesn't repeat it.

### `nomarchy.system.accessibility.enable`

`bool`, default `false`. Accessibility preset: enables `services.gnome.at-spi2-core` (AT-SPI2 framework), installs `pkgs.orca` (screen reader) into `environment.systemPackages`, and sets `XCURSOR_SIZE` to `accessibility.cursorSize`. Off by default — accessibility is a personal preference, not hardware-derived. The Hyprland-side bits (slower key-repeat, Orca launch keybinding, high-contrast palette) are a separate roadmap item.

### `nomarchy.system.accessibility.cursorSize`

`int`, default `32`. `XCURSOR_SIZE` when `accessibility.enable = true`. NixOS default is 24; 32 is a safer floor for low-vision users.

### `nomarchy.system.gaming.enable`

`bool`, default `false`. Gaming preset: enables `programs.steam` (with `remotePlay` and `localNetworkGameTransfers` firewall holes opened by `mkDefault`), `programs.gamemode` (the launching user must be in the `gamemode` group), and `services.flatpak`. The flathub remote isn't added declaratively — after first boot, run `flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo`. Pair with the home-side companion `nomarchy.gaming.enable` for the Hyprland fullscreen-on-Steam-launch window rule.

### `nomarchy.system.containers.enable`

`bool`, default `false`. Rootless Podman with Docker compatibility (`docker` → `podman`), plus `podman-compose`, `podman-tui`, and `dive`.

### `nomarchy.system.virtualization.libvirt.enable`

`bool`, default `false`. libvirt daemon, virt-manager, and OVMF. Add your user to the `libvirtd` group.

### `nomarchy.system.virtualization.docker.enable`

`bool`, default `false`. Docker daemon and docker-compose. Add your user to the `docker` group.

### `nomarchy.system.keyring.enable`

`bool`, default `true`. Auto-unlock GNOME Keyring at login and route SSH keys through `gcr-ssh-agent`. On by default — near-universal QoL improvement.

### `nomarchy.system.inputMethod.enable`

`bool`, default `false`. fcitx5 input method for CJK / IME. Wires NixOS's `i18n.inputMethod` and autostarts `fcitx5-daemon`.

### `nomarchy.system.voxtype.enable`

`bool`, default `false`. voxtype voice-typing integration. voxtype isn't packaged in nixpkgs — when you enable this, install voxtype yourself (e.g. `home.packages = [ (pkgs.callPackage … {}) ]`). With this off the `SUPER+CTRL+X` keybinding and waybar widget are no-ops.

### `nomarchy.hardware.isXPS`

`bool`, default `false`. Dell XPS fixes — haptic touchpad service and PCI/I²C power-control udev rules.

### `nomarchy.hardware.isT2Mac`

`bool`, default `false`. Apple T2 MacBook fixes — IOMMU kernel params, `apple-bce` module, brcmfmac feature mask.

### `nomarchy.hardware.isFramework`

`bool`, default `false`. Framework laptop QMK HID udev rule.

### `nomarchy.hardware.fwupd`

`bool`, default `false`. Enables `services.fwupd` firmware update service.

### `nomarchy.hardware.hasIPU7Camera`

`bool`, default `false`. Intel IPU7 camera support (kernel modules + firmware).

### `impermanence.enable`

`bool`, default `false`. Erase Your Darlings root wipe on boot. Defined in `core/system/impermanence.nix`. The installer writes the flag based on the impermanence prompt.

---

## Home Manager options (`home.nix`)

### `nomarchy.theme`

`str`, default `"summer-night"`. Active theme name. Available themes are the directories under `themes/palettes/`.

### `nomarchy.panelPosition`

`enum ["top", "bottom"]`, default `"top"`. Waybar panel position.

### `nomarchy.formFactor`

`enum [ "laptop" "desktop" ]`, default `"laptop"`. Mirror of `nomarchy.system.formFactor`. Filters laptop-only widgets out of waybar (battery) when set to `"desktop"`. The installer writes both system and home values together.

### `nomarchy.wallpaper`

`str`, default `""`. Absolute path to a wallpaper override. Empty string means "use the active theme's default wallpaper".

### `nomarchy.toggles.suspend`

`bool`, default `true`. Whether suspend appears in the system menu.

### `nomarchy.toggles.screensaver`

`bool`, default `true`. Whether the screensaver is enabled.

### `nomarchy.toggles.idle`

`bool`, default `true`. Whether the idle lock is enabled (hypridle).

### `nomarchy.toggles.nightlight`

`bool`, default `false`. Enables hyprsunset.

### `nomarchy.toggles.waybar`

`bool`, default `true`. Whether the top bar is deployed at all.

### `nomarchy.toggles.skipVsCodeTheme`

`bool`, default `false`. Skip theme overrides in VSCode — useful if you manage VSCode themes yourself.

### `nomarchy.nightlightTemperature`

`int`, default `4000`. Nightlight color temperature (Kelvin).

### `nomarchy.hyprland.gaps_in`

`int`, default `5`. Inner gaps.

### `nomarchy.hyprland.gaps_out`

`int`, default `10`. Outer gaps.

### `nomarchy.hyprland.border_size`

`int`, default `2`. Window border width.

### `nomarchy.fonts.monospace`

`str`, default `"JetBrainsMono Nerd Font"`. Used by terminals, VSCode, etc.

### `nomarchy.iconsTheme`

`str`, default derived from the active theme (falls back to `"Yaru-blue"`). GTK/Qt icon theme name. `core/home/state.nix` computes this from the theme's palette metadata; override to pin a specific icon theme regardless of palette.

### `nomarchy.isLightMode`

`bool`, default derived from the active theme. Whether the active theme is a light theme. `core/home/state.nix` computes this from the theme directory; affects nightlight defaults and a few app theme decisions. Override only if you need to force a specific value.

### `nomarchy.cursor.name`

`str`, default `"Bibata-Modern-Ice"`. Cursor theme name.

### `nomarchy.cursor.package`

`package`, default `pkgs.bibata-cursors`. Package providing the cursor theme. Override both `name` and `package` together if you switch themes.

### `nomarchy.configOverrides`

`nullOr path`, default `null`. Path to a replacement config directory. When set, the items listed in `core/home/configs.nix` (`fastfetch`, `fcitx5`, `fontconfig`, `git`, `imv`, `nautilus-python`, `nomarchy`, `nomarchy-skill`, `uwsm`, `wiremix`, plus the loose files) are read from `<this-path>/<name>` instead of the bundled defaults. Distinct from `nomarchy.overrides.*` below — `configOverrides` is a working bulk redirect; `overrides.*` is a reserved option surface (currently a no-op).

### `nomarchy.apps.opencode.enable`

`bool`, default `false`. opencode AI coding CLI integration. Deploys `~/.config/opencode/opencode.json`. The `opencode` package itself is **not** installed by Nomarchy — add it to your `home.packages`.

### `nomarchy.gaming.enable`

`bool`, default `false`. Home-side companion to `nomarchy.system.gaming.enable`. Adds a Hyprland `windowrulev2 = fullscreen, class:^(steam_app_).*$` so games launched through Steam grab the whole screen instead of opening windowed. Set to the same value as the system option; the installer flips both when the Gaming profile is selected.

### `nomarchy.vscode.devExtensions`

`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (Nix, language servers, theme variants).

### `nomarchy.themeLoader.enable`

`bool`, default `true`. Auto-load theme-specific app configs (btop, waybar, mako, kitty, alacritty) from the active theme. Disable if you want to provide your own.

### `nomarchy.themeLoader.apps.{btop,waybar,mako,kitty,alacritty}`

`bool`, default `true` each. Per-app toggles for the theme loader — pick which apps follow the active theme.

### `nomarchy.overrides.enable`

`bool`, default `true`. **Reserved — currently a no-op.** Intended to gate a future file-based override loader (drop a file under `~/.config/nomarchy/overrides/`, have it substitute the bundled default for that path). The option exists so configs that set it don't fail to evaluate; setting it has no effect today. Use `nomarchy.configOverrides` for bulk redirection, or set `xdg.configFile.<path>.source` directly in your `home.nix` for per-file overrides — Nomarchy's defaults use `lib.mkDefault` and yield to higher-priority assignments. Tracked in `docs/ROADMAP.md`.

### `nomarchy.overrides.paths`

`attrsOf path`, default `{}`. **Reserved — currently unused.** Will be populated by the future override loader.

---

## Examples

### Minimal `system.nix` for a desktop with Cloudflare DNS, Snapper, and rootless Podman

```nix
{
  nomarchy.system = {
    dns = "Cloudflare";
    formFactor = "desktop";
    snapper.enable = true;
    containers.enable = true;
  };
}
```

### Minimal `home.nix` for a Tokyo-night user with custom gaps and opencode

```nix
{
  nomarchy = {
    theme = "tokyo-night";
    hyprland.gaps_in = 8;
    hyprland.gaps_out = 16;
    apps.opencode.enable = true;
  };
}
```

### Ship your own Hyprland keybindings instead of Nomarchy's defaults

Nomarchy deploys its `bindings.conf` with `lib.mkDefault`, so a higher-priority assignment from your own `home.nix` wins:

```nix
{
  xdg.configFile."hypr/bindings.conf".source = ./my-bindings.conf;
}
```

The same pattern works for any file Nomarchy deploys via `xdg.configFile.<path>.source = lib.mkDefault …` — point at your own file and skip the default.

---

## Where these are defined

- `core/system/options.nix` — most `nomarchy.system.*` options
- `core/system/hardware.nix` — `nomarchy.hardware.*`
- `core/system/impermanence.nix` — `impermanence.enable`
- `core/home/options.nix` — most home-side `nomarchy.*` options
- `core/home/overrides.nix` — `nomarchy.overrides.*` (reserved; currently no-op)
- `themes/engine/loader.nix` — `nomarchy.themeLoader.*`
- `features/apps/vscode.nix` — `nomarchy.vscode.*`