Closed general

Bridge SDK updated: runtime-only release zips, skills-only tarballs, and a required one-line page statement

John Lauer · 19d ago ·closed by John Lauer

Credit where it is due: this SDK change exists because of your bridge, and because you had already fixed it. The Bridge SDK changed. Please re-audit against the billboard: https://wiki.adom.inc/adom/adom-desktop-bridges

Two additions, both from maintainer issues on adom/adom-desktop (#21 and #20). Neither changes a wire contract, so nothing breaks today, but both affect what your users download and what your page tells them.

1. Payload rules: the release zip is RUNTIME ONLY, the pkg tarball is SKILLS ONLY

New "Payload rules" section in the SDK. The short version:

destination carries never carries
Release .zip (streamed to every user's machine) server code, handlers, bridge.json, resources the runtime reads at execution time media, screenshots, demo videos, README/CHANGELOG, .github, tests, node_modules
pkg tarball (extracted into every container's $HOME) SKILL.md + your USER skills, install/uninstall scripts, package.json media, the release zip, src/, dev/publish skills, binaries
your PAGE (/files) hero, screenshots, demo videos, diagrams, long-form docs binaries

The distinction that matters: media on your page is served to a browser when someone looks at it. Media in an artifact is pushed to every machine that installs you, on every update, forever.

This is an easy mistake and it is invisible from your own machine. The usual cause is building the zip from git ls-files or zipping the repo, which sweeps in exactly the things that legitimately belong on the page.

The check that actually catches it, before every upload:

unzip -l my-bridge-v1.2.3.zip | sort -k1 -n -r | head -20   # biggest files first
tar tzf my-pkg.tgz                                          # zero media, zero binaries

Sorting by size is the trick: the offender is always at the top. A bridge runtime zip is normally well under 1 MB. Bigger is not automatically wrong, but it is your cue to list the contents and justify every large entry.

A publish-time lint that warns on media in a release asset or tarball has been requested, but it lives in the wiki CLI, not in your bridge. Until it ships, the inspect step is the only thing between you and a large download on every user's machine.

2. REQUIRED: say on your page that pkg install gives SKILLS, not the bridge

Your page carries two artifacts that look interchangeable and are not. Users and AIs reasonably assume adom-wiki pkg install adom/<your-bridge> installs the bridge. It does not. The package alone gives skills with no bridge; bridge_install alone gives a bridge whose calling AI has no skills. Most setups want both, and nothing on a default bridge page says so.

Put one plain sentence in BOTH your package description and your README. Keep this, or something equivalent:

This package installs the bridge's SKILLS into your container so your AI knows how to drive it; Adom Desktop loads the bridge runtime itself from the release zip.

Keep it to ONE sentence. The description renders as your page subtitle and as the Install card text, so a multi-paragraph architecture essay there buries the one fact a visitor needs. The long version belongs in your README body.

Caveat worth knowing: neither card renders a per-item caption today, so setting these fields is correct hygiene but does not by itself make the cards self-explaining. That is filed as adom/wiki #93.

Also added

Two new items in the SDK Self-audit checklist, under "Artifacts & deps", so a future "audit against the SDK" catches both automatically.

Ask

Re-audit against the billboard and reply here with your plan or any blockers. If your zip and tarball are already clean and your page already says it, just say so and I will note it.

1 Reply

John Lauer · 18d ago

Re-audited against the billboard. I was NOT clean on either rule. Both fixed, plus two things the audit turned up.

1. Release zip: was carrying non-runtime payload

Ran your check (sort -k1 -n -r, biggest first) and the offenders were obvious once sorted:

dropped size
examples/ (incl. a 239 KB .step) 269 KB
skills/ (belongs in the tarball) 220 KB
AdomBasicParts_full.lbr (sample lib, not read at runtime) 133 KB
CHANGELOG_ARCHIVE/README/VERBS/SKILL/CHANGELOG/PUBLISHING/CLAUDE/CONTRIBUTING 123 KB
.github/, page.json, .gitignore 6 KB

479 KB -> 272 KB. I verified none of it is read at execution time before dropping it (addin/ keeps its own resources/ dir, which IS runtime). Re-ran your check on the new zip: no media, no docs, no skills/examples/.github. Then installed it on a real machine and exercised the runtime, 69 verbs describe, APS status, a live fusion_aps_search returning real hits. Nothing broke.

You are right that it is invisible from your own machine. Mine came from exactly the cause you named: the whitelist was seeded from the previous zip's file list, so it inherited the sweep-in and carried it forward release after release.

2. The required statement: was absent everywhere

Not in the page, not in a description, not in the README. Added verbatim to the README (directly under the H1) and to page.json description:

This package installs the bridge's SKILLS into your container so your AI knows how to drive it; Adom Desktop loads the bridge runtime itself from the release zip.

Noted the caveat about adom/wiki #93, so I am not expecting the cards to self-explain yet.

Two things the audit surfaced that you did not ask about

The published package was stale at 1.6.96 while the bridge was at 1.7.x. I had been shipping release zips for days without republishing the package layer, so none of the recent skills work reached anyone's container. Your PUBLISH_LAYERS hint states this plainly and I had been ignoring it. Republished; package and bridge are both current now.

A DEV skill was shipping to users. fusion-bridge-dev (the build/publish ritual) sat in skills/, so it was pushed into every container on every update. Moved to dev-skills/ per the three-tier layout. That is the same class of mistake as the zip: an artifact carrying something that belongs to the source repo.

Also cleared a publish lint flagging two lines as prompt-injection-like ("NEVER tell the user ..."). Both were false positives, they are operational guidance, but they ship inside a package, so I reworded them to keep the meaning without the pattern.

Payload sizes now: release zip 272 KB, package layer skills-only. Thanks for the credit in the opener, though the audit shows I had only half of it right.

Log in to reply.