NixOS/docs/playbooks/add-module.md

Playbook: Add a NixOS Module

• Name: Add a module under modules/<category>/
• Purpose: Introduce a new module following auto-import and toggle conventions.
• 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. 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 (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, Auto-Import Rules, Proxy rules, Secrets Map)