Install/Download cards should explain WHAT each is + WHO it's for (and why pkg vs release versions differ)

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 14d ago ·closed by Colby Knox

Feature: the Install and Download cards at the top of a page should say WHAT each item is and WHO it's for — inline, not just in the README below.

The confusion (real, on adom/adom-desktop-puppeteer-bridge): the page header shows two cards with two different version numbers and zero explanation:

Install — adom-wiki pkg install … · Latest v1.8.28
Download for your machine — adom-bridge-puppeteer-v…zip · v1.8.20

A user reasonably asks: why two versions? which do I need? what's the difference? The answer exists (one is the AI skill pack for the container, bumps often; the other is the runtime the desktop app auto-manages, bumps rarely) — but it's buried in the README, and neither card surfaces it.

What I tried: I set a clear description on the pkg and real titles/changelogs on the releases. Neither renders on the cards — the Install card shows only the command + version; the Download card only the filename + size. So authoring metadata can't currently fix this.

Ask — render short, author-supplied context ON the cards:

Install card: show the pkg's description (or a dedicated one-line install_summary) as a subtitle, e.g. "The AI skill pack — installs into your container so the AI knows the verbs. Not the runtime."
Download card: show a one-liner (from the release, or a page field), e.g. "The bridge runtime — Adom Desktop auto-installs & updates this; manual download is only for offline installs." Ideally a "managed by " badge when a dependency app auto-manages it.
Version-difference hint: when the pkg version ≠ the latest release version, a tiny "?" tooltip: "These version independently — the skill pack and the runtime are separate artifacts." Removes the "are these out of sync?" worry.

Why it matters: the two-artifact split (skills pkg vs runtime release) is standard for every bridge, so every bridge page has this same confusion. A per-card one-liner + a version-difference hint fixes it everywhere, and lets authors control the wording via metadata they already can set.

1 Reply

Colby Knox · 13d ago

Shipped and live on the adom-desktop page. The Install + Download cards are now grouped in a bordered "Get it" block (so Contents below starts a clear new region -- #92), each card carries an author caption (#91/#93), a "?" appears next to the Download heading when the pkg and release versions differ (#91), and the download card has a native details-on-hover tooltip with the full filename + exact bytes + sha256 + platform/arch + upload time (#94).

Author controls: the Install caption comes from the manifest install_caption (falling back to the pkg description); the Download caption comes from the release title -- set it with adom-wiki release edit <ref> <version> --title "For your Windows PC — the signed desktop app" and it renders on the card (previously it did not).

Deferred: the "managed by " badge on the download card (needs reverse-dep knowledge of which app auto-manages the runtime) -- say the word if you want it as a follow-up. Closing.