split home-manager into their own submodules

docs/reference/index.md

@@ -1,24 +1,33 @@
 # Reference Map
 
 ## Module Directories
-- apps → `modules/apps/` (desktop/workstation apps, auto-imported)
-- dev → `modules/dev/` (language toolchains and dev shells, auto-imported)
-- scripts → `modules/scripts/` (script units built via `mkscript`, auto-imported)
-- servers → `modules/servers/` (reverse-proxied services built via `mkserver`)
-- services → `modules/services/` (supporting services like syncthing, wireguard)
-- shell → `modules/shell/` (shell customizations and CLI tooling)
-- websites → `modules/websites/` (static nginx vhosts for portfolio/blog and reports)
-- network → `modules/network/` (networking rules, firewall helpers)
+- apps → `modules/apps/` (desktop/workstation apps; supports legacy flat modules and preferred split feature directories)
+- dev → `modules/dev/` (language toolchains and dev shells; supports legacy flat modules and preferred split feature directories)
+- scripts → `modules/scripts/` (script units built via `mkscript`; supports legacy flat modules and preferred split feature directories)
+- servers → `modules/servers/` (reverse-proxied services built via `mkserver`; supports legacy flat modules and preferred split feature directories)
+- services → `modules/services/` (supporting services like syncthing, wireguard; supports legacy flat modules and preferred split feature directories)
+- shell → `modules/shell/` (shell customizations and CLI tooling; supports legacy flat modules and preferred split feature directories)
+- websites → `modules/websites/` (static nginx vhosts for portfolio/blog and reports; supports legacy flat modules and preferred split feature directories)
+- network → `modules/network/` (networking rules, firewall helpers; supports legacy flat modules and preferred split feature directories)
 - users → `modules/users/` (user-related options)
 - nix → `modules/nix/` (Nix configuration and helpers)
 - factories → `modules/factories/` (`mkserver.nix`, `mkscript.nix` shared helpers)
+- home-manager loader → `modules/home-manager.nix` (discovers nested `home.nix` files under `modules/`)
 ## Root Directories
 - patches → `patches/` (patch artifacts referenced by modules)
 
+## User Config Split
+- System-side user config: `config/<name>.nix` for NixOS user accounts, host secrets, groups, and other OS-owned state.
+- Home-side user config: `config/<name>-home.nix` for Home Manager-only files, shell/program configuration, and per-user match blocks.
+- Current example: `config/jawz.nix` and `config/jawz-home.nix`.
+
 ## Auto-Import Rules
-- Source: `modules/modules.nix` uses `inputs.self.lib.autoImport` to load `.nix` files from module directories.
-- Filter: Excludes `librewolf.nix`; all other `.nix` files in target dirs are loaded automatically.
-- Implication: Place new modules in the correct category directory with a `.nix` filename; no manual import wiring required unless adding a new factory. Patch artifacts under `patches/` are not auto-imported.
+- Source: `modules/modules.nix` uses `inputs.self.lib.autoImport` for legacy flat `.nix` files and `inputs.self.lib.autoImportLeaf` for nested `nixos.nix` files.
+- Home Manager source: `config/base.nix` registers `modules/home-manager.nix` in `home-manager.sharedModules`, and that module uses `inputs.self.lib.autoImportLeaf` to discover nested `home.nix` files anywhere under `modules/`.
+- Filter: Legacy flat auto-import excludes `librewolf.nix`; nested split modules are discovered by exact leaf name (`nixos.nix` or `home.nix`).
+- Preferred layout: `modules/<category>/<name>/nixos.nix` and `modules/<category>/<name>/home.nix`.
+- Migration rule: Legacy flat `modules/<category>/<name>.nix` modules remain supported while features are moved into split directories.
+- Implication: Place new dual-surface modules in a feature directory so NixOS and Home Manager stay adjacent; no manual import wiring is required unless adding a new factory.
 
 ## Hosts and Roles
 - Configs: `hosts/<name>/configuration.nix` with toggles in `hosts/<name>/toggles.nix`.
@@ -58,6 +67,7 @@
 ## Playbooks and Templates
 - Playbook template: `docs/playbooks/template.md`
 - Playbook: `docs/playbooks/add-module.md` — add a module in the right category and confirm auto-import.
+- Playbook: `docs/playbooks/split-home-manager.md` — migrate a mixed module into paired `nixos.nix` and `home.nix` files.
 - Playbook: `docs/playbooks/add-server.md` — add a reverse-proxied server via `mkserver` and proxy rules.
 - Playbook: `docs/playbooks/add-script.md` — add a script unit via `mkscript` with install/service/timer options.
 - Playbook: `docs/playbooks/add-host-toggle.md` — add or update host toggle maps under `hosts/<name>/toggles.nix`.
@@ -69,7 +79,7 @@
 - MCP server reference: `docs/reference/mcp-server.md` (tool catalog, `nixos-mcp` wrapper, invocation, sync-docs)
 
 ## Quick Audit Checklist
-- Module coverage: All categories (apps, dev, scripts, servers, services, shell, websites, network, users, nix) have corresponding entries and auto-import rules; `patches/` is documented as a root directory.
+- Module coverage: All categories (apps, dev, scripts, servers, services, shell, websites, network, users, nix) have corresponding entries and auto-import rules for both legacy flat modules and split `nixos.nix`/`home.nix` modules; `patches/` is documented as a root directory.
 - Host coverage: Active hosts listed with roles and secureHost status; `mainServer` noted.
 - Proxy rules: `enableProxy` usage, proxy helper selection, and `my.ips` mappings documented.
 - Secrets map: Every secrets file and secureHost gating captured; new secret types aligned to file purposes.