diff --git a/README.md b/README.md
index c2a5f3c..4835a3c 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,43 @@
-IyB3cC11cGRhdGVzCgpTaGFyZWQsIHNlbGYtaG9zdGVkICoqdXBkYXRlIGNoYW5uZWwqKiBmb3IgdGhlIGB3b3JkcHJlc3NgIG9yZydzIFdvcmRQcmVzcwpwcm9qZWN0cy4gSXQgaXMgdGhlIGNvdW50ZXJwYXJ0IHRvIGBlZS1leHRlbnNpb25zL2ZvaC11cGRhdGVzYDogYSBwbGFpbiwKcHVibGljIHJlcG8gdGhhdCBob3N0cyB0aGUgdXBkYXRlICoqbWFuaWZlc3RzKiogYW5kIHJlbGVhc2UgcGF5bG9hZHMgdGhhdApXb3JkUHJlc3MgaW5zdGFsbHMgcHVsbCBmcm9tLgoKIyMgV2hhdCBsaXZlcyBoZXJlCgpFYWNoIG1hbmFnZWQgcHJvamVjdCBnZXRzOgoKLSBge3NsdWd9Lmpzb25gIOKAlCB0aGUgUFVDLWNvbXBhdGlibGUgSlNPTiBtYW5pZmVzdCAoYXQgbWluaW11bSBgdmVyc2lvbmAgYW5kCiAgYGRvd25sb2FkX3VybGA7IGV2ZXJ5IG90aGVyIFBVQyBmaWVsZCBpcyBvcHRpb25hbCBhbmQgZW5yaWNoZXMgdGhlIFVwZGF0ZXMKICBzY3JlZW4gLyAiVmlldyBkZXRhaWxzIiBtb2RhbCkuCi0gYHtzbHVnfS9gIOKAlCBhIGRpcmVjdG9yeSBmb3IgdGhhdCBwcm9qZWN0J3MgcmVsZWFzZSBhc3NldHMgKHppcHMsIGljb25zLAogIGJhbm5lcnMsIHNjcmVlbnNob3RzKSByZWZlcmVuY2VkIGJ5IGl0cyBtYW5pZmVzdC4KCmBtYW5pZmVzdC11cGRhdGVyYCBpcyB0aGUgZmlyc3QgcmVzaWRlbnQgKGBtYW5pZmVzdC11cGRhdGVyLmpzb25gICsKYG1hbmlmZXN0LXVwZGF0ZXIvYCkuIFRoZSBjaGFubmVsIGNhbiBob3N0IG1hbnkgcHJvamVjdHMgc2lkZSBieSBzaWRlLCBleGFjdGx5Cmxpa2UgYGVlLWV4dGVuc2lvbnMvZm9oLXVwZGF0ZXNgIGRvZXMuCgojIyBIb3cgaXQncyBjb25zdW1lZAoKUHJvamVjdHMgb3B0IGluIHRocm91Z2ggdGhlaXIgV29yZFByZXNzICoqYFVwZGF0ZSBVUkk6YCoqIGhlYWRlciwgcG9pbnRpbmcgYXQKdGhpcyByZXBvJ3MgcmF3IG1hbmlmZXN0IFVSTCB3aXRoIGEgYCNtYW5pZmVzdC11cGRhdGVyLmpzb25gIGZyYWdtZW50LCBlLmcuOgoKYGBgClVwZGF0ZSBVUkk6IGh0dHBzOi8vZ2l0ZWEubXVsbGlnYW4uY2FzYS93b3JkcHJlc3Mvd3AtdXBkYXRlcy9yYXcvYnJhbmNoL21haW4vbWFuaWZlc3QtdXBkYXRlci5qc29uI21hbmlmZXN0LXVwZGF0ZXIuanNvbgpgYGAKClRoZSBuZXR3b3JrLWFjdGl2YXRlZCAqKm1hbmlmZXN0LXVwZGF0ZXIqKiBwbHVnaW4gcmVhZHMgdGhhdCBoZWFkZXIsIGZldGNoZXMgdGhlCm1hbmlmZXN0IGZyb20gaGVyZSwgYW5kIHN1cmZhY2VzIHRoZSB1cGRhdGUgdGhyb3VnaCBXb3JkUHJlc3MncyBuYXRpdmUgUGx1Z2lucyAvClVwZGF0ZXMgc2NyZWVucy4KCiMjIE11c3QgcmVtYWluIHB1YmxpYwoKSW5zdGFsbGVkIHNpdGVzIGZldGNoIG1hbmlmZXN0cyBhbmQgcmVsZWFzZSBwYXlsb2FkcyBvdmVyIHVuYXV0aGVudGljYXRlZApgcmF3L2JyYW5jaC9tYWluLy4uLmAgVVJMcy4gKipUaGlzIHJlcG9zaXRvcnkgbXVzdCBzdGF5IHB1YmxpYyoqIOKAlCBtYWtpbmcgaXQKcHJpdmF0ZSBicmVha3Mgc2VsZi11cGRhdGVzIGZvciBldmVyeSBwcm9qZWN0IHRoYXQgcG9pbnRzIGl0cyBgVXBkYXRlIFVSSTpgCmhlcmUuCg==
\ No newline at end of file
+# wp-updates
+
+Shared, self-hosted **update channel** for the `wordpress` org's WordPress
+projects. It is the counterpart to `ee-extensions/foh-updates`: a plain,
+public repo that hosts the update **manifests** and release payloads that
+WordPress installs pull from.
+
+## What lives here
+
+Each managed project gets:
+
+- `{slug}.json` — the PUC-compatible JSON manifest (at minimum `version` and
+  `download_url`; every other PUC field is optional and enriches the Updates
+  screen / "View details" modal).
+- `{slug}/` — a directory for that project's release assets (zips, icons,
+  banners, screenshots) referenced by its manifest.
+
+These files are not hand-edited: each project's release CI publishes its
+manifest and zip here on release.
+
+`manifest-updater` is the first resident (`manifest-updater.json` +
+`manifest-updater/`). The channel can host many projects side by side, exactly
+like `ee-extensions/foh-updates` does.
+
+## How it's consumed
+
+Projects opt in through their WordPress **`Update URI:`** header, pointing at
+this repo's raw manifest URL with a `#manifest-updater.json` fragment, e.g.:
+
+```
+Update URI: https://gitea.mulligan.casa/wordpress/wp-updates/raw/branch/main/manifest-updater.json#manifest-updater.json
+```
+
+The network-activated **manifest-updater** plugin reads that header, fetches the
+manifest from here, and surfaces the update through WordPress's native Plugins /
+Updates screens.
+
+## Must remain public
+
+Installed sites fetch manifests and release payloads over unauthenticated
+`raw/branch/main/...` URLs. **This repository must stay public** — making it
+private breaks self-updates for every project that points its `Update URI:`
+here.