Adom Wiki Skill Pack

@@ -102,7 +102,7 @@ important enough to state up front: | **wiki-api** | The REST API + ``adom-wiki pkg`` CLI, the two storage layers, the publish workflow. | | **wiki-publish-safely** | The operational pitfalls as hard rules; the verify-in-pup gate. | | **wiki-readme** | How to make a great README: `README.md` vs `readme.html`, sections, embeds (YouTube player via `::youtube{}`), images. |-| **wiki-readme-html** | Build a custom `readme.html`: sandbox limits, shadowing, self-containment, theming, verify loop. |+| **wiki-readme-html** | Build a custom `readme.html` or a custom HTML section (`section_sources`): sandbox limits, shadowing, self-containment, theming, verify loop; one project's interactive tool goes here, never in the widget registry. | | **wiki-sub-readme** | Make a sub-readme (`<folder>/README.md`) and ALWAYS its section card in the main README (header, AI-made thumbnail, three sentences). The repo-push / path / verify gotchas. | | **wiki-visibility** | Public vs private source, public releases, the private readme, open vs closed pages. | | **wiki-repo-styles** | The archetype taxonomy (Page / Skillpack / Family) and how to choose. |@@ -129,6 +129,7 @@ important enough to state up front: - "Write a README for this page" → wiki-readme - "Embed a YouTube video / demo video in the README" → wiki-readme (`::youtube{id="VIDEO_ID"}`) - "I want a custom HTML readme / tabs / designed layout" → wiki-readme-html+- "Add an interactive explorer / simulator / calculator for this project" / "register it as a widget" → wiki-readme-html (a custom section or readme.html; the widget registry is for generic widgets only) - "Create me a sub-readme" / "make a sub-readme" / "my README is too long, split it" / "link a deep-dive doc" → wiki-sub-readme - "Keep the source private but let people install it" → wiki-visibility - "Ship my Hydrogen layout with the project" / "open the author's bench" / "WORKSPACE_URL_LOCAL" → wiki-workspaces

@@ -1,7 +1,7 @@ {   "slug": "adom-wiki-skillpack",   "title": "Adom Wiki Skill Pack",-  "version": "0.8.46",+  "version": "0.8.47",   "type": "skill",   "hero": {     "path": "screenshots/hero.png"

@@ -201,7 +201,7 @@       "prompt": "Before I create this wiki page, check whether the thing already has a home."     }   ],-  "version": "0.8.46",+  "version": "0.8.47",   "description": "The Adom Wiki Skill Pack : one main skill plus the focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, name the wiki repo archetypes (Page, Skillpack, Family), and publish rich component pages (chips, molecules, boards). The wiki is six tools in one: git, package manager, releases, discussions, pull requests, and discovery. One package manager install drops the whole set onto your container. Includes reviewed Z-up component artwork, surface-selected MPN marking, reusable thumbnail caches and component-page widgets. Includes canonical video widgets, synchronized captions and chapters, and voiceover pacing checks.",   "dependencies": {     "adom/adom-wiki-hero-image": "^0.2.2",

@@ -730,6 +730,11 @@ chip thumbnail, heat-sink via, molecule, table) live in **adom/component-widgets JSON in its `tools/`, and are registered in adom/widgets. Never host an ecosystem widget on a personal page (john/...): build it there and move it before anyone embeds it (John, 2026-10-04). +A widget is generic: every component page can use it with its own JSON. An interactive tool for one+board or one part (a circuit explorer, a simulator of that design) is not a widget and is never registered:+ship it on its own page as a custom section (page.json `section_sources`) or a `readme.html`. See+**wiki-readme-html**, "One project's tool is custom HTML, never a registry widget" (adom/widgets PR 6, 2026-10-20).+ ## Component states: `states.json` and the `::adom-states` widget (LEDs: off and on)  A part that LOOKS different when it is working carries one 3D model per state, so a viewer, a board render or a

