feat(cli): --overlay FILE, so a local calendar can be supplied

The Overlay algebra has been built and tested since Plan 2, and
Date_spec grew movable variants last commit, but there was still no way
to hand colitur a file: bin/main.ml applied exactly one overlay, the
shipped data/ef/adjustments.sexp, with the path hardcoded. This is the
plumbing.

--overlay is repeatable and ordered, and applies ON TOP of the shipped
adjustments rather than instead of them. That ordering is the whole
point: adjustments.sexp carries RG 110's own 30 June companion, the Major
Litanies, St Barbara and Rogation Wednesday, and a user file that
replaced it would silently drop all four while appearing merely to add a
local feast. Overlay.merge is last-writer-wins, so a local calendar can
still override a universal entry deliberately, by naming its slug.

The dispatch needed real argument parsing. It matched Sys.argv as an
exact array, which does not survive a repeatable flag -- two --overlay
arguments are a different array shape from one, and each further flag
would multiply the patterns again. Flags are now stripped first and the
remaining words matched as command plus year. Hand-rolled, because the
dependency list is frozen and this is fifteen lines. One defect found by
the cram suite on the first run: the unknown-option guard rejected
--help and --version, having excluded only their short forms.

Refused, not ignored, on easter and temporal. Neither reads sanctoral
data -- temporal deliberately runs the cycle before any layer exists --
so accepting the flag there and silently doing nothing is the failure
mode this project refuses everywhere else.

A file that fails to load is fatal, exactly as the shipped overlay is; a
directive naming a slug that does not exist warns on stderr and the run
continues. The second matters more for a user file than for ours: a typo
in a diocesan calendar should say so rather than quietly do nothing.

test/fixtures/overlay-example-diocesan.sexp is a worked example and is
labelled as invented, not calendar data. It carries both shapes a real
local calendar needs: a fixed-date patron, and a dedication on "the first
Sunday of October" -- which is the case the Date_spec work existed to
unlock and which lands on 4 October in 2026, 3 October in 2027, 1 October
in 2028. The dedication is I class because a church's own dedication
anniversary is I class in that church; at III class it lost to the
II-class Sunday every year, which a first draft demonstrated correctly
and uselessly.

The man page gains an OVERLAYS section saying plainly that an overlay is
applied, NOT validated: the five test layers assert things about the
shipped calendar and none of them can vouch for a file the user supplies.
This is the first feature that lets someone change what colitur computes,
and that distinction should not have to be inferred.

1 files changed, 76 insertions, 0 deletions

diff --git a/man/colitur.1 b/man/colitur.1
index c65cc58..a18b299 100644
--- a/man/colitur.1
+++ b/man/colitur.1
@@ -7,6 +7,12 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite,
 .I YEAR
 .br
 .B colitur
+.BR day | readings
+.I YEAR
+.BI \-\-overlay " FILE"
+.RI [ ... ]
+.br
+.B colitur
 .BR \-h | \-\-help
 .SH DESCRIPTION
 .B colitur
@@ -59,8 +65,20 @@ occurrence, commemoration and transfer.
 .BI readings " YEAR"
 The Mass reading citations, one line per day.
 .TP
+.BI \-\-overlay " FILE"
+Apply a user calendar on top of the shipped one. Repeatable and ordered;
+.B day
+and
+.B readings
+only. See
+.B OVERLAYS
+below.
+.TP
 .BR \-h ", " \-\-help
 Print a usage summary to standard output and exit 0.
+.TP
+.BR \-V ", " \-\-version
+Print the version and exit 0.
 .SH OUTPUT FORMAT
 .SS day
 .RS
@@ -114,6 +132,55 @@ Both reports are one line per day and ordered by date, so they compose with
 and
 .BR join (1)
 in the ordinary way.
+.SH OVERLAYS
+.TP
+.BI \-\-overlay " FILE"
+.RB ( \-o )
+Apply a user\-supplied calendar on top of the shipped universal one. Repeatable
+and ordered.
+.PP
+Overlays are applied
+.I on top of
+the 1962 universal calendar, never instead of it. The shipped adjustments \(em
+which carry the inseparable Peter/Paul commemoration, the Major Litanies, St
+Barbara and Rogation Wednesday \(em are applied first, then each
+.B \-\-overlay
+in the order given. Last writer wins, so a later file may deliberately override
+an earlier one, or a universal entry, by naming its slug.
+.PP
+An overlay is an S\-expression file with an
+.I id
+and a list of directives:
+.BR Add ", " Suppress ", " Replace " and " Edit .
+An added entry carries its own date specification, which may be a fixed
+.RI ( month ", " day )
+pair, an
+.I Easter_offset
+in days, or an
+.I Nth_weekday
+of a month \(em so a patronal feast on "the first Sunday of October" or a
+dedication anniversary reckoned from Easter are both expressible. See
+.I test/fixtures/overlay\-example\-diocesan.sexp
+in the source distribution for a worked example of both shapes.
+.PP
+Accepted on
+.B day
+and
+.B readings
+only. The other commands read no sanctoral data at all, so the flag would have
+no effect there and is
+.I refused
+rather than silently ignored.
+.PP
+.B An overlay is applied, not validated.
+This program's test layers \(em properties over every year in the domain, a
+differential against a sibling engine, two published\-calendar oracles, and
+hand\-verified pins \(em assert things about the
+.I shipped
+calendar. None of them can vouch for a file you supply. A directive naming a
+slug that does not exist prints a warning to standard error and the run
+continues, so a typo in a local calendar is visible rather than silent; a file
+that fails to load is fatal.
 .SH ENVIRONMENT
 .TP
 .B COLITUR_DATA_DIR
@@ -182,6 +249,15 @@ Days carrying at least one commemoration:
 .fi
 .RE
 .PP
+A local calendar on top of the universal one:
+.RS
+.nf
+
+.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp
+.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp \-\-overlay ~/calendars/parish.sexp
+.fi
+.RE
+.PP
 Run against a checkout's data rather than the installed copy:
 .RS
 .nf