Adom Wiki Skill Pack

@@ -2,23 +2,10 @@ name: adom-wiki-skillpack user-invocable: true description: >--  The Adom Wiki Skill Pack, the entry point for working with the Adom Wiki-  (wiki.adom.inc). Read this BEFORE creating, publishing, or restructuring any-  wiki page. The wiki is six tools in one (git host + wiki package manager (`adom-wiki pkg`) +-  release database + discussion forum + pull requests + discovery), and three repo-  archetypes have emerged from real use: Page, Skillpack, and Family. This pack-  routes to 24 focused sub-skills and carries the hard rules that keep pages from-  breaking. Trigger words: adompkg (deprecated old name), the wiki, adom wiki, wiki.adom.inc, publish to the-  wiki, wiki repo, wiki page, what kind of wiki repo, repo archetype, skillpack,-  super-skill, wiki family, parent child repo, wiki readme, hero unlinked,-  proprietary wiki page, private source public app, wiki breadcrumb, fork a wiki-  page, wiki discovery, page not surfacing, wiki scoring, trending, high five,-  adom-wiki pkg publish, publish a chip, component page, chip page, molecule page,-  tape and reel, pin 1 orientation, cached chip thumbnails, Z-up component hero,-  reviewed laser etch, reusable chip outlines, component page widget, shared-  workspace, hydrogen/workspace.json, ship my Hydrogen layout, open in Hydrogen,-  brand guide, my brand, whose brand, owner brand, brand.json,-  hero GLB, adomLayer, layer intro, extras.tooltip, viewer_3d, KHR_lights_punctual.+  Hub for authoring Adom Wiki pages: pick the repo archetype (Page, Skillpack, Family), the+  page-breaking rules, and the map of the wiki-* authoring skills. Use when creating or+  restructuring a wiki page, writing its README or hero, or publishing a chip, molecule or board+  page. ---  # Adom Wiki Skill Pack@@ -28,6 +15,11 @@ pack is the map for working with it, and it is the **source of truth**: the skills here plus the repo archetypes that have emerged from heavy real-world use. Update this pack directly when the wiki changes. +**Which wiki skill?** `wiki-publish-safely` before and after any publish;+`wiki-discovery` to find a tool or make a page findable; `wiki` for how the system+works (repo vs registry, source vs release, skill tiers); `adom-wiki-cli` for exact+commands and flags; `wiki-api` for raw REST calls; this pack for authoring a page.+ > **`adompkg` is the deprecated old name of the package manager.** It is dead; do not run it. Every old `adompkg <verb>` maps to `adom-wiki pkg|page|repo|release <verb>` (e.g. `adompkg publish` -> `adom-wiki pkg publish`, `adompkg install` -> `adom-wiki pkg install`). If a doc or a user says adompkg, translate and continue.  ## The wiki is six tools in one@@ -58,9 +50,9 @@ actual sandboxed player. Requests such as "add captions", "no dead air",  | Archetype | One line | Examples | Build skill | |---|---|---|---|-| **Page** | One page = one thing. Open-source (public source) or Closed-source (private source, public compiled app). | chip-fetcher, adom-usb / hydrogen-desktop, adom-desktop | wiki-visibility |+| **Page** | One page = one thing. Open-source (public source) or Closed-source (private source, public compiled app). | adom-usb / hydrogen, adom-bridge | wiki-visibility | | **Skillpack** | One repo, one main skill + N sub-skills, installed together. Suffix `-skillpack`. | adom-ui-design, **this pack** | wiki-skillpack |-| **Family** | An anchor page + children published as separate pages, joined by naming + a family tag + breadcrumbs. | adom-desktop, adom-usb | wiki-family |+| **Family** | An anchor page + children published as separate pages, joined by naming + a family tag + breadcrumbs. | adom-usb (+ adom-usb-sniffer-*), adom-bridge (+ bridge pages like kicad-bridge) | wiki-family |  Decision: **Skillpack** when one author owns all the skills and they version together; **Family** when children have independent owners or update cadences@@ -109,15 +101,18 @@ important enough to state up front: | **wiki-component** | Publish a component page: chip / molecule / board; the tabbed chip CAD-hub README. | | **wiki-family** | Build a Family: naming convention, family tag, anchor registry, breadcrumbs, built-from template provenance. | | **wiki-skillpack** | Build a Skillpack: layout, install.sh, files[], skill map, the `-skillpack` suffix. |-| **wiki-hero** | The hero image: generate it (adom-wiki-hero-image), and never let it get unlinked. |+| **wiki-hero** | The hero image in `page.json`, and never let it get unlinked (make it with wiki-hero-studio). | | **wiki-hero-studio** | Generate the page hero: RUN `hero-studio pose <owner/slug>` (human clicks Generate). Do NOT open its wiki page. | | **wiki-breadcrumbs** | Third-party "I built an add-on for X" links: the breadcrumb system. | | **wiki-forking** | Fork + community-PR contribution flow (PRs live; fork-button planned). | | **wiki-discovery** | How pages get found: the two layers, current state, and the TODO list. |-| **wiki-scoring** | Stars / high-fives / installs / trending: what's tracked and how to earn it. |+| **wiki-scoring** | Stars / vouches / installs / trending: what's tracked and how to earn it. | | **wiki-workspaces** | Ship a Hydrogen bench with a project: `hydrogen/workspace.json` (panes + apps by wiki page), export with adom-cli, push, fork or clone, apply in a container; the WORKSPACE_* hints. | | **wiki-brand** | Whose brand a page wears: every owner's guide at `<owner>/brand` (brand.json, fonts, logos), `adom-wiki brand show|pull|set|push|confirm`, the BRAND_* hints, and the rule that Adom's look belongs only on adom pages. | | **wiki-hero-glb** | What the wiki's 3D viewer reads from a GLB: `extras.adomLayer` (+ the hidden-layer `intro`), `extras.tooltip`, `adomRole` groups and lights, `component.viewer_3d` and the `?repeat= ?loop= ?animate=` knobs, honoured glTF extensions, materials, node naming, which model the page shows. |+| **wiki-readme-slideshow** | A narrated, fullscreen slideshow inside a `readme.html` (per-slide TTS, arrow keys). |+| **wiki-video-captions** | A narrated `::adom-video` in a README with WebVTT captions and chapters. |+| **wiki-component-lod** | High/medium/low component GLB detail caches for heavy board scenes. | | **wiki-bloat** | THE rule against page sprawl: find where a thing already lives BEFORE creating anything; "add to the skillpack" means add a SKILL.md there, never mint a page. |  ## Talk to the AI

