From 3ab9688fe12517a5a4e1317564792866502ee960 Mon Sep 17 00:00:00 2001
From: hermes <hermes@obahan.xyz>
Date: Mon, 5 Oct 2026 15:43:48 +0200
Subject: [PATCH] Add TRMNL e-ink feed endpoint /trmnl.json

---
 README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/README.md b/README.md
index 2a65b6e..0f9b5ac 100644
--- a/README.md
+++ b/README.md
@@ -37,4 +37,36 @@ docker compose up -d --build
 ## Endpoints
 
 - `GET /` — today's 5 jokes + link to the featured article
+- `GET /trmnl.json` — JSON feed for TRMNL e-ink displays (see `trmnl-plugin/`)
 - `GET /health` — JSON: whether today's jokes exist / retries exhausted
+
+## TRMNL e-ink feed
+
+`GET /trmnl.json` returns the day's jokes in a shape ready for a TRMNL
+Private Plugin with the **polling** strategy:
+
+```json
+{
+  "refresh_interval": 900,
+  "day": "2026-10-05",
+  "stale": false,
+  "article_title": "White-headed fruit dove",
+  "article_url": "https://en.wikipedia.org/...",
+  "jokes": [{"text": "..."}]
+}
+```
+
+Optional access token: set `TRMNL_TOKEN` in `.env`; requests must then carry
+`?token=<token>` or the header `trmnl-token: <token>` (put the token directly
+in TRMNL's polling URL or polling headers). Without the env var the endpoint
+is open — the jokes themselves are public anyway.
+
+Setup on my.trmnl.com:
+
+1. Plugins → New private plugin. Strategy **Polling**, URL
+   `https://wiki-jokes.obahan.xyz/trmnl.json` (+ token if enabled).
+2. Markup (Full layout): paste `trmnl-plugin/full.liquid`.
+3. Assign the plugin to your device's playlist.
+
+The template was verified to render against the live payload with
+python-liquid (5 items, day, stale flag).