---
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\<bridge>\`).
   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>-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-<name>-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`).