# 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)