split home-manager into their own submodules

docs/constitution.md

@@ -7,7 +7,7 @@
 
 ## Repository Overview
 - Architecture: Flake-based repo using `flake-parts` with inputs for pkgs (stable/unstable), stylix, home-manager, sops-nix, and service overlays. Common modules are composed through `parts/core.nix` and `parts/hosts.nix`.
-- Module auto-import: `modules/modules.nix` auto-imports `.nix` files under `modules/apps`, `modules/dev`, `modules/scripts`, `modules/servers`, `modules/services`, `modules/shell`, `modules/websites`, and `modules/network`, excluding `librewolf.nix`. Factories live in `modules/factories/` (`mkserver`, `mkscript`), and shared options are in `modules/nix` and `modules/users`.
+- Module auto-import: `modules/modules.nix` auto-imports legacy flat modules under `modules/apps`, `modules/dev`, `modules/scripts`, `modules/servers`, `modules/services`, `modules/shell`, `modules/websites`, and `modules/network`, excluding `librewolf.nix`, and also discovers nested `nixos.nix` files under those trees. `config/base.nix` registers `modules/home-manager.nix` as a Home Manager shared module, which discovers nested `home.nix` files under `modules/` for every Home Manager user. Factories live in `modules/factories/` (`mkserver`, `mkscript`), and shared options are in `modules/nix` and `modules/users`.
 - Hosts and toggles: Host definitions live in `hosts/<name>/configuration.nix` with host-specific toggles in `hosts/<name>/toggles.nix`. The `my` namespace carries toggles for apps/dev/scripts/services/shell, feature flags like `enableProxy` and `enableContainers`, and per-host `interfaces` and `ips` maps.
 - Port assignment: Service ports should live with the service module when the port is intrinsic to a server definition under `modules/servers/`. Miscellaneous or host-specific ports that do not belong to a server module should be centralized in `my.ports` in `modules/modules.nix` and referenced via `config.my.ports.*` (use `toString config.my.ports.*` where a string is required).
 - Main server and proxies: `my.mainServer` selects the host that should serve traffic by default (default `vps`). Reverse proxies use helpers in `parts/core.nix` (`proxy`, `proxyReverse`, `proxyReverseFix`, `proxyReversePrivate`) and pick IPs from `my.ips` plus the hostName/ip set by `mkserver` options. Nginx defaults to `proxyReverse` for any server with `enableProxy = true` unless `useDefaultProxy = false` or the server is listed in the Fix/Private proxy lists.