@@ -1,7 +1,8 @@ {   "slug": "adom-wiki-skillpack",   "title": "Adom Wiki Skill Pack",-  "version": "0.8.51",+  "version": "0.8.52",+  "changelog": "0.8.52: skill cleanup: shorter valid descriptions (sub-skills name this pack as their hub), no global entry-point claims, retired names (adom-desktop, hydrogen-desktop) replaced, dead skill links fixed, pup_* verbs in the verify step.",   "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.51",+  "version": "0.8.52",   "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",@@ -265,5 +265,6 @@     "name": "Colby Knox",     "email": "[email protected]"   },-  "org": "adom"+  "org": "adom",+  "changelog": "0.8.52: skill cleanup: shorter valid descriptions (sub-skills name this pack as their hub), no global entry-point claims, retired names (adom-desktop, hydrogen-desktop) replaced, dead skill links fixed, pup_* verbs in the verify step." }\ No newline at end of file

@@ -1,14 +1,8 @@ --- name: wiki-anatomy description: >--  The mental model of the Adom Wiki (wiki.adom.inc): it is five familiar tools-  fused into one product keyed off a single slug per page, a git host, the-  wiki package manager (`adom-wiki pkg`), a release database, a discussion forum, pull requests,-  and discovery, plus a presentation layer. Read this to understand WHAT the wiki-  is before learning HOW to drive it. Trigger words: what is the adom wiki, how-  does the wiki work, wiki architecture, wiki mental model, git plus npm plus-  releases, wiki page is a repo, two storage layers, why both git and registry,-  wiki anatomy, explain the wiki, six tools in one.+  Mental model of the wiki: one slug = git repo + registry + releases + issues/PRs + discovery.+  Part of adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**

@@ -1,13 +1,9 @@ --- name: wiki-api description: >--  How to drive the Adom Wiki (wiki.adom.inc) programmatically: the `adom-wiki pkg` CLI,-  the REST API (/api/v1/...), authentication, and the publish workflow that-  writes BOTH storage layers (git repo + package registry). Read this before any-  create-page, push-files, or publish call. Trigger words: wiki api, `adom-wiki pkg`,-  adom-wiki pkg publish, adom-wiki pkg install, POST pages, push files to wiki, wiki rest-  api, publish to the wiki, create wiki page, commit to wiki repo, wiki bearer-  token, adom-wiki auth, two storage layers, wiki tarball.+  The Adom Wiki REST API (/api/v1) and auth: bearer token, raw HTTP calls, the publish order that+  writes both storage layers, the text-vs-base64 rule. Use when calling the wiki API directly,+  scripting without the CLI, pushing files over HTTP, or debugging a 401 or 429. ---  Parent skill: **adom-wiki-skillpack**

