hooks: ship three commented examples, install them, document the contract

Add hooks/on_start, hooks/on_done and hooks/on_quit. They are named
after the hooks themselves so copying one into ~/.config/ttym/hooks/ is
the entire installation step, and each carries its argument contract in
a header comment.

  on_start  sets the terminal window title to what is running
  on_done   desktop notification plus a sound, both backgrounded, with
            the first available of paplay/aplay/mpv/ffplay
  on_quit   records abandoned sessions to a TSV under XDG_STATE_HOME and
            restores the terminal title

make install places them in PREFIX/share/doc/ttym/hooks; make uninstall
removes them and both directories; make dist ships hooks/ with the
executable bits intact.

The man page's HOOKS section now documents what the code actually does
rather than what could be assumed from the call sites:

  - $2 differs per hook: requested duration on on_start, full duration
    on on_done, and time actually elapsed -- excluding time spent paused
    -- on on_quit. An abandoned 25m countdown reports what really ran.
  - $3 is always passed, so it is never unset.
  - hooks block: timer forks and waitpid()s, so on_done delays the
    completion bell and the alert loop. Background anything slow.
  - stdin, stdout and stderr all go to /dev/null, which is why printing
    is pointless and cannot corrupt the redrawn progress line.
  - execvp(3) means a script needs a #! line.

README gains a Hooks section. All three examples pass sh -n and
shellcheck, and were tested end to end through the documented flow:
make install to a staging prefix, copy into a config dir, run.

Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP

1 files changed, 31 insertions, 0 deletions

diff --git a/hooks/on_done b/hooks/on_done
new file mode 100755
index 0000000..955cd13
--- /dev/null
+++ b/hooks/on_done
@@ -0,0 +1,31 @@
+#!/bin/sh
+# ttym on_done -- runs when a countdown reaches zero.
+#
+#   $1  mode      always "countdown" (a stopwatch never completes)
+#   $2  seconds   the full duration that elapsed
+#   $3  comment   the -c text, or an empty string
+#
+# timer waits for this to exit before ringing the bell and entering the
+# alert loop, so background anything slow.
+
+seconds=$2 comment=$3
+mins=$((seconds / 60))
+
+# Desktop notification. Gives the base build what the notify patch adds.
+if command -v notify-send > /dev/null 2>&1; then
+	notify-send -u critical "Timer" "${mins}m done${comment:+ -- $comment}" &
+fi
+
+# A sound, first player that exists wins. Backgrounded so it never blocks.
+for player in paplay aplay mpv ffplay; do
+	if command -v "$player" > /dev/null 2>&1; then
+		sound=/usr/share/sounds/freedesktop/stereo/complete.oga
+		[ -r "$sound" ] && "$player" "$sound" > /dev/null 2>&1 &
+		break
+	fi
+done
+
+# Push to your phone (uncomment and set your topic):
+# curl -fsS -d "${mins}m done${comment:+ -- $comment}" ntfy.sh/your-topic &
+
+wait