hooks: replace the examples with ones that do what the binary cannot

The previous examples largely duplicated features of the patched build.
on_done sent a desktop notification and played a sound, both of which
the notify patch already does, so a user who copied it got two of each.
on_quit recorded abandoned sessions, but the logging patch calls
write_log() unconditionally at the end of every run: abandoned sessions
were already in the log behind timer -r.

The new set does two things nothing else can:

  - Intent versus outcome. The log stores elapsed seconds only, so a
    finished 25m and an abandoned 30m that ran 25m are indistinguishable
    in it. The duration actually requested is visible to on_start and
    nowhere else, so the examples write START/DONE/QUIT records to
    $XDG_STATE_HOME/ttym/sessions.tsv.

  - Focus mode. During a countdown, pause dunst notifications and any
    playerctl/mpc playback; restore on done or quit. Countdown only, so
    a stopwatch cannot silence notifications indefinitely.

A timewarrior bridge is included but commented out.

Two behaviours documented in the file comments, both read off the code
rather than assumed: notify_and_sound() runs before the on_done hook, so
with dunst paused the completion popup is queued and appears when the
hook unpauses -- delayed, not lost; and nothing restores dunst if the
process is killed with -9.

Every external command is guarded with command -v, so the examples
degrade to the session record alone on a machine without those tools.
Each hook works standalone -- the man page and README now say so
explicitly, since installing only on_quit is a normal setup. All three
pass sh -n and shellcheck, and were tested across all three paths:
completed countdown, abandoned countdown, stopped stopwatch, with
dunstctl is-paused confirmed false afterwards.

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

1 files changed, 31 insertions, 3 deletions

diff --git a/timer.1 b/timer.1
index e3fe0bc..e7850f9 100644
--- a/timer.1
+++ b/timer.1
@@ -256,6 +256,9 @@ or when a stopwatch is stopped.
 .PP
 A hook is any executable file at that name; there is nothing to enable.
 A file that is missing or not marked executable is skipped silently.
+The three are independent: installing only
+.BR on_quit ,
+for instance, is a complete and normal setup.
 .SS Arguments
 Each hook is run with exactly three positional arguments.
 .TP
@@ -316,9 +319,34 @@ line like any other.
 Three commented, working examples ship with the source and are installed
 to
 .IR PREFIX/share/doc/ttym/hooks/ .
-They set the terminal title, send a desktop notification and play a
-sound on completion, and record abandoned sessions to a TSV file. Copy
-the ones you want and edit:
+They form one coherent set but each works alone. Together they do two
+things the binary cannot:
+.IP \(bu 2
+Record intent against outcome. The session log behind
+.B timer \-r
+stores elapsed seconds only, so a finished 25m and an abandoned 30m that
+ran 25m look identical in it. The duration you asked for is visible to
+.B on_start
+and nowhere else, so the examples write a START/DONE/QUIT record to
+.I $XDG_STATE_HOME/ttym/sessions.tsv
+that shows follow\-through.
+.IP \(bu 2
+Focus mode. During a countdown they pause
+.BR dunst (1)
+notifications and any
+.BR playerctl (1)
+or
+.BR mpc (1)
+playback, and restore both when it ends. Every external command is
+guarded, so the examples are harmless on a machine without them.
+.PP
+A commented
+.BR timew (1)
+bridge is included but off by default; it turns
+.B \-c
+comments into timewarrior tags.
+.PP
+Copy the ones you want and edit:
 .PP
 .RS
 .nf