feat(data): ship a worked example overlay calendar

`--overlay` shipped last week with nothing to point at. The only example
was a test fixture, explicitly labelled invented and living where no user
would find it, so "colitur supports local calendars" was true but
undemonstrated.

data/ef/examples/diocesan-example.sexp is installed to
<prefix>/share/colitur/examples/ and is runnable documentation: every
celebration in it is invented, with example- slugs that cannot collide,
and its header explains the four directives, the three date shapes, and
the field vocabularies before showing any of them.

It demonstrates the range deliberately rather than the minimum: a
fixed-date local patron with its own propers; a movable dedication on the
first Sunday of October, I class because a church's own dedication
anniversary is I class in that church and at III it would lose to the
Sunday every year; an Easter-relative commemoration; an Edit raising a
universal feast for local use; and a Suppress shown commented out,
because suppressing a universal feast is a real liturgical act and an
example should not invite it casually.

Two things the header says plainly, since this is the one file that lets
someone change what colitur computes: an overlay is applied ON TOP of the
shipped calendar and never instead of it, and an overlay is applied, NOT
validated -- the five test layers assert things about the shipped data
and cannot vouch for a user's file.

A test asserts it loads against the real EF rank vocabulary, still
demonstrates at least four directives, and applies with NO diagnostics.
The last matters most: a directive naming a slug the universal calendar
lacks would warn, and an example that warns teaches the wrong lesson. It
deliberately does not pin which days it produces -- those celebrations
are invented, and pinning their dates would make an illustrative file
behave like calendar data.

1 files changed, 102 insertions, 0 deletions

diff --git a/data/ef/examples/diocesan-example.sexp b/data/ef/examples/diocesan-example.sexp
new file mode 100644
index 0000000..65acf3a
--- /dev/null
+++ b/data/ef/examples/diocesan-example.sexp
@@ -0,0 +1,102 @@
+; ============================================================================
+; An EXAMPLE overlay calendar for `colitur --overlay`.
+;
+; This file is shipped as documentation you can run, not as calendar data.
+; Every celebration in it is INVENTED, with slugs prefixed `example-` so they
+; cannot collide with anything real. Copy it, gut it, and put your own diocese
+; or parish in its place.
+;
+;     colitur day 2026 --overlay <prefix>/share/colitur/examples/diocesan-example.sexp
+;
+; WHAT AN OVERLAY IS
+;
+; A list of directives applied ON TOP of the shipped 1962 universal calendar,
+; never instead of it. colitur applies its own data/ef/adjustments.sexp first,
+; then each --overlay in the order given. Later writers win, so a local
+; calendar can deliberately override a universal entry by naming its slug.
+;
+; AN OVERLAY IS APPLIED, NOT VALIDATED. colitur's five test layers assert
+; things about the SHIPPED calendar; none of them can vouch for this file or
+; yours. A directive naming a slug that does not exist prints a warning on
+; stderr and the run continues, so a typo is visible rather than silent; a
+; file that fails to parse is fatal.
+;
+; THE FOUR DIRECTIVES
+;
+;   (Add     <entry>)          a celebration the universal calendar lacks
+;   (Suppress <slug>)          remove one it has
+;   (Replace <slug> <entry>)   swap one out wholesale
+;   (Edit    <slug> (<edits>)) change named fields only
+;
+; DATES
+;
+;   (Fixed (month 7) (day 11))                      a civil date, every year
+;   (Easter_offset -9)                              signed days from Easter
+;   (Nth_weekday (month 10) (nth 1) (weekday Sun))  nth weekday of a month;
+;                                                   negative nth counts back,
+;                                                   so (nth -1) is the last
+;
+; RANKS are Class1..Class4; STATUS is Feast or Commemoration_only; COLOUR is
+; White Red Green Violet Rose Black; SUBJECT is Lord Bvm Saint Temporal.
+; NAMES are keyed by language code and any set of languages is allowed.
+; CITATIONS are reading references, never scripture text; omit them and the
+; day falls through to whatever the resolution chain finds.
+; ============================================================================
+((id diocesan-example)
+  (directives
+    (
+
+     ; ---- 1. A fixed-date local patron, with its own proper readings -------
+     ; The commonest thing a local calendar adds. III class is the usual rank
+     ; for a diocesan patron who is not the cathedral's titular.
+     (Add
+       ((date (Fixed (month 7) (day 11)))
+         (cel
+           ((slug example-local-patron)
+             (names ((la "Sancti Exempli Patroni") (en "St Example, Patron")
+                     (pl "\197\154w. Przyk\197\130adu, Patrona")))
+             (rank Class3) (status Feast) (colour White) (subject Saint)
+             (citations (((part First) (reference "Ecclus 45:1-6"))
+                         ((part Gospel) (reference "Matt 25:14-23"))))
+             (layer diocesan-example)))))
+
+     ; ---- 2. A MOVABLE feast: the first Sunday of October ------------------
+     ; The anniversary of a church's own dedication is I class IN THAT CHURCH,
+     ; which is why this one outranks and displaces the Sunday it lands on --
+     ; at III class it would lose to a II-class Sunday every year.
+     (Add
+       ((date (Nth_weekday (month 10) (nth 1) (weekday Sun)))
+         (cel
+           ((slug example-dedication)
+             (names ((la "Dedicatio Ecclesiae Exempli")
+                     (en "Dedication of the Example Church")))
+             (rank Class1) (status Feast) (colour White) (subject Saint)
+             (citations (((part First) (reference "Apoc 21:2-5"))
+                         ((part Gospel) (reference "Luke 19:1-10"))))
+             (layer diocesan-example)))))
+
+     ; ---- 3. An EASTER-RELATIVE local commemoration ------------------------
+     ; Easter+61 is the Friday after Corpus Christi. A commemoration never
+     ; wins the day; it is added to whatever office the day already has,
+     ; subject to the admission limits of RG 111.
+     (Add
+       ((date (Easter_offset 61))
+         (cel
+           ((slug example-local-commemoration)
+             (names ((la "Commemoratio Exempli") (en "A Local Commemoration")))
+             (rank Class4) (status Commemoration_only) (colour White)
+             (subject Saint) (citations ()) (layer diocesan-example)))))
+
+     ; ---- 4. RAISING a universal feast for local use -----------------------
+     ; A saint the whole Church keeps at III class may be the patron of your
+     ; diocese and kept higher. Edit changes only the fields named; everything
+     ; else, including the date and the readings, stays as shipped.
+     (Edit stanislaus ((Set_rank Class1) (Set_colour Red)))
+
+     ; ---- 5. SUPPRESSING one -----------------------------------------------
+     ; Shown for completeness and commented out, because suppressing a
+     ; universal feast is a real liturgical act and should be a deliberate
+     ; one. Uncomment only if your own calendar genuinely omits it.
+     ;
+     ; (Suppress example-not-kept-here)
+     )))