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.

1 files changed, 18 insertions, 0 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