--- name: adom-wiki-skillpack user-invocable: true description: >-, wiki bloat, too many wiki pages, should this be a page. 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 16 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. --- # Adom Wiki Skill Pack The Adom Wiki at **https://wiki.adom.inc** is the single canonical wiki. This 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. > **`adompkg` is the deprecated old name of the package manager.** It is dead; do not run it. Every old `adompkg ` maps to `adom-wiki pkg|page|repo|release ` (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 It feels like a wiki, but it's a fusion of six tools you already know, all keyed off one slug per page: 1. **Git host**, every page is a real git repo (Files tab, commits, contributors). 2. **`adom-wiki pkg`**, an npm-style package manager: dependency maps, `adom-wiki pkg update`. 3. **Release database**, versioned binary/tarball releases (like GitHub Releases). 4. **Discussion forum**, a thread per page (like GitHub Issues). 5. **Pull requests**, community edits proposed to a repo, the owner reviews/merges. 6. **Discovery**, how a page/skill gets found (search, `/discover` triggers, local skill matching); a first-class pillar, fed by the scoring/trending signals. Plus a **presentation layer** (a plain `README.md`, or a custom `readme.html`, plus a separate **private readme** for proprietary-source pages). Full model → **wiki-anatomy**. ## Three repo archetypes (pick one before you publish) | 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 | | **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 | Decision: **Skillpack** when one author owns all the skills and they version together; **Family** when children have independent owners or update cadences (e.g. per-vendor scrapers that change daily). Full taxonomy → **wiki-repo-styles**. ## The hard rules (the page-breakers) These are the mistakes that recur. They each have a dedicated skill, but they're important enough to state up front: > ⛔ **NEVER use em-dashes (,) in ANY wiki content** (John, 2026-06-26): page titles, briefs, > descriptions, README bodies, hero text, sample prompts, changelogs, even commit messages. Use a > comma, a regular hyphen `-`, or a colon `:`. The en-dash `–` is banned too. ASCII punctuation only. 1. **Write BOTH storage layers, every publish.** The git repo (Files/README) and the package registry (tarball/`adom-wiki pkg install`) are independent. Do only one and the page is broken. → **wiki-api**, **wiki-publish-safely**. 2. **`adom-wiki pkg publish` clobbers the hero.** It overwrites the repo's `page.json` with the package manifest (which has no `hero`), so the page-header hero gets unlinked on every publish. The image isn't deleted, its reference is. **Fix: publish FIRST, then push a complete `page.json` (with `hero`) to git LAST.** → **wiki-hero**, **wiki-publish-safely**. 3. **NEVER embed the hero image in the README body.** The wiki renders the hero at the top of the page automatically (from `page.json`). Repeating it inline shows the human the same image twice, redundant and rude. README images must be OTHER screenshots, never the hero. → **wiki-readme**. 4. **Never base64 a text file.** Text (`.md`, `.json`, `.sh`) goes as plain `content`; only real binaries (images) go base64. → **wiki-api**. 5. **Versions are immutable.** Bump before republishing; never delete-and-recreate (soft-delete trips a UNIQUE constraint). → **wiki-publish-safely**. 6. **Verify with your eyes.** After ANY wiki edit, open the live page in pup and screenshot-confirm it rendered before calling it done. → **wiki-publish-safely**. ## Skill map | Skill | Use it for | |---|---| | **wiki-anatomy** | The mental model: the six tools in one, and how the layers relate. | | **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, images. | | **wiki-readme-html** | Build a custom `readme.html`: sandbox limits, shadowing, self-containment, theming, verify loop. | | **wiki-sub-readme** | Make a sub-readme: a 2nd doc in the page repo, linked from the README. The repo-push / relative-link / image-path 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. | | **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. | | **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-studio** | Generate the page hero: RUN `hero-studio pose ` (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-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 - "Publish this tool to the wiki" → wiki-api + wiki-publish-safely - "What kind of wiki repo should this be?" → wiki-repo-styles - "Make a hero for this page" / "the hero disappeared" → wiki-hero - "Show/open hero studio" / "generate a hero" / HERO_STUDIO_REQUIRED → wiki-hero-studio (RUN the app, do not browse the page) - "Write a README for this page" → wiki-readme - "I want a custom HTML readme / tabs / designed layout" → wiki-readme-html - "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 - "Bundle these skills into one package" → wiki-skillpack - "Add a child plugin to adom-usb" → wiki-family - "Publish this chip / molecule / board to the wiki" → wiki-component