@@ -14,7 +14,10 @@ description: >-   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.+  updating, fully custom page layout, custom page body, unsanitized readme,+  custom section, section_sources, sections, html section next to the readme,+  interactive explorer, circuit explorer, simulator, calculator, applet for my+  page, should this be a widget, register a widget, widgets.json, adom/widgets. user-invocable: true --- @@ -33,11 +36,59 @@ rendered iframe → styles applied → `<script>` ran). | 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**) |+| An interactive tool for this one project (explorer, simulator, calculator) next to a markdown README | `README.md` + a custom section (below) |  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. +## One project's tool is custom HTML, never a registry widget++The widget registry (`widgets.json` on adom/widgets) is for **generic** widgets:+one script that many pages reuse, each page passing its own data through+attributes or a `src` file (pinout, table, stock, video player). A tool built+for ONE project is not a widget, however polished: a circuit explorer for one+board, a simulator of one design, a calculator for one part. Its data lives in+its own script and only its own page can use it, so it goes on that page as+custom HTML. Do not open a PR against adom/widgets for it; such PRs are closed+(adom/widgets PR 6, 2026-10-20, John and Colby).++The test: could two unrelated pages each use it with their own data? If not, it+is custom HTML. Its two homes:++- **A custom section** next to the markdown README (below). Best when the page+  is mostly prose and the tool is one block of it.+- **`readme.html`**, when the designed layout IS the page.++Both get the same sandbox contract (the rest of this skill): opaque origin, no+cookies, `readme-height` to size the frame, the private-page capability.++## A custom section next to README.md (`section_sources`)++Declare a page-owned HTML file in page.json and list its name in `sections`:++```json+"section_sources": { "explorer": "explorer/index.html" },+"sections": ["hero", "viewers", "readme", "explorer", "deps", "breadcrumbs", "info"]+```++- It renders as its own main-column block with an `## Explorer` header (the name,+  title-cased) in a sandboxed frame behind a click-to-load slot, so nothing+  heavy loads until the reader asks.+- `sections` is an ALLOWLIST and the ORDER of the main column: list every block+  you still want (copy the page's current `sections` from+  `GET /api/pages/<owner>/<slug>` and insert your name). A name only in+  `section_sources` renders nothing.+- Names: lowercase slug, up to 24 characters, at most 8 sections, never a+  built-in name (`hero viewers install deps readme breadcrumbs info`).+  Paths: repo-relative `.html`, no `..`.+- **Inline the JS and CSS** in the HTML file. The wiki serves a `.js` file from+  `/render/` as a download (`application/octet-stream`, `nosniff`), so+  `<script src="tool.js">` does not run. Same self-containment rules as below.+- Post `readme-height` (see Sizing) or the frame stays at its default height.+- Push the HTML file before (or with) the page.json; a missing file answers+  `SECTION_SOURCE_MISSING` and renders an empty frame.+ ## How to ship one  Put `readme.html` at the root of the publish tree and `adom-wiki pkg publish`.

@@ -14,7 +14,8 @@ description: >-   readme, embed hero, hero image in readme, hero in the body, hero shows twice,   duplicate hero, repeated hero, don't repeat the hero, readme hero image, add   image to readme, readme screenshots, youtube video, embed youtube, youtube in-  readme, video player in readme, demo video, ::youtube.+  readme, video player in readme, demo video, ::youtube, interactive tool in+  readme, explorer in readme, applet, custom section, should this be a widget. ---  Parent skill: **adom-wiki-skillpack**@@ -62,6 +63,15 @@ Ship a `readme.html` in the publish tree and `pkg publish`. That's it.   is the mode the old "standalone prototype in the container" workaround was   waiting for; prototype straight in `readme.html` now. +## Interactive tools: custom HTML, not a widget++A `::adom-...` tag is a registry widget: generic, reused by many pages with+their own data. An interactive tool made for THIS project (an explorer for this+board, a simulator of this design) never goes in the registry. Ship it as a+custom section next to this README (page.json `section_sources`) or as the+whole `readme.html`. See **wiki-readme-html**, "One project's tool is custom+HTML, never a registry widget".+ ## Markdown mode: what HTML survives (the sanitizer reality)  The rendered README.md is run through `sanitize-html` with a **strict allowlist**.