NixOS/docs/playbooks/add-script.md

Playbook: Add a Script Unit

• Name: Add a script via mkscript
• Purpose: Ship a script package with optional user service and timer.
• Prerequisites: Identify target users (my.toggleUsers.scripts defaults), secureHost status if the script needs secrets, and whether a timer/service is required.
• Inputs: Script name, package derivation, description, timer schedule, users list, service needs.
• Steps:
  1. Add a definition under my.scripts.<name> in modules/scripts/<name>.nix using mkscript options (enable, install, service, users, timer, package, description).
  2. Ensure the package exposes the executable name used by the service/timer.
  3. For user scoping, set users to a single user or list; defaults come from my.toggleUsers.scripts.
  4. If secrets are required, guard references with lib.mkIf config.my.secureHost and map them to the appropriate secrets file.
  5. Enable the script toggle in hosts/<host>/toggles.nix under scripts or units, and ensure timers/services are expected on that host.
• Validation:
  • Script installs for intended users; systemd user service/timer activates only when enable and service are true.
  • secureHost gating present for any secrets; no orphaned timers.
• Outputs: New script module and updated host toggles if needed.
• References: docs/constitution.md (Terminology, Secrets Map), docs/reference/index.md (Module Directories, Secrets Map, Hosts and Roles)