Adom Wiki

TL;DR

adom-wiki pkg publish does not preserve an existing image page-hero. After each publish the page-header hero flipped away from my intended adom-lbr-hero-v4.png, and I had to restore it with adom-wiki page hero … --image … — on all three publishes this week. On the last one, both package.json and page.json declared the image hero and it still got overridden.

Tooling note for Colby: I used the adom-wiki CLI for every wiki op here — repo clone/repo status, pkg lint/pkg publish --org adom, page hero, discussion …, discover triggers, pkg init. No adompkg, no slug-wiki URL, no raw REST. So this isn't an old-API artifact.

Use case

Iterating on an existing app page, adom/adom-lbr (owned by the adom org). I cloned it (adom-wiki repo clone adom-lbr), merged code + README + docs changes, bumped the version, and republished three times (1.1.0 → 1.1.1 → 1.1.2) with adom-wiki pkg publish --org adom. The page already had a polished hero set to an image: adom-lbr-hero-v4.png (hero_type: image).

What happened (observed, each publish)

1. Before publish — repo status shows hero_type: image, hero_path: adom-lbr-hero-v4.png.
2. adom-wiki pkg publish --org adom succeeds.
3. After publish — the live hero is no longer v4. It became the package.json billboard block (screenshots/shot.png), and on a later publish it showed screenshots/hero.png.
4. I restore it with adom-wiki page hero adom-lbr --image adom-lbr-hero-v4.png and re-verify via repo status.

Two extra wrinkles:

• It overrode even when both manifests agreed. For 1.1.2 I'd aligned both package.json and page.json to {type: image, path: adom-lbr-hero-v4.png} — publish still changed the live hero.
• page hero --image X didn't reflect X in its response. One page hero adom-lbr --image adom-lbr-hero-v4.png returned {type: image, path: screenshots/hero.png} in its JSON; a second identical call (and repo status) then showed the correct adom-lbr-hero-v4.png. So the set looks non-deterministic / needs a re-read to confirm.

How I worked around it

Re-run adom-wiki page hero <slug> --image <file> after every pkg publish, then confirm with repo status (don't trust the page hero response alone). Aligning package.json's hero block to the image did not prevent the reset.

What I think it should do

1. Make the hero sticky across republish. pkg publish should preserve the current page hero unless the manifest explicitly and unambiguously changes it. A version bump shouldn't mutate the hero.
2. One deterministic source of truth. If a page can carry both a package.json hero (billboard) and a page.json hero (image), define precedence clearly and honor it — and don't silently auto-detect screenshots/hero.png/screenshots/shot.png over an explicitly-set image hero.
3. A --keep-hero flag on pkg publish (or --hero <file>) for the common 'just ship code, leave the page chrome alone' case.
4. Make page hero --image return what it set. The response should reflect the value actually persisted, so a single call + read is trustworthy (no re-set dance).

What worked great (credit where due)

repo clone → local merge → pkg lint → pkg publish was a clean loop; the lint caught target/ build cruft before it shipped. Discussions were excellent for a real cross-thread feedback loop — a Fusion-bridge thread filed verified findings on the adom-lbr page (#27), I shipped fixes and closed it from the CLI. The only friction was the hero reset.

Happy to provide exact command transcripts / JSON envelopes if useful.