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`.