diff --git a/pages/README.md b/pages/README.md
new file mode 100644
index 0000000..88fe7d1
--- /dev/null
+++ b/pages/README.md
@@ -0,0 +1,11 @@
+# Teahub pages (`green-tea-pages`)
+
+The pages convention for orgs on prod: an org's public `site` repo is served at its domain. `PAGES_SITES` in
+`fly.toml` maps hostnames to `org/site`. The server clones each repo over https (no token), serves static files
+(directory → `index.html`, missing → `404.html`), and re-pulls every 5 minutes or on `POST /_hook/<org>/site`
+(a Gitea webhook on the repo, push events, no secret: the hook only triggers a pull of public content).
+
+Adding a site: a line in `PAGES_SITES` + `fly deploy` (operator lane), `fly certs add <host>`, the `_acme-challenge`
+CNAME, then A/AAAA to the app's IPs (`fly ips list`), and a push webhook on the `site` repo.
+
+Live: persimmons.app → `persimmons/site`, phast.app → `phast/site`.