feat: move core apps to downstream and make app modules opt-in

core/home/options.nix

@@ -144,14 +144,25 @@ in
     };
 
     apps = {
-      opencode = {
+      alacritty.enable = lib.mkEnableOption "Alacritty terminal integration";
-        enable = lib.mkEnableOption ''
+      btop.enable = lib.mkEnableOption "btop resource monitor integration";
-          opencode AI coding CLI integration. When on, deploys
+      ghostty.enable = lib.mkEnableOption "Ghostty terminal integration";
-          ~/.config/opencode/opencode.json. The `opencode` package itself
+      kitty.enable = lib.mkEnableOption "Kitty terminal integration";
-          is not installed by Nomarchy — add it to your home.nix if you
+      lazygit.enable = lib.mkEnableOption "lazygit integration";
-          want it on PATH.
+      tmux.enable = lib.mkEnableOption "tmux integration";
-        '';
+      elephant.enable = lib.mkEnableOption "Elephant menu provider integration";
+      walker.enable = lib.mkEnableOption "Walker launcher integration";
+      swayosd.enable = lib.mkEnableOption "SwayOSD integration";
+      vscode = {
+        enable = lib.mkEnableOption "VSCode integration";
+        devExtensions = lib.mkEnableOption "Nomarchy's curated VSCode extension pack (language servers + git + editor enhancements)";
       };
+      opencode.enable = lib.mkEnableOption ''
+        opencode AI coding CLI integration. When on, deploys
+        ~/.config/opencode/opencode.json. The `opencode` package itself
+        is not installed by Nomarchy — add it to your home.nix if you
+        want it on PATH.
+      '';
     };
 
     gaming = {

docs/AGENT.md

@@ -64,10 +64,12 @@ bin/          Convenience wrappers for testing (nomarchy-test-installer, …).
 
 When you add a new feature:
 
-- A new app → `features/apps/<name>/default.nix` (+ optional `config/`), import it from `features/default.nix`.
+- A new app → `features/apps/<name>/default.nix` (+ optional `config/`), import it from `features/default.nix`. **All app modules must be opt-in** via a `nomarchy.apps.<name>.enable` option defined in `core/home/options.nix`. Enabling the module should also handle the `programs.<name>.enable` or `home.packages` installation where applicable.
 - A new system service → `core/system/<name>.nix`, import from `core/default.nix`.
 - A new toggle → add to `core/system/options.nix` or `core/home/options.nix`, wire it into the relevant module, document it in `docs/OPTIONS.md`.
 
+Core user-facing apps (browsers, file managers, media players) are **not** installed by the `features/default.nix` module list. Instead, they are managed in the downstream `home.nix` (which the installer pre-fills with defaults like `firefox` and `thunar`). This keeps the Nomarchy core modules focused on the desktop environment while giving the user explicit control over their app set.
+
 ---
 
 ## 3. Guardrails (non-negotiable unless the user overrides)

docs/MIGRATION.md

@@ -123,11 +123,24 @@ create minimal versions to start:
 { pkgs, ... }:
 {
   home.packages = with pkgs; [
-    btop
+    firefox
+    xfce.thunar
+    imv
+    mpv
     fastfetch
     chromium
-    # …add anything you want; firefox/thunar/mpv/mako/etc. ship with Nomarchy.
+    # …add anything you want; mako/hyprlock/swww/rofi/etc. ship with Nomarchy.
   ];
+
+  # Enable Nomarchy's curated app configurations
+  nomarchy.apps = {
+    alacritty.enable = true;
+    btop.enable = true;
+    elephant.enable = true;
+    swayosd.enable = true;
+    walker.enable = true;
+    vscode.enable = true;
+  };
 }
 ```
 

docs/OPTIONS.md

@@ -253,6 +253,50 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 `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.paths` is a *per-file* attrset map.
 
+### `nomarchy.apps.alacritty.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Alacritty configuration. The installer enables this by default.
+
+### `nomarchy.apps.btop.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated btop configuration (themed color scheme, vim keys). The installer enables this by default.
+
+### `nomarchy.apps.ghostty.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated Ghostty configuration.
+
+### `nomarchy.apps.kitty.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated Kitty configuration.
+
+### `nomarchy.apps.lazygit.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated lazygit configuration.
+
+### `nomarchy.apps.tmux.enable`
+
+`bool`, default `false`. Deploys Nomarchy's curated tmux configuration.
+
+### `nomarchy.apps.elephant.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Elephant menu provider integration (required for the theme picker and background selector). The installer enables this by default.
+
+### `nomarchy.apps.walker.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated Walker launcher configuration. The installer enables this by default.
+
+### `nomarchy.apps.swayosd.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated SwayOSD configuration. The installer enables this by default.
+
+### `nomarchy.apps.vscode.enable`
+
+`bool`, default `false`. Enables Nomarchy's curated VSCode configuration (theming, fonts). The installer enables this by default.
+
+### `nomarchy.apps.vscode.devExtensions`
+
+`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (language servers + git + editor enhancements). The palette theme extensions are *always* installed when `vscode.enable` is true — every palette except `ethereal`, `hackerman`, and `vantablack` resolves its `workbench.colorTheme` via either `pkgs.vscode-extensions` (catppuccin/nord/tokyo-night/rose-pine/gruvbox) or `pkgs.vscode-utils.extensionFromVscodeMarketplace` with version + sha256 pinned (sainnhe.everforest, qufiwefefwoyn.kanagawa, monokai.theme-monokai-pro-vscode, oldjobobo.{lumon,miasma,retro-82}, shadesOfBuntu.flexoki-light, jovejonovski.ocean-green, TahaYVR.matteblack, Bjarne.white-theme). The three palettes whose theme extension isn't on the marketplace fall back to VSCode's default theme; see the ROADMAP Later row.
+
 ### `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`.
@@ -263,11 +307,7 @@ Without prime config, supergfxd still switches modes but render-offload via `nvi
 
 ### `nomarchy.accessibility.enable`
 
-`bool`, default `false`. Home-side companion to `nomarchy.system.accessibility.enable`. Three Hyprland-side adjustments: slows `input.repeat_rate` to `25` (default `40`) and `input.repeat_delay` to `1000` ms (default `600`) so holding a key isn't a runaway machine-gun for low-mobility users; binds `SUPER+ALT+S` to launch the Orca screen reader (the system preset already puts `orca` on PATH). Set to the same value as the system option. Update the bullet in `docs/ROADMAP.md` if a high-contrast palette ships as a `themes/palettes/` entry — it'll be gated on this option.
+`bool`, default `false`. Home-side companion to `nomarchy.system.accessibility.enable`. Three Hyprland-side adjustments: slows `input.repeat_rate` to `25` (default `40`) and `input.repeat_delay` to `1000` ms (from `600`) so holding a key isn't a runaway machine-gun for low-mobility users; binds `SUPER+ALT+S` to launch the Orca screen reader (the system preset already puts `orca` on PATH). Set to the same value as the system option. Update the bullet in `docs/ROADMAP.md` if a high-contrast palette ships as a `themes/palettes/` entry — it'll be gated on this option.
-
-### `nomarchy.vscode.devExtensions`
-
-`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (language servers + git + editor enhancements). The palette theme extensions are *always* installed regardless of this flag — every palette except `ethereal`, `hackerman`, and `vantablack` resolves its `workbench.colorTheme` via either `pkgs.vscode-extensions` (catppuccin/nord/tokyo-night/rose-pine/gruvbox) or `pkgs.vscode-utils.extensionFromVscodeMarketplace` with version + sha256 pinned (sainnhe.everforest, qufiwefefwoyn.kanagawa, monokai.theme-monokai-pro-vscode, oldjobobo.{lumon,miasma,retro-82}, shadesOfBuntu.flexoki-light, jovejonovski.ocean-green, TahaYVR.matteblack, Bjarne.white-theme). The three palettes whose theme extension isn't on the marketplace fall back to VSCode's default theme; see the ROADMAP Later row.
 
 ### `nomarchy.themeLoader.enable`
 

features/apps/alacritty/default.nix

@@ -1,25 +1,27 @@
 { config, pkgs, lib, ... }:
 
 {
-  programs.alacritty = {
+  config = lib.mkIf config.nomarchy.apps.alacritty.enable {
-    enable = lib.mkDefault true;
+    programs.alacritty = {
-    settings = lib.mkDefault {
+      enable = lib.mkDefault true;
-      env = {
+      settings = lib.mkDefault {
-        TERM = "xterm-256color";
+        env = {
-      };
+          TERM = "xterm-256color";
-      terminal = {
+        };
-        osc52 = "CopyPaste";
+        terminal = {
-      };
+          osc52 = "CopyPaste";
-      window = {
+        };
-        padding = { x = 14; y = 14; };
+        window = {
-        decorations = "None";
+          padding = { x = 14; y = 14; };
-      };
+          decorations = "None";
-      keyboard = {
+        };
-        bindings = [
+        keyboard = {
-          { key = "Insert"; mods = "Shift"; action = "Paste"; }
+          bindings = [
-          { key = "Insert"; mods = "Control"; action = "Copy"; }
+            { key = "Insert"; mods = "Shift"; action = "Paste"; }
-          { key = "Return"; mods = "Shift"; chars = "\\u001B\\r"; }
+            { key = "Insert"; mods = "Control"; action = "Copy"; }
-        ];
+            { key = "Return"; mods = "Shift"; chars = "\\u001B\\r"; }
+          ];
+        };
       };
     };
   };

features/apps/btop/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."btop/btop.conf".source = ./config/btop.conf;
+  config = lib.mkIf config.nomarchy.apps.btop.enable {
+    programs.btop.enable = lib.mkDefault true;
+    xdg.configFile."btop/btop.conf".source = ./config/btop.conf;
+  };
 }

features/apps/elephant/default.nix

@@ -1,8 +1,10 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."elephant" = {
+  config = lib.mkIf config.nomarchy.apps.elephant.enable {
-    source = ./config;
+    xdg.configFile."elephant" = {
-    recursive = true;
+      source = ./config;
+      recursive = true;
+    };
   };
 }

features/apps/ghostty/default.nix

@@ -1,5 +1,7 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."ghostty/config".source = ./config/config;
+  config = lib.mkIf config.nomarchy.apps.ghostty.enable {
+    xdg.configFile."ghostty/config".source = ./config/config;
+  };
 }

features/apps/kitty/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."kitty/kitty.conf".source = ./config/kitty.conf;
+  config = lib.mkIf config.nomarchy.apps.kitty.enable {
+    programs.kitty.enable = lib.mkDefault true;
+    xdg.configFile."kitty/kitty.conf".source = ./config/kitty.conf;
+  };
 }

features/apps/lazygit/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."lazygit/config.yml".source = ./config/config.yml;
+  config = lib.mkIf config.nomarchy.apps.lazygit.enable {
+    home.packages = [ pkgs.lazygit ];
+    xdg.configFile."lazygit/config.yml".source = ./config/config.yml;
+  };
 }

features/apps/swayosd.nix

@@ -1,41 +1,43 @@
 { config, pkgs, lib, ... }:
 
 {
-  services.swayosd = {
+  config = lib.mkIf config.nomarchy.apps.swayosd.enable {
-    enable = lib.mkDefault true;
+    services.swayosd = {
-    stylePath = lib.mkDefault "${config.home.homeDirectory}/.config/swayosd/style.css";
+      enable = lib.mkDefault true;
+      stylePath = lib.mkDefault "${config.home.homeDirectory}/.config/swayosd/style.css";
+    };
+
+    xdg.configFile."swayosd/style.css".text = lib.mkDefault ''
+      @define-color background-color #${config.colorScheme.palette.base00};
+      @define-color border-color #${config.colorScheme.palette.base0E};
+      @define-color label #${config.colorScheme.palette.base05};
+      @define-color image #${config.colorScheme.palette.base05};
+      @define-color progress #${config.colorScheme.palette.base0B};
+
+      window {
+        border-radius: 0;
+        opacity: 0.97;
+        border: 2px solid @border-color;
+        background-color: @background-color;
+      }
+
+      label {
+        font-family: '${config.nomarchy.fonts.monospace}';
+        font-size: 11pt;
+        color: @label;
+      }
+
+      image {
+        color: @image;
+      }
+
+      progressbar {
+        border-radius: 0;
+      }
+
+      progress {
+        background-color: @progress;
+      }
+    '';
   };
-
-  xdg.configFile."swayosd/style.css".text = lib.mkDefault ''
-    @define-color background-color #${config.colorScheme.palette.base00};
-    @define-color border-color #${config.colorScheme.palette.base0E};
-    @define-color label #${config.colorScheme.palette.base05};
-    @define-color image #${config.colorScheme.palette.base05};
-    @define-color progress #${config.colorScheme.palette.base0B};
-
-    window {
-      border-radius: 0;
-      opacity: 0.97;
-      border: 2px solid @border-color;
-      background-color: @background-color;
-    }
-
-    label {
-      font-family: '${config.nomarchy.fonts.monospace}';
-      font-size: 11pt;
-      color: @label;
-    }
-
-    image {
-      color: @image;
-    }
-
-    progressbar {
-      border-radius: 0;
-    }
-
-    progress {
-      background-color: @progress;
-    }
-  '';
 }

features/apps/tmux/default.nix

@@ -1,5 +1,8 @@
 { config, pkgs, lib, ... }:
 
 {
-  xdg.configFile."tmux/tmux.conf".source = ./config/tmux.conf;
+  config = lib.mkIf config.nomarchy.apps.tmux.enable {
+    programs.tmux.enable = lib.mkDefault true;
+    xdg.configFile."tmux/tmux.conf".source = ./config/tmux.conf;
+  };
 }

features/apps/vscode.nix

@@ -96,15 +96,7 @@ let
   ];
 in
 {
-  options.nomarchy.vscode = {
+  config = lib.mkIf config.nomarchy.apps.vscode.enable {
-    devExtensions = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      description = "Whether to install development extensions for VSCode.";
-    };
-  };
-
-  config = {
     programs.vscode = {
       enable = lib.mkDefault true;
       package = lib.mkDefault pkgs.vscode;
@@ -118,7 +110,7 @@ in
         };
         extensions = lib.mkDefault (
           themeExtensions
-          ++ lib.optionals config.nomarchy.vscode.devExtensions devExtensions
+          ++ lib.optionals config.nomarchy.apps.vscode.devExtensions devExtensions
         );
       };
     };

features/apps/walker.nix

@@ -1,49 +1,51 @@
 { config, pkgs, lib, ... }:
 
 {
-  home.packages = [ pkgs.lua ];
+  config = lib.mkIf config.nomarchy.apps.walker.enable {
+    home.packages = [ pkgs.lua ];
 
-  programs.walker = {
+    programs.walker = {
-    enable = lib.mkDefault true;
+      enable = lib.mkDefault true;
-    runAsService = lib.mkDefault true;
+      runAsService = lib.mkDefault true;
-    config = lib.mkDefault {
+      config = lib.mkDefault {
-      theme = "nomarchy";
+        theme = "nomarchy";
-      ui = {
+        ui = {
-        anchors = {
+          anchors = {
-          top = true;
+            top = true;
+          };
+        };
+        selection_wrap = true;
+        hide_action_hints = true;
+        placeholders = {
+          "default" = { input = " Search..."; list = "No Results"; };
+        };
+        keybinds = {
+          quick_activate = [];
+        };
+        columns = {
+          symbols = 1;
+        };
+        providers = {
+          max_results = 256;
+          default = [
+            "desktopapplications"
+            "websearch"
+          ];
+          prefixes = [
+            { prefix = "/"; provider = "providerlist"; }
+            { prefix = "."; provider = "files"; }
+            { prefix = ":"; provider = "symbols"; }
+            { prefix = "="; provider = "calc"; }
+            { prefix = "@"; provider = "websearch"; }
+            { prefix = "$"; provider = "clipboard"; }
+          ];
         };
       };
-      selection_wrap = true;
+      themes."nomarchy" = lib.mkDefault {
-      hide_action_hints = true;
+        style = ''
-      placeholders = {
+          @import "${config.home.homeDirectory}/.config/nomarchy/current/theme/apps/walker/style.css";
-        "default" = { input = " Search..."; list = "No Results"; };
+        '';
       };
-      keybinds = {
-        quick_activate = [];
-      };
-      columns = {
-        symbols = 1;
-      };
-      providers = {
-        max_results = 256;
-        default = [
-          "desktopapplications"
-          "websearch"
-        ];
-        prefixes = [
-          { prefix = "/"; provider = "providerlist"; }
-          { prefix = "."; provider = "files"; }
-          { prefix = ":"; provider = "symbols"; }
-          { prefix = "="; provider = "calc"; }
-          { prefix = "@"; provider = "websearch"; }
-          { prefix = "$"; provider = "clipboard"; }
-        ];
-      };
-    };
-    themes."nomarchy" = lib.mkDefault {
-      style = ''
-        @import "${config.home.homeDirectory}/.config/nomarchy/current/theme/apps/walker/style.css";
-      '';
     };
   };
 }

features/default.nix

@@ -44,14 +44,6 @@ in
   # the installer's profile packages), silently removing firefox, mako,
   # hyprlock, mpv, etc. — which broke notifications and the lock screen.
   home.packages = (with pkgs; [
-    # Core applications
-    firefox
-    xfce.thunar
-
-    # Media
-    imv              # Image viewer
-    mpv              # Video player
-
     # Hyprland ecosystem
     swww             # Wallpaper daemon
     mako             # Notification daemon

flake.nix

@@ -88,6 +88,25 @@
       modules = [{
         nomarchy.theme = lib.mkForce themeName;
         nomarchy.wallpaper = lib.mkForce "";
+        nomarchy.apps = {
+          alacritty.enable = true;
+          btop.enable = true;
+          elephant.enable = true;
+          swayosd.enable = true;
+          walker.enable = true;
+          vscode.enable = true;
+          kitty.enable = true;
+          lazygit.enable = true;
+          tmux.enable = true;
+        };
+        home.packages = with pkgs; [
+          firefox
+          xfce.thunar
+          imv
+          mpv
+          fastfetch
+          chromium
+        ];
       }];
     }).activationPackage;
     allThemeVariants = pkgs.linkFarm "nomarchy-all-theme-variants"
@@ -169,6 +188,25 @@
             home-manager.users.nixos = {
               imports = [ ./features ];
               home.stateVersion = "25.11";
+              nomarchy.apps = {
+                alacritty.enable = true;
+                btop.enable = true;
+                elephant.enable = true;
+                swayosd.enable = true;
+                walker.enable = true;
+                vscode.enable = true;
+                kitty.enable = true;
+                lazygit.enable = true;
+                tmux.enable = true;
+              };
+              home.packages = with pkgs; [
+                firefox
+                xfce.thunar
+                imv
+                mpv
+                fastfetch
+                chromium
+              ];
 
               # Live-ISO-only welcome. Pops a notification a few seconds
               # after the graphical session is up and opens a terminal
@@ -221,6 +259,25 @@
             home-manager.users.nomarchy = {
               imports = [ ./features ];
               home.stateVersion = "25.11";
+              nomarchy.apps = {
+                alacritty.enable = true;
+                btop.enable = true;
+                elephant.enable = true;
+                swayosd.enable = true;
+                walker.enable = true;
+                vscode.enable = true;
+                kitty.enable = true;
+                lazygit.enable = true;
+                tmux.enable = true;
+              };
+              home.packages = with pkgs; [
+                firefox
+                xfce.thunar
+                imv
+                mpv
+                fastfetch
+                chromium
+              ];
             };
           }
         ];

installer/install.sh

@@ -1729,13 +1729,16 @@ EOF
 
   # User-level packages (Home Manager).
   #
-  # Nomarchy already ships a minimal desktop (firefox, thunar, mpv, imv, mako,
+  # Nomarchy already ships the core Hyprland ecosystem (mako, hyprlock, swww,
-  # hyprlock, swww, wl-clipboard, grim, slurp, rofi-wayland, etc.). The list
+  # wl-clipboard, grim, slurp, rofi, etc.). The list below includes the
-  # below is a menu of extras — uncomment what you want and run
+  # default user apps and a menu of extras — uncomment what you want and
-  # \`nomarchy-env-update\`.
+  # run \`nomarchy-env-update\`.
   home.packages = with pkgs; [
     # --- Enabled by default ---
-    btop                # Resource monitor (TUI)
+    firefox
+    xfce.thunar
+    imv                 # Image viewer
+    mpv                 # Video player
     fastfetch           # System info at login
     chromium            # Secondary browser
     $PROFILE_HOME_PACKAGES
@@ -1797,12 +1800,32 @@ EOF
     # tldr
   ];
 
-  # --- Optional Nomarchy app modules ---
+  # --- Nomarchy app modules ---
 
-  # opencode AI coding CLI integration (deploys ~/.config/opencode/opencode.json).
+  # These enable Nomarchy's curated configurations for the respective apps.
-  # The \`opencode\` package itself is not installed automatically — add it to
+  # Most are enabled by default to give you a complete desktop experience.
-  # \`home.packages\` above if you want it on PATH.
+  # Enabling the module also installs the corresponding package.
-  # nomarchy.apps.opencode.enable = true;
+  nomarchy.apps = {
+    alacritty.enable = true;
+    btop.enable = true;
+    elephant.enable = true;
+    swayosd.enable = true;
+    walker.enable = true;
+    vscode.enable = true;
+    kitty.enable = true;
+    lazygit.enable = true;
+    tmux.enable = true;
+
+    # opencode AI coding CLI integration (deploys ~/.config/opencode/opencode.json).
+    # The \`opencode\` package itself is not installed automatically — add it to
+    # \`home.packages\` above if you want it on PATH.
+    # opencode.enable = true;
+
+    # Deploys themed config if you install the package (Ghostty is not in nixpkgs)
+    # ghostty.enable = true;
+  };
+
+  # --- Optional Nomarchy app modules ---
 
   # Extra Home Manager modules go here (program configs, services, etc.).
 }