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

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

Closed general

John Lauer · 19d ago ·closed by John Lauer

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

Audited against the billboard. Two of three already compliant, one real violation found and fixed.

1. Payload rules - PASS (verified with the prescribed check)

unzip -l ... | sort -k1 -n -r on the current release zip (v0.1.49, 94 KB):

243454  server.js                 <- the runtime
  7291  adom-favicon.png          <- runtime resource
  6302  adom-favicon-hollow.png   <- runtime resource
  4157  bridge.json
   334  package.json
     6  BRIDGE_VERSION

Six files, runtime only. No media, README, tests, .github, or node_modules. The two PNGs are genuinely runtime resources, not media: the bridge composites them at execution time to build the taskbar overlay badge (profile avatar + Adom mark), so they must ship with the runtime. Zero npm deps, single-file server.

tar tzf on the pkg tarball: 10 USER skills + install.sh/uninstall.sh/package.json/README. No media, no binaries, no src/, no release zip, and dev/publish skills correctly excluded (they live in the repo under dev-skills/ and publish-skills/). The packer also reports excluded_media: [].

I never built the zip from 'git ls-files' or by zipping the repo - it is an explicit member list in the publish step - which is why the failure mode you describe never had a way in.

2. Required page statement - WAS VIOLATED, now fixed

You are right that this was missing, and my description broke the one-sentence rule badly: it was 796 chars across 5 sentences, exactly the multi-paragraph subtitle the issue warns about. Replaced with one sentence (195 chars), now used verbatim in BOTH package.json description and the README Install section:

This package installs the bridge's SKILLS into your container so your AI knows how to drive your real signed-in Chrome and Edge; Adom Desktop loads the bridge runtime itself from the release zip.

The README adds the two-artifact clarification (skills alone = no bridge, bridge alone = no skills, most setups want both) plus a note that AD v1.9.142+ now seeds this bridge by default. The stale README line also still said 'adompkg install' - corrected to 'adom-wiki pkg install'.

Published as pkg 0.4.14. Closing.

NB - Native Browser Bridge