feat(modules): core option system and shared lib helpers

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

modules/README.md

@@ -0,0 +1,295 @@
+# Modules Directory
+
+The `modules/` directory contains the modular NixOS configuration system that makes up Omnixient. Each module is responsible for a specific aspect of the system and can be enabled, disabled, or configured independently.
+
+## Module Architecture
+
+Each module follows the standard NixOS module structure:
+```nix
+{ config, lib, pkgs, ... }:
+with lib;
+{
+  options = {
+    # Configuration options for this module
+  };
+
+  config = mkIf cfg.enable {
+    # Module implementation
+  };
+}
+```
+
+## Core System Modules
+
+### `core.nix`
+**Purpose**: Base system settings and Omnixient-specific options
+**What it configures**:
+- Essential system services (NetworkManager, Bluetooth, Audio)
+- Graphics support (OpenGL/Vulkan)
+- Font management
+- Basic security settings
+- Omnixient module system foundations
+
+**Key Features**:
+- Automatic hardware graphics detection
+- Unified font configuration across the system
+- Essential service enablement
+- Module option definitions
+
+### `packages.nix`
+**Purpose**: The always-installed **base** package set + fonts
+**What it manages**:
+- Core utilities, file/network/archive tools, system monitoring
+- Text processing, version control, shells, Nix tooling
+- System + programming + icon fonts
+
+> The optional category bundles (development, multimedia, productivity,
+> gaming) that used to live here have moved into **opt-in packs** under
+> [`modules/packs/`](packs/README.md) — see the
+> [**Opt-in packs**](#opt-in-packs) section below and
+> [`docs/packs.md`](../docs/packs.md). `packages.nix` now carries only the
+> base set everyone gets.
+
+### `services.nix`
+**Purpose**: System service configuration and management
+**What it configures**:
+- Display manager (GDM)
+- Audio system (PipeWire)
+- Network services
+- Container services (Docker, Podman)
+- Development services (databases, etc.)
+
+**Service Categories**:
+- Desktop services (compositor, display manager)
+- Audio/media services
+- Network and connectivity
+- Development and container services
+
+### `users.nix`
+**Purpose**: User account management and configuration
+**What it manages**:
+- User account creation and settings
+- Shell configuration defaults
+- User group memberships
+- Home directory setup
+
+**Features**:
+- Automatic user creation based on configuration
+- Shell preferences (zsh as default)
+- Group membership for hardware access
+- Integration with home-manager
+
+## Security and System
+
+### `security.nix`
+**Purpose**: Security settings and authentication methods
+**What it configures**:
+- Multi-factor authentication
+- Fingerprint support (fprintd)
+- FIDO2 security keys
+- System hardening options
+- Firewall configuration
+
+**Authentication Methods**:
+- Password authentication
+- Fingerprint recognition
+- FIDO2/WebAuthn security keys
+- Two-factor authentication
+
+### `boot.nix`
+**Purpose**: Boot system and kernel configuration
+**What it manages**:
+- Boot loader configuration (systemd-boot)
+- Kernel parameters and modules
+- Plymouth boot theme
+- Early boot optimizations
+
+**Boot Features**:
+- Fast boot configuration
+- Kernel optimization
+- Boot splash screen
+- Hardware initialization
+
+## User Interface
+
+### `menus.nix`
+**Purpose**: Application menus and launchers
+**What it configures**:
+- Application launchers (rofi alternatives)
+- Desktop menu systems
+- Quick access interfaces
+- Search functionality
+
+### `walker.nix`
+**Purpose**: Walker application launcher configuration
+**What it manages**:
+- Walker launcher settings
+- Search backends and plugins
+- Keybindings and interface
+- Theme integration
+
+### `fastfetch.nix`
+**Purpose**: System information display tool
+**What it configures**:
+- System info formatting
+- Logo and branding display
+- Performance metrics
+- Terminal integration
+
+## Development Environment
+
+### `development.nix`
+**Purpose**: The richer dev module (shells, dev services, helper scripts)
+**What it provides**:
+- Multiple language support (Rust, Go, Python, Node.js, C/C++)
+- Language servers and tools
+- Development containers and databases
+
+> Now **gated on `omni.packs.development.enable`** (not `features.coding`)
+> and part of the *development pack* — see
+> [**Opt-in packs**](#opt-in-packs). Imported by hosts via the pack, not by
+> the ISO.
+
+**Language Support**:
+- Runtime environments
+- Package managers
+- Language-specific tools
+- IDE and editor integration
+
+### `scripts.nix`
+**Purpose**: Omnixient utility script management
+**What it manages**:
+- System management scripts
+- Theme switching utilities
+- Development helper scripts
+- Unix philosophy tools
+
+## Opt-in Packs
+
+The `packs/` subdirectory implements the **core + opt-in goodies** model:
+bundles of (packages + services + config) toggled with
+`omni.packs.<name>.enable`, always imported but inert until enabled.
+Packs are exposed as reusable `flake.nixosModules.<pack>` outputs, and the
+`lnbits` / `aiolabs` / `bitcoin` packs are standalone-importable onto a
+non-Omnixient NixOS.
+
+| Pack | Provides |
+|---|---|
+| `media` | players, image/video editing, screen capture, PDF |
+| `development` | editors, LSPs, compilers, build tools, container CLIs, `development.nix` |
+| `gaming` | Steam, Lutris, Wine, performance tools |
+| `office` | browsers, comms, office suites, notes, backup |
+| `containers` | Docker + Podman (unified) |
+| `lnbits` | the LNbits dev environment (`dev-env`) |
+| `aiolabs` | aiolabs projects/deploy/tmux, on top of `lnbits` |
+| `bitcoin` | a real bitcoind + lightning node via nix-bitcoin (opt-in import) |
+
+Legacy `omni.preset` / `omni.features.*` still work — they drive packs
+via `packs/compat.nix`. Full guide:
+[`modules/packs/README.md`](packs/README.md) and
+[`docs/packs.md`](../docs/packs.md).
+
+## Hardware Support
+
+The `hardware/` subdirectory contains hardware-specific modules:
+
+### `default.nix`
+**Purpose**: Hardware detection and automatic configuration
+**What it does**:
+- Detects available hardware
+- Enables appropriate drivers
+- Configures hardware-specific settings
+- Imports relevant hardware modules
+
+### GPU Support
+- `amd.nix`: AMD GPU drivers and configuration
+- `intel.nix`: Intel integrated graphics
+- `nvidia.nix`: NVIDIA proprietary drivers
+
+### Audio and Input
+- `audio.nix`: Audio system configuration
+- `touchpad.nix`: Laptop touchpad settings
+- `bluetooth.nix`: Bluetooth device support
+
+## Theme System
+
+The `themes/` subdirectory contains complete theme definitions:
+
+Each theme module (e.g., `tokyo-night.nix`) configures:
+- Color palette definitions
+- Terminal color schemes
+- Editor themes (Neovim, VSCode)
+- Desktop component theming (Waybar, Hyprland)
+- GTK/Qt application themes
+
+## Desktop Environment
+
+The `desktop/` subdirectory contains desktop-specific configurations:
+
+### `hyprland.nix`
+**Purpose**: Hyprland compositor configuration
+**Sub-modules**:
+- `bindings.nix`: Keyboard shortcuts and bindings
+- `autostart.nix`: Applications started with the desktop
+- `idle.nix`: Idle management and screen locking
+
+## Utility Modules
+
+### `lib.nix`
+**Purpose**: Shared library functions and utilities
+**What it provides**:
+- Helper functions used across modules
+- Common configuration patterns
+- Utility functions for theme and configuration management
+
+### `colors.nix`
+**Purpose**: Color management and palette definitions
+**What it manages**:
+- Color space conversions
+- Palette generation utilities
+- Theme color validation
+
+### `helpers.nix`
+**Purpose**: Additional helper functions
+**What it provides**:
+- File and directory utilities
+- Configuration templating functions
+- System integration helpers
+
+## Module Dependencies
+
+```
+core.nix (foundation)
+    ↓
+packages.nix + services.nix (system layer)
+    ↓
+security.nix + boot.nix (system hardening)
+    ↓
+themes/*.nix (visual layer)
+    ↓
+desktop/*.nix (user interface)
+    ↓
+development.nix (developer tools)
+```
+
+## Adding New Modules
+
+To add a new module:
+
+1. Create the module file in the appropriate subdirectory
+2. Follow the standard NixOS module structure
+3. Define clear options with types and descriptions
+4. Import the module in `configuration.nix`
+5. Document the module's purpose and options
+6. Test the module in isolation and with others
+
+## Module Best Practices
+
+1. **Single Responsibility**: Each module handles one aspect
+2. **Clear Options**: Well-defined configuration interface
+3. **Documentation**: Comments and option descriptions
+4. **Dependencies**: Explicit module dependencies
+5. **Testing**: Verify module works in isolation
+6. **Performance**: Efficient evaluation and build times
+
+This modular architecture makes Omnixient highly customizable while maintaining clean separation of concerns.

modules/core.nix

@@ -0,0 +1,390 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+let
+  inherit (lib)
+    mkEnableOption
+    mkOption
+    mkIf
+    mkMerge
+    mkDefault
+    types
+    ;
+  cfg = config.omni;
+in
+{
+  options.omni = {
+    enable = mkEnableOption "Omnixient system configuration";
+
+    # User Configuration
+    user = mkOption {
+      type = types.str;
+      default = "user";
+      description = "Primary user for the system";
+      example = "john";
+    };
+
+    # Theme Configuration
+    theme = mkOption {
+      type = types.enum [
+        "tokyo-night"
+        "catppuccin"
+        "gruvbox"
+        "nord"
+        "everforest"
+        "rose-pine"
+        "kanagawa"
+      ];
+      default = "tokyo-night";
+      description = "System theme - changes colors, wallpaper, and overall look";
+      example = "catppuccin";
+    };
+
+    # User-friendly theme aliases
+    darkMode = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Use dark theme variant when available";
+    };
+
+    displayManager = mkOption {
+      type = types.enum [
+        "gdm"
+        "tuigreet"
+      ];
+      default = "tuigreet";
+      description = "Display manager to use for login";
+    };
+
+    colorScheme = mkOption {
+      type = types.nullOr types.attrs;
+      default = null;
+      description = "Color scheme from nix-colors. If null, uses theme-specific colors.";
+      example = "inputs.nix-colors.colorSchemes.tokyo-night-dark";
+    };
+
+    wallpaper = mkOption {
+      type = types.nullOr types.path;
+      default = null;
+      description = "Path to wallpaper for automatic color generation";
+    };
+
+    # Feature Categories - Simple on/off switches for major functionality
+    features = {
+      # Development
+      coding = mkEnableOption "Development tools, editors, and programming languages";
+      containers = mkEnableOption "Docker and container support";
+
+      # Entertainment
+      gaming = mkEnableOption "Gaming support with Steam, Wine, and performance tools";
+      media = mkEnableOption "Video players, image viewers, and media editing tools";
+
+      # Productivity
+      office = mkEnableOption "Office suite, PDF viewers, and productivity apps";
+      communication = mkEnableOption "Chat apps, email clients, and video conferencing";
+
+      # System
+      virtualization = mkEnableOption "VM support (VirtualBox, QEMU, etc.)";
+      backup = mkEnableOption "Backup tools and cloud sync applications";
+
+      # Appearance
+      customThemes = mkEnableOption "Advanced theming with nix-colors integration";
+      wallpaperEffects = mkEnableOption "Dynamic wallpapers and color generation";
+    };
+
+    # Simple Presets - Predefined feature combinations
+    preset = mkOption {
+      type = types.nullOr (
+        types.enum [
+          "minimal"
+          "developer"
+          "creator"
+          "gamer"
+          "office"
+          "everything"
+        ]
+      );
+      default = null;
+      description = ''
+        Quick setup preset that automatically enables related features:
+        - minimal: Just the basics (browser, terminal, file manager)
+        - developer: Coding tools, containers, git, IDEs
+        - creator: Media editing, design tools, content creation
+        - gamer: Gaming support, performance tools, Discord
+        - office: Productivity apps, office suite, communication
+        - everything: All features enabled
+      '';
+      example = "developer";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Apply preset configurations automatically
+    omni.features = mkMerge [
+      # Default features based on preset
+      (mkIf (cfg.preset == "minimal") {
+        # Only basic features
+      })
+      (mkIf (cfg.preset == "developer") {
+        coding = mkDefault true;
+        containers = mkDefault true;
+        customThemes = mkDefault true;
+        media = mkDefault true;
+        communication = mkDefault true;
+      })
+      (mkIf (cfg.preset == "creator") {
+        media = mkDefault true;
+        office = mkDefault true;
+        customThemes = mkDefault true;
+        wallpaperEffects = mkDefault true;
+      })
+      (mkIf (cfg.preset == "gamer") {
+        gaming = mkDefault true;
+        media = mkDefault true;
+        communication = mkDefault true;
+      })
+      (mkIf (cfg.preset == "office") {
+        office = mkDefault true;
+        communication = mkDefault true;
+        backup = mkDefault true;
+      })
+      (mkIf (cfg.preset == "everything") {
+        coding = mkDefault true;
+        containers = mkDefault true;
+        gaming = mkDefault true;
+        media = mkDefault true;
+        office = mkDefault true;
+        communication = mkDefault true;
+        virtualization = mkDefault true;
+        backup = mkDefault true;
+        customThemes = mkDefault true;
+        wallpaperEffects = mkDefault true;
+      })
+    ];
+
+    # Basic system configuration
+    system.autoUpgrade = {
+      enable = true;
+      flake = "/etc/nixos#omni";
+      flags = [
+        "--update-input"
+        "nixpkgs"
+        "--commit-lock-file"
+      ];
+      dates = "weekly";
+    };
+
+    # Enable documentation
+    documentation = {
+      enable = true;
+      man.enable = true;
+    };
+
+    # Security settings
+    security.sudo = {
+      enable = true;
+      wheelNeedsPassword = true;
+      extraRules = [
+        {
+          groups = [ "wheel" ];
+          commands = [
+            {
+              command = "/run/current-system/sw/bin/nixos-rebuild";
+              options = [ "NOPASSWD" ];
+            }
+          ];
+        }
+      ];
+    };
+
+    # Services, hardware, bluetooth, graphics, polkit, openssh, fstrim,
+    # thermald, power-profiles, avahi, smartd are all in:
+    #   modules/services.nix and modules/hardware/
+
+    # Programs configuration
+    programs = {
+      # nh — Rust frontend for nixos-rebuild used by omni-rebuild.
+      # Sets $NH_FLAKE / $FLAKE so `nh os switch` (and `nh home switch`)
+      # resolve the right flake without an explicit path.
+      nh = {
+        enable = true;
+        flake = "/etc/nixos";
+      };
+
+    };
+
+    # Environment variables
+    environment.variables = {
+      EDITOR = "nvim";
+      VISUAL = "nvim";
+      BROWSER = "chromium";
+      TERM = "xterm-256color";
+
+      # Development
+      CARGO_HOME = "$HOME/.cargo";
+      GOPATH = "$HOME/go";
+      NPM_CONFIG_PREFIX = "$HOME/.npm";
+
+      # Omnixient specific
+      OMNI_ROOT = "/etc/nixos";
+      OMNI_VERSION = "1.0.0";
+    };
+
+    # Shell configuration
+    programs.bash = {
+      interactiveShellInit = ''
+        # Omnixient bash initialization
+        export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$HOME/go/bin:$HOME/.npm/bin:$PATH"
+
+        # Aliases
+        alias ll='eza -la'
+        alias ls='eza'
+        alias cat='bat'
+        alias grep='rg'
+        alias find='fd'
+        alias vim='nvim'
+        alias vi='nvim'
+        alias n='nvim'
+
+        # Omnixient specific aliases (omni-rebuild is a script, not an alias)
+        alias omni-update='nix flake update --flake /etc/nixos'
+        alias omni-clean='sudo nix-collect-garbage -d'
+        alias omni-search='nix search nixpkgs'
+
+        # Functions
+        omni-theme() {
+          local theme=$1
+          if [ -z "$theme" ]; then
+            echo "Available themes: tokyo-night, catppuccin, catppuccin-latte, gruvbox, nord, everforest, rose-pine, kanagawa, matte-black, osaka-jade, ristretto"
+            return 1
+          fi
+
+          echo "Switching to theme: $theme"
+          # This would need to update the configuration and rebuild
+          sudo sed -i "s/currentTheme = \".*\"/currentTheme = \"$theme\"/" /etc/nixos/configuration.nix
+          omni-rebuild
+        }
+
+        omni-help() {
+          cat << EOF
+        Omnixient Commands:
+        ===============
+        omni-rebuild  - Rebuild system configuration
+        omni-update   - Update flake inputs
+        omni-clean    - Garbage collect nix store
+        omni-search   - Search for packages
+        omni-theme    - Change system theme
+        omni-help     - Show this help message
+
+        Key Bindings (Hyprland):
+        =======================
+        Super + Return   - Open terminal
+        Super + B        - Open browser
+        Super + E        - Open file manager
+        Super + D        - Application launcher
+        Super + Q        - Close window
+        Super + F        - Fullscreen
+        Super + Space    - Toggle floating
+
+        For more information, visit: https://github.com/TheArctesian/omnixy
+        EOF
+        }
+
+        # Welcome message
+        if [ -z "$IN_NIX_SHELL" ]; then
+          echo "Welcome to Omnixient! Type 'omni-help' for available commands."
+        fi
+      '';
+
+      promptInit = ''
+        # Starship prompt
+        if command -v starship &> /dev/null; then
+          eval "$(starship init bash)"
+        fi
+
+        # try — experiment directory manager
+        if command -v try &> /dev/null; then
+          eval "$(try init ~/Work/tries)"
+        fi
+      '';
+    };
+
+    # System-wide packages
+    environment.systemPackages =
+      with pkgs;
+      [
+        # Core utilities
+        coreutils
+        findutils
+        gnugrep
+        gnused
+        gawk
+
+        # System tools
+        htop
+        fastfetch
+        tree
+        wget
+        curl
+
+        # Text editors
+        vim
+        nano
+
+        # Version control (always needed, even on minimal/ISO)
+        git
+
+        # Experiment directory manager (tobi/try)
+        ruby
+        (pkgs.callPackage ../packages/try-cli.nix { })
+
+        # Nix tools
+        nix-prefetch-git
+        nixfmt
+        nil
+
+        # Custom Omnixient scripts
+        (writeShellScriptBin "omni-info" ''
+          #!/usr/bin/env bash
+          echo "🌟 Omnixient NixOS Configuration"
+          echo "============================="
+          echo ""
+          echo "📋 Basic Settings:"
+          echo "   User: ${cfg.user}"
+          echo "   Theme: ${cfg.theme}"
+          echo "   Preset: ${if cfg.preset != null then cfg.preset else "custom"}"
+          echo "   Display Manager: ${cfg.displayManager}"
+          echo ""
+          echo "🎯 Active Features:"
+          echo "   Development: ${if cfg.features.coding or false then "✅" else "❌"}"
+          echo "   Containers: ${if cfg.features.containers or false then "✅" else "❌"}"
+          echo "   Gaming: ${if cfg.features.gaming or false then "✅" else "❌"}"
+          echo "   Media: ${if cfg.features.media or false then "✅" else "❌"}"
+          echo "   Office: ${if cfg.features.office or false then "✅" else "❌"}"
+          echo "   Communication: ${if cfg.features.communication or false then "✅" else "❌"}"
+          echo "   Virtualization: ${if cfg.features.virtualization or false then "✅" else "❌"}"
+          echo "   Backup: ${if cfg.features.backup or false then "✅" else "❌"}"
+          echo ""
+          echo "🎨 Theming:"
+          echo "   Custom Themes: ${if cfg.features.customThemes or false then "✅" else "❌"}"
+          echo "   Wallpaper Effects: ${if cfg.features.wallpaperEffects or false then "✅" else "❌"}"
+          echo "   Color Scheme: ${if cfg.colorScheme != null then "Custom" else "Theme-based"}"
+          echo "   Wallpaper: ${if cfg.wallpaper != null then toString cfg.wallpaper else "Not set"}"
+          echo ""
+          echo "💡 Quick Commands:"
+          echo "   omni-setup-colors  - Configure colors and themes"
+          echo "   omni-rebuild       - Rebuild system configuration"
+          echo "   omni-help          - Show keyboard shortcuts and help"
+          echo ""
+          echo "📊 System Information:"
+          nixos-version --json | ${pkgs.jq}/bin/jq -r '"   NixOS: " + .nixosVersion'
+          echo "   Kernel: $(uname -r)"
+          echo "   Uptime: $(uptime -p)"
+        '')
+      ];
+  };
+}

modules/lib.nix

@@ -0,0 +1,202 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+# Shared library module for Omnixient
+# Exposes helpers via config.omni.lib for use by all other modules.
+# This replaces the old import-based helpers.nix pattern.
+
+let
+  inherit (lib)
+    mkIf
+    mkOption
+    types
+    concatStringsSep
+    mapAttrsToList
+    ;
+  cfg = config.omni;
+
+  helpers = {
+    # Check if a feature is enabled
+    isEnabled = feature: cfg.features.${feature} or false;
+
+    # User-specific paths
+    userPath = path: "/home/${cfg.user}/${path}";
+    configPath = path: "/home/${cfg.user}/.config/${path}";
+    cachePath = path: "/home/${cfg.user}/.cache/${path}";
+
+    # Color helper: use nix-colors if available, otherwise fallback
+    getColor =
+      colorName: fallback:
+      if cfg.colorScheme != null && cfg.colorScheme ? colors && cfg.colorScheme.colors ? ${colorName} then
+        "#${cfg.colorScheme.colors.${colorName}}"
+      else
+        fallback;
+
+    # Feature-based conditional inclusion
+    withFeature = feature: content: mkIf (helpers.isEnabled feature) content;
+    withoutFeature = feature: content: mkIf (!(helpers.isEnabled feature)) content;
+
+    # User-specific home-manager configuration
+    forUser = userConfig: {
+      home-manager.users.${cfg.user} = userConfig;
+    };
+
+    # Package filtering with exclusion support
+    filterPackages =
+      packages:
+      builtins.filter (
+        pkg:
+        let
+          name = pkg.name or pkg.pname or "unknown";
+        in
+        !(builtins.elem name (cfg.packages.exclude or [ ]))
+      ) packages;
+
+    # Create a script with set -euo pipefail
+    makeScript =
+      name: description: script:
+      pkgs.writeShellScriptBin name ''
+        #!/usr/bin/env bash
+        # ${description}
+        set -euo pipefail
+        ${script}
+      '';
+
+    # Standard paths
+    paths = {
+      config = "/etc/nixos";
+      logs = "/var/log/omni";
+      cache = "/var/cache/omni";
+      runtime = "/run/omni";
+    };
+
+    # Default color palette (Tokyo Night)
+    colors = {
+      bg = "#1a1b26";
+      bgAlt = "#16161e";
+      bgAccent = "#2f3549";
+      fg = "#c0caf5";
+      fgAlt = "#9aa5ce";
+      fgDim = "#545c7e";
+      red = "#f7768e";
+      orange = "#ff9e64";
+      yellow = "#e0af68";
+      green = "#9ece6a";
+      cyan = "#7dcfff";
+      blue = "#7aa2f7";
+      purple = "#bb9af7";
+      brown = "#db4b4b";
+    };
+
+    # Systemd service helpers
+    service = {
+      make = name: serviceConfig: {
+        description = serviceConfig.description or "Omnixient ${name} service";
+        wantedBy = serviceConfig.wantedBy or [ "multi-user.target" ];
+        after = serviceConfig.after or [ "network.target" ];
+        serviceConfig = {
+          Type = serviceConfig.type or "simple";
+          User = serviceConfig.user or cfg.user;
+          Group = serviceConfig.group or "users";
+          Restart = serviceConfig.restart or "on-failure";
+          RestartSec = serviceConfig.restartSec or "5";
+        }
+        // (serviceConfig.serviceConfig or { });
+      };
+
+      user = name: serviceConfig: {
+        home-manager.users.${cfg.user}.systemd.user.services.${name} = {
+          description = serviceConfig.description or "Omnixient ${name} user service";
+          wantedBy = [ "default.target" ];
+          after = [ "graphical-session.target" ];
+          serviceConfig = {
+            Type = serviceConfig.type or "simple";
+            Restart = serviceConfig.restart or "on-failure";
+            RestartSec = serviceConfig.restartSec or "5";
+          }
+          // (serviceConfig.serviceConfig or { });
+        };
+      };
+    };
+  };
+
+in
+{
+  # Expose helpers to all modules via config.omni.lib
+  options.omni.lib = mkOption {
+    type = types.attrs;
+    internal = true;
+    description = "Omnixient shared helper functions (internal)";
+  };
+
+  config = {
+    omni.lib = helpers;
+
+    # Ensure required directories exist
+    systemd.tmpfiles.rules = [
+      "d ${helpers.paths.logs} 0755 root root -"
+      "d ${helpers.paths.cache} 0755 root root -"
+      "d ${helpers.paths.runtime} 0755 root root -"
+      "d ${helpers.userPath ".local/bin"} 0755 ${cfg.user} users -"
+      "d ${helpers.userPath ".local/share/omni"} 0755 ${cfg.user} users -"
+    ];
+
+    environment.variables = {
+      OMNI_USER = cfg.user;
+      OMNI_THEME = cfg.theme;
+      OMNI_PRESET = cfg.preset or "custom";
+      OMNI_CONFIG_DIR = helpers.paths.config;
+      OMNI_CACHE_DIR = helpers.paths.cache;
+    };
+
+    programs.bash.shellAliases = {
+      # omni-rebuild is a script (packages/scripts.nix), not an alias
+      omni-build = "sudo nixos-rebuild build --flake ${helpers.paths.config}#omni";
+      omni-test = "sudo nixos-rebuild test --flake ${helpers.paths.config}#omni";
+      omni-update = "cd ${helpers.paths.config} && sudo nix flake update";
+      omni-clean = "sudo nix-collect-garbage -d && nix-collect-garbage -d";
+      omni-generations = "sudo nix-env --list-generations --profile /nix/var/nix/profiles/system";
+      omni-status = "omni-info";
+      omni-features = "echo 'Enabled features:' && omni-info | grep -A 10 'Active Features'";
+      omni-config = "cd ${helpers.paths.config}";
+      omni-logs = "cd ${helpers.paths.logs}";
+    };
+
+    environment.systemPackages = [
+      (helpers.makeScript "omni-lib-test" "Test Omnixient library functions" ''
+        echo "Omnixient Library Test"
+        echo "===================="
+        echo ""
+        echo "Configuration:"
+        echo "  User: ${cfg.user}"
+        echo "  Theme: ${cfg.theme}"
+        echo "  Preset: ${cfg.preset or "none"}"
+        echo ""
+        echo "Colors (base16 scheme):"
+        echo "  Background: ${helpers.colors.bg}"
+        echo "  Foreground: ${helpers.colors.fg}"
+        echo "  Primary: ${helpers.colors.blue}"
+        echo "  Success: ${helpers.colors.green}"
+        echo "  Warning: ${helpers.colors.yellow}"
+        echo "  Error: ${helpers.colors.red}"
+        echo ""
+        echo "Paths:"
+        echo "  Config: ${helpers.paths.config}"
+        echo "  Logs: ${helpers.paths.logs}"
+        echo "  Cache: ${helpers.paths.cache}"
+        echo "  User home: ${helpers.userPath ""}"
+        echo ""
+        echo "Features:"
+        ${concatStringsSep "\n" (
+          mapAttrsToList (
+            name: enabled: ''echo "  ${name}: ${if enabled then "enabled" else "disabled"}"''
+          ) cfg.features
+        )}
+      '')
+    ];
+  };
+}