# Adom Wiki Skill Pack

**One install, 15 skills that teach the AI to use the Adom Wiki without breaking
pages — plus a write-up of the wiki repo archetypes that have emerged from real
use.**

Publishing to [wiki.adom.inc](https://wiki.adom.inc) is powerful but fraught: the
AI re-breaks pages (unlinks heroes, base64-mangles READMEs, writes only one of
the two storage layers, forgets to verify what it shipped). And as the wiki has
been used heavily, a set of **repo archetypes** has quietly emerged — patterns
nobody had named or written down. This pack fixes both: it bundles the publishing
know-how as installable skills, and it names the archetypes so they can be used
deliberately.

> **📌 Note for Colby (and anyone building the wiki):** the section
> [**The repo archetypes**](#the-repo-archetypes-emerging-from-real-use) is for
> you. It documents the page structures that have emerged from heavy real-world
> use of the wiki — Page, Skillpack, and Family — and a few features they lean on
> (private source + public releases, the private readme, breadcrumbs, scoring).
> Some of it is built, some is partial, some is still a spec; each skill labels
> its status honestly. This is meant as a design mirror: here's how your heaviest
> user is actually structuring repos, so the platform can meet those patterns.

## Install

```bash
adompkg install adom-wiki-skillpack
```

This drops the main `adom-wiki-skillpack` skill plus 14 sub-skills onto your
container, and pulls in **`adom-wiki-hero-image`** (a dependency) for hero
generation.

## 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:

| # | Tool | Like | What it powers |
|---|---|---|---|
| 1 | **Git host** | GitHub repo | Files tab, README, commits, contributors |
| 2 | **adompkg** | npm | `install` / `publish` / `update`, dependency maps |
| 3 | **Release database** | GitHub Releases | versioned downloadable binaries |
| 4 | **Discussions** | GitHub Issues | a forum thread per page |
| 5 | **Pull requests** | GitHub PRs | community edits, owner reviews/merges |
| 6 | **Discovery** | npm search / app-store surfacing | how a page/skill gets found — search, `/discover` triggers, local skill matching |

Plus a **presentation** layer (`README.md` or a custom `readme.html`, and a separate
**private readme** for proprietary pages). The **scoring/trending** signals (stars /
high-fives / installs) feed Discovery's ranking.

> **Discovery is a first-class pillar, and it's the least-finished one.** Layer 1
> (local installed-skill matching) works; Layer 2 (the registry `/discover`
> endpoint) does not yet match declared `discovery_triggers`. The `wiki-discovery`
> skill carries the current state + a TODO list of what discovery still needs —
> see it (and finding #3 in our Colby feedback).

The single most important consequence: **the git repo and the package registry are
two independent storage layers.** `adompkg publish` does *not* push your source to
git, and pushing files does *not* make a tarball. A correct publish writes both.
Doing one leaves the page half-broken — the root of most incidents.

## The repo archetypes (emerging from real use)

Three repo shapes have emerged. Naming them turns "how should I structure this?"
into a deliberate choice.

![The three Adom Wiki repo archetypes](/blob/skill/adom-wiki-skillpack/screenshots/archetypes.png)

### 1. Page — one page = one thing

A single page for a single app/tool/skill/doc. Two sub-variants by **source
visibility**:

- **Open-source Page** — source public + installable. _e.g._ `chip-fetcher`,
  `adom-usb`. MIT, contributions welcome.
- **Closed-source Page** — source **private**, releases/adompkg **public**, so
  people install the compiled app but can't read the code. _e.g._
  `hydrogen-desktop`, `adom-desktop`. Uses the **private readme** so the page
  still has public docs.

> The wiki lets the git source, the release/package, and the readme each be public
> or private independently — that's what makes a proprietary app and an
> open-source library both first-class on the same platform.

### 2. Skillpack — one repo, one main skill + N sub-skills

One repo / one installable package carrying a whole set of skills, deployed
together by a single `adompkg install`. Sub-skills are files under `skills/`, not
separate pages. **Convention: the slug ends in `-skillpack`** so the class is
recognizable.

- _e.g._ `adom-ui-design` (grandfathered, predates the suffix), and **this pack**.
- **This very repo is a Skillpack** — it dogfoods its own archetype.

### 3. Family — an anchor page + separately-published children

An anchor page plus children published as **their own pages**, joined by
convention rather than living in one repo:

- **Slug** `<parent>-<descriptor>`; **Title** leads with the parent
  (`Adom USB - CDC serial sniffer`); a **family tag** (`<parent>-plugin`); and
  **breadcrumbs** linking children back to the anchor.
- _e.g._ `adom-desktop` (+ bridges), `adom-usb` (+ sniffer/firmware plugins).

### Skillpack vs Family — the decision rule

Both are "a main thing + many smaller things." The divider is **ownership and
update cadence**:

- **Skillpack** when one author owns all the parts and they version *together*.
- **Family** when children have *independent owners or release cadences* — each is
  its own page, and third parties can add their own without touching the anchor.

**Worked example — `chip-fetcher`:** it's open source AND has many per-vendor
scraper skills (DigiKey, Mouser, TI, Analog Devices) that **change daily** and
that **third parties** want to own. As a Skillpack, every vendor tweak would force
the single owner to re-publish the whole pack. So it's better as a **Family**: an
anchor plus `chip-fetcher-digikey`, `chip-fetcher-mouser`, … each independently
publishable, discovered via the family tag + breadcrumbs. Rule of thumb: _does
each part need its own lifecycle and maybe its own author?_ Yes → Family.

## The hard rules (page-breakers)

The pack encodes these; they're worth stating here too:

1. **Write both storage layers** every publish (git + registry).
2. **`adompkg publish` clobbers the hero** — it overwrites the repo's `page.json`
   (no `hero`), so the hero gets *unlinked* (not deleted) on every publish. Fix:
   **publish first, push a complete `page.json` LAST.** (This is the recurring
   "hero disappeared" bug.)
3. **Never base64 a text file** — only real binaries are base64.
4. **Versions are immutable** — bump; never delete-and-recreate (soft-delete trips
   a UNIQUE constraint).
5. **Verify with your eyes** — open the live page in pup and screenshot it before
   calling any wiki edit done.

## Skills in this pack

| Skill | What it's for |
|---|---|
| **adom-wiki-skillpack** | Entry point: the five-tools model, the archetypes, the hard rules, the map. |
| **wiki-anatomy** | The mental model — six tools in one, and the two storage layers. |
| **wiki-api** | The REST API + `adompkg` CLI and the publish workflow. |
| **wiki-publish-safely** | Operational pitfalls as hard rules + the verify-in-pup gate. |
| **wiki-readme** | Make a great README — `README.md` vs `readme.html`, sections, embeds. |
| **wiki-visibility** | Public vs private source, public releases, the private readme. |
| **wiki-repo-styles** | The archetype taxonomy and how to choose. |
| **wiki-component** | Publish a component — chip / molecule / board; the tabbed chip CAD-hub README (symbol, footprint, 3D, pins, specs, sourcing, tape & reel). |
| **wiki-family** | Build a Family: naming, family tag, anchor registry, breadcrumbs. |
| **wiki-skillpack** | Build a Skillpack: layout, install.sh, files[], the `-skillpack` suffix. |
| **wiki-hero** | Generate a hero, and never let it get unlinked. |
| **wiki-breadcrumbs** | Third-party "I built an add-on for X" links _(implemented, basic)_. |
| **wiki-forking** | Fork + community-PR contribution _(PRs live; fork-button planned)_. |
| **wiki-discovery** | How pages get found — the two layers, current state, and the TODO list _(Layer 1 live; `/discover` partial)_. |
| **wiki-scoring** | Stars / high-fives / installs / trending _(stars live; rest partial)_. |

## 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
- "Write a README for this page" → wiki-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 / a bridge to adom-desktop" → wiki-family

## Dependencies

| Dependency | Required? | Why |
|---|---|---|
| **adom-wiki-hero-image** | Yes | Generates the 16:10 hero billboard every page needs; self-contained (bundles brand fonts + wordmark + render pipeline). Pulled automatically by `adompkg install`. |

Companion tools (not hard dependencies): `adompkg` itself (the package manager),
and `adom-desktop` / pup for the verify-in-pup step.

## Relationship to gallia

Gallia's `adom-wiki-v2` and `adom-wiki-hero-image` skills remain the
employee-internal source of truth. This pack is the **public, installable digest**
of that knowledge plus the archetype taxonomy — same model as `adom-ui-design`.
Update gallia first, then refresh this page.

## License

MIT.