docs(man): explain how an overlay is actually applied

The format was documented; the pipeline was not. The commonest surprise when
writing a local calendar is 'my feast does not appear', and it is almost never
a loading failure -- which means the existing docs answered a question nobody
was asking.

Four stages, named: load, merge, resolve, emit. The one that matters is
resolve, and the point it makes explicit is that overlay entries take part in
precedence on EQUAL TERMS. A local feast is not privileged for being local; it
competes under RG 91's table exactly as a universal one does.

Three concrete causes of a missing feast, each of which came up while testing
this branch: outranked by the day it lands on, a date structurally occupied
(an easter+60 feast can never appear, because Corpus Christi is Easter+60 and
is I class), or a commemoration past RG 111's limit for the day's class. And
the diagnostic rule -- if check says the file loaded and every directive found
its target, the answer is stage 3, so raise the class or move the date.

Also records why the shipped adjustments are applied first and why that is not
configurable: replacing rather than layering would silently drop the
inseparable Peter/Paul commemoration, the Major Litanies, St Barbara and
Rogation Wednesday. Overriding one deliberately by naming its slug is a
different thing from losing it by accident.

1 files changed, 65 insertions, 0 deletions

diff --git a/man/colitur-overlay.5 b/man/colitur-overlay.5
index a2d2dae..f1360e2 100644
--- a/man/colitur-overlay.5
+++ b/man/colitur-overlay.5
@@ -228,6 +228,71 @@ Recolour a universal entry without otherwise touching it:
 A worked file exercising all four directives and all three date shapes is
 installed at
 .IR <prefix>/share/colitur/examples/diocesan\-example.sexp .
+.SH HOW AN OVERLAY IS APPLIED
+Worth understanding, because the commonest surprise \(em "my feast does not
+appear" \(em is almost never a loading failure.
+.PP
+Four stages, in order:
+.TP
+.B 1. Load
+Each file is parsed into a list of directives. A syntax error here is fatal
+and names the section and the value.
+.TP
+.B 2. Merge
+The shipped universal calendar is taken as the base, then
+.I data/ef/adjustments.sexp
+(colitur's own corrections \(em the inseparable Peter/Paul commemoration, the
+Major Litanies, St Barbara, Rogation Wednesday), then each
+.B \-\-overlay
+in command\-line order. Within a file, directives apply in the order written.
+Last writer wins per slug.
+.IP
+A directive whose slug is not present is
+.I not
+fatal: it warns and the run continues, so an overlay written against a
+slightly different base stays usable.
+.B colitur check
+turns the same condition into exit 2.
+.TP
+.B 3. Resolve
+For each day, the temporal cycle and the merged sanctoral calendar are
+reconciled by the rite's own rules \(em occurrence, precedence, commemoration
+and transfer.
+.B Your entries take part in this on equal terms.
+An overlay feast is not privileged for being local: it competes for its day
+under RG 91's table exactly as a universal feast does.
+.TP
+.B 4. Emit
+One line per day.
+.SS Why a feast may not appear
+Because it lost stage 3, not because it failed stage 1. Some common causes:
+.IP \(bu 2
+It is outranked. A III\-class local feast loses to any I\- or II\-class day it
+lands on, including every Sunday of Advent, Lent and Paschaltide, and to a
+universal feast of higher class on the same date.
+.IP \(bu 2
+Its date is structurally occupied. An
+.B easter+60
+feast will never appear, because Corpus Christi is Easter+60 and is I class.
+The same is true of any offset already carrying a I\-class day.
+.IP \(bu 2
+It is a
+.B commemoration
+and the day already admits its limit \(em RG 111 allows one on a II\-class
+day and two on a III\- or IV\-class one.
+.PP
+.B colitur check
+confirms the file loaded and every directive found its target. If it says so
+and the feast is still absent, stage 3 is the answer: raise its class, or
+choose a date that is not already spoken for.
+.SS Why the shipped adjustments are applied first
+An overlay is applied
+.I on top of
+colitur's own corrections, never instead of them. Replacing them would
+silently drop four things the universal calendar needs, so the order is not
+configurable. A local calendar can still override any of them deliberately by
+naming the slug \(em last writer wins \(em which is a different thing from
+losing them by accident.
 .SH CAVEATS
 .B An overlay is applied, not validated.
 .BR colitur (1)