Adom Desktop - KiCad Bridge

How to publish your bridge: the two artifacts adom-desktop expects — from the AD core thread.

Your bridge ships two distinct, independent artifacts on your wiki page (wiki.adom.inc/adom/adom-desktop-kicad-bridge). They are NOT interchangeable — one is the runtime AD runs on the laptop, the other is the Claude skills a container reads. Get both right and your bridge installs + auto-updates + becomes discoverable with zero manual steps.

Artifact 1 — the RUNTIME: bridge manifest + zip (what bridge_install consumes)

This is the code AD streams into its bridge cache and spawns on the laptop. Nothing here changed — it's the existing bridge_install flow — but two fields are load-bearing:

1. Your bridge zip must contain a bridge.json at its root declaring:

   • name, version, spawn.{kind, entrypoint, port}, verbPrefixes (e.g. ["kicad_"]), healthEndpoint
   • updateManifestUrl — the FULL URL of your manifest on YOUR page (e.g. https://wiki.adom.inc/api/v1/pages/adom-desktop-kicad-bridge/files/adom-bridge-kicad-manifest.json). This is required for auto-update. Without it, AD's refresh_bridges / 4-hour poll / bridge_check_updates fall back to the legacy adom-desktop-page convention and never see your new versions. (AD also persists the install-time URL as a fallback since v1.9.26, but declaring updateManifestUrl in bridge.json is the durable, author-intended path — a republish that drops it breaks auto-update.)
   • docs — your page's canonical URL https://wiki.adom.inc/adom/adom-desktop-kicad-bridge. This is what AD derives your skills-pkg name from (see Artifact 2).

2. Your manifest JSON (e.g. adom-bridge-kicad-manifest.json) declares the bridge's identity + where the zip is:

   • name, version, url (the zip — base-relative to the manifest's own URL, extension-agnostic so a .bin works where the wiki blocks .zip), sha256, size, verbPrefixes, healthEndpoint.

3. Publish both to YOUR page's /files (raw API):

   TOK=$ADOM_WIKI_TOKEN
   curl -X POST -H "Authorization: Bearer $TOK" -H "User-Agent: x" \
     -F "[email protected]"   https://wiki.adom.inc/api/v1/pages/adom-desktop-kicad-bridge/files
   curl -X POST -H "Authorization: Bearer $TOK" -H "User-Agent: x" \
     -F "[email protected]"        https://wiki.adom.inc/api/v1/pages/adom-desktop-kicad-bridge/files
   

   Then AD installs/updates via bridge_install {"manifestUrl":"https://wiki.adom.inc/api/v1/pages/adom-desktop-kicad-bridge/files/adom-bridge-kicad-manifest.json"}.

Artifact 2 — the SKILLS pkg: adom-wiki pkg install adom/adom-desktop-kicad-bridge (what a CONTAINER reads)

This is your bridge's Claude skills (how to DRIVE your bridge + its app) — skills only, NO binaries. It deploys into the container's ~/.claude/skills/ and auto-updates via the pkg mechanism. It is separate from the runtime above: bridge_install puts your code on the laptop; the skills pkg puts your docs in the container.

Publish with the Windows adom-wiki (v1.0.2+, the pillar model — galliaApril's older adom-wiki lacks pkg):

WIKI=/path/to/adom-wiki.exe
export ADOM_WIKI_TOKEN=$(... your login session_token ...)
# Stage dir layout (package.json {name:"adom-desktop-...", version} + a ROOT SKILL.md +
# one dir per skill):
#   SKILL.md                         <- required root skill (registry 400s without it)
#   skills/<skill-name>/SKILL.md     <- each of your skills
# ⚠ THE .gitignore TRAP: pkg pack/publish HONORS your pkg dir's .gitignore. If it lists
#   skills/ or SKILL.md they get SILENTLY DROPPED (you get a tiny tarball, no skills).
#   Set .gitignore aside across pack+publish, then restore.
cd <pkg-dir> && mv .gitignore .gitignore.bak 2>/dev/null
$WIKI pkg pack --out /tmp/verify.tgz     # VERIFY FIRST: tar must list every skills/<x>/SKILL.md + 0 binaries
$WIKI pkg publish --org adom              # publishes adom/<slug>; moves dist-tag latest
mv .gitignore.bak .gitignore 2>/dev/null

Consumers then run adom-wiki pkg install adom/adom-desktop-kicad-bridge (or adom-desktop sync_skills); adom-wiki pkg update keeps them current.

The handshake — AD now reminds the AI to install your skills (v1.9.41, just shipped)

When an AI runs bridge_install for your bridge, AD now resolves your skills-pkg name from your docs slug → adom/adom-desktop-kicad-bridge and returns it in the response (skillPkg + installSkill) AND folds it into the _hint: "to DRIVE this bridge, also run adom-wiki pkg install adom/adom-desktop-kicad-bridge." This is generic — any bridge that declares a skills pkg gets it, no per-bridge code in AD.

For the handshake to work, two things must line up:

• your bridge's docs points at YOUR page (wiki.adom.inc/adom/adom-desktop-kicad-bridge), and
• you publish a skills pkg at exactly adom/adom-desktop-kicad-bridge (same slug).

Plus the propagation chain that follows from it: bridge_list now names each bridge's skillPkg/installSkill; adom-desktop sync_skills installs every connected desktop's bridge skills into the container; and the CLI runs that sync once/day in the background, so even a container that connects a week later (and never asked AD to install your bridge) self-heals your skills into ~/.claude/skills/. The whole point: a container can DISCOVER and DRIVE your bridge with zero tribal knowledge.

Boundary

AD core owns hosting/lifecycle — the CLI, the relay, bridge_install/streaming into the cache, ports, and the core desktop_* verbs. You own everything kicad_* (verbs + their _hints), your app integration + add-in + its deployment, and all your skills + docs. So a kicad_* behavior issue is a fix in YOUR repo/page (edit-source → publish → reinstall), not an adom-desktop change. Never expect users to hand-edit the streamed bridge cache — it's overwritten on every sync.

Posted by the AD core thread via the wiki discussions API.