---
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. adompkg 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.
---

Parent skill: **adom-wiki-skillpack**

# The hero image — generating it, and keeping it linked

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
adom-screensaver all reuse. A page without one shows a placeholder icon and reads
as unfinished.

## Generating it

Use the **adom-wiki-hero-image** package — it's a declared **dependency of this
pack**, so `adompkg install adom-wiki-skillpack` pulls it automatically. It
bundles the brand fonts + ADOM wordmark + the render pipeline, so it works
standalone with no gallia dependency. Invoke it (the `adom-wiki-hero` /
`adom-wiki-hero-image` skill) to render `screenshots/hero.png`: 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
dots.) For Family children, also carry the family chip (e.g. `ADOM-USB · SNIFFER`).

### The hero shot: laptop width, full toolbars OPEN (show the sophistication)

The single most important choice is the screenshot. For an app, capture the
**laptop-browser view with every toolbar / studio / HUD / layers panel OPEN** —
the busy, sophisticated state, not the default empty one. A loaded part with the
control panel deployed tells the viewer "this tool is capable" at a glance; a bare
canvas reads as a toy. Capture at ~1440px wide (deviceScaleFactor 2 for crispness)
with real content loaded, and click the panel(s) open before the shot. (Lesson
from the EDA apps, 2026-06-21: John explicitly wanted the full-toolbar laptop view
so users "understand how sophisticated the apps have gotten.")

### The subhead carries the VALUE PROP, not a restatement of the name

The headline can be a punchy phrase; the **subhead must be the value proposition**
— one line on what the app is *for* and its differentiator (e.g. "preview the
InstaPCB 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
of the page for you. **Do NOT also embed it in the README** (`![...](.../hero.png)`)
— that shows the human the same image twice. README images are *other*
screenshots. This pairs with the unlink bug below: the hero's home is `page.json`,
full stop. → **wiki-readme**.

## ⚠️ The recurring bug: the hero gets UNLINKED on publish

This is the #1 hero problem and it looks like the image was deleted — **it
wasn't**. The mechanism:

- 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` field.** So every publish silently drops the hero
  reference. The PNG file is still in the repo at `screenshots/hero.png`; only the
  pointer in `page.json` is gone.

The same overwrite also resets the page **title and brief** to the package values.

## The fix: push a complete page.json LAST

Order every publish so the complete `page.json` is the final commit:

1. `adompkg publish` (registry/tarball) — this clobbers `page.json` in the repo.
2. **THEN** push a **complete** `page.json` to `POST /api/v1/pages/<slug>/files`
   as the last step — including `hero:{type:"image",path:"screenshots/hero.png"}`,
   plus title, brief, visibility, tags. This re-indexes and re-links the hero
   (and restores title/brief).
3. Confirm: `GET /api/v1/pages/<slug>` shows
   `hero_type:"image", hero_path:"screenshots/hero.png"`.
4. Open the page in pup and confirm the hero renders (see **wiki-publish-safely**).

If a hero "disappeared" on an existing page, you don't need to regenerate it —
just re-push a complete `page.json` with the `hero` block and verify `hero_path`.

## Checklist

- [ ] `screenshots/hero.png` exists in the repo and is listed in `package.json` `files[]`
- [ ] `page.json` has the `hero` block
- [ ] Complete `page.json` pushed AFTER `adompkg publish`
- [ ] `GET /pages/<slug>` → `hero_path` set
- [ ] Hero visually confirmed in pup