1 files changed, 37 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e7b8c6e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# colitur-x
+
+A raw Xlib front-end for [colitur](../colitur): reads `colitur emit --format
+csv` on stdin, draws the year as a month grid coloured by each day's
+liturgical colour, and shows the selected day's readings underneath.
+
+    colitur emit --format csv --from 2027 --to 2027 | colitur-x
+
+Keys: arrows or `hjkl` move, `n`/`p` change month, `q` quits.
+
+## Why it exists
+
+colitur is a Unix tool: it computes and prints. This is a separate program
+that composes with it, so colitur's own dependencies stay frozen
+(`dune alcotest qcheck qcheck-alcotest sexplib ppx_sexp_conv`) and its
+kernel stays pure.
+
+## Build
+
+    make
+
+`-std=c99 -Os -Wall -Wextra`, linking libX11 and libXft. ~17 KB.
+
+Configuration is compile-time, suckless style: edit `config.h` and rebuild.
+There is deliberately no runtime config file — colitur itself owns the
+calendar's configuration (language, sigla, overlays); this program owns only
+how it is painted.
+
+## Limits, stated rather than discovered
+
+- X11 only. Runs under XWayland but is not a Wayland client.
+- Read-only. It renders what colitur emits; it edits nothing.
+- Xft is used for antialiasing and UTF-8. Dropping it for core X11 fonts
+  would reduce the dependency list to libX11 and libc alone, at the cost of
+  correct rendering for `æ`/`œ` and Polish diacritics. Not worth it.
+- A tiling window manager will ignore the size hints and give the grid its
+  own tile; the layout handles that, the empty space is the WM's choice.