--- name: adom-desktop-bridge-ownership description: The boundary between Adom Bridge core and a bridge author — what AD owns vs what you (the bridge) own. Read before filing an AD bug about a bridge (kicad, fusion360, native-browser, puppeteer, blender, rdp, or any third-party bridge) or before editing bridge code, so you fix and report in the right place. --- # Who owns what: AD core vs bridge author **Read this FIRST if you're working on, debugging, or filing a bug about a bridge (kicad, fusion360, native-browser, puppeteer, blender, rdp, or any third-party bridge).** It exists because an AI drove the Fusion bridge end-to-end, hit a dozen issues, and filed almost all of them against **adom-desktop** — when nearly every one was **bridge code**. The platform never stated the boundary, so the AI guessed "AD," posted to the wrong place, and hand-edited the wrong copy. Don't repeat that. ## The split ### Adom Bridge (AD) core owns - The `adom-desktop` CLI + the **relay / `/command` passthrough** (AD relays a bridge's response **verbatim** — incl. `_hint`/`_next`/`related` and every other top-level field the bridge sets; v1.9.30 made this a denylist, never an allowlist). - **Bridge lifecycle**: discover/register/spawn/reap, stable ports, the `bridge_*` verbs, and **streaming a bridge from its wiki page into the local cache** (`bridge_install` / `refresh_bridges` / the 4-h auto-sync). - The core `desktop_*` verbs (input, screenshot, UIA, tunnels, wsl, …). - Generic, app-agnostic behavior. **AD returns good DATA so the calling AI decides — it does NOT bake in app-specific verbs** (see CLAUDE.md "AD stays GENERIC"). ### The bridge author owns (NOT AD) - **Every bridge-specific verb and its behavior** — args, outputs, and the per-call `_hint`/`_next`/`related`/`pitfalls` (the rich-hint contract). A wrong/missing hint is a **bridge** fix. - **Any integration the bridge ships** — e.g. Fusion's **APS** cloud search: its OAuth/auth, its config, its `*_aps_*` verbs, its never-charge caps. AD does NOT manage it. Divergent results from the bridge's own status verb = a **bridge** bug. - **The bridge's add-in / plugin code AND getting it deployed into the host app.** Editing the streamed cache source is not enough if the host app loads the add-in from elsewhere (e.g. Fusion loads from `%APPDATA%\…\API\AddIns\`, not the bridges-cache) — wiring cache→host-app is the **bridge's** concern. - The bridge's `SKILL.md`, `describe` verb, hero/wiki page, and version. - The **edit-source → publish → bump version → reinstall** loop. ## The cardinal rules 1. **NEVER hand-edit the streamed cache** (`%LOCALAPPDATA%\Adom Desktop\bridges-cache\\`). It's a download. Edit the **source** (the bridge's own repo/wiki), `publish`, bump the version, then `bridge_install`/`refresh_bridges` to pull it. A hand-edit is overwritten on the next sync and may not even be what the host app runs (cache-vs-deployed-copy gotcha). 2. **Before filing a bridge bug against adom-desktop, ask "who owns this?"** If it's verb behavior, a hint, an integration, an add-in, or the bridge's docs → it's the **bridge author's** repo/wiki, not AD. Cloud-owned bridges (kicad, fusion, puppeteer) live in their OWN wiki repos (see CLAUDE.md "Cloud-owned bridge repos"). 3. **AD's job is to relay + host, generically.** If AD is *dropping* or *mangling* a bridge's data, or missing a lifecycle/verb capability — THAT is an AD bug. Fix the AD VERB; don't re-absorb the bridge. When in doubt: data-shape/relay/lifecycle/ports → **AD**; what a verb does, its hints, its integration, its add-in, its docs → **the bridge**. ## Skill ownership — a bridge ships its OWN skill pkg (not bundled in AD-core) The same boundary applies to the **consumer skill** (the SKILL.md that teaches a cloud container how to drive a bridge's verbs): - **The AD-core pkg** (`adom-wiki pkg install adom/adom-desktop`) ships ONLY core skills — desktop verbs, discovery, direct-api, installer, notify, multi-ad, bridge-sdk, bridge-ownership, windows-host. It must NOT bundle a cloud/3rd-party bridge's skill (it would go stale and isn't AD's to own). (2026-06-28: `eagle-commands.md` — Fusion-Electronics, `fusion_electron_run` — was dropped for this reason; 2026-06-29: `pup-SKILL.md` was dropped too when Puppeteer became cloud-owned. Both belong in their bridge's own pkg.) - **Each cloud/3rd-party bridge publishes its OWN skill pkg** carrying its SKILL.md, e.g. `adom/adom-desktop-kicad-bridge`, `adom/adom-desktop-fusion-bridge`, `adom/adom-desktop-puppeteer-bridge`. The cloud thread that owns the bridge owns + bumps it. (Puppeteer's runtime still ships as an NSIS-bundled SEED for fresh-PC/offline spawn — but its *skill* now ships from its own page, like the other cloud bridges.) - **How a container gets dynamic bridge skills:** it does NOT get them from the AD-core install. It (a) installs AD-core (CLI + core skills), then (b) `adom-desktop bridge_list` against the live laptop AD to see which bridges are present, then (c) `adom-wiki pkg install adom/adom-desktop--bridge` for each one it needs (and `adom-wiki pkg update` keeps them fresh, version-matched to the bridge the cloud thread published). The bridge's runtime PAYLOAD (what AD spawns on the laptop) is a SEPARATE artifact — the `/files` manifest+zip that `bridge_install`/`refresh_bridges` pull — don't conflate it with the skill pkg. - **Discoverability gap / enhancement:** `bridge_list` should surface the exact `adom-wiki pkg install adom/adom-desktop--bridge` line per live bridge so a container knows precisely which skill pkg to pull (today it infers the slug from the bridge's `docs`).