Nomarchy/docs/OVERRIDES.md

# Overriding Nomarchy's defaults

You consume Nomarchy as a flake input and own two files: `system.nix` and
`home.nix`. Your config is **merged** with Nomarchy's modules, so changing a
default is just a matter of knowing which of three knobs to reach for. The
rule of thumb:

> **Appearance → the CLI. Behaviour → `home.nix`. Whole component → toggle it off.**

## 1. Appearance (gaps, colors, rounding, fonts, opacity) — use the CLI

Everything that defines the *look* flows from `theme-state.json`, the single
source of truth. Change it with `nomarchy-theme-sync`, which writes the JSON
and rebuilds — one generation, applied to Hyprland, Waybar, Ghostty, btop and
Stylix at once:

```sh
nomarchy-theme-sync set ui.gapsOut 16      # gaps, borders, rounding, opacity
nomarchy-theme-sync set ui.rounding 0
nomarchy-theme-sync set fonts.mono "FiraCode Nerd Font"
nomarchy-theme-sync apply gruvbox          # whole palette
```

These values are deliberately kept at normal priority in the modules, so they
stay owned by the theme system. If you *insist* on pinning one in `home.nix`
regardless of the active theme, use `lib.mkForce` (see §4) — but then the CLI
can no longer change that knob.

## 2. Behaviour (input, misc, monitor, animations, terminal chrome) — `home.nix`

Non-appearance defaults are set with `lib.mkDefault`, so a **plain assignment**
in your `home.nix` wins — no `mkForce` needed:

```nix
# home.nix
{ ... }:
{
  wayland.windowManager.hyprland.settings = {
    input.follow_mouse = 0;            # was 1
    input.touchpad.natural_scroll = false;
    misc.disable_splash_rendering = false;
    monitor = [ "DP-1,2560x1440@144,0x0,1" ];   # raw rule — replaces the default
    animations.enabled = false;
  };

  programs.ghostty.settings = {
    window-padding-x = 4;              # was 12
    window-decoration = true;
  };
}
```

For monitor layout, prefer the friendlier **`nomarchy.monitors`** (a list of
per-output submodules — resolution/position/scale/rotation — turned into
Hyprland rules and applied on hotplug; run `nwg-displays` to find the values
interactively). Assigning `settings.monitor` directly, as above, replaces it.

### Adding vs. overriding lists

`bind`, `bindel`, `bindl`, `bindm` and `exec-once` are lists kept at normal
priority, so anything you add **concatenates** with Nomarchy's — your binds and
autostarts run *alongside* the defaults:

```nix
{
  wayland.windowManager.hyprland.settings = {
    bind = [
      "$mod, B, exec, firefox"
      "$mod SHIFT, S, exec, grim -g \"$(slurp)\" - | swappy -f -"
    ];
    exec-once = [ "nm-applet --indicator" ];
  };
}
```

To **remove or replace** a default bind, override the whole `bind` list with
`lib.mkForce [ … ]` (you then own the full list), or rebind the key to
something else (last definition for a key wins in Hyprland).

You can also drop raw config that doesn't fit the Nix schema:

```nix
{ wayland.windowManager.hyprland.extraConfig = ''
    bindl = , switch:Lid Switch, exec, hyprlock
  '';
}
```

### Waybar

For a themed bar identity, ship whole-swap assets
(`themes/<slug>/waybar.jsonc` and `waybar.css`) — see the main README. To
replace the bar wholesale from `home.nix`, assign `programs.waybar.settings.
mainBar` / `programs.waybar.style` (both `mkDefault`, so a plain assignment
wins). For a one-off tweak of a single generated key, `lib.mkForce` it.

## 3. Whole component — toggle it off and bring your own

Each desktop piece has an enable flag (all default `true`). Turn one off and
Nomarchy contributes nothing for it, leaving the field clear for your own:

```nix
# home.nix
{
  nomarchy.hyprland.enable = false;   # then write your own wayland.windowManager.hyprland
  nomarchy.waybar.enable = false;
  nomarchy.swaync.enable = false;
  nomarchy.idle.enable = false;       # no hyprlock/hypridle
}
```

```nix
# system.nix
{
  nomarchy.system.plymouth.enable = false;
  nomarchy.system.greeter.enable = false;   # bring your own login manager
}
```

See the option tables in the README for the full list.

## 4. Last resort: `lib.mkForce`

To override a value Nomarchy sets at normal priority (an appearance value, or
a whole list), raise your definition's priority:

```nix
{ lib, ... }:
{
  # hardcode rounding against the theme (the CLI can no longer change it)
  wayland.windowManager.hyprland.settings.decoration.rounding = lib.mkForce 0;

  # own the entire keybind list
  wayland.windowManager.hyprland.settings.bind = lib.mkForce [ "$mod, Return, exec, kitty" ];
}
```

If a plain assignment errors with *"has conflicting definition values"*, that
value is theme-owned at normal priority — either change it via the CLI (§1) or
`mkForce` it here.

## Quick reference

| You want to… | Do this |
|---|---|
| Change gaps / colors / rounding / fonts | `nomarchy-theme-sync set …` or `apply` |
| Change input / misc / monitor / animations / terminal chrome | plain assignment in `home.nix` |
| Arrange monitors declaratively | `nomarchy.monitors` (values via `nwg-displays`) |
| Add keybinds / autostarts | add to the `bind` / `exec-once` list (concatenates) |
| Replace all keybinds | `bind = lib.mkForce [ … ]` |
| Hardcode an appearance value against the theme | `lib.mkForce` in `home.nix` |
| Drop a whole component | `nomarchy.<component>.enable = false` |
| Raw Hyprland lines | `wayland.windowManager.hyprland.extraConfig` |