Surface the readme.html feature in AI-facing hints (agents default to markdown + images)

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity

Closed feature request

Ray · 2mo ago ·closed by Colby Knox

Filing this after building adom/component-widgets, a page whose whole value is a set of reusable, interactive web-component widgets (pinout, heat-sink via, ganged molecule, chip thumbnail).

What happened

The page is only worth shipping if the widgets are live on it. But working from the wiki's own affordances, the AI (Claude) kept concluding the opposite: that the readme sandbox strips <iframe> and <script>, so the only option was to render each widget to a static PNG and inline the images. It built the entire page around images and reported that as done. That is wrong (a readme.html runs scripts inside a sandboxed iframe), but nothing in the live workflow corrected the assumption. It took a human on the team pointing at "the readme HTML feature" for the AI to find it.

Root cause

The capability is documented well in the wiki-readme-html skill. The gap is that nothing an agent actually touches while building a page points at it. README.md is the obvious default, markdown silently drops scripts and iframes, and none of the live surfaces (the publish/push linter, the pkg init scaffold, page create output, the repo push response) ever mention that a script-running readme.html variant exists. So an agent reasonably infers "interactive content is impossible here" and falls back to images.

Concrete hint additions that would have prevented it

Publish/push linter (highest leverage): when a README.md contains <iframe> or <script>, emit a hint like: "markdown strips these. For interactive content ship a readme.html, which renders in a sandboxed iframe with scripts enabled. See wiki-readme-html." It fires exactly when the author is reaching for something interactive.
page create / pkg init output: one line noting readme.html is a supported Overview variant for designed or interactive pages.
repo push response: when a readme.html lands at repo root, confirm "registered as the HTML readme variant (bareHtml). It now shadows README.md." Today that registration happens silently, so an agent cannot tell it worked.
Optionally expose the variant in a machine-readable place (page API or adom-wiki help) so agents can discover it without relying on prose.

Proof the platform is fine

adom/component-widgets now renders a readme.html with all four widgets live and cross-highlighting in the real sandbox: inline JSON (no fetch, since connect-src is none), inlined widget JS and fonts, and the readme-height reporter for sizing. Verified inside an actual sandbox="allow-scripts allow-downloads" opaque-origin iframe, not just a local file load. So the capability works end to end. The only thing missing was discoverability.

Happy to help wire any of the linter hints if that would save time.

1 Reply

Colby Knox · 2mo ago

Shipped to prod. Two push hints close the discovery loop: a README.md reaching for script or iframe gets README_HTML_FOR_INTERACTIVE (markdown strips these; ship a readme.html, which runs scripts in the sandboxed iframe and shadows README.md), and pushing a readme.html gets README_HTML_REGISTERED confirming the registration that used to happen silently, pointing at readme_variants_json for machine verification (your ask 4 already existed there). Staging-verified live with a real push carrying both files; both hints fired alongside the existing README_SHADOWED. The create-output line (ask 2) is CLI territory and noted for their tracker. Closing.