Adom Wiki Skill Pack

@@ -0,0 +1,127 @@+---+name: wiki-readme-html+description: >-+  How to build a custom HTML readme (readme.html) for an Adom Wiki page — the+  fully designed, unsanitized alternative to README.md. Covers when to choose+  html over markdown, the shadowing rule (readme.html makes README.md invisible+  on the page), the sandboxed-iframe render pipeline and its exact limits+  (scripts run, but no same-origin, no cookies, no wiki API, external links and+  popups need care), self-containment (inline CSS/JS, base64 fonts/images,+  /blob/ asset URLs), the six readme variant slots (bare/public/private ×+  html/md), dark-theme styling so the page doesn't flash white, and the+  curl + pup verification loop. Read this BEFORE writing a readme.html and when+  one renders blank, unstyled, clipped, or won't update. Trigger words: html+  readme, readme.html, custom readme, custom html readme, designed readme,+  readme with tabs, readme with accordion, readme iframe, readme sandbox,+  readme shadowed, README_SHADOWED, readme.html not rendering, readme not+  updating, fully custom page layout, custom page body, unsanitized readme.+user-invocable: true+---++Parent skill: **adom-wiki-skillpack** · Sibling: **wiki-readme** (markdown mode ++the content rules that apply to BOTH modes)++# Building a custom HTML readme (readme.html)++Verified end to end 2026-07-15 with a live probe page (publish → API variants →+rendered iframe → styles applied → `<script>` ran).++## When to use html vs markdown++| Situation | Mode |+|---|---|+| Prose + images + tables sells the page fine | `README.md` (cheaper to write and maintain; see **wiki-readme**) |+| Tabs, accordions, toolbars, lightboxes, custom typography, interactive JS | `readme.html` |+| A component CAD hub with an Open-in toolbar + provenance lightbox | `readme.html` (see **wiki-component**) |++Markdown is still the right default. An HTML readme is a designed artifact: it+costs real effort to build well, and a half-styled HTML page reads worse than+clean markdown. Choose it when the layout IS the value.++## How to ship one++Put `readme.html` at the root of the publish tree and `adom-wiki pkg publish`.+The page registers it (API: `readme_variants_json.bareHtml = "readme.html"`)+and the Overview tab switches to HTML mode.++## The shadowing rule (the #1 gotcha)++`readme.html` **fully shadows README.md on the page**. The publish linter warns:+`README_SHADOWED: readme.html is what renders on the page, so edits to README.md+will not be visible.` Keep a README.md anyway — the Files tab, `repo clone`+readers, and git tooling still use it — but every page-visible edit goes in the+HTML file. If "my readme edit isn't showing up," check which file you edited.++## How it renders (and what the sandbox forbids)++Only HTML-mode pages get an iframe (markdown renders inline in the page). The+Overview embeds:++```+https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public+```++in `<iframe sandbox="allow-scripts allow-downloads">`. The endpoint serves your+file **byte-for-byte — no sanitizer**. Consequences:++- `<style>`, `style=`, and `<script>` all work. Scripts run inside the sandbox.+- **No `allow-same-origin`**: the iframe runs as an opaque origin. No cookies,+  no wiki session, no `fetch` to the wiki API, no localStorage. The readme+  cannot know who is viewing it or call authenticated endpoints.+- **No `allow-popups` / `allow-top-navigation`**: `target="_blank"` links and+  `window.open` are blocked by the sandbox. Plain same-frame links navigate the+  iframe itself, not the wiki page. Design navigation accordingly (prefer+  in-page JS interactions; verify any external link actually opens before+  relying on it).+- It is a full document of its own: include your own base styles; nothing+  cascades in from the wiki.++## Self-containment (assets)++Treat the file like an email template: everything inline.++- Inline all CSS and JS. Base64-inline fonts and small images.+- Repo files are reachable at absolute `/blob/<type>/<slug>/...` URLs for+  `<img>`/`<video>` — but note the known content-type bug (SVGs served as+  `application/octet-stream`, adom/wiki issue #38); PNG/JPG are safe.+- Never reference the hero image — the page header already renders it+  (**wiki-readme**'s #1 rule applies in both modes).++## Theme: the wiki is dark++The wiki chrome around your iframe is dark. A bare HTML file renders on a+default **white** body and will glare. Set your own background and text colors+explicitly (match the wiki's dark look or design deliberately), and follow the+Adom brand rules (tokens, brand fonts, monochrome icons, no emoji, no+em-dashes).++## Variants (public/private pages)++The page tracks six slots in `readme_variants_json`:+`bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd`.+A plain `readme.html` registers as `bareHtml`. The html-vs-md choice composes+with the private-readme system for private-source/public-releases pages+(**wiki-visibility**) — the `?variant=` query selects which one renders.++## Verify loop (do all three)++1. **curl the endpoint** — confirm your exact bytes are live:+   `curl -s "https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public"`+2. **Open the page in pup** (cache-bust `?v=<ver>`) and screenshot — confirm the+   iframe shows your layout, styles applied, at a sane height with no clipping+   or double scrollbars. Iframe sizing is controlled by the page, not you —+   if your content clips, restructure toward a natural document flow and+   re-verify. (Sizing behavior is not yet fully characterized; report surprises+   on adom/wiki.)+3. **Check any JS actually ran** — bake a visible self-test into the page while+   iterating (an element whose text a script rewrites), remove it when done.++## Pitfalls recap++- Edited README.md, page unchanged → shadowing rule; edit readme.html.+- Renders but unstyled/white → you assumed wiki CSS; the iframe gets nothing.+- Buttons/links dead → sandbox blocks popups/top-nav; keep interactions in-frame.+- Fetch to the wiki API fails → no same-origin; the readme is display-only.+- SVG `<img>` broken → content-type bug (issue #38); use PNG or inline the SVG markup.+- Works locally, stale on the wiki → you pushed the repo but didn't `pkg publish`+  (or vice versa); the readme the page renders comes from the published layer.