wheneverd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9af22418de7ea3db50ee8a05d5614f172154a7d6b1b750017594b6202aa5298
+  data.tar.gz: 77c113c6dc437c94f59ef019cd0c274ecd94c9af2463fcfea712bbd87b109387
+SHA512:
+  metadata.gz: 2f27bd8f52c7d9e111d8b3cdcb1170b1f584f30db2e601c3938b67db29d2d1ca433e419c3020dbe01636e7e62d1798a987173deb7d1d8c3f14be91f5abf0f203
+  data.tar.gz: 6cbacc2cc72b97b1dee8dd196c1bb332c47c8a0da0cd9e01473abf8cb799b96a6a9d2c3484d7294ae5b70fc392a6287c1ba55a6ad364547ce59387d7224c82a1

data/.gitignore

@@ -0,0 +1,26 @@
+.bundle/
+.yardoc/
+/.yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rubocop_cache/
+
+# Ruby
+*.gem
+*.rbc
+*.bundle
+*.so
+*.o
+*.a
+*.log
+
+# Bundler
+/vendor/bundle
+
+# Editors/OS
+.DS_Store
+.idea/
+.vscode/

data/.rubocop.yml

@@ -0,0 +1,41 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+  CacheRootDirectory: .rubocop_cache
+  Exclude:
+    - "vendor/**/*"
+    - "pkg/**/*"
+    - "tmp/**/*"
+
+Layout/LineLength:
+  Max: 100
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Metrics:
+  Enabled: true
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/wheneverd/systemd/cron_parser.rb"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "lib/wheneverd/systemd/cron_parser.rb"
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/wheneverd/systemd/cron_parser.rb"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/wheneverd/systemd/cron_parser.rb"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/wheneverd/systemd/cron_parser.rb"

data/.yardopts

@@ -0,0 +1,8 @@
+--quiet
+--markup markdown
+--markup-provider redcarpet
+--output-dir doc
+--title "wheneverd"
+--readme README.md
+--files LICENSE,CHANGELOG.md,FEATURE_SUMMARY.md
+lib/**/*.rb

data/AGENTS.md

@@ -0,0 +1,42 @@
+# Agent Notes (wheneverd)
+
+## Project
+
+`wheneverd` is a Ruby gem that aims to generate `systemd` timer/service units from a Ruby DSL (analogous to the `whenever` gem for cron). The current state is an early scaffold with a placeholder CLI; systemd generation is not implemented yet.
+
+Primary docs:
+- `README.md` for usage and dev setup.
+- `FEATURE_SUMMARY.md` for user-visible behavior changes.
+- `CHANGELOG.md` for versioned release notes.
+
+Documentation hygiene:
+- After completing a prompt that changes user-visible behavior or developer workflow, update `README.md`, `FEATURE_SUMMARY.md`, and `CHANGELOG.md` as needed.
+- Before committing any change, run `bundle exec rake ci`; it must complete with no errors (fix failures first).
+- When implementing or changing behavior, add/adjust tests to tighten the implementation and prevent regressions.
+- When committing, commit only the changes from the current session: stage explicit files (or use `git add -p`) and avoid committing unrelated modified files.
+
+## Repo Layout
+
+- `lib/wheneverd.rb`: gem entrypoint.
+- `lib/wheneverd/cli.rb`: Clamp-based CLI (currently prints help / version only).
+- `lib/wheneverd/version.rb`: gem version.
+- `exe/wheneverd`: executable entrypoint.
+- `test/`: Minitest suite (with SimpleCov configured in `test/test_helper.rb`).
+- `Rakefile`: CI-like tasks for lint + tests.
+
+## Common Commands
+
+- Install deps: `bundle install`
+- Run tests: `bundle exec rake test`
+- Run RuboCop (autocorrect): `bundle exec rake ci:rubocop`
+- Run lint + tests (default): `bundle exec rake ci`
+
+Notes:
+- `bundle exec rake ci` runs `rubocop -A .` (it may modify files) and then runs tests.
+- Tests write coverage output to `coverage/`. Coverage threshold defaults to 100% and can be set via `MINIMUM_COVERAGE` (e.g. `MINIMUM_COVERAGE=95 bundle exec rake test`).
+
+## Conventions
+
+- Ruby target is 2.7 (`.rubocop.yml` / gemspec).
+- Prefer double-quoted strings and keep lines <= 100 chars (RuboCop).
+- Add/update `FEATURE_SUMMARY.md` only for user-visible changes (CLI UX, defaults, generated output, breaking changes).

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+This project keeps all changes in `## Unreleased` until they are released.
+On release, entries are moved into `## x.y.z` sections that match the gem version.
+
+## Unreleased
+
+- No changes yet.
+
+## 0.1.0
+
+- Provides a Clamp-based `wheneverd` CLI with `--help`, `--version`, and `--verbose` (usage errors in `ERROR: ...` format).
+- Adds core domain objects and helpers for building schedules (interval parsing, durations, triggers, entries, jobs).
+- Adds a Ruby DSL loader (`Wheneverd::DSL::Loader.load_file`) supporting `every(...)` blocks with `command(...)` jobs.
+- Schedule DSL: `every` accepts multiple calendar period symbols in one block (e.g. `every :tuesday, :wednesday`).
+- Cron strings: supports standard 5-field crontab syntax (including month/day-of-week and steps); expressions that require
+  cron day-of-month vs day-of-week OR semantics may expand into multiple `OnCalendar=` lines.
+- Adds systemd unit rendering (`Wheneverd::Systemd::Renderer.render`) for interval and calendar triggers.
+- Systemd: unit basenames use a stable ID derived from the job’s trigger + command (reordering schedule blocks won’t rename units).
+- Interval timers now include both `OnActiveSec=` and `OnUnitActiveSec=` so newly enabled timers have a next run scheduled.
+- Adds helpers to write and delete generated unit files (`Wheneverd::Systemd::UnitWriter`/`UnitDeleter`).
+- Adds CLI subcommands: `init`, `show`, `write`, `delete`, `activate`, `deactivate`, `reload`, and `current`.
+- `wheneverd init` prints whether it wrote or overwrote the schedule template.
+- Schedule DSL supports `every :reboot` as a boot trigger (rendered as `OnBootSec=1`).
+- Developer: `rake ci` runs with Bundler setup (so it works without `bundle exec` after `bundle install`).
+- Developer: adds YARD tasks (`rake yard` / `rake doc`) and inline API documentation.
+- CLI: `delete` / `current` only operate on units matching the identifier and generated marker.
+- CLI: `write` / `reload` prune previously generated units for the identifier by default (use `--no-prune` to disable pruning).

