Ship the hero as content: hero.js + site.yaml; docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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
+(image URL), and the landing page's `hero`:
-landing page. Absent file = the historical uhhm look (YES canvas,
+
-/wordmark.svg).
+```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