@@ -30,10 +30,10 @@ config.services = {
 ```
 
 ## Terminology and Naming Standards
-- Module: A Nix module under `modules/<category>/<name>.nix` auto-imported into the system.
+- Module: Prefer a feature directory under `modules/<category>/<name>/` with `nixos.nix` for system concerns and `home.nix` for Home Manager concerns. Legacy flat modules at `modules/<category>/<name>.nix` remain valid during migration.
 - Factory: Shared option constructors in `modules/factories/` (use `mkserver` for server modules, `mkscript` for script units).
 - Options: Settings under the `my` namespace (e.g., `my.services.<service>`, `my.scripts.<script>`).
-- Toggles: Enablement maps in `hosts/<name>/toggles.nix` controlling categories (apps/dev/shell/scripts/services/servers/units) and features (`enableProxy`, `enableContainers`).
+- Toggles: Enablement maps in `hosts/<name>/toggles.nix` controlling categories (apps/dev/shell/scripts/services/servers/units) and features (`enableProxy`, `enableContainers`). Future standalone Home Manager or Darwin homes should mirror that shape in home-specific toggle files instead of embedding Home Manager settings in NixOS modules.
 - Servers: Reverse-proxied services under `modules/servers/`, normally created with `mkserver` options (including `useDefaultProxy` to opt out of default proxyReverse).
 - Websites: Static nginx vhosts under `modules/websites/` (portfolio/blog, mb-report), gated by `my.websites.*.enableProxy`.
 - Scripts: Units defined via `mkscript` with `enable`, `install`, `service`, `users`, `timer`, and `package` fields.
@@ -48,6 +48,8 @@ config.services = {
 
 ## Module Categories and Active Hosts
 - Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix. Factories sit in `modules/factories/` and are imported explicitly; patch artifacts live at the repo root in `patches/`.
+- Split-module preference: For categories that need both system and Home Manager behavior, co-locate both surfaces in `modules/<category>/<name>/nixos.nix` and `modules/<category>/<name>/home.nix`. Keep helpers local to that directory only when they are feature-specific; otherwise promote them into shared helpers/factories.
+- User config split: Personal configs may also split across `config/<name>.nix` for NixOS-side account/secrets state and `config/<name>-home.nix` for Home Manager-only state imported from the user home module.
 - Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. Host roles and secure status are defined in `hosts/<name>/configuration.nix` and toggles in `hosts/<name>/toggles.nix`.
 
 ## Precedence and Conflict Resolution
@@ -55,7 +57,7 @@ config.services = {
 - Conflict handling steps: identify the divergent rule, cite the source files, decide the authoritative rule per this constitution, update both the source file and the relevant doc, and record the decision and timestamp.
 
 ## Maintenance Triggers and Update Process
-- Triggers: New factory/helper, new module category, new host, new toggle set, new proxy rule, new secret category/file, change to `my.mainServer` or `my.ips`, stylix scheme changes, or new auto-import filters.
+- Triggers: New factory/helper, new module category, new host, new toggle set, new proxy rule, new secret category/file, change to `my.mainServer` or `my.ips`, stylix scheme changes, or new auto-import filters/import trees.
 - Update flow: (1) Amend the relevant module or toggle files; (2) Update `docs/constitution.md` for rules/terminology changes; (3) Update playbooks under `docs/playbooks/` affected by the change; (4) Update `docs/reference/index.md` for navigation paths; (5) Note the decision in `specs/001-ai-docs/research.md` and refresh `quickstart.md` if discoverability shifts.
 - Validation: Confirm discoverability within two clicks (constitution → reference map/playbook), secrets map completeness, and alignment with success criteria SC-001–SC-004.
 
@@ -64,6 +66,7 @@ config.services = {
 - Reference map: `docs/reference/index.md` (paths, hosts, secrets, proxies, stylix)
 - MCP server reference: `docs/reference/mcp-server.md` (tools, invocation, sync checks)
 - 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`.

docs/playbooks/add-module.md

@@ -5,14 +5,14 @@
 - Prerequisites: Identify target host(s) and toggle category; confirm `my.secureHost` if secrets are involved.
 - Inputs: Module name, category (apps/dev/scripts/servers/services/shell/network), required options, secret needs, proxy requirements if server-facing.
 - Steps:
-  1. Choose the category path from `docs/reference/index.md` and create `modules/<category>/<name>.nix` (auto-import picks it up; avoid names filtered out such as `librewolf.nix`).
+  1. Choose the category path from `docs/reference/index.md`. Prefer `modules/<category>/<name>/nixos.nix` plus `modules/<category>/<name>/home.nix` when the feature spans both system and Home Manager; use a legacy flat `modules/<category>/<name>.nix` only for NixOS-only modules or temporary migration work.
   2. Define options under `my.<category>` or reuse factories (`mkserver` for servers, `mkscript` for scripts) instead of hand-rolled patterns.
   3. If the module needs secrets, guard references with `lib.mkIf config.my.secureHost` and map them to the correct secrets file (see secrets map).
   4. For networked services, align host selection with `my.mainServer` and `my.ips`; enable reverse proxy via `enableProxy` when applicable.
   5. Wire toggles for target hosts in `hosts/<host>/toggles.nix`, ensuring users/groups and containers/proxy flags are set.
 - Validation:
-  - Module loads without extra imports (auto-import applies).
+  - Module loads without extra imports (`nixos.nix` and `home.nix` are auto-discovered; legacy flat modules remain supported).
   - Toggle wiring matches intended hosts; secureHost gating present for secrets.
   - Proxy and port choices align with `my.mainServer`, `my.ips`, and firewall rules.
 - Outputs: New module file and updated host toggles if required.
-- References: `docs/constitution.md` (Module Categories, Secrets Map, Main server and proxies), `docs/reference/index.md` (Module Directories, Proxy rules, Secrets Map)
+- References: `docs/constitution.md` (Module Categories, Secrets Map, Main server and proxies), `docs/reference/index.md` (Module Directories, Auto-Import Rules, Proxy rules, Secrets Map)

docs/playbooks/split-home-manager.md

@@ -0,0 +1,19 @@
+# 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 or promote it into `modules/factories/` when reused across features.
+  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.
+- 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)

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.