---
name: adom-usb-publish
description: >
  How to publish or republish adom-usb and its plugins to the Adom Wiki
  (wiki.adom.inc). Carries the naming + hero + publish-order conventions for the
  whole Adom USB family so they travel with the repo. Use when: release adom-usb,
  publish adom-usb, cut an adom-usb version, publish an adom-usb plugin, add a new
  USB sniffer/firmware plugin to the wiki, fix an adom-usb hero, rename a plugin
  title. Trigger words: publish adom-usb, release adom-usb, bump adom-usb, adom-usb
  plugin publish, adom-usb wiki, adom-usb hero, name an adom-usb plugin.
---

# Publishing Adom USB (app + plugins) to the wiki

The canonical wiki is **https://wiki.adom.inc** via `adompkg` (see the
`adom-wiki-v2` skill for the general flow). This skill pins the conventions that
keep the Adom USB family consistent. Follow them every time.

## 1. Naming — every family member announces it's Adom USB

Users meet plugins out of context (a wiki card, a search hit, a billboard in the
adom-screensaver), so the relationship must be obvious without reading the slug:

- **Slug**: `adom-usb-<kind>-<chip>` — e.g. `adom-usb-stub-rp2040`,
  `adom-usb-sniffer-cdc`. Dash separators; never a colon (illegal in slugs).
- **Title** (the human name shown on cards / search / screensaver — the one that
  matters; nobody reads slugs): MUST lead with **`Adom USB`** and use a **plain
  ASCII hyphen with spaces** as the separator — `Adom USB - RP2040 persona pack`,
  `Adom USB - CDC serial sniffer`. **NEVER an em-dash (—)** — keep it identical to
  the sibling packages. A bare title like "RP2040 persona pack" hides the family.
- **Hero billboard**: carry the family chip `ADOM-USB · FIRMWARE` /
  `ADOM-USB · SNIFFER` (built per the `adom-wiki-hero-image` skill).
- **Tag/keyword**: include `adom-usb-plugin` so `adom-usb plugins search` finds it.

## 2. The hero gotcha — push page.json LAST

The page-header hero renders from the DB `hero_type`/`hero_path`, which the wiki
indexer derives from the repo's **`page.json` `hero:{type,path}`**.
**`adompkg publish` OVERWRITES `page.json` in the repo with the package manifest
(which has no `hero`), clobbering the hero on every publish.** So the order is:

1. `adompkg publish` (the tarball / registry step) FIRST.
2. THEN push a **complete** `page.json` (type, slug, **title**, brief, version,
   visibility, `hero:{type:"image",path:"screenshots/hero.png"}`, install,
   tags, license, metadata) to `POST /api/v1/pages/<slug>/files` as the LAST
   step. That re-indexes and sets `hero_path`. Verify:
   `GET /api/v1/pages/<slug>` → `hero_type:"image", hero_path:"screenshots/hero.png"`.

## 3. App-page requirements (the wiki rejects publishes missing these)

`type:"app"`, top-level `version`, `install.binary_name`, a hero (page.json +
push the PNG to `screenshots/hero.png`), a `SKILL.md` (root or `skills/<slug>/`),
and a non-empty `tags` array.

## 4. Publish steps

```bash
export ADOMPKG_REGISTRY=https://wiki.adom.inc
# org packages (canonical) — publish into the adom org, not your personal namespace:
adompkg publish --org adom -y
# downloadable per-platform binary (adds the "Download for your machine" button):
adompkg release upload adom/<slug>@<ver> ./bin/<bin> --platform linux
# push source + a complete page.json (with title + hero) to the git layer LAST.
```

For the main app, also: bump VERSION/Cargo.toml/package.json/page.json together,
`cargo build --release`, GitHub release, then the steps above.

**Binary-not-in-tarball gotcha:** `bin/` is gitignored (keeps the binary off
GitHub) and `adompkg pack` HONORS `.gitignore`, so the binary is NOT in the
tarball. `install.sh` therefore **downloads it from the wiki release asset**
(`/download/john/adom-usb/<ver>/adom-usb`). So you MUST `adompkg release upload`
the binary BEFORE anyone installs that version, and `install.sh` must read the
version from `package.json` to build the URL (don't bundle the binary; don't
un-gitignore `bin/`).

## 5. After ANY title/hero/page.json change — verify the card

`GET /api/v1/pages/<slug>` and confirm `title` leads with `Adom USB - …` and
`hero_path` is set; the card/search/screensaver read those fields.