NixOS/docs/playbooks/split-home-manager.md

Playbook: Split a Mixed Module into NixOS and Home Manager

• Name: Split a feature module into nixos.nix and home.nix
• Purpose: Keep category-first organization while separating system concerns from Home Manager concerns for standalone homes and future Darwin usage.
• Prerequisites: Identify the feature path, current toggle shape under my.*, and whether the module has shared helpers that should stay adjacent or move into a factory.
• Inputs: Existing mixed module path, target category/name, host toggle impact, Home Manager consumers, secrets/proxy requirements.
• Steps:
  1. Create modules/<category>/<name>/nixos.nix for NixOS-only concerns such as users.users, environment.systemPackages, services.*, programs.*, firewall rules, and SOPS-backed system resources.
  2. Create modules/<category>/<name>/home.nix for Home Manager concerns such as programs.*, xdg.*, home.file.*, services.* within Home Manager, and per-user shell aliases/config files.
  3. Keep the toggle namespace aligned across both files so the same feature name remains recognizable. During migration, duplicate the option schema if needed rather than keeping Home Manager logic embedded in the NixOS module.
  4. If the feature has truly shared logic, extract it into a local helper file within the feature directory. If the same Home Manager wrapper pattern repeats across multiple features, promote that wrapper logic into parts/core.nix helpers instead of cloning the same osConfig and shell-selection code.
  5. Remove the legacy flat module only after the paired files evaluate cleanly and all references are updated.
• Validation:
  • modules/modules.nix discovers the feature’s nixos.nix.
  • config/base.nix registers modules/home-manager.nix in home-manager.sharedModules, and that loader discovers the feature’s home.nix.
  • System-only settings no longer reference home-manager.users.*.
  • Home Manager settings no longer depend on osConfig unless that coupling is intentional and documented.
  • Repeated HM wrapper logic uses shared helpers from parts/core.nix instead of being copied between modules.
• Outputs: Split module directory, retained toggle shape, and updated docs if the feature introduces new structure patterns.
• References: docs/constitution.md (Repository Overview, Terminology and Naming Standards, Maintenance Triggers), docs/reference/index.md (Module Directories, Auto-Import Rules)