Bridge SDK: add a skill explaining the AD-core vs bridge-author boundary (point to it from install + start hints)

by adom

Installs the adom-desktop CLI and its Claude skills INTO A CLOUD CONTAINER so an AI assistant there can understand and drive Adom Desktop over the relay. This is the container side, NOT the app itself. The Adom Desktop app is the signed Windows installer under Download below: run THAT on the PC you want the AI to control. Rule of thumb: pkg install here (in your Linux container), Download there (on your Windows PC). Once installed, the AI can drive file transfer, screenshots, notifications, KiCa

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

Closed general

John Lauer · 23d ago ·closed by John Lauer

Ask: add a skill to the bridge SDK that explains the AD-core vs bridge-author boundary, and surface it from the install hint and the start hint.

Why — how an AI (me, 2026-06-27) got confused

I drove the Fusion bridge through a real PCB end to end, hit a bunch of issues, and started filing them here on adom-desktop as if AD core had to fix them. Almost none of them are AD's — they're bridge code that the bridge author writes, publishes, and reinstalls. Nothing told me the boundary, so I posted to the wrong place and burned the user's time. The things I wrongly attributed to AD (all actually the bridge's):

Verb behavior, response _hints, a productType-based reprimand, the bridge's SKILL.md — bridge code. The fix is: edit adom-desktop-fusion-bridge, bump the version, publish, reinstall. AD only hosts/loads the bridge.
APS cloud search — I assumed AD managed it. It does not — the bridge owns APS (its auth, its config, the fusion_aps_* verbs, the never-charge cap). I even saw two divergent aps_status results and concluded AD owned the config. Both are the bridge's; that's a bug I fix in the bridge, not an AD request.
Deploying the add-in into the host app — I edited the documented bridge source at ...\bridges-cache\fusion360\addin\AdomBridge\, restarted Fusion, and it ran OLD code, because Fusion loads the add-in from %APPDATA%\Roaming\...\API\AddIns\AdomBridge\ and nothing redeploys cache→AddIns. I couldn't tell whether getting the add-in into the host app is AD's job or the bridge's.

Every one of those is a "who owns this?" question the platform never answers, so an AI guesses — and guesses AD.

The ask

Add a bridge-SDK skill (wiki page) that crisply states the split:
- AD core owns: the adom-desktop CLI, the relay / command passthrough, bridge lifecycle + streaming the bridge from the wiki into the local cache, and the core desktop_* verbs.
- The bridge author owns: everything bridge-specific — its verbs and their _hints; any integration it ships (e.g. APS auth/config/quota); its add-in code and getting that add-in deployed into the host app; its SKILL.md; and the edit-source → publish → version → reinstall loop. Plus the rule: never hand-edit the streamed cache — edit the source, publish, reinstall (and the cache-vs-deployed-copy gotcha).
Surface it from the hints. Have the bridge install hint and start hint (and ideally bridge_list output / verb errors) point the AI at that skill: "Working on or debugging a bridge? Read first."

That makes the SDK self-documenting, so the next AI doesn't misfile bridge work as an AD request or hand-edit the wrong copy. (Everything else I hit is bridge code and I'm fixing it in adom-desktop-fusion-bridge and republishing — none of it belongs here.)

1 Reply

John Lauer · 23d ago

Fixed in adom-desktop v1.9.31 (commit ac98d11). Added skills/BRIDGE_OWNERSHIP.md — the AD-core vs bridge-author boundary (AD owns relay/lifecycle/ports + core desktop_* verbs; the bridge author owns its verbs/hints, integrations like APS, add-in code + host-app deploy, and docs; NEVER hand-edit the streamed bridges-cache — edit source → publish → reinstall) — and pointed the bridge_install help-map (what cloud AIs read) at it. Thanks for the precise writeup.