data/FEATURE_SUMMARY.md

@@ -0,0 +1,38 @@
+# Feature Summary
+
+This file tracks the most important *user-visible* behavior changes in `wheneverd`.
+It complements [`CHANGELOG.md`](CHANGELOG.md) by staying high-level and focusing on what users will notice.
+
+## How to update
+
+- Update `## Unreleased` in commits that change user-facing behavior (CLI UX, defaults, generated output, breaking changes).
+- Skip internal refactors, tests, and docs-only tweaks unless they affect users.
+- Keep entries short, written from the user’s point of view.
+- On release, move items from `## Unreleased` into a new `## x.y.z` section that matches the gem version.
+
+## Unreleased
+
+- No changes yet.
+
+## 0.1.0
+
+- The `wheneverd` CLI is implemented using Clamp (`--help`, usage errors in `ERROR: ...` format, `--verbose` for details).
+- The gem includes a small “whenever-like” domain model (interval parsing, durations, triggers, schedules).
+- The gem can load a Ruby schedule DSL file via `Wheneverd::DSL::Loader.load_file`.
+- Schedule DSL supports `every(period, at: ..., roles: ...) { command("...") }` entries (multiple `command` calls per entry).
+- Schedule DSL supports multiple calendar period symbols per `every` block (e.g. `every :tuesday, :wednesday`).
+- Supported `every` periods include interval strings/durations, calendar shortcuts (`:hour`, `:day`, `:month`, `:year`),
+  day selectors (`:monday..:sunday`, `:weekday`, `:weekend`), and standard 5-field cron strings.
+- `at:` supports a string or an array of strings (for calendar schedules), like `"4:30 am"` or `"00:15"`.
+- `roles:` is accepted and stored on entries, but is not used for filtering yet.
+- The gem can render systemd `.service` and `.timer` units via `Wheneverd::Systemd::Renderer.render`.
+- Generated unit basenames include a stable ID derived from the job’s trigger + command (reordering schedule blocks won’t rename units).
+- Interval timers include both `OnActiveSec=` and `OnUnitActiveSec=` to ensure a newly started timer has a next run scheduled.
+- The gem can write/delete generated unit files via `Wheneverd::Systemd::UnitWriter` and `Wheneverd::Systemd::UnitDeleter`.
+- The `wheneverd` CLI supports `init`, `show`, `write`, `delete`, `activate`, `deactivate`, and `reload` for working with
+  schedule files, unit directories, and managing user timers via `systemctl --user`.
+- `wheneverd write` / `wheneverd reload` prune previously generated units for the identifier by default (use `--no-prune` to disable pruning).
+- The `wheneverd current` command prints the currently installed unit file contents from disk for an identifier.
+- The `wheneverd delete` / `wheneverd current` commands only operate on units matching the identifier and generated marker.
+- `wheneverd init` prints whether it wrote or overwrote the schedule template.
+- Schedule DSL supports `every :reboot` as a boot trigger (rendered as `OnBootSec=1`).

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "irb", require: false
+  gem "minitest"
+  gem "rake"
+  gem "rdoc", require: false
+  gem "redcarpet", require: false
+  gem "rubocop", "~> 1.0", require: false
+  gem "simplecov", require: false
+  gem "yard", require: false
+end

