fix(home): remove dead behavior options, reserve overrides API

Two declared-but-non-functional option subsystems in core/home were
documented in OPTIONS.md and actively misleading users.

1. `nomarchy.behavior.hyprland.{bindings,input,windowRules,autostart}`
   were declared in core/home/behavior.nix with a `behaviorConfigs`
   mapping let-binding — both completely unread elsewhere in the tree.
   The actual hypr/*.conf files are deployed by
   features/desktop/hyprland/default.nix with `lib.mkDefault`,
   unconditionally. Setting `behavior.hyprland.bindings = false` had
   zero effect. OPTIONS.md's "Disable Nomarchy's default Hyprland
   keybindings" example was a lie. Removed the four dead options,
   deleted behavior.nix entirely, dropped the import from
   core/home/default.nix, and rewrote the OPTIONS.md example to use
   `xdg.configFile."hypr/bindings.conf".source = ./mine` (which
   actually works against the existing `lib.mkDefault` priority).

2. `nomarchy.overrides.{enable,paths}` advertised a file-based override
   loader that doesn't exist. The module created
   `~/.config/nomarchy/overrides/{hypr,waybar,apps}` directories and
   wrote a README claiming "place files here to override upstream
   defaults" — but `getOverrideOrDefault` was never called and `paths`
   was never populated. Rewrote core/home/overrides.nix to keep just
   the option declarations (so configs that already set these still
   evaluate) and marked them clearly as reserved/no-op in OPTIONS.md.
   Removed the misleading README write and dir-creation. Logged a
   Next-column roadmap row for implementing the loader properly.

While here:
- Clarified `nomarchy.configOverrides` (the *working* bulk-redirect
  mechanism) vs `nomarchy.overrides.*` (the reserved one) in OPTIONS.md
  — they're different things and the "See Overrides below" link was
  pointing at the broken subsystem.
- Fixed OPTIONS.md `nomarchy.iconsTheme` / `nomarchy.isLightMode`
  default text — both are derived from the active theme in
  core/home/state.nix, not the static literals the docs claimed.
- Updated docs/AGENT.md §2 and docs/STRUCTURE.md to reflect the
  behavior.nix removal and the overrides.nix reservation.

Found during Pillar 8 audit of core/home modules.

core/home/behavior.nix

@@ -1,94 +0,0 @@
-{ config, lib, ... }:
-
-# Behavior Configuration Module
-#
-# This module deploys non-visual configuration files (keybindings, input settings,
-# window rules, etc.) with lib.mkDefault, allowing downstream users to override.
-#
-# Visual/theme configs are handled separately by theme-loader.nix and stylix.nix.
-#
-# Behavior configs include:
-# - Keybindings (bindings, media keys, clipboard)
-# - Input settings (keyboard, mouse, touchpad)
-# - Window rules and layouts
-# - Autostart applications
-# - Environment variables
-
-let
-  configDir = ./config;
-  overridesDir = "${config.home.homeDirectory}/.config/nomarchy/overrides";
-
-  # Behavior config categories with their source paths
-  behaviorConfigs = {
-    # Hyprland behavior (non-visual)
-    "nomarchy/default/hypr/bindings.conf" = "hypr/bindings.conf";
-    "nomarchy/default/hypr/bindings/media.conf" = "hypr/bindings/media.conf";
-    "nomarchy/default/hypr/bindings/clipboard.conf" = "hypr/bindings/clipboard.conf";
-    "nomarchy/default/hypr/bindings/tiling-v2.conf" = "hypr/bindings/tiling-v2.conf";
-    "nomarchy/default/hypr/bindings/utilities.conf" = "hypr/bindings/utilities.conf";
-    "nomarchy/default/hypr/input.conf" = "hypr/input.conf";
-    "nomarchy/default/hypr/windows.conf" = "hypr/windows.conf";
-    "nomarchy/default/hypr/autostart.conf" = "hypr/autostart.conf";
-    "nomarchy/default/hypr/envs.conf" = "hypr/envs.conf";
-    "nomarchy/default/hypr/looknfeel.conf" = "hypr/looknfeel.conf";
-
-    # App-specific window rules (behavior, not visual)
-    "nomarchy/default/hypr/apps.conf" = "hypr/apps.conf";
-    "nomarchy/default/hypr/apps/qemu.conf" = "hypr/apps/qemu.conf";
-    "nomarchy/default/hypr/apps/steam.conf" = "hypr/apps/steam.conf";
-    "nomarchy/default/hypr/apps/terminals.conf" = "hypr/apps/terminals.conf";
-    "nomarchy/default/hypr/apps/walker.conf" = "hypr/apps/walker.conf";
-    "nomarchy/default/hypr/apps/browser.conf" = "hypr/apps/browser.conf";
-    "nomarchy/default/hypr/apps/1password.conf" = "hypr/apps/1password.conf";
-    "nomarchy/default/hypr/apps/bitwarden.conf" = "hypr/apps/bitwarden.conf";
-    "nomarchy/default/hypr/apps/pip.conf" = "hypr/apps/pip.conf";
-    "nomarchy/default/hypr/apps/system.conf" = "hypr/apps/system.conf";
-    "nomarchy/default/hypr/apps/localsend.conf" = "hypr/apps/localsend.conf";
-    "nomarchy/default/hypr/apps/telegram.conf" = "hypr/apps/telegram.conf";
-    "nomarchy/default/hypr/apps/geforce.conf" = "hypr/apps/geforce.conf";
-    "nomarchy/default/hypr/apps/moonlight.conf" = "hypr/apps/moonlight.conf";
-    "nomarchy/default/hypr/apps/retroarch.conf" = "hypr/apps/retroarch.conf";
-    "nomarchy/default/hypr/apps/webcam-overlay.conf" = "hypr/apps/webcam-overlay.conf";
-    "nomarchy/default/hypr/apps/davinci-resolve.conf" = "hypr/apps/davinci-resolve.conf";
-    "nomarchy/default/hypr/apps/hyprshot.conf" = "hypr/apps/hyprshot.conf";
-  };
-
-in
-{
-  options.nomarchy.behavior = {
-    hyprland = {
-      bindings = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default Hyprland keybindings.";
-      };
-      input = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default input settings.";
-      };
-      windowRules = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default window rules.";
-      };
-      autostart = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = "Whether to deploy default autostart configuration.";
-      };
-    };
-  };
-
-  config = {
-    # Note: The actual config deployment is handled by configs.nix
-    # This module provides the options and documentation for behavior configs
-    # The separation allows users to selectively disable behavior categories
-
-    # Ensure behavior config directories exist in overrides
-    home.activation.createBehaviorOverrideDirs = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
-      mkdir -p "${overridesDir}/hypr/bindings"
-      mkdir -p "${overridesDir}/hypr/apps"
-    '';
-  };
-}

core/home/default.nix

@@ -5,7 +5,6 @@
     ./options.nix
     ./state.nix
     ./overrides.nix
-    ./behavior.nix
     ./fonts.nix
     ./configs.nix
     ./security.nix

core/home/overrides.nix

@@ -1,97 +1,34 @@
 { config, lib, ... }:
 
-# File-based override system for Nomarchy
+# File-based override system for Nomarchy.
 #
-# Users can place config files in ~/.config/nomarchy/overrides/ to completely
+# STATUS: option surface only — the actual override mechanism is NOT yet
-# replace upstream defaults. Override priority (highest to lowest):
+# implemented. The options are kept so configs that already set
-# 1. User Nix options
+# `nomarchy.overrides.enable = …;` continue to evaluate; setting them has
-# 2. User file overrides (~/.config/nomarchy/overrides/)
+# no effect today. Tracked in docs/ROADMAP.md.
-# 3. Upstream defaults
 #
-# Supported override paths:
+# When implemented, this module should substitute sources in
-# - hypr/             - Hyprland configs (bindings.conf, input.conf, etc.)
+# `xdg.configFile.<path>.source` based on the presence of matching files
-# - waybar/           - Waybar config and style
+# under ~/.config/nomarchy/overrides/.
-# - alacritty/        - Alacritty terminal config
-# - walker/           - Walker launcher config
-# - kitty/            - Kitty terminal config
-# - btop/             - Btop resource monitor config
-# - apps/             - Other application configs
 
-let
-  overridesDir = "${config.home.homeDirectory}/.config/nomarchy/overrides";
-
-  # Helper to get override from options
-  getOverrideOrDefault = { path, default }:
-    config.nomarchy.overrides.paths.${path} or default;
-
-in
 {
   options.nomarchy.overrides = {
     enable = lib.mkOption {
       type = lib.types.bool;
       default = true;
-      description = "Whether to enable file-based override loading from ~/.config/nomarchy/overrides/";
+      description = ''
+        Reserved for the future file-based override loader. Currently a
+        no-op — setting this has no effect. See docs/ROADMAP.md.
+      '';
     };
 
     paths = lib.mkOption {
       type = lib.types.attrsOf lib.types.path;
       default = {};
-      description = "Override paths discovered at build time. Populated by the override system.";
+      description = ''
+        Reserved for the future file-based override loader. Currently
+        unused.
+      '';
     };
   };
-
-  config = lib.mkIf config.nomarchy.overrides.enable {
-    # Create the overrides directory structure if it doesn't exist
-    home.activation.createOverridesDir = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
-      mkdir -p "${overridesDir}"
-      mkdir -p "${overridesDir}/hypr"
-      mkdir -p "${overridesDir}/waybar"
-      mkdir -p "${overridesDir}/apps"
-    '';
-
-    # Document the override system
-    xdg.configFile."nomarchy/overrides/README.md".text = lib.mkDefault ''
-      # Nomarchy Configuration Overrides
-
-      Place files in this directory to override upstream Nomarchy defaults.
-
-      ## Directory Structure
-
-      ```
-      overrides/
-      ├── hypr/
-      │   ├── bindings.conf    # Keybindings
-      │   ├── input.conf       # Input settings
-      │   ├── monitors.conf    # Monitor layout
-      │   ├── rules.conf       # Window rules
-      │   └── autostart.conf   # Startup apps
-      ├── waybar/
-      │   ├── config.jsonc     # Waybar layout
-      │   └── style.css        # Waybar styling
-      ├── apps/
-      │   ├── alacritty.toml   # Terminal behavior
-      │   └── ...
-      └── README.md            # This file
-      ```
-
-      ## Override Priority
-
-      1. **Nix Options** (highest) - Set in your flake/config
-      2. **File Overrides** - Files in this directory
-      3. **Upstream Defaults** (lowest) - Nomarchy defaults
-
-      ## Usage
-
-      1. Copy the file you want to customize from the upstream config
-      2. Place it in the appropriate directory here
-      3. Edit to your preferences
-      4. Run `nixos-rebuild switch` or `home-manager switch`
-
-      ## Tips
-
-      - For keybindings, copy `~/.config/hypr/bindings.conf` to `overrides/hypr/`
-      - For Waybar styling, copy `~/.config/waybar/style.css` to `overrides/waybar/`
-      - Changes here persist across Nomarchy updates
-    '';
-  };
 }

docs/AGENT.md

@@ -41,8 +41,7 @@ core/         Foundational OS + user defaults. Don't put apps here.
     scripts/          Low-level system scripts (battery, brightness, hardware).
   home/         Home Manager modules.
     options.nix       Most home-side nomarchy.* options.
-    behavior.nix      nomarchy.behavior.* (deploy-default-config toggles).
+    overrides.nix     nomarchy.overrides.* (reserved; currently no-op — see ROADMAP).
-    overrides.nix     File-based overrides from ~/.config/nomarchy/overrides/.
     config/           Plain dotfiles symlinked into ~/.config.
 
 features/     Apps and desktop components. Add new apps here.

docs/OPTIONS.md

@@ -223,11 +223,11 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.iconsTheme`
 
-`str`, default `"Yaru-blue"`. GTK/Qt icon theme name.
+`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 `false`. Whether the active theme is a light theme. Affects nightlight defaults and a few app theme decisions.
+`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`
 
@@ -239,23 +239,7 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.configOverrides`
 
-`nullOr path`, default `null`. Path to a directory containing config overrides. See "Overrides" below.
+`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.behavior.hyprland.bindings`
-
-`bool`, default `true`. Deploy the default Hyprland keybindings. Set to `false` if you want to write `bindings.conf` from scratch.
-
-### `nomarchy.behavior.hyprland.input`
-
-`bool`, default `true`. Deploy default input settings (kb_layout, mouse accel, etc).
-
-### `nomarchy.behavior.hyprland.windowRules`
-
-`bool`, default `true`. Deploy default window rules.
-
-### `nomarchy.behavior.hyprland.autostart`
-
-`bool`, default `true`. Deploy the default `autostart.conf` (hypridle, mako, swayosd, nm-applet, etc).
 
 ### `nomarchy.apps.opencode.enable`
 
@@ -279,11 +263,11 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.overrides.enable`
 
-`bool`, default `true`. Enable file-based overrides loaded from `~/.config/nomarchy/overrides/`. With this on, Nomarchy looks for matching files in that directory and substitutes them for the bundled defaults.
+`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 `{}`. Override paths discovered at build time. Populated by the override system — you don't normally set this directly.
+`attrsOf path`, default `{}`. **Reserved — currently unused.** Will be populated by the future override loader.
 
 ---
 
@@ -315,15 +299,17 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 }
 ```
 
-### Disable Nomarchy's default Hyprland keybindings to ship your own
+### 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
 {
-  nomarchy.behavior.hyprland.bindings = false;
+  xdg.configFile."hypr/bindings.conf".source = ./my-bindings.conf;
 }
 ```
 
-Then put your own `bindings.conf` at `~/.config/nomarchy/overrides/hypr/bindings.conf` (with `nomarchy.overrides.enable = true;`, which is the default).
+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.
 
 ---
 
@@ -333,7 +319,6 @@ Then put your own `bindings.conf` at `~/.config/nomarchy/overrides/hypr/bindings
 - `core/system/hardware.nix` — `nomarchy.hardware.*`
 - `core/system/impermanence.nix` — `impermanence.enable`
 - `core/home/options.nix` — most home-side `nomarchy.*` options
-- `core/home/behavior.nix` — `nomarchy.behavior.*`
+- `core/home/overrides.nix` — `nomarchy.overrides.*` (reserved; currently no-op)
-- `core/home/overrides.nix` — `nomarchy.overrides.*`
 - `themes/engine/loader.nix` — `nomarchy.themeLoader.*`
 - `features/apps/vscode.nix` — `nomarchy.vscode.*`

docs/ROADMAP.md

@@ -28,6 +28,7 @@ Guardrails (apply when adding anything):
 - **Accessibility — home-side companion.** Hyprland-side bits the system preset can't reach: slower `input.repeat_rate` / `repeat_delay` defaults, `SUPER+ALT+S` keybinding to launch Orca, and a high-contrast palette under `themes/palettes/`. Gated on a new `nomarchy.accessibility.enable` mirror of the system option.
 - **Gaming — declarative flathub remote.** `services.flatpak.enable` doesn't ship a declarative remote API in nixpkgs. Either add the `flatpak-managed-install` overlay, write a one-shot systemd unit that runs `flatpak remote-add --if-not-exists flathub …`, or surface the manual step in `nomarchy-welcome`.
 - **Plymouth theme variants per palette.** Currently one Plymouth theme; could template per-palette so the boot splash matches the active theme.
+- **Implement `nomarchy.overrides.*` file-based override loader.** The option surface is declared in `core/home/overrides.nix` but the loader doesn't exist — files dropped under `~/.config/nomarchy/overrides/` are ignored. Spec: when `overrides.enable = true`, for each `xdg.configFile.<path>` Nomarchy deploys with `lib.mkDefault`, check whether `~/.config/nomarchy/overrides/<path>` exists at build time; if so, use it as the source. Requires deciding whether discovery happens at activation time (cheap, but rebuild-required to pick up new files) or via a populated `paths` attrset (Nix-side, evaluated once per rebuild). Until shipped, document the per-file workaround (`xdg.configFile.<path>.source = ./mine`) in OPTIONS.md.
 
 ### Later (speculative or research-shaped)
 

docs/STRUCTURE.md

@@ -70,8 +70,8 @@ The `core/` directory contains the foundational modules required for a functiona
 - **`default.nix`**: The entry point for the base Home Manager module.
 - **`options.nix`**: Defines the `nomarchy` user options (Toggles, Theme, Fonts, etc.).
 - **`state.nix`**: Loads and applies user-level state (from `~/.config/nomarchy/state.json`).
-- **`behavior.nix`**: Deploys non-visual configs (Keybindings, Input settings, Window rules) with `lib.mkDefault`.
+- **`overrides.nix`**: Declares `nomarchy.overrides.*` (reserved for a future file-based override loader; currently no-op).
-- **`configs.nix`**: Manages static configuration files and directories in `~/.config/`.
+- **`configs.nix`**: Manages static configuration files and directories in `~/.config/`. Honors `nomarchy.configOverrides` as a bulk redirect to a replacement config dir.
 - **`bash.nix`**: Shell environment, aliases, and specialized `env-update` hooks.
 - **`security.nix`**: Polkit, keyring management, and GPG settings.
 - **`config/`**: Contains the physical source files for the base user configuration (e.g., `starship.toml`, `hypr/` behavior configs).