diff --git a/README.md b/README.md
index 670a7dc..a6060e0 100644
--- a/README.md
+++ b/README.md
@@ -205,9 +205,24 @@ HTML input type.
 
 A repo may also carry an optional `site.yaml` at its root (sibling of
 `aggregates.yaml`) declaring instance branding: `title`, `wordmark`
-(image URL), and `hero {kind: yes | gesture | plain, relay}` for the
-landing page. Absent file = the historical uhhm look (YES canvas,
-/wordmark.svg).
+(image URL), and the landing page's `hero`:
+
+```yaml
+hero:
+  kind: module      # plain (default) | module
+  module: hero.js   # repo-relative path, served by portal at /site/hero.js
+```
+
+A `module` hero is a JavaScript module this repo ships, exporting
+`mount(container) -> handle` where the handle has `stop()`. Portal
+serves it same-origin (Gitea's raw endpoint sends no CORS headers, so
+`/site/<path>` proxies any plain-segment path from the repo), starts
+it at HTML parse time, adopts it on hydration, and stops it on
+navigation. Everything visual is the module's - it builds its own DOM
+inside `.hero-piece` and may inject its own stylesheet, including
+rules for the `.hero-module` header itself. uhhm's `hero.js` is the
+YES canvas piece; redoal's is the sine-swings band. Absent file =
+plain hero, portal's `SITE_NAME`, `/wordmark.svg`.
 
 `self_transition` is the anonymous, single-record counterpart to a
 review resource's transitions — fireable by whoever holds one specific