@@ -1,7 +1,8 @@ --- name: wiki-bloat description: >--  Wiki-bloat is when wayyyy too many wiki pages are being made. THE rule against it, straight from John (Adom's founder): before creating ANYTHING on the wiki, first find where that thing should already live, and put it there. "Add it to the skillpack" means literally that, locate the existing pack's repo and add a SKILL.md file to it; it never means mint a new page. Read this BEFORE any POST /pages, any new slug, any "should this be its own page" moment. Trigger words: wiki bloat, wiki-bloat, too many wiki pages, too many pages, should this be a page, new wiki page, create a wiki page, standalone page or skillpack, where should this skill live, add a skill to the pack, fold into existing, one page too many, page sprawl, new slug.+  Before creating any wiki page or slug: find where the thing already lives and add it there. Part+  of adom-wiki-skillpack. ---  # Wiki-bloat, and how not to cause it@@ -101,7 +102,7 @@ wiki-bloat?"* Three homes already existed, and the agent had touched two of them that same session:  - **`adom/adom-tsci` already owns `guides/export-wiki.md`** — literally a guide on this exact-  subject, with a deploy path (`adom-tsci install` → `~/.claude/skills/adom-tsci/guides/`) so+  subject, with a deploy path (`adom-tsci install` → `~/.claude/skills/adom-tsci/guides/`, present only where adom-tsci is installed) so   it reaches every user of the app automatically. The agent had READ this guide earlier in the   session to learn the publish flow, and still did not put the content back into it. - **`wiki-readme-html` in this pack** already documented the storage shim, the `blob:`→`data:`

@@ -1,25 +1,16 @@ --- name: wiki-brand description: >--  Whose brand a wiki page wears, and how to read and edit it. Every owner (a-  user or an org) has one brand guide at <owner>/brand: brand.json (colors,-  fonts, logos), SKILL.md, the logo files. Heroes, composed billboards and-  AI-built pages use the PAGE OWNER's guide, never Adom's on someone else's-  page. Read this before any visual work on a page you do not own, when a-  publish returns BRAND_GUIDE_STARTER or BRAND_GUIDE_MISSING, when a resolver-  says starter/missing/invalid/private, or when someone asks for their colors,-  fonts, logo, brand guide, wordmark, or "make it look like my brand".-  Trigger words: brand guide, brand.json, whose brand, owner brand, my colors,-  my fonts, my logo, wordmark, kcknox brand, org brand, adom-wiki brand,-  BRAND_GUIDE_STARTER, BRAND_GUIDE_MISSING, BRAND_JSON_INVALID, BRAND_EDITORS,-  confirm the brand, starter guide, /api/owners/<owner>/brand.+  Whose brand a page wears (<owner>/brand, brand.json) and the BRAND_GUIDE_* hints. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**  # wiki-brand: whose brand a page wears -Adom's own guide is the `brand` skill (page `adom/brand`); this skill is about+Adom's own guide is the `brand` skill (page `adom/brand`; `adom-wiki pkg install adom/brand`+ships it); this skill is about EVERY owner's guide, including Adom's, and the rule that decides which one applies. 

@@ -1,15 +1,8 @@ --- name: wiki-breadcrumbs description: >--  The breadcrumb system on the Adom Wiki, how a third party attaches a small-  "trail marker" link to someone else's page to announce a related thing they-  built ("I made a new OrCAD bridge, so adom-desktop should know an add-on-  exists"), without editing that page. Like Hansel & Gretel dropping breadcrumbs-  so a path can be followed back. Read this when an add-on/plugin/bridge for an-  existing page needs to be discoverable from it. Trigger words: wiki breadcrumb,-  attach a breadcrumb, announce an add-on, third party plugin link, new bridge for-  adom-desktop, link my page to another, trail marker, discover add-ons, breadcrumb-  api.+  Breadcrumbs: link your add-on from someone else's page without editing it. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -29,10 +22,10 @@ mark a trail to a related thing they built, without needing edit rights on that page. The metaphor is the fairy tale: drop breadcrumbs through the forest so a path can be followed. -The motivating case: someone builds a **new OrCAD bridge** for `adom-desktop`.-They don't own `adom-desktop` and shouldn't edit it, but `adom-desktop` (and its+The motivating case: someone builds a **new OrCAD bridge** for `adom-bridge`.+They don't own `adom-bridge` and shouldn't edit it, but `adom-bridge` (and its users, and the AI) should be able to discover that a new add-on bridge exists. So-they drop a breadcrumb on `adom-desktop` pointing at their bridge page. Now the+they drop a breadcrumb on `adom-bridge` pointing at their bridge page. Now the anchor surfaces "add-ons that lead here," and the trail is followable both ways.  ## How it fits the archetypes

@@ -1,6 +1,8 @@ --- name: wiki-component-lod-description: "Create and reuse high, medium, low and super-low component GLB detail caches; stream reviewed wiki component artwork into Babylon board, scaffold and digital-twin views without exhausting GPU memory. Covers LOD (also called LDO), zoom-driven detail, cached laser-etch fidelity, draw-call budgets and freeze prevention."+description: >-+  High/medium/low component GLB detail caches for heavy Babylon board scenes. Part of+  adom-wiki-skillpack. --- # Component detail caches and resource-aware assembly 

@@ -1,18 +1,9 @@ --- name: wiki-discovery description: >--  Discovery on the Adom Wiki, a FIRST-CLASS component of the wiki, peer to git,-  `adom-wiki pkg`, releases, discussions, and pull requests. How pages/skills get FOUND:-  the two layers (local installed-skill matching vs the registry /discover + search-  endpoints), how to make a page discoverable (manifest + page discovery_triggers),-  how `adom-wiki discover find "<the user's own words>"` ranks pages, the-  current state, and what discovery still needs. Read this when a page won't surface, when setting-  discovery triggers, or when reasoning about how the AI finds the right skill.-  Trigger words: wiki discovery, discover endpoint, discovery_triggers, page not-  surfacing, skill not found, how does the AI find skills, wiki search, make a page-  discoverable, trigger words, /discover, registry discovery, why isn't my page-  showing up, discover find, find a skill I don't have, is there a tool for this,-  is there an app for.+  Finding things on the Adom Wiki: `adom-wiki discover find "<the user's words>"`, search filters,+  discovery_triggers and the prompt hook. Use when asked "is there a tool/app/skill for X", to+  find a skill you do not have, or when a page will not surface in search. ---  Parent skill: **adom-wiki-skillpack**@@ -162,7 +153,7 @@ it never makes the hook speak up, by design. ## Relationship to scoring  Discovery answers "can this be found?"; **wiki-scoring** covers the engagement-signals (stars / high-fives / installs / trending) that *rank* what's found. They+signals (stars / vouches / installs / trending) that *rank* what's found. They are linked, ranking is part of discovery, but distinct: a page can be perfectly discoverable with zero stars, and discovery should surface it on relevance, with scoring breaking ties among relevant results.

@@ -1,15 +1,8 @@ --- name: wiki-family description: >--  How to build a Family-style wiki repo on the Adom Wiki, an anchor page plus-  children published as their own pages, joined by a naming convention, a family-  tag, and breadcrumbs (e.g. adom-usb + adom-usb-sniffer-cdc, adom-desktop +-  bridges). Use this when a hub has parts that need their own owners or release-  cadence, or when adding a child/plugin to an existing family. Trigger words:-  wiki family repo, parent child wiki page, add a plugin to the family, anchor-  page, family tag, name a child page, adom-usb plugin, adom-desktop bridge,-  publish a child page, family naming convention, register a child,-  template revision, built_from, which template made this child, family provenance.+  Family repos: an anchor page plus separately published children, naming and family tag. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -20,7 +13,7 @@ A **Family** is an anchor page plus children published as **separate** wiki page (not files in one repo), joined by convention so the relationship survives even when a child is seen out of context. Use it when children need independent owners or update cadences, see **wiki-repo-styles** for Family-vs-Skillpack. Examples:-`adom-usb` (+ sniffer/firmware plugins), `adom-desktop` (+ bridges).+`adom-usb` (+ sniffer/firmware plugins), `adom-bridge` (+ bridges).  ## 1. Naming: every member announces its family @@ -39,7 +32,7 @@ exactly this format, every time, identically across siblings: ```  - Separator is a **space, a plain ASCII hyphen `-`, and a space** (`" - "`).-- The parent is its **proper Title Case** product name (`Adom USB`, `Adom Desktop`),+- The parent is its **proper Title Case** product name (`Adom USB`, `Adom Bridge`),   NOT the slug. - **NEVER** a colon (`:`), an em-dash (`,`) or en-dash (`–`), a slug-style hyphen   with no spaces, or the bare descriptor on its own.@@ -48,11 +41,11 @@ exactly this format, every time, identically across siblings: |---|---|---| | `Adom USB - CDC serial sniffer` | `CDC serial sniffer` | bare descriptor: hides the family | | `Adom USB - RP2040 persona pack` | `adom-usb-stub-rp2040` | slug used as the title |-| `Adom Desktop - KiCad Bridge` | `Adom Desktop: KiCad Bridge` | colon, not `" - "` |-| `Adom Desktop - Bridge SDK` | `Adom Desktop: Bridge SDK` | em-dash, not ASCII hyphen |-| `Adom Desktop - Altium Bridge` | `adom-desktop-altium-bridge` | slug as title (a real offender) |-| `Adom Desktop - Demo` | `Demo` | orphan: doesn't announce the family at all |-| `Adom Desktop - Bridges Registry` | `Adom Desktop Bridges Registry` | no `" - "` separator |+| `Adom Bridge - KiCad Bridge` | `Adom Bridge: KiCad Bridge` | colon, not `" - "` |+| `Adom Bridge - Bridge SDK` | `Adom Bridge: Bridge SDK` | em-dash, not ASCII hyphen |+| `Adom Bridge - Altium Bridge` | `adom-desktop-altium-bridge` | slug as title (a real offender, from the retired adom-desktop name) |+| `Adom Bridge - Demo` | `Demo` | orphan: doesn't announce the family at all |+| `Adom Bridge - Bridges Registry` | `Adom Bridge Bridges Registry` | no `" - "` separator |  (The ❌ column is drawn from real inconsistencies already on the wiki, colons, em-dashes, slug-as-title, and orphan titles all exist today. Match the ✅ column.)@@ -60,7 +53,7 @@ em-dashes, slug-as-title, and orphan titles all exist today. Match the ✅ colum ### The slug: dashes, no spaces  - **Slug**: `<parent>-<descriptor>`, `adom-usb-sniffer-cdc`,-  `adom-desktop-kicad-bridge`. Dash separators, lowercase, **never a colon**+  `adom-usb-stub-teensy`. Dash separators, lowercase, **never a colon**   (illegal in slugs) and never spaces. The slug is NOT the title, convert it to   the spaced, Title-Cased form above for the `title` field. 

@@ -1,14 +1,8 @@ --- name: wiki-forking description: >--  Forking and community contribution on the Adom Wiki, how someone who doesn't-  own a page proposes changes to it. Pull requests are live (propose edits to a-  page's repo, the owner reviews and merges); a dedicated fork button is planned.-  Read this when contributing to a wiki repo you don't own, or planning the-  community-contribution path for a repo you do. Trigger words: fork a wiki page,-  fork wiki repo, contribute to a wiki page, propose changes wiki, wiki pull-  request, wiki PR, community update wiki, submit a change to someone's page,-  review a wiki PR, accept community changes.+  Propose changes to a wiki page you do not own: pull requests, review, merge. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**

@@ -1,26 +1,8 @@ --- name: wiki-hero-glb description: >--  What the Adom Wiki's 3D viewer reads from a GLB, in one page: declared layers-  (extras.adomLayer: key, label, group, hidden, the built-in PCB vocabulary,-  the nearest-declaring-ancestor rule, the two-layer minimum), the intro-  preview of a hidden layer (extras.adomLayer.intro), hover tooltips-  (extras.tooltip and the tooltips policy), switchable groups and lights inside-  the GLB (extras.adomRole / Adom.* nodes, KHR_lights_punctual, the light-  budget), animation (which groups autoplay, component.viewer_3d repeat / loop /-  animate / ground / shadows / tooltips / camera and the ?repeat= ?loop=-  ?animate= ?ground= query knobs, the Replay button), which glTF extensions-  the viewer honours, materials for translucent artwork (alphaMode BLEND,-  doubleSided), quantization, Draco, GPU instancing (refused), node naming-  that survives step2glb, and how the page picks the model it shows. Use-  when authoring or reviewing a hero GLB, a field-of-view cone, an LED that lights, a-  laser-etch overlay, or any GLB whose parts should be switchable or-  introduced. Trigger words: hero GLB, hero glb, adomLayer, layer intro,-  fade in the layer, highlight the toggle, field of view cone, extras.tooltip,-  adomRole, Adom.LED.State, KHR_lights_punctual, viewer_3d, repeat loop-  animate ground, replay animation, KHR_animation_pointer, alphaMode BLEND,-  doubleSided, Draco, gpu instancing warning, what does the wiki viewer read-  from a glb, glb authoring, 3D | Hero toggle.+  What the wiki 3D viewer reads from a GLB: adomLayer, tooltips, lights, animation, viewer_3d.+  Part of adom-wiki-skillpack. --- Parent skill: **adom-wiki-skillpack** 

@@ -1,16 +1,8 @@ --- name: wiki-hero-studio description: >--  Generate a wiki page's hero image with Hero Studio, the human-gated hero lab. The wiki REQUIRES-  every new app/skill hero to carry Hero Studio provenance (publish fails with HERO_STUDIO_REQUIRED-  otherwise), and a hero can ONLY be produced by a human clicking Generate in the studio, an AI-  cannot make or fake one. Use when a `pkg publish` is blocked on HERO_STUDIO_REQUIRED, when a page-  needs a hero or a hero refresh, or when the user says "hero studio". THE ONE MISTAKE TO AVOID:-  Hero Studio is an APP you RUN (`hero-studio pose <owner/slug>`), not a wiki page you open in pup,-  opening wiki.adom.inc/adom/hero-studio in a browser shows the brochure, not the tool. Trigger-  words: hero studio, hero-studio, HERO_STUDIO_REQUIRED, hero must be generated through Hero Studio,-  generate a hero, make a hero, hero image, hero provenance, publish blocked on hero, refresh the-  hero, page hero, billboard image.+  Make a page hero with Hero Studio (run `hero-studio pose`); fixes HERO_STUDIO_REQUIRED. Part of+  adom-wiki-skillpack. ---  # Hero Studio: the human-gated hero image

@@ -1,17 +1,8 @@ --- name: wiki-hero description: >--  The hero image for an Adom Wiki page, how to generate one (via the-  adom-wiki-hero-image package, a dependency of this pack) and, critically, how to-  stop it from getting unlinked. adom-wiki pkg publish overwrites the repo's page.json-  (which has no hero), so the page-header hero is dropped on every publish unless-  you re-push a complete page.json LAST. Read this when adding a hero, or when a-  hero that used to show is suddenly gone. The hero lives in page.json ONLY ,-  never embed it in the README body (that shows the human the same image twice).-  Trigger words: wiki hero, hero image, hero disappeared, hero unlinked, hero gone-  after publish, page shows placeholder icon, generate a hero, billboard image,-  adom-wiki-hero-image, re-link hero, hero_path empty, hero shows twice, duplicate-  hero, hero in readme, embed hero in readme.+  The page hero in page.json, why it vanishes after pkg publish, never in the README. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -22,7 +13,7 @@ Parent skill: **adom-wiki-skillpack**   Every wiki page needs a hero: the 16:10 dark-mode billboard the page header, the-landing-grid card, the Hydrogen Desktop installer, the homepage, and the+landing-grid card, the Hydrogen installer, the homepage, and the adom-screensaver all reuse. A page without one shows a placeholder icon and reads as unfinished. @@ -36,11 +27,11 @@ inside window chrome is not the component hero recipe. Preserve the manufacturer original model, validate the derived pose in the actual viewer and keep virtual MPN markings identified as overlays. The app-specific composition below applies to apps. -Use the **adom-wiki-hero-image** package, it's a declared **dependency of this-pack**, so `adom-wiki pkg install adom-wiki-skillpack` pulls it automatically. It-bundles the brand fonts + ADOM wordmark + the render pipeline, so it works-standalone. Invoke it (the `adom-wiki-hero` /-`adom-wiki-hero-image` skill) to render `screenshots/hero.png`: the app NAME as+New app and skill heroes come from **Hero Studio**: the registry refuses a hero+without its provenance stamp (HERO_STUDIO_REQUIRED). Run `hero-studio pose+<owner>/<slug>` and a human clicks Generate; see **wiki-hero-studio**. (The older+`adom-wiki-hero-image` billboard renderer is deprecated in favour of it.) What a+good hero shows, either way: the app NAME as the headline, a one-line value prop, the teal→blue→purple accent, and one gorgeous shot of the real UI as a floating Windows-style webview window. Readable in one second. (Faux app windows use **Windows** min/max/close controls, never macOS@@ -64,9 +55,6 @@ The headline can be a punchy phrase; the **subhead must be the value proposition 300µm solder-paste dots no other tool shows"). Don't waste the subhead paraphrasing the title. Keep it to ~1 line so the composer doesn't truncate it. -> TODO (pack maintainers): we depend on `adom-wiki-hero-image` rather than folding-> its content in. Revisit whether to inline it here later.- ## The hero goes in page.json ONLY: never in the README body  The hero is set via `page.json` → `hero.path` and the wiki renders it at the top

@@ -1,15 +1,10 @@ --- name: wiki-publish-safely description: >--  The hard rules and operational pitfalls for editing Adom Wiki pages-  (wiki.adom.inc) without breaking them, write both storage layers, never-  base64 a text file, versions are immutable, soft-delete blocks re-creation, the-  hero gets clobbered on publish, rate limits, and the non-negotiable verify-in-pup-  step. Read this before AND after any publish, file push, README change, or-  metadata edit. Trigger words: wiki publish broke the page, page shows-  placeholder, readme is gibberish, files tab empty, hero disappeared, hero-  unlinked, UNIQUE constraint pages, immutable version, `adom-wiki pkg` 429, ghost page,-  verify wiki in pup, wiki publish checklist, don't break the wiki page.+  Hard rules for editing an Adom Wiki page without breaking it: write both layers, immutable+  versions, soft-delete, hero lost on publish, verify in pup. Use before and after any publish,+  file push or README/metadata edit, or when a page broke (placeholder, empty Files tab, hero+  gone). ---  Parent skill: **adom-wiki-skillpack**@@ -59,17 +54,20 @@ companion.    rendered. Do not report a wiki edit as done from API JSON alone.     ```bash-   OWNER=john; SLUG=my-page; LAP=AdomLapper   # `adom-desktop status` shows the laptop host-   adom-desktop browser_open_window \+   OWNER=john; SLUG=my-page; LAP=AdomLapper   # `adom-bridge targets` lists the machines+   adom-bridge --ai-thread "<thread name>" pup_open_window \      "{\"sessionId\":\"wiki\",\"profile\":\"wiki\",\"url\":\"https://wiki.adom.inc/$OWNER/$SLUG\"}" \      --target "$LAP"    sleep 3-   adom-desktop browser_screenshot '{"sessionId":"wiki","maxWidth":1500}' --target "$LAP"+   adom-bridge --ai-thread "<thread name>" pup_screenshot '{"sessionId":"wiki"}' --target "$LAP"    # Read the screenshot; confirm it rendered before telling the user it's done.    ```     Reuse `sessionId:"wiki"` / `profile:"wiki"` every time so the login persists;-   `browser_navigate` an already-open window rather than spawning new ones.+   `pup_navigate` an already-open window rather than spawning new ones.+   A private page shows a login wall at its plain URL: open the `logged_in_url`+   from `adom-wiki auth login --page $OWNER/$SLUG --json` instead (or+   `adom-wiki auth login --next /$OWNER/$SLUG --open` for a Hydrogen webview tab).  ## Never show the hero twice 

@@ -1,24 +1,8 @@ --- 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, how readme.html and README.md share the page (both-  render, HTML first; page.json readme_order sets the order or shows one),-  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_order, readme order, html above-  markdown, markdown under the readme, readme.html not rendering, readme not-  updating, fully custom page layout, custom page body, unsanitized readme,-  interactive explorer, circuit explorer, simulator, calculator, applet for my-  page, should this be a widget, register a widget, widgets.json, adom/widgets.+  Custom readme.html: sandboxed iframe limits, self-contained assets, readme_order. Part of+  adom-wiki-skillpack. user-invocable: true --- 

@@ -1,6 +1,8 @@ --- name: wiki-readme-slideshow-description: Build a narrated, fullscreen-capable slideshow INSIDE a wiki page's readme.html - per-slide TTS audio, arrow-key navigation, auto-advance on audio end - without losing the markdown README (fold it in below the show). Born on the adom-theme page (2026-08-02, John's ask while driving). Trigger words - readme slideshow, narrated readme, slideshow in readme, audio tour, page tour, narrated tour, embeddable slideshow, readme with audio, slide deck on a wiki page.+description: >-+  Narrated slideshow inside a readme.html (per-slide TTS, arrow keys). Part of+  adom-wiki-skillpack. ---  # A narrated slideshow inside readme.html

@@ -1,21 +1,8 @@ --- name: wiki-readme description: >--  How to make a great Adom Wiki page presentation, the README is the page. Covers-  the choice between a plain README.md and a fully custom readme.html, the-  mandatory sections every page needs, embedding live demos / videos / iframes,-  and referencing inline images from the repo. Read this when writing or fixing-  the Overview tab of a wiki page, and BEFORE adding any image to a README ,-  NEVER embed the page hero in the README body (the page header already shows it,-  so embedding it makes the human see the same image twice). Trigger words: how to-  make a readme, wiki readme, readme.html, custom readme, write a readme for the-  wiki, wiki page overview, embed iframe wiki, embed demo, inline images readme,-  wiki page presentation, mandatory readme sections, readme renders blank, hero in-  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, interactive tool in-  readme, explorer in readme, applet, should this be a widget.+  Write a wiki page README: required sections, images, videos, embeds; never repeat the hero. Part+  of adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -295,7 +282,7 @@ Video rules (wiki 2026-09-14 and later): - Verify the rendered page after pushing, same as images.  The full record-and-publish checklist lives in the `demo-video-publishing`-skill (adom/demo-authoring-skillpack).+skill (`adom-wiki pkg install adom/demo-authoring-skillpack` ships it).  ## Known rendering pitfalls 

@@ -1,14 +1,8 @@ --- name: wiki-repo-styles description: >--  The taxonomy of Adom Wiki repo archetypes that have emerged from real use, and-  how to choose between them BEFORE you publish: Page (open- or closed-source),-  Skillpack (one repo, many bundled sub-skills, suffix -skillpack), and Family (an-  anchor page plus separately-published children). Read this when starting any new-  wiki repo or deciding how to structure related pages. Trigger words: what kind-  of wiki repo, wiki repo archetype, wiki repo style, page vs skillpack vs family,-  parent child wiki, super skill repo, bundle skills or separate, how to structure-  a wiki repo, skillpack vs family, one repo or many, chip-fetcher structure.+  Choose a wiki repo archetype before publishing: Page, Skillpack or Family. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -25,11 +19,11 @@ flow differ. A single wiki page for a single app, tool, skill, or doc. Two sub-variants by **source visibility** (see **wiki-visibility**): -- **Open-source Page**, source public + installable. e.g. `chip-fetcher`,+- **Open-source Page**, source public + installable. e.g.   `adom-usb`. MIT, contributions welcome. - **Closed-source Page**, source **private**, releases/`adom-wiki pkg` **public** →-  install the compiled app, can't read the code. e.g. `hydrogen-desktop`,-  `adom-desktop`. Uses the private readme.+  install the compiled app, can't read the code. e.g. `hydrogen`,+  `adom-bridge`. Uses the private readme.  > **Page _type_ vs archetype.** Every page has a `type` (`app` | `skill` | > `component`), orthogonal to these archetypes. A **component** (a chip, molecule,@@ -60,7 +54,7 @@ joined not by living in one repo but by convention: - **Breadcrumbs**: third parties attach a link back to the anchor (see   **wiki-breadcrumbs**). -- Examples: **adom-desktop**, **adom-usb**.+- Examples: **adom-bridge**, **adom-usb**. - Build it → **wiki-family**.  ## Skillpack vs Family: the decision rule

@@ -1,14 +1,8 @@ --- name: wiki-scoring description: >--  The scoring / trending system on the Adom Wiki, the signals tracked to know-  whether a page is doing well (stars / high-fives, install counts, and a-  trending surface) and how an author legitimately earns them (great hero, strong-  README, working demo). Stars are live; install counts, high-fives, and a-  dedicated trending endpoint are still being surfaced. Read this when asked how a-  page is performing or how to make one trend. Trigger words: wiki scoring, wiki-  trending, high five, star a page, install count, is my page trending, page-  popularity, wiki metrics, how to trend, what's popular on the wiki, page score.+  How page performance is tracked (stars, vouches, installs, trending) and earned. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -29,10 +23,12 @@ because it has zero stars yet.  - **Stars: live.** `POST/DELETE /api/v1/pages/:slug/star` and   `GET /api/v1/pages/:slug/stars` work (`→ {"count":N,"starred_by_me":bool}`).-- **High-fives / install counts / a dedicated trending endpoint: Partial /-  Planned.** These signals are intended but not yet exposed through the public API- , page metadata doesn't surface install/high-five/score fields today, and-  `GET /api/v1/trending` returns 404. Treat trending rank as not-yet-queryable.+- **Vouches: live.** `adom-wiki pkg vouch <ref>` endorses a page (any type);+  `adom-wiki pkg vouches <ref>` lists who vouched. High-fives were removed (the+  server answers REACTIONS_REMOVED).+- **Trending / popular: live in the CLI.** `adom-wiki page trending` and+  `adom-wiki discover popular` list pages. Install counts and a numeric score are+  still not exposed as page fields.  Don't report a numeric "score" or "trending rank" you can't read from the API. Stars you can read and state; the rest, describe as intended, and re-probe before@@ -40,7 +36,7 @@ claiming numbers.  ## The signals (the model) -- **High-fives**, lightweight positive user feedback on a page.+- **Vouches**, one-click endorsement of a page (high-fives were retired). - **Stars**, a user bookmarking/endorsing a page (live). - **Install counts**, how many times the package was installed (the strongest   signal of real use).@@ -71,5 +67,5 @@ curl -s -H "User-Agent: `adom-wiki pkg`/2.1.0" \   "https://wiki.adom.inc/api/v1/pages/<slug>/stars"   # {"count":N,"starred_by_me":bool} ``` -Update this skill as install-count / high-five / trending endpoints come online ,+Update this skill as install-count / score endpoints come online , re-probe and label them honestly.

@@ -1,15 +1,8 @@ --- name: wiki-skillpack description: >--  How to build a Skillpack, one Adom Wiki repo that bundles a main skill plus-  many sub-skills, installed together by a single adom-wiki pkg install, with the slug-  suffix -skillpack so the class is recognizable. Covers the bundle layout (root-  SKILL.md + skills/<sub>/SKILL.md), an install.sh that lists every skill, the-  package.json files[] whitelist, frontmatter conventions, and the skill-map-  table. Read BEFORE creating a new skill set so you never make a repo per skill.-  Trigger words: make a skillpack, super skill, bundle skills, one repo many-  skills, skill bundle, do not make a repo per skill, skillpack suffix, author a-  skill set, SKILL.md bundle, install.sh skills, wiki skill package.+  Build a Skillpack: one repo bundling a main skill and sub-skills, its install.sh and skill map.+  Part of adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**

@@ -2,16 +2,8 @@ name: wiki-sub-readme user-invocable: true description: >--  Make a SUB-README on an Adom Wiki page: a README.md inside a subfolder of the page's repo that fully-  documents ONE topic (a feature-set, a lab, a runbook, an event plan, how a video was made), rendered as-  its own sub-page, and ALWAYS introduced from the main README by a section card: a section header, a-  thumbnail the AI makes from the sub-readme's most relevant visual, and a three-sentence write-up with-  links. Use whenever someone says "create me a sub-readme" or a page has grown topics that would bloat-  its README. Covers the card, the folder layout, publishing with `adom-wiki repo push` (not the files-  blob API), image and link paths, and verifying the RENDERED page. Trigger words: sub-readme, sub-  readme, subreadme, create me a sub-readme, make a sub-readme, folder README, README in a subfolder,-  second readme, feature guide, deep-dive doc, wiki sub page, add a page to my wiki page, nested doc on a-  wiki page, split my readme, my readme is too long, share this doc on our page but not on the overview.+  Sub-README: a folder README.md rendered as a sub-page, introduced by a card. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -79,7 +71,7 @@ guide) is fine **in addition** to the cards on a page with many guides, never in  - **Images and media inside a folder README:** since wiki 2026-09-14, a folder README resolves a relative path from its own folder first, then from the page root. So `![shot](img/x.png)` (next to the README) and `![shot](tether-lab/img/x.png)` (from the root) both work. `repo push` answers `README_ASSET_UNRESOLVED` when a referenced file exists in neither place. - **If an image still shows broken on the rendered sub-page**, use the absolute blob URL, which always works: `https://wiki.adom.inc/blob/<type>/<slug>/<repo-path>`. `<type>` is the page's type (`app`, `skill`, `component`, ...), and there is no owner in a blob path.-- **Video** `src` and `poster` follow the same rules. Video, audio and iframes are capped at the column width. For a long or full-resolution video, link a YouTube upload (or use `::youtube{id="VIDEO_ID"}` on its own line) rather than committing a large file. See `demo-video-publishing` (adom/demo-authoring-skillpack).+- **Video** `src` and `poster` follow the same rules. Video, audio and iframes are capped at the column width. For a long or full-resolution video, link a YouTube upload (or use `::youtube{id="VIDEO_ID"}` on its own line) rather than committing a large file. See the `demo-video-publishing` skill (`adom-wiki pkg install adom/demo-authoring-skillpack` ships it). - **Links between docs:** relative repo paths (`../other/README.md`, `tether-lab/README.md`). The renderer rewrites them. Links to other wiki PAGES stay normal URLs (`https://wiki.adom.inc/<owner>/<slug>`). - **An HTML document** in a folder (`readme.html` / `index.html`) renders as the folder's sub-page in the sandboxed frame (see `wiki-readme-html`). On a PRIVATE page the listing shows a link instead of the frame. To link one from prose, use its raw-route URL `https://wiki.adom.inc/<owner>/<slug>/render/<folder>/<file>.html`. 

@@ -1,19 +1,15 @@ --- name: wiki-video-captions description: >--  Publish a narrated video in an Adom Wiki README using ::adom-video, generate-  synchronized WebVTT captions and chapters, remove padded dead air, and verify-  the real widget. Read before adding or replacing any wiki video. Triggers:-  adom-video, ::adom-video, video in README, narrated demo, closed captions,-  subtitles, VTT, SRT, caption files, video chapters, no dead air, voiceover gaps,-  video widget, video first, process video, publish a demo video.+  Narrated ::adom-video in a README with WebVTT captions and chapters. Part of+  adom-wiki-skillpack. ---  # Wiki video and caption delivery  Use the existing page and the registered **::adom-video** widget. Do not create a separate video page or hand-written HTML player. Read **demo-video-publishing**-for production/editing and **adom-tts** for narration. This skill covers the+(`adom-wiki pkg install adom/demo-authoring-skillpack` ships it) for production/editing and **adom-tts** for narration. This skill covers the README delivery path, including existing videos with no caption sidecar.  ## Find and embed the supported widget

@@ -1,19 +1,8 @@ --- name: wiki-visibility description: >--  How visibility and licensing work on the Adom Wiki (wiki.adom.inc): a page can-  keep its git source PRIVATE while its releases / wiki package stay PUBLIC, so-  people install the compiled app but can't read the code, the pattern for-  proprietary apps. Covers who can read a PRIVATE page (org pages like adom/x:-  every org member; personal pages like ray/x: only the owner plus explicit-  share grants), public vs private source, the private readme, and the-  open-source vs closed-source Page variants. Read this when deciding how much of-  a page to expose, or shipping a proprietary tool. Trigger words: private wiki-  source, public app private source, proprietary wiki page, closed source app,-  private readme, hide source code wiki, install compiled app no source, open-  source wiki repo, license a wiki repo, visibility settings wiki, who can see my-  source, who can see my private page, can employees see my private page,-  share a private page with my team, page share, org private vs personal private.+  Page visibility: private source with public releases, who can read a private page. Part of+  adom-wiki-skillpack. ---  Parent skill: **adom-wiki-skillpack**@@ -58,17 +47,16 @@ The combination that makes proprietary apps work on the wiki: - **Readme: public** (or a private readme for internal docs).  So users install and run the app just fine, but never see the source. This is how-**hydrogen-desktop** and **adom-desktop** ship: the binary is a public release-asset, the Rust/Tauri source stays private. Contrast with **chip-fetcher** and-**adom-usb**, which are fully open source, source public, MIT-licensed,+**hydrogen** and **adom-bridge** ship: the binary is a public release+asset, the Rust/Tauri source stays private. Contrast with **adom-usb**, which is fully open source, source public, MIT-licensed, contributions welcome.  This visibility split is exactly what distinguishes the **two Page sub-variants** in the archetype taxonomy (see **wiki-repo-styles**): -- **Open-source Page**, public source + public install (chip-fetcher, adom-usb).-- **Closed-source Page**, private source + public install (hydrogen-desktop,-  adom-desktop).+- **Open-source Page**, public source + public install (adom-usb).+- **Closed-source Page**, private source + public install (hydrogen,+  adom-bridge).  ## The private readme 

@@ -1,6 +1,8 @@ --- name: wiki-workspaces-description: Ship and receive a Hydrogen bench with a wiki project. hydrogen/workspace.json in the page repo is the author's pane layout with apps referenced by wiki page (never by URL); export it from a live Hydrogen with adom-cli, push it with adom-wiki, fork or clone it, and apply it in a container. Covers the file format, the WORKSPACE_* hints, the resolved route, and the apply and export verbs. Trigger words - shared workspace, project workspace, hydrogen/workspace.json, workspace apply, workspace export, ship my layout, author's bench, open in hydrogen, WORKSPACE_INVALID, WORKSPACE_URL_LOCAL, WORKSPACE_APP_UNDECLARED, WORKSPACE_AVAILABLE, dock manifest, dockbar.json.+description: >-+  Ship a Hydrogen layout with a page (hydrogen/workspace.json): export, push, apply. Part of+  adom-wiki-skillpack. ---  # Shared Hydrogen workspaces@@ -40,6 +42,8 @@ The project page draws the bench (pane boxes with tab names) and its "Open in Hy  ## The file +Illustrative example (`adom/drone-dashboard` and `adom/drone` are placeholder pages, not real ones):+ ```json {   "workspace_manifest": "1.0",