diff --git a/CLAUDE.md b/CLAUDE.md
index 0ee50ef..8ea81e9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,3 +19,39 @@ update these together before considering the task done:
 
 Internal/invisible changes (refactors, tooling, comments) don't need a
 version bump or changelog entry.
+
+## When the OTE spec publishes a new version
+
+The support window is the last three minors, computed — not listed — so
+one edit moves it:
+
+1. Append the new version to `PUBLISHED_SPEC_VERSIONS` in `app.js`. The
+   window, the latest version and every message derive from it.
+2. Update the **OTE spec badge range** at the top of `README.md` (e.g.
+   `v0.4 – v0.6`). This is the one thing nothing checks for you — see
+   below.
+
+`npm run check` reads the npm registry and the published event schema and
+fails when `PUBLISHED_SPEC_VERSIONS` or `INHERITED_FEED_FIELDS` in
+`app.js` have drifted from them. It does **not** look at the README, so
+the badge goes stale silently.
+
+A document is always judged against the version it *declares*, never
+against the latest one, and a feed outside the window still opens — being
+on an older release is a notice, never a defect, and no message blames
+the publisher. Deliberately no dependency on `@opentechevents/validate`:
+a reader must be more tolerant than a validator. The reasoning is in
+README under "OTE spec version support"; don't re-litigate it without
+reading that first.
+
+## When `<ote-events>` publishes a new version
+
+The widget is pinned by URL in `index.html` (`/embed/vX.Y.Z/`) and is a
+separate version line from the OTE spec — the widget's own
+`oteSpecVersion` says which spec release it targets, and it lags. Before
+bumping, check the widget's **source** for the attributes and properties
+this app sets (`layout`, `group-events`, `fields-preview`,
+`fields-detail`, `show-past`, `sort`, `event-actions`, `theme`, and
+`events` / `eventActions` / `eventClassName` / `eventBadges`), then
+verify in a browser — the reader renders nothing itself, so a widget
+regression is invisible to `npm run check`.
diff --git a/README.md b/README.md
index 61508b6..4150e1b 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,16 @@
 # OTE Reader
 
+[![Deploy GitHub Pages](https://github.com/OpenTechEvents/ote-reader/actions/workflows/pages.yml/badge.svg)](https://github.com/OpenTechEvents/ote-reader/actions/workflows/pages.yml)
+[![OTE spec](https://img.shields.io/badge/OTE%20spec-v0.4%20%E2%80%93%20v0.6-2563eb)](#ote-spec-version-support)
+[![Reader](https://img.shields.io/badge/reader-opentechevents.org-2563eb)](https://reader.opentechevents.org)
+![PWA](https://img.shields.io/badge/PWA-offline--first-5b21b6)
+![Build step](https://img.shields.io/badge/build%20step-none-555555)
+![License](https://img.shields.io/badge/license-MIT-339933)
+
+Supported OTE spec minors: **0.4, 0.5, 0.6** — the last three published minors,
+computed at runtime from `PUBLISHED_SPEC_VERSIONS` in `app.js`. Feeds outside
+that window still open; see [OTE spec version support](#ote-spec-version-support).
+
 Attendee-facing MVP for OpenTechEvents feeds.
 
 The first version is a static PWA that lets people: