# Bridges: the mini-apps that teach Adom Bridge new tricks

Bridges are how Adom Bridge (Adom Bridge) reaches beyond the operating system into specific
apps. Each bridge is a small, independently-versioned process that Adom Bridge spawns,
supervises, health-checks, and auto-updates from its own wiki page. Every install ships
with six of them:

![Bridge cards in the sidebar with health LEDs](bridge-cards-pup-fusion.png)

| Bridge | Verb prefix | What it does |
|---|---|---|
| Puppeteer | `pup_*` | A dedicated Chrome-for-Testing (or Edge) that Adom Bridge downloads and manages: windows, tabs, page drive, JS eval, screenshots, recording. |
| Native Browser | `nbrowser_*` | Your real, signed-in Chrome or Edge profile, for the logins and forms a throwaway automation profile cannot do. Works extension-free out of the box; the companion extension unlocks full in-page drive. |
| KiCad | `kicad_*` | Schematic and PCB automation: DRC/ERC, gerber and STEP export, 3D render, netlist and footprint queries. |
| Fusion 360 + APS | `fusion_*`, `aps_*` | Parametric modeling scripts and exports, plus fast indexed cloud-file search. |
| Blender | `blender_*` | Headless Python scripting and renders. |
| Hydrogen | `hd_*` | The local dev-environment app Adom Bridge can embed into; Adom Bridge relays its runtime state. |

Third-party bridges install the same way and show up in the same place.

## The Bridges sidebar

The right side of the Adom Bridge window is a full-height sidebar showing each installed bridge
as a mini-app card:

- A hero image (the bridge's own wiki billboard), the bridge name, a short description,
  the author, and a star count.
- A health LED with a short status label next to it.
- Language and source badges (Python or Node; bundled, cache, or third-party).
- A small `?` help icon. Hover it for the full tooltip: the bridge's own detailed status
  text, its wiki page, and where its hero image came from.

Click a card to open the wide pop-out console:

- A live console: the bridge's own log plus the history of commands routed to it.
- A ports and process debug view with live PIDs (more than one PID flags a runaway).
- Every management action: install, uninstall, kill, restart, pause, resume, plus
  "filter the activity log to this bridge" and "copy contribution prompt".

The sidebar collapses to a thin rail if you want the space back. Two buttons live at the
top: **+ Bridge** (install one by manifest URL) and **Check for updates**.

## What the LED colors mean

The bridge itself decides its color and status text; Adom Bridge just paints what it reports,
refreshing about every 15 seconds. The one exception is gray, which Adom Bridge owns, because a
dead bridge cannot report anything.

| LED | Meaning | What to do |
|---|---|---|
| Green | Healthy. The bridge reported it is fine (or is reachable and did not say otherwise). | Nothing. |
| Yellow | Degraded, per the bridge itself. For example, an upstream it depends on is partially down. | Hover the `?` for the bridge's own explanation. |
| Red | The bridge knows it is broken. For example, it lost its connection to the app it drives. | Read the tooltip, then open the card's console for the live log. |
| Gray | Off or unreachable. The bridge process is not running or its health endpoint is not answering. | Usually fine: bridges start on first use. A bridge marked persistent respawns by itself within seconds. |

A gray dot on a bridge you have never used is normal. Bridges spawn on the first command
of their prefix, not at Adom Bridge startup, and a bridge whose host app (KiCad, Fusion) is not
installed on this machine is deliberately left un-spawned.

## How a bridge runs (the short version)

- Adom Bridge starts a bridge automatically on the first verb that targets it.
- Each bridge keeps one stable port across restarts, so external clients (like the
  browser extension) always find it in the same place.
- Adom Bridge enforces a single instance per bridge: duplicates are detected and reaped, and a
  stale copy is cleaned up before a fresh one starts.
- Bridges marked persistent are auto-respawned on death by a supervisor. Killing one to
  pick up new code just brings it right back.

## Installing a bridge

From the GUI: click **+ Bridge** at the top of the sidebar and paste the bridge's
manifest URL (published on its wiki page). From the command line:

```bash
adom-bridge-cli bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/<bridge-page>/files/<bridge>-bridge-manifest.json"}'
```

On success the card appears in the sidebar immediately. It sits gray until its first
use, then goes green. On failure nothing is registered and no card appears; the error
says why (most commonly the manifest's download URL could not be fetched).

Uninstalling from the card's pop-out (or `bridge_uninstall`) removes a third-party
bridge entirely; a bundled bridge reverts to the copy that shipped in the installer.

## How updates arrive

You normally do nothing. On launch and every 4 hours, Adom Bridge checks each bridge's own wiki
page for a newer version. When one exists, Adom Bridge downloads it (checksum-verified) into a
local cache, and the cached copy supersedes the bundled one. The bridge picks up the
new code on its next natural respawn.

On demand, the **Check for updates** button next to **+ Bridge** does the same sweep
immediately, or:

```bash
adom-bridge-cli bridge_check_updates          # read-only: what is behind, per bridge
adom-bridge refresh_bridges               # update everything that is behind
```

Note that Puppeteer is bundled-only (its dependencies exceed the wiki file limit), so it
updates with the Adom Bridge installer itself rather than from a wiki page.

## When something is wrong

- **Gray and it should be running:** call any verb of its prefix, or open the card and
  use Restart. Persistent bridges come back on their own.
- **Red or yellow:** the tooltip is the bridge's own diagnosis; the card's live console
  shows its log as it runs.
- **A bridge keeps restarting:** the console tail includes Adom Bridge's own lifecycle record,
  which survives restarts. A line saying Adom Bridge reaped the process means Adom Bridge removed a
  duplicate; a spawn line with no reap before it means the bridge exited on its own.
- **A verb answers "paused":** someone paused routing to that bridge. Resume from the
  card or with `bridge_resume`. Pausing never kills the process; it only makes the
  bridge's verbs fail fast.

## Where each bridge's real documentation lives

This page covers the lifecycle: how bridges run, install, and update. How to actually
USE a bridge (its verbs, workflows, and recipes) is documented by the bridge itself, on
its own wiki page, which is also where its skill package for AI callers ships from:

- Puppeteer: wiki.adom.inc, the `pup-bridge` page
- KiCad: the `kicad-bridge` page
- Fusion 360: the `fusion-bridge` page
- Blender: the `adom-desktop-blender-bridge` page
- Native Browser: the `adom-browser-extension` page

Each card's wiki link takes you straight there. To build a bridge of your own, start
with the Bridge SDK on the `adom-bridge` wiki page.

## Private bridges

A bridge on a private wiki page works like any other as long as Adom Bridge is signed in with an account that can see the page: installs and automatic updates send your signed-in token. Teams keep org-internal bridges private for exactly this reason. If an install reports that the page was not found, check the signed-in identity in the footer first.