Initial code commit

docs/systemd.md

@@ -0,0 +1,106 @@
+# systemd backend
+
+`schedls` manages systemd **timers**. A timer is always paired with a
+oneshot service that holds the command.
+
+## Layout
+
+| Scope  | Unit directory               | Manager              |
+|--------|------------------------------|----------------------|
+| user   | `~/.config/systemd/user`     | `systemctl --user`   |
+| system | `/etc/systemd/system`        | `systemctl`          |
+
+`new --timer` defaults to user scope. System scope must be requested
+explicitly with `--system` and appropriate privileges; `schedls` never invokes
+`sudo` for you.
+
+## Created files
+
+For a job named `backup`:
+
+```ini
+# ~/.config/systemd/user/schedls-backup.service
+# Managed by schedls
+# Name: backup
+
+[Unit]
+Description=schedls job backup
+
+[Service]
+Type=oneshot
+ExecStart="/usr/local/bin/backup" "/srv/data"
+```
+
+```ini
+# ~/.config/systemd/user/schedls-backup.timer
+# Managed by schedls
+# Name: backup
+
+[Unit]
+Description=schedls job backup (timer)
+
+[Timer]
+OnCalendar=*-*-* 02:00:00
+Persistent=true
+Unit=schedls-backup.service
+
+[Install]
+WantedBy=timers.target
+```
+
+The `schedls-` prefix and the header comments provide provenance without a
+database.
+
+## Argument handling
+
+`ExecStart=` is not shell syntax. `schedls` serializes each argument with
+systemd's own quoting rules and always quotes arguments, so a value such as
+`$(...)`, `%i`, `$HOME` or an argument beginning with `-` is passed literally.
+Use `--shell` to explicitly request `/bin/sh -c`.
+
+Every rendered unit is validated with `systemd-analyze verify` before
+installation.
+
+## Calendar expressions
+
+Convenience flags compile to native `OnCalendar=` values:
+
+| Flag             | Example                    | Compiles to                        |
+|------------------|----------------------------|------------------------------------|
+| `--daily TIME`   | `--daily 02:00`            | `*-*-* 02:00:00`                   |
+| `--weekdays TIME`| `--weekdays 08:30`         | `Mon..Fri *-*-* 08:30:00`          |
+| `--weekly D TIME`| `--weekly sun 04:00`       | `Sun *-*-* 04:00:00`               |
+| `--monthly D TIME`| `--monthly 1 06:00`       | `*-*-01 06:00:00`                  |
+| `--calendar EXPR`| `--calendar 'Mon..Fri 02:30'` | used verbatim                   |
+
+`--calendar` may be repeated; systemd supports multiple `OnCalendar=` entries.
+
+## Discovery
+
+Timers are listed with `systemctl list-unit-files` and `list-units`, then
+properties are read with `systemctl show`. OnCalendar, Persistent and the
+command are read from the unit fragments. The next elapse is taken from
+`NextElapseUSecRealtime`; monotonic timers have no wall-clock next run and are
+reported as unknown.
+
+## Logs
+
+`schedls logs NAME` queries the service unit's journal via `journalctl
+--no-pager`. The job command is never re-executed.
+
+Two options control how much is shown, both passed to `journalctl`:
+
+| Option         | Default | Meaning                                                       |
+|----------------|---------|---------------------------------------------------------------|
+| `--lines N`    | `50`    | number of recent entries (`journalctl --lines=N`)             |
+| `--since TIME` | none    | lower bound on entry time (`journalctl --since=TIME`)         |
+
+`TIME` accepts any value `journalctl --since` accepts, for example
+`'2026-09-01'`, `'2 hours ago'` or `'2026-09-01 10:00:00'`. `--since` bounds the
+range and `--lines` caps how many entries within it are shown. See
+[cli.md](cli.md#logs-name) for the full command reference.
+
+## Lingering
+
+User timers only run while the user's systemd manager is alive. `schedls`
+warns when lingering is disabled but never enables it.