docs: point --help and the man page at the new overlay workflow

Both listed check and new-overlay among the commands but neither told a
reader how they fit together, which is the part that makes them useful. The
overlay sections now carry the four-step loop -- new-overlay, edit, check,
run -- and state what check does not do, since its name invites a stronger
reading than it earns.

Also documents what the format now permits: citations and layer optional, the
signed Easter_offset, the negative nth counting from the end of the month,
and the legal values of each of the six required fields, which previously
appeared only in the shipped example.

2 files changed, 60 insertions, 3 deletions

diff --git a/bin/main.ml b/bin/main.ml
index a6af8df..93ce023 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -420,6 +420,24 @@ overlays:
             supply. A directive naming a slug that does not exist warns on
             stderr and the run continues; a file that fails to load is fatal.
 
+            To write one:
+
+              colitur new-overlay > my-parish.sexp   # a commented starter
+              $EDITOR my-parish.sexp
+              colitur check my-parish.sexp           # parses? every directive hit?
+              colitur day 2026 --overlay my-parish.sexp
+
+            `check` reports what each directive targets and exits 2 if a file
+            will not load or a directive matched nothing, so it fits a
+            Makefile or a pre-commit hook. It does not check a calendar
+            against the rubrics -- nothing here can.
+
+            In an added celebration, `citations` and `layer` may be omitted:
+            they default to empty and to the overlay's own id. Dates may be
+            (Fixed (month M) (day D)), (Easter_offset N) signed, or
+            (Nth_weekday (month M) (nth N) (weekday W)) with N negative to
+            count from the end of the month.
+
 environment:
   COLITUR_DATA_DIR
             Read the calendar data from this directory instead of the
diff --git a/man/colitur.1 b/man/colitur.1
index a637f19..6e380ce 100644
--- a/man/colitur.1
+++ b/man/colitur.1
@@ -169,6 +169,17 @@ Barbara and Rogation Wednesday \(em are applied first, then each
 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
+The workflow:
+.RS
+.nf
+
+.B colitur new\-overlay > my\-parish.sexp
+.B $EDITOR my\-parish.sexp
+.B colitur check my\-parish.sexp
+.B colitur day 2026 \-\-overlay my\-parish.sexp
+.fi
+.RE
+.PP
 An overlay is an S\-expression file with an
 .I id
 and a list of directives:
@@ -177,10 +188,38 @@ 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
+in days (signed; Easter itself is 0), 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
+of a month \(em the
+.I nth
+may be negative to count from the end, so
+.B \-1
+is the last \(em so a patronal feast on "the first Sunday of October" or a
+dedication anniversary reckoned from Easter are both expressible.
+.PP
+In an added celebration the
+.I citations
+and
+.I layer
+fields may be omitted: they default to empty and to the overlay's own
+.IR id .
+The remaining six are required, and each is a closed set \(em
+.I rank
+is
+.BR Class1 ", " Class2 ", " Class3 " or " Class4 ,
+.I status
+is
+.B Feast
+or
+.BR Commemoration_only ,
+.I colour
+is
+.BR White ", " Red ", " Violet ", " Green ", " Black " or " Rose ,
+and
+.I subject
+is
+.BR Lord ", " Bvm ", " Saint " or " Temporal .
+See
 .I <prefix>/share/colitur/examples/diocesan\-example.sexp
 for a worked, runnable example of all four directives and all three date
 shapes: