diff --git a/README.md b/README.md
index f7cfe39..bd33e06 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,20 @@
-# maineaa-updates
+# maineaa-updates — update channel for the Maine AA Area 28 theme
 
-Self-hosted update channel for the aa/maineaa GeneratePress child theme (manifest + zips, consumed anonymously by WordPress). Must remain public.
\ No newline at end of file
+This repository is the **self-hosted update channel** for the
+[`aa/maineaa`](https://gitea.mulligan.casa/aa/maineaa) GeneratePress child theme
+(Maine AA Area 28). It is consumed by the **`manifest-updater`** WordPress plugin
+via the theme's `Update URI` header, which points at the manifest published here.
+
+## How it works
+
+- The shared build/publish script (`release.sh`) lives in
+  **`ee-extensions/foh-updates/.ci/`** and runs from the theme repo's CI on a
+  tagged (`v*`) release.
+- On each tagged release it publishes here automatically:
+  - **`maineaa.json`** — the update manifest the plugin reads.
+  - **`maineaa/maineaa-<version>.zip`** — the versioned theme package.
+- WordPress fetches the manifest and zip **anonymously**, so
+  **this repository must remain public.** Do not make it private.
+
+This repo starts nearly empty; the manifest and versioned zips appear
+automatically on the first tagged release of `aa/maineaa`.