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

# Hero Studio: the human-gated hero image

Every new app/skill page on the Adom Wiki needs a hero with **Hero Studio provenance**. A publish
without one fails:

```
HERO_STUDIO_REQUIRED: hero must be generated through Hero Studio.
```

A hero can **only** be made by a **human clicking Generate** in the studio. An AI cannot generate
one, cannot fake the provenance, and re-linking an existing PNG that lacks studio provenance is also
refused. This is intentional: it is the quality gate that keeps wiki heroes from looking like AI
slop.

## ⛔ Run the APP. Do NOT open the wiki page.

Hero Studio is a **tool you launch from the CLI**, not a page you browse.

- ✅ `hero-studio pose adom/<slug>` , launches the studio, posed for that package, in front of the human.
- ❌ opening `https://wiki.adom.inc/adom/hero-studio` in pup / a browser , that is just the app's
  brochure page. It does NOT let you make a hero. (An AI did exactly this once when asked to "show
  hero studio"; do not repeat it.)

If the user says "show me / open hero studio", they mean **run the tool posed for their page**, not
navigate to its wiki listing.

## The flow

```bash
adom-wiki pkg install adom/hero-studio      # once; gives you the `hero-studio` command
hero-studio pose adom/<slug>                # opens the studio, BLOCKS until the human clicks Generate
```

- `pose` opens the studio as a **Hydrogen webview tab** ("Hero Studio") in the user's workspace,
  pre-posed for `<owner/slug>` (title, brief, type pulled from the page). It runs a local server on
  **127.0.0.1:8846**.
- It **blocks** until the human art-directs and clicks **Generate**, then prints the generated PNG
  path on stdout and exits 0. Exit 2 = timed out with no human action; exit 1 = setup error.
- Flags: `--title`, `--brief`, `--type app|skill`, `--timeout SECS`.

Because it blocks on a human, run it and WAIT. Tell the user the studio is open in their workspace
and ask them to click Generate. Do not poll-spam or assume it finished.

## After Generate

The studio writes the provenance-stamped **2000x1250 PNG** into the page repo (`screenshots/hero.png`)
and registers it. Then:

```bash
adom-wiki pkg publish --version <next> -y     # now passes the hero gate
```

The stamped image bakes the page title + artwork, plus the type pill (top right) and full wiki slug
(bottom right). The page shows the hero bare; only the homepage marquee overlays its own info.

## Gotchas

- **Port 8846 already in use / EADDRINUSE:** the studio server is already running from a prior
  session, that is fine, `pose` reuses it. Only the first launch starts it.
- **Transferring a page can drop hero provenance:** a page moved between owners/orgs may lose its
  grandfathered hero and require a fresh Hero Studio run before it can publish again. This is
  working as intended, remake the hero rather than looking for a bypass.
- **This is a HUMAN step. Never try to route around it.** No hand-rolled PNG, no copying another
  page's hero, no faking the stamp. If there is no human to click Generate, the publish waits.

## Related

- **wiki-hero** , where the hero fits in a page (page.json `hero.path`, never embed it in the README).
- **adom-wiki-hero-image** , the design system for what makes a good hero (name-first hierarchy,
  the teal accent, one real-UI shot). Hero Studio is the human-gated way to PRODUCE that image.