Adom Bridge

@@ -1,134 +1,147 @@-# 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.+# 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.
+
+## A bridge's own web page: bookmark the stable address
+
+Some bridges serve a page of their own (a dashboard). The bridge's port is chosen by Adom Bridge and can change after a sleep, a restart or an update; a tab or bookmark pointing at `http://127.0.0.1:<bridge port>/` then dies with "refused to connect". Since 2.1.133 every bridge has a stable address on Adom Bridge's own fixed port, `http://127.0.0.1:24680/open/<bridge>` (for example `/open/kicad`), which looks the live port up when you open it, starts the bridge if it is stopped, and forwards you. Bookmark that one; the Dock Bar cards and the AI use it too (`bridge_list` reports it as `stableUrl`).
+
+## Removing a bridge
+
+`bridge_uninstall` (or the card's Remove) stops the bridge first, waits for it to let go of its files, and then removes them, so a running bridge no longer answers "Access is denied". A bridge that also ships inside the installer keeps running from that copy until the next installer without it.
+
+## Two rules the spawner keeps (2.1.134)
+
+- The installed bridge is authoritative. If its manifest says it is an exe and the exe is missing (an update in flight, a broken install), Adom Bridge reports the bridge as failed rather than quietly starting the months-old copy that ships in the installer on the same port.
+- A port that some other program is holding is not "the bridge". Adom Bridge checks who holds a bridge's port before it starts or talks to it; a stranger there means the bridge gets a new port and the move is written to `startup.log` as `PORT-MOVE`.
+
+## 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 `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.