data/Gemfile.lock

@@ -0,0 +1,129 @@
+PATH
+  remote: .
+  specs:
+    wheneverd (0.1.0)
+      clamp (~> 1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    clamp (1.3.2)
+    date (3.5.1)
+    docile (1.4.1)
+    erb (6.0.1)
+    io-console (0.8.2)
+    irb (1.16.0)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.7.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rdoc (7.1.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    redcarpet (3.6.1)
+    regexp_parser (2.11.3)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    yard (0.9.38)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  irb
+  minitest
+  rake
+  rdoc
+  redcarpet
+  rubocop (~> 1.0)
+  simplecov
+  wheneverd!
+  yard
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  clamp (1.3.2) sha256=4f6a99a8678d51abbf1650263a74d1ac50939edc11986271431d2e03a0d7a022
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  minitest (6.0.1) sha256=7854c74f48e2e975969062833adc4013f249a4b212f5e7b9d5c040bf838d54bb
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.0) sha256=ce3587fa5cc55a88c4ba5b2b37621b3329aadf5728f9eafa36bbd121462aabd6
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.7.0) sha256=10062f734bf7985c8424c44fac382ac04a58124ea3d220ec3ba9fe4f2da65103
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rdoc (7.1.0) sha256=494899df0706c178596ca6e1d50f1b7eb285a9b2aae715be5abd742734f17363
+  redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rubocop (1.82.1) sha256=09f1a6a654a960eda767aebea33e47603080f8e9c9a3f019bf9b94c9cab5e273
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  wheneverd (0.1.0)
+  yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
+
+BUNDLED WITH
+  4.0.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Go
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# wheneverd
+
+Wheneverd is to systemd timers what the [`whenever` gem](https://github.com/javan/whenever) is to cron.
+
+Tagline / repo: `git@github.com:bigcurl/wheneverd.git`
+
+## Status
+
+Working end-to-end: schedule DSL loading, systemd unit rendering, and safe unit write/list/delete are implemented, along with a CLI for `init`, `show`, `write`, `delete`, `activate`, `deactivate`, `reload`, and `current`.
+
+Known limitations: `roles:` is accepted but not used for filtering yet.
+
+See `FEATURE_SUMMARY.md` for high-level user-visible behavior, and `CHANGELOG.md` for release notes.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "wheneverd"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+```bash
+wheneverd --help
+wheneverd init
+wheneverd show
+wheneverd write
+wheneverd delete
+wheneverd activate
+wheneverd deactivate
+wheneverd reload
+wheneverd current
+```
+
+### Minimal `config/schedule.rb` example
+
+```ruby
+# frozen_string_literal: true
+
+every "5m" do
+  command "echo hello"
+end
+
+every 1.day, at: "4:30 am" do
+  command "echo four_thirty"
+end
+```
+
+Preview the generated units:
+
+```bash
+wheneverd show
+```
+
+### Activating / deactivating (systemd)
+
+After `wheneverd write`, use `wheneverd activate` to enable + start the generated timer units (by default, user units
+in `~/.config/systemd/user`):
+
+```bash
+wheneverd activate
+```
+
+Deactivate a timer:
+
+```bash
+wheneverd deactivate
+```
+
+After changing your schedule, rewrite units and restart the timer(s) to pick up changes:
+
+```bash
+wheneverd reload
+```
+
+## Syntax
+
+Schedules are defined in a Ruby file (default: `config/schedule.rb`) and evaluated in a dedicated DSL context.
+
+Note: schedule files are executed as Ruby. Do not run untrusted schedule code.
+
+The core shape is:
+
+```ruby
+every(period, at: nil, roles: nil) do
+  command "echo hello"
+end
+```
+
+For calendar schedules, you can also pass multiple period symbols (or an array) to run the same jobs on multiple days:
+
+```ruby
+every :tuesday, :wednesday, at: "12pm" do
+  command "echo midweek"
+end
+```
+
+### `command`
+
+`command("...")` appends a oneshot `ExecStart=` job. Commands must be non-empty strings.
+
+The command string is inserted into `ExecStart=` as-is (no shell wrapping). If you need shell features
+(pipes, redirects, globbing, env var expansion), wrap it yourself, for example:
+
+```ruby
+command "/bin/bash -lc 'echo hello | sed -e s/hello/hi/'"
+```
+
+### `every` periods
+
+Supported `period` forms:
+
+- Interval strings: `"<n>s|m|h|d|w"` (examples: `"5m"`, `"1h"`) for monotonic timers (`OnActiveSec=` + `OnUnitActiveSec=`).
+- Duration objects: `1.second`, `1.minute`, `1.hour`, `1.day`, `1.week` (and plurals), using the same interval semantics.
+- Symbol shortcuts:
+  - `:hour`, `:day`, `:month`, `:year` (calendar schedules, mapped to `hourly`, `daily`, `monthly`, `yearly`)
+- `:reboot` (boot trigger, mapped to `OnBootSec=1`).
+- Day selectors: `:monday..:sunday`, plus `:weekday` and `:weekend` (calendar schedules; multiple day symbols supported).
+- Cron strings (5 fields), like `"0 0 27-31 * *"` (calendar schedules).
+
+Notes:
+
+- Interval/duration schedules are monotonic (run relative to last execution), while calendar schedules are wall-clock
+  based. In particular, `every 1.day` is monotonic, but `every :day` is calendar-based.
+- `at:` is only supported with calendar periods. `every 1.day, at: ...` is supported as a convenience and is treated
+  as a daily calendar trigger.
+- `at:` is not supported with `every :reboot`.
+
+### `at:` times
+
+`at:` may be a single string or an array of strings. Times are normalized at render time.
+
+`at:` is not supported for interval strings (like `"5m"`) or cron strings.
+
+Accepted examples:
+
+- `"4:30 am"`, `"6:00 pm"`, `"12pm"`
+- `"00:15"` (24h)
+
+### Cron strings
+
+Cron translation supports standard 5-field crontab strings (`minute hour day-of-month month day-of-week`), including:
+
+- Wildcards, lists, ranges, and steps (`*`, `1,2,3`, `1-5`, `*/15`, `1-10/2`)
+- Month and day-of-week names (`Jan`, `Mon`)
+- Cron day-of-month vs day-of-week OR semantics (may expand into multiple `OnCalendar=` lines)
+
+Unsupported cron patterns raise an error at render time (e.g. non-5-field strings, `@daily`, `L`, `W`, `#`, `?`).
+
+### `roles:`
+
+`roles:` is accepted and stored on entries, but is ignored in v1 (no role-based filtering yet).
+
+## CLI
+
+Defaults:
+
+- schedule path: `config/schedule.rb` (override with `--schedule PATH`)
+- identifier: current directory name (override with `--identifier NAME`)
+- unit dir: `~/.config/systemd/user` (override with `--unit-dir PATH`)
+
+Notes:
+
+- Errors use Clamp-style `ERROR: ...` formatting; add `--verbose` to include error details.
+- `wheneverd delete` / `wheneverd current` only operate on units matching the identifier *and* the generated marker line.
+- Identifiers are sanitized for use in unit file names (non-alphanumeric characters become `-`).
+- Unit basenames include a stable ID derived from the job’s trigger + command (reordering schedule blocks won’t rename units).
+- `wheneverd write` / `wheneverd reload` prune previously generated units for the identifier by default (use `--no-prune` to keep old units around).
+
+Commands:
+
+- `wheneverd init [--schedule PATH] [--force]` writes a template schedule file.
+- `wheneverd show [--schedule PATH] [--identifier NAME]` prints rendered units to stdout.
+- `wheneverd write [--dry-run] [--unit-dir PATH] [--[no-]prune]` writes units to disk (or prints paths in `--dry-run` mode).
+- `wheneverd delete [--dry-run] [--unit-dir PATH]` deletes previously generated units for the identifier.
+- `wheneverd activate [--schedule PATH] [--identifier NAME]` runs `systemctl --user daemon-reload` and enables/starts the timers.
+- `wheneverd deactivate [--schedule PATH] [--identifier NAME]` stops and disables the timers.
+- `wheneverd reload [--schedule PATH] [--identifier NAME] [--unit-dir PATH] [--[no-]prune]` writes units, reloads systemd, and restarts timers.
+- `wheneverd current [--identifier NAME] [--unit-dir PATH]` prints the currently installed unit file contents from disk.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rake ci
+bundle exec rake yard
+
+# Also supported after `bundle install`:
+rake ci
+rake yard
+```
+
+Test runs write a coverage report to `coverage/`.
+
+YARD docs are written to `doc/` (and `.yardoc/`).