--- name: adom-bridge-bridge-sdk description: Author, PUBLISH, and make-discoverable an adom-bridge bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-bridge. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files [server deps in the zip; the pkg declares dependencies:{adom/adom-bridge}], manifest + runtime-asset placement); the pkg carries ONLY user skills while dev + publish skills live in your source repo (not the pkg); the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; and the auto-discover → install-check → use flow. --- # Bridge SDK — build, publish, and surface a bridge for Adom Bridge A **bridge** is a small local program (Python, Node, Rust, anything) that AD spawns and routes a **namespace of verbs** to over HTTP. KiCad, Fusion 360, Puppeteer (pup), native-browser, Blender are bridges. The modern flow has THREE moving parts you own — get all three right and a cloud/WSL2 container can *discover* your bridge from a plain-English request, confirm it's installed, and drive it with zero tribal knowledge: 1. **Runtime** — a versioned **Release `.zip`** + a **manifest** on your wiki page. AD's `bridge_install` streams it onto the user's machine and spawns it. 2. **Skills** — an **`adom-wiki pkg`** tarball carrying your consumer SKILL.md(s). A container installs it into `~/.claude/skills/` (or `~/.codex/skills/`) so the AI *there* knows your verbs. 3. **Discoverability** — **`discovery_triggers`** on your wiki page so a user saying *"open my app in pup"* surfaces YOU via `adom-wiki discover find`. > **THE ONE PRINCIPLE THAT MATTERS MOST — read this before anything else.** > **The AI almost never reads your on-disk SKILL.md. It ALWAYS reads the OUTPUT of a CLI call.** > So your leverage is in the **`_hint` / `_next` / `related` / `pitfalls` you return on EVERY verb response.** A verb that returns `{success:true}` and nothing else leaves the AI guessing and retry-looping. A verb that returns *what just happened, the obvious next verb, the related verbs, and the pitfall to avoid* gets driven perfectly on the first try. AD relays every field of your response **verbatim** to the calling AI. Treat each verb's output as the documentation the AI will actually read. (Your SKILL.md is for the *human* author + the rare AI that does read it; your verb OUTPUT is for the AI in the loop.) --- ## Where every file lives — the two artifacts, their deps, and which skills go where **Two DISTINCT artifacts, two DIFFERENT homes, two DIFFERENT consumers. Crossing them is the #1 inconsistency across bridge repos — pin it here before anything else.** (Live audit 2026-07-06: fusion + pup do this right; kicad had **61** loose `adom-bridge-kicad-v*.zip` on `/files` + a `mesa-llvmpipe-x64.zip`; blender dumped 2 loose zips too.) | | **RUNTIME artifact** (Artifact 1) | **SKILLS pkg** (Artifact 2) | |---|---|---| | **What it is** | your bridge's actual CODE | your consumer `SKILL.md` docs | | **Runs on** | the user's **DESKTOP** — AD spawns it | **nothing runs it** — docs the CONTAINER reads | | **Published as** | a versioned **Release** (`release create` + `release upload --platform any`) | an **`adom-wiki pkg`** (`pkg publish --org adom`) | | **Installed by** | `bridge_install {manifestUrl}` → AD streams, unzips, spawns | `pkg install adom/` / `sync_skills` → `~/.claude/skills` + `~/.codex/skills` | | **Contains** | server code + `bridge.json` at the zip **ROOT** + assets. **Node: SOURCE ONLY, no `node_modules`.** | ONLY: ROOT `SKILL.md`, `skills//SKILL.md` (user skills), `package.json`, `install.sh`, `uninstall.sh`. **Text only — the whole tarball should be a few KB.** | | **NEVER contains** | the skills pkg | **ANY image (hero / screenshots — those are WIKI PAGE assets, see below), any binary, the Release zip, `src/`, `node_modules`, dev/publish skills, or the server's npm deps.** If `tar tzf` shows a `.png`/`.jpg`/`.zip`/`.exe`, you bundled bloat — remove it. | | **its `package.json`** | (node) the **bridge SERVER's runtime deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **pkg manifest**: `files[]` (user skills), `discovery_triggers`, scripts, **AND `dependencies:{"adom/adom-bridge":"^1.9.x"}`** (the container needs the AD CLI + core skills to drive you) — but NOT the server's npm deps | **Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the **bridge server's** runtime deps (puppeteer, sharp, ...) that AD installs on the *desktop* at spawn. The other is the **pkg manifest** in the skills tarball: it lists your user-skill `files[]` + `discovery_triggers` AND declares **`dependencies:{"adom/adom-bridge":"^1.9.x"}`** — `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-bridge CLI + core skills the container needs to drive you. What the pkg manifest must NOT list is the **server's** npm deps (those are desktop-side, in the zip) — put them there and you bloat every container install, since the container never runs your server. **Where each file physically lives (this is the map that ends the inconsistency):** - **`bridge.json`** → the **root of the Release zip** (AD reads it post-unzip). Carries `version` + `updateManifestUrl`. - **The Release `.zip`** → upload it as a **Release asset** (`release upload … --platform any`) and point the manifest `url` at its **release-download path**: `https://wiki.adom.inc/download/adom///.zip` (verified to serve anon 206). **fusion + pup do exactly this — copy them.** A loose `/files` blob technically serves too (206), so this is a HYGIENE + right-home rule, not "it won't work": the `/files` store is your git **page repo** (for the manifest, text, images), so a binary there accumulates forever (kicad has **61** stale `-v*.zip`), isn't pinned to a Release, and the `/blob/...` URL is just an **alias of the same blob** (same sha) — you can't tidy it. **⚠ Migrating off `/files` is a SEQUENCE, not a delete:** (1) `release upload` the zip, (2) repoint the manifest `url` at the `/download/` path, (3) verify it serves anon, (4) *only then* `repo rm` the old `/files` copies. **NEVER `repo rm` a zip while your manifest still points at it** (or at its `/blob` alias) — that breaks `bridge_install` + auto-update instantly. - **The manifest** (`adom-bridge--manifest.json`, this naming is the consistent one — keep it) → POSTed to your page **`/files`**. Its `url` points at the **Release download** (`https://wiki.adom.inc/download/adom///.zip`), base-relative + extension-agnostic. `updateManifestUrl` (in the manifest AND in bridge.json) points back at this manifest. - **A big RUNTIME ASSET** (a headless-GL pack like Mesa, a browser download) → declare it in **`prewarm.assets`** so AD downloads + manages it, or bundle it in your seed. **NOT a loose `/files` blob** — kicad's `mesa-llvmpipe-x64.zip` on `/files` is the anti-pattern. - **Your hero image + screenshots** → **WIKI PAGE assets** — set them on the page (the page's hero / `repo push` the image to the page), **NEVER in the skills tarball.** A container that `pkg install`s your skills never renders a hero, so a bundled hero (a real one was **1 MB**) is pure download bloat on every install. **Do NOT put `hero: docs/hero.png` + `docs/**` in the pkg `package.json`** — that is exactly what stuffs the image into the tarball. **The three kinds of skill — where each goes (this IS the demarcation, one table):** | Skill kind | Who reads it | Lives in | In the pkg tarball? | Public? | |---|---|---|---|---| | **USER** (the public / consumer skill) | a consumer AI driving your verbs | your **pkg** | **YES** — that is the pkg's whole job | yes (the pkg is public) | | **DEV** | a maintainer editing the bridge | your **source repo** | **NO, never** | only if your repo is public | | **PUBLISH** | a maintainer releasing the bridge | your **source repo** | **NO, never** | only if your repo is public | **The one rule:** the pkg tarball carries **USER skills only**; **DEV + PUBLISH skills live in the source repo.** Do NOT "scope" dev/publish into the pkg with `user-invocable:false` — that still ships them (pure bloat). Open-vs-closed source only sets your repo's *visibility*; it never changes what's in the pkg. adom-bridge core does exactly this: user/integration skills in the pkg; `RELEASE` / `WIKI_PUBLISH` / `SIGNING` / `AD_RELAUNCH` live only in the source repo. --- ## The boundary — what AD owns vs what YOU own The #1 mistake is filing AD bugs for bridge issues. The split: **AD core owns** (don't reimplement): the CLI/relay/`/command` passthrough (AD relays your JSON verbatim — every field); spawning/reaping your process, the **stable port**, single-instance, the persistent-respawn supervisor, cache install + auto-update; host/process facts (running? pid? port?), the status-chip rendering, the GUI card, the activity log; `status`/`_hint` classification for timeouts/disconnects (AD authors those — you never stamp them). **You own**: your verbs + their behavior + their **rich hints**; your `/health` (+ optional chip fields); your `describe` catalog; your wiki page (hero, brief, `discovery_triggers`, docs); your published **manifest + Release zip**; and your **skills pkg**. If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* is missing (a new lifecycle verb, a relay field) → file it against AD, but don't re-absorb the bridge into AD. --- ## Calling AD back (outbound) — you reach the FULL AD verb set (v1.9.84) Your callback channel is AD's loopback direct API: `POST /command` (env var; fallback `~/.adom/direct-api-port` = `host:port`). As of **AD v1.9.84** this reaches **every dispatchable AD verb**, not just `desktop_*` — same dispatcher the CLI uses, identical JSON back. `GET /commands` lists the full set so you can capability-probe (don't hardcode). - **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"","args":{…}}`. (Pass `app` to override the inference.) - **Top-level verbs you can now call:** `notify_user` (walk the user through something — returns `{action:"displayed"}`), `notify_response` (poll a toast button/input), `targets` (list the OTHER ADs on the relay), `ping`, `bridge_list`, `runtimes`, `status`, … — plus every `desktop_*` and every *other* bridge's verbs. - **Cross-AD (`target`):** add `"target":""` (from `targets`) or `"all"` to route the call to a PEER AD via the relay — e.g. **you run on a VM but the user is on their laptop**: `notify_user` with `target:""` reaches them where they are. `"attended"` isn't resolvable yet (use a concrete clientName). - **`X-Adom-Bridge-Token` (optional, attribution).** AD injects `ADOM_BRIDGE_TOKEN` into your spawn env. Send it as the `X-Adom-Bridge-Token` header and AD badges your calls "bridge" in its Activity Log — nice for the user's transparency. It is **NOT** an approval gate: you're trusted by transport (AD binds 127.0.0.1 only + the user consented by installing you), so your calls — including `write_file`/`run_script` — run ungated. A stale token → 403 (re-read it from your env after an AD restart); omitting it is fine. - **`cliRequired`** verbs (`pull_file`/`send_files`/`shell_execute`) return `412 cli_required` — they need the streaming/approval CLI path, not this HTTP channel. ```bash # Discover, then call — no hardcoding. curl -s "$ADOM_DIRECT_API_URL/commands" curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \ -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \ -d '{"command":"notify_user","args":{"title":"Heads up","body":"…"}}' ``` ### Notify the user AND get their answer back (`notify_user` — two separate axes) Your bridge can prompt the user with a native toast and read their reply — the same `notify_user` verb the AI uses. It has **two independent axes; don't conflate them** (full ref: the `adom-bridge-notify` skill / `skills/NOTIFY.md`): - **Axis 1 — get the answer back.** There is no server-push, so either **`wait:true`** (the `notify_user` call blocks and returns the user's choice inline — best for a one-shot prompt) or fire-and-continue then poll **`notify_events {sinceSeq}`** (drains every click) / **`notify_response {id}`**. The click is recorded durably, so it survives even on a headless box. - **Axis 2 — reveal a window (`focus`).** A LOCAL desktop action, not a reply. `focus:{hwnd|cacheKey|titleContains|app|host}` raises a window on the user's screen when they click. **`focus:{app:""}`** points the click at a window YOUR bridge drives; **`focus:{host:true}`** points it at the app AD is embedded under (Hydrogen Desktop). Pass `focus` whenever the toast is *about* a window, so the click lands there instead of opening AD. ```bash # Ask, and get the answer back inline: curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \ -d '{"command":"notify_user","args":{"title":"Overwrite board?","scenario":"reminder", "buttons":[{"label":"Overwrite"},{"label":"Cancel"}],"wait":true,"timeoutSec":90}}' # -> { "pending": false, "action": "Overwrite" } ``` The response always carries `_capabilities` / `_couldHaveDoneBetter` when a call left something on the table — read them; they teach the verb from use. --- ## Caller provenance: WHO asked (v1.9.180) A user runs roughly **20 AI threads against one desktop**. Until v1.9.180 AD relayed every command indistinguishably, so a bridge received **no caller identity at all**. Three consequences, all real: - You could not **arbitrate concurrent agents** — two threads grabbing the same session looked identical to you. - No bridge log could **attribute a verb** to the thread that issued it, so interference was impossible to reconstruct afterwards. - Any agent's `bridge_kill` **destroyed every other agent's work**, silently, with no way for anyone to see who did it. Filed as wiki issue `adom/adom-bridge#34` by AdityaAngajala, with the pup half at `adom/adom-desktop-puppeteer-bridge#22`. ### What you now receive, for free AD stamps three headers on **every relayed bridge request** — all four request paths (browser, kicad, fusion, and the dynamic third-party dispatch): | Header | What it carries | |---|---| | `X-Adom-Caller-Thread` | The AI thread / conversation tab name, self-reported by the caller | | `X-Adom-Caller-Container` | The container it runs in | | `X-Adom-Caller-Reason` | The per-call justification, when the caller supplied one (control chars stripped, truncated to 300 chars) | **You do nothing to receive these.** No manifest field, no signature change, no opt-in. Reading them is the opt-in part. ### Trust rule — read this before you use them for anything These values are **SELF-ASSERTED**, exactly like `reason`. Use them for **attribution, logging, UX and arbitration hints**. **NEVER for authorization, and never as a security boundary.** AD's own security model is transport-based (the `adom-bridge-permissions` skill has the full model): a caller is trusted because of *how it reached AD*, not because of what it *says about itself*. A header a caller supplies about itself cannot gate anything — if you write `if (thread === "admin-tab") allowDangerousThing()`, you have written a hole, not a check. One asymmetry worth knowing: the container name in `X-Adom-Caller-Container` is the one the **caller claimed**. AD separately knows a **verified** container (the authenticated relay connection name) and shows the user **both** when they disagree. You only get the claimed one, so treat it as a label, not an identity. ### What to do with it **1. Log it.** Put the thread in your per-verb log line. This is the single highest-value use, and it is three lines of code: ```javascript // node — read once, at the top of your request handler const caller = { thread: req.headers['x-adom-caller-thread'] || 'unidentified', container: req.headers['x-adom-caller-container'] || 'unknown', reason: req.headers['x-adom-caller-reason'] || null, }; console.log(`[verb] ${verb} session=${sessionId} caller="${caller.thread}"`); ``` ```python # python — same idea; header lookup is case-insensitive on BaseHTTPRequestHandler caller_thread = self.headers.get('X-Adom-Caller-Thread', 'unidentified') caller_container = self.headers.get('X-Adom-Caller-Container', 'unknown') caller_reason = self.headers.get('X-Adom-Caller-Reason') log.info('[verb] %s session=%s caller="%s"', verb, session_id, caller_thread) ``` That one field is what makes an interference report reconstructable: `[verb] browser_eval session=rev caller="chip-fetcher tab 3"` answers "who moved my page?" instantly, where a bare `[verb] browser_eval session=rev` never can. **2. Arbitrate.** If your bridge has **sessions or resources an agent can own** — pup sessions are the motivating case — record the owning thread at creation time and check it on every later use: ```javascript // on create sessions.set(id, { ...state, ownerThread: caller.thread }); // on use by a DIFFERENT thread const s = sessions.get(id); if (s.ownerThread && s.ownerThread !== caller.thread) { // warn loudly by default; refuse only if this is destructive result._warning = `session ${id} is owned by "${s.ownerThread}" — you are "${caller.thread}". ` + `Two agents driving one session will interfere. Coordinate, or open your own session.`; } ``` The recommended posture: - **Warn loudly by default.** A second agent reading or screenshotting a session is usually fine, and hard-blocking it turns a shared machine into a locked one. - **Refuse only for destructive operations** — closing, resetting, navigating away, deleting. - **Always name the current owner in the message.** The whole point is that the second agent can now go coordinate with a thread it can identify. An error that says "session busy" without a name is barely better than no header at all. **3. Label the UI.** If your bridge drives a visible window, put the owning thread where the **user** can see it — window title, taskbar tooltip, or jump-list name — via `desktop_set_window_identity` (and `desktop_taskbar`'s `thumbnailTooltip` for uncapped hover text). The user is the one with 20 tabs open; showing which tab owns which window is the fix for their side of the problem. Full guide: the `adom-bridge-window-identity` skill, and the "Branding + driving a window you borrowed" section immediately below. **4. Report it back.** Include the owning thread in your **status / list verbs**, so an agent can *discover* it is not alone before it stomps on something: ```jsonc // _list_sessions { "sessions": [ { "id": "rev", "ownerThread": "chip-fetcher tab 3", "url": "…" } ], "_hint": "A session with an ownerThread other than yours is being driven by another AI thread. Open your own session rather than sharing one." } ``` ### Notifications already carry it `notify_user` derives its toast attribution line from the caller automatically, so a toast your bridge sends **on an agent's behalf already names the thread** — you do not have to build that string. Pass an explicit `attribution` string only when you want to override it. ### ⚠ REQUIRED — when YOU call an AD verb, forward the identity This is the half most bridges will miss, and it is the half that makes the whole feature work or fail. Your bridge calls AD verbs to do its job: `desktop_screenshot_window`, `desktop_set_window_identity`, `notify_user`, `desktop_taskbar`. When you make that call **while carrying out a verb an AI thread asked you for, you are acting on that thread's behalf** — so echo the identity you were handed straight back onto your own request. Otherwise the chain dies at your doorstep: the user's Activity Log says *"pup did this"*, the originating thread vanishes, and the approval toast asks them to authorize a nameless bridge. **Echo all four headers, verbatim:** ```javascript // node — inside the handler for a verb an AI asked you for const fwd = { 'X-Adom-Caller-Thread': req.headers['x-adom-caller-thread'] || '', 'X-Adom-Caller-Container': req.headers['x-adom-caller-container'] || '', 'X-Adom-Caller-Reason': req.headers['x-adom-caller-reason'] || '', 'X-Adom-Caller-Delegate': 'pup', // ← YOUR bridge name }; await fetch(`http://127.0.0.1:${adPort}/command`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...fwd }, body: JSON.stringify({ command: 'desktop_screenshot_window', args: { hwnd } }), }); ``` ```python fwd = { 'X-Adom-Caller-Thread': self.headers.get('X-Adom-Caller-Thread', ''), 'X-Adom-Caller-Container': self.headers.get('X-Adom-Caller-Container', ''), 'X-Adom-Caller-Reason': self.headers.get('X-Adom-Caller-Reason', ''), 'X-Adom-Caller-Delegate': 'kicad', # YOUR bridge name } ``` `X-Adom-Caller-Delegate` is the one you **add** rather than forward. It names *you*, and it is what lets AD show the user both facts at once: **`chip-fetcher tab 3 (via pup)`**. Attributing the call to the thread alone would hide who ran it; attributing it to the bridge alone would hide who asked. Omit the header and AD falls back to the generic `via bridge`, which is honest but much less useful. **When you are acting on your OWN behalf — a health poll, a timer, a crash cleanup — do NOT forward a stale identity.** Send your own instead: ```jsonc { "command": "notify_user", "args": { "caller": { "aiThread": "pup bridge (self)", "containerName": "local" }, … } } ``` An explicit `caller` block in the args always beats the headers, so this is unambiguous. **Two things AD does for you here:** explicit args win over forwarded headers (so the override above just works), and AD carries the delegate forward onto any onward hop, so a chain two bridges deep still shows the original delegate. ### Where it comes from (the caller side) Useful to understand, though none of it is your responsibility: ```bash # Per call — the CORRECT mechanism: adom-bridge-cli --ai-thread "chip-fetcher tab 3" '' ``` The `adom-bridge` CLI attaches a `caller` block to **every** verb automatically. A relay call with **no `aiThread` is REFUSED by AD** with `errorCode: caller_identity_required` before it ever reaches a bridge. > **Correction, 2026-07-25 (AD 1.9.182):** an earlier version of this page told callers to `export ADOM_AI_THREAD` once per session. **That advice was wrong and has been withdrawn.** Roughly 20 AI threads share one container and one `$HOME`, so the env var scopes to the shell environment, not to the thread — every thread then reports the *same* name, which is worse than no name at all because it is confident and plausible. It also failed silently: tool shells are non-interactive, so an export appended below `~/.bashrc`'s `case $- in *i*` early-return never ran. The env var is still honored, but only fits a container running exactly one agent (CI, a single-purpose job). **If your bridge's own docs repeat the export advice, please correct them.** **So by the time a request reaches you, identity is normally present.** The exception is **loopback callers** — HD, another bridge, or the local CLI — which are trusted by transport and not yet *required* to identify (that gate tightens once bridges adopt the forwarding contract above). Code for the absent case (`|| 'unidentified'`), never assume the header exists. ### If your bridge wants to REQUIRE identity — use the shared contract Some verbs are worth refusing anonymously. If you do, **use AD's exact refusal shape** so the AI sees one consistent remedy across the whole ecosystem instead of a different fix per bridge: ```jsonc { "success": false, "errorCode": "caller_identity_required", "error": "'' needs to know WHO is asking — the user runs many AI threads and needs to see which one drove this.", "supplyIdentity": { "bestWay": "adom-bridge-cli --ai-thread \"\" ''", "orInArgs": { "caller": { "aiThread": "", "containerName": "" } } }, "_hint": "This is attribution, not a permission check — the name is self-reported and nothing is gated on it." } ``` Reusing `caller_identity_required` verbatim is the point: an AI that learned the remedy once applies it everywhere. ### Self-audit - [ ] Does every verb log line include the **caller thread**? - [ ] Do your **session-creating** verbs record the owning thread on the session? - [ ] Do your **session-using** verbs warn (or, if destructive, refuse) when a different thread arrives — **naming the current owner**? - [ ] Does any **window you drive** show the owning thread to the user (title / tooltip / jump-list)? - [ ] Do your **status / list verbs** report `ownerThread` so an agent can discover it is not alone? - [ ] **When you call an AD verb on a thread's behalf, do you FORWARD all three caller headers plus your own `X-Adom-Caller-Delegate`?** - [ ] When you call an AD verb on your **own** behalf (poll, timer, cleanup), do you send your own `caller` block rather than a stale forwarded one? - [ ] If your docs told callers to `export ADOM_AI_THREAD`, have you corrected them to the per-call `--ai-thread` flag? - [ ] Have you confirmed you use these headers **nowhere** as an authorization check? --- ## Branding + driving a window you borrowed (window identity + taskbar, v1.9.106–1.9.153) If your bridge drives a window another process owns — the classic case is a **Chrome for Testing** window that otherwise reads *"Test"* with Chrome's icon — AD gives you a generic verb family to make it present as YOUR app across every Windows shell surface, and to show live status on its taskbar button. AD stays generic: it applies whatever name/icon/command you pass; it knows nothing about your app. **Full guide: the `adom-bridge-window-identity` skill** (`https://wiki.adom.inc/api/v1/pages/adom-bridge/files/docs/WINDOW_IDENTITY.md` or the repo `skills/WINDOW_IDENTITY.md`). The essentials: - **Two halves, you need both:** `desktop_register_app_identity {appId, displayName, iconPath, shortcut}` teaches Windows what an AUMID means (HKCU only, no UAC; `shortcut:false` for a per-session id with no Start Menu spam), and `desktop_set_window_identity {hwnd, appId, iconPath, displayName, relaunchCommand}` stamps it on the live window. Stamp without register → Alt-Tab / taskbar fall back to the owning exe's icon. - **Per-session identity:** register `shortcut:false` per window (e.g. `Adom.Pup.`) so each keeps its own taskbar button; `desktop_unregister_app_identity {appId}` on close. - **Jump list + header:** `desktop_set_window_jumplist {appId, tasks, hwnd?, headerIcon?, headerCommand?}` adds the right-click menu AND (with `hwnd`+`headerIcon`) brands the header row (the app tile above Pin/Close) with no Start Menu shortcut. - **Taskbar status:** `desktop_taskbar {hwnd, progress?, overlay?, flash?, thumbnailTooltip?, thumbnailClip?}` paints glanceable state on any window's button. **New in v1.9.153:** `thumbnailTooltip` is the ONLY uncapped hover-text surface (the window title truncates ~25-30 chars; this does not, and takes newlines; `""` clears it), and `thumbnailClip:{x,y,w,h}` crops the live hover preview to a region (`null` resets). Overlay compositing (`overlay.avatar`/`profileDir`) preserves a browser profile face while adding your mark. - **Icon format — read the `iconCheck` in every response.** The identity verbs inspect any icon you pass and return `iconCheck {kind,sizes,issues,ok,hint}`. The traps it catches: a **256px `.ico` size that is not PNG-compressed** renders as the generic white-document icon (Vista+ rule); **SVG can't be loaded** by the Win32 shell; the AUMID registry icon wants a `.ico`/`.png`, not an `.exe`. If `iconCheck.ok` is false, fix the file and re-stamp — don't ship the broken icon. Ship a multi-size `.ico` (16/24/32/48/256, the 256 PNG-compressed). - **The live-tile trap:** re-stamping the SAME appId with a new icon updates the title bar + Alt-Tab but NOT the taskbar tile (Win11 bakes it at button creation). To change a live tile, register + stamp a DIFFERENT appId; the button is recreated in ~1s. --- ## Runtime contract — AD provisions Node/Python; you bind loopback (v1.9.63 / v1.9.69) **The single most important change for a Node or Python bridge.** As of AD **v1.9.63** you no longer bootstrap your own interpreter, and you MUST bind loopback. Four rules: 1. **Don't bootstrap your own Node/Python.** AD owns a global, portable, **no-UAC** runtime under `~/.adom/adom-runtimes/`: a system install if one's on PATH, else a portable copy it downloads + prewarms in the background on first launch. AD spawns your `entrypoint` with that interpreter **by absolute path**. So **delete every `winget install node` / `desktop_install_node` / "please install Python" / self-download step** from your bridge and its skills. `spawn.kind: "node"|"python"` IS your runtime declaration — AD reads it and provisions the runtime. Anyone can check status with the **`runtimes`** verb (`state ∈ absent|installing|ready|failed`, `source ∈ system|cache`, version). AD pins the version (Node 22.11.0 / Python 3.12.13 today) — need a different major? ask the AD-core thread; don't ship your own. 2. **Bind `ADOM_BIND_HOST`, never `0.0.0.0`.** AD passes an **`ADOM_BIND_HOST`** env var (always `127.0.0.1`) to every bridge it spawns. A bare listen that defaults to `0.0.0.0` pops a **Windows Firewall "allow access?" dialog** on first run — and AD's hard guarantee to users is **no firewall prompt by default**. - Node: `server.listen(PORT, process.env.ADOM_BIND_HOST || '127.0.0.1', cb)` - Python: `HTTPServer((os.environ.get('ADOM_BIND_HOST', '127.0.0.1'), PORT), Handler)` 3. **Ship the Release zip source-only — AD installs your deps, and v1.9.69 makes it bulletproof.** A Node bridge's zip carries SOURCE only (no `node_modules`). AD reuses the bundled seed's `node_modules` via `NODE_PATH` when versions match, else runs **`npm install --include=optional`** for you with the managed runtime's own npm. **As of v1.9.69 AD puts the managed runtime's dir on the child PATH for that install AND for your spawned process** — so a dep's postinstall / `node-gyp` / `prebuild-install` that shells out to a **bare** `node`/`npm`/`npx` (puppeteer's own `node install.mjs`, `sharp`, `keytar`, `better-sqlite3`, `bcrypt`) resolves even on a machine with **no system Node**. **You do NOT add the runtime to PATH yourself** — AD guarantees it. (Python: the interpreter dir + `Scripts/` are on PATH too, so pip can build wheels.) 4. **Bundle deps in your SEED for an instant first spawn.** Source-only zip + a bundled-seed `node_modules` at the same version = AD reuses the seed via `NODE_PATH` (instant); a wiki version newer than the seed forces one cold `npm install` (now PATH-correct, but slower). Bump the seed in lockstep with each Release. **Net:** declare `spawn.kind`, bind `ADOM_BIND_HOST`, ship source-only. AD does the rest — no UAC, no firewall prompt, no `'node' is not recognized`. --- ## Staying current — catch up on SDK changes yourself (no prompt needed) This SDK evolves. When it does, AD posts a re-audit notice to **YOUR bridge's wiki discussion** and re-publishes this billboard. You do NOT need a human to hand you a prompt — self-serve at the start of a work session: 1. **Check your discussion for a notice.** `adom-wiki discussion list ` (or open your page's Discussions tab) and read any "SDK update" / "re-audit" thread. A notice can be EDITED after posting (a correction), so always read the **current** body, not a cached earlier version. 2. **Re-read this billboard**, especially "Where every file lives" (above) and the "Self-audit checklist" (below): `https://wiki.adom.inc/adom/adom-bridge-sdk` (or `curl -s https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files/README.md`). 3. **Run the Self-audit checklist** (next section) against your code, `bridge.json`, skills, README, and wiki page. Fix every miss. 4. **Reply on the discussion** with what you changed or any blockers. That thread is the ONLY channel AD uses to reach you, so closing the loop there is how AD knows you are current. --- ## Ask the AI to report bugs, in the OUTPUT, not the skill file You cannot reproduce every environment. Your bridge runs on machines with browser installs, OS versions, security policies, hardware and concurrency patterns you will never have locally. **The AI driving your bridge is standing on exactly that machine.** It is the only party holding the failing response, and the moment it holds it is the only moment it will file anything. So make the invitation part of your verb output, the same way `_hint` is. This is THE ONE PRINCIPLE at the top of this page applied to feedback: the AI almost never reads your on-disk SKILL.md, and it ALWAYS reads the output of a CLI call. **The evidence that this channel works.** In roughly two days, wiki issues filed against the puppeteer bridge produced: a CPU-pegging orphaned-renderer bug that froze a laptop and forced a reboot (#14, #21), a respawn failure that broke the bridge on every idle cycle (#15), a session-tracking bug where windows were open and drivable but reported as zero (#16), a repo-versus-release divergence that would have silently reverted five releases (#19), and a concurrency and readiness report that caught a live blocking regression shipped hours earlier (#22). **Not one of those would have been found on a maintainer's machine.** They came from real installs: different Chrome and Edge combinations, different AD versions, concurrent agents, a macOS box, a stalled download. **Return a `_reportIssues` field naming YOUR page's issue list, with the exact commands:** ```jsonc { "success": false, "errorCode": "…", "_hint": "…", "_reportIssues": "THIS MAY BE A BUG. PLEASE REPORT IT. Check for a duplicate with `adom-wiki issue list adom/`, then file: `adom-wiki issue create adom/ --title \"\" --category bug-report --body \"\"`. Reports from real machines are the only way this bridge gets correct. (An AD-core problem, such as the relay, bridge lifecycle or caller identity, belongs on adom/adom-bridge instead.)" } ``` **When to attach it. Throttle it, or the AI learns to skip it:** | Moment | Why | |---|---| | **Always on a failure** | The highest-value moment: a bug just happened and the evidence is still in the response. | | **Once per bridge process, on the first verb** | Orientation, so the AI knows where to report *before* anything breaks. | | **Occasionally after that** (e.g. every ~40th call) | A quiet reminder on a long-running session without taxing every response. | A line on **every** response is noise that trains the caller to ignore the field. A line on every **failure** is a bug report waiting to be filed. **Make it actionable, not a slogan.** "Report bugs" produces nothing. Give the AI the exact `adom-wiki issue create` command, your slug, a `--category`, and the list of evidence to include (the verbatim response JSON and your bridge version are the two that make a report reproducible). Tell it to check for a duplicate first: an `issue list` call costs nothing and keeps your page clean. **Route the report to the repo that owns the code.** Say explicitly, in the same string, that AD-core problems (the relay and `/command` passthrough, spawn and provisioning, bridge lifecycle, caller identity) go to **`adom/adom-bridge`**, not to your page. Authors get this wrong in the other direction too, which is the next section: a misfiled issue is a note to yourself that the people who can fix it never read. **Let the user turn it off.** Ship a settings toggle (pup uses `browser_configure {reportIssues:"off"}`) so a user who finds it noisy can silence it without losing functionality. Default it **on**: the cost is a few tokens on failures, and the benefit is the bug class you would otherwise ship to every user. **Reference implementation:** the puppeteer bridge does this at its single `sendJSON` chokepoint (v1.9.95), so all ~155 response sites are covered from one place, and it never overwrites a `_hint` a handler already set. --- ## Filing issues against AD (and the other repos you depend on) You WILL find AD-core bugs and gaps while building your bridge. That is expected and useful. But file them in the RIGHT repo's issue list, or the people who can fix them never see it. **The rule: an issue lives on the issue list of the repo that OWNS the code that must change.** - A bug in YOUR bridge's verb / hint / self-heal / status chip goes to **YOUR page's issue list** (or you just fix it, since you own it). - A missing or broken **AD-CORE** capability (a lifecycle verb, a spawn / provision / bind behavior, the relay passthrough dropping a field, a manifest field AD must honor, the status-chip contract) goes to **`adom/adom-bridge`**, NOT your own page. AD-core's maintainers and AI watch `adom/adom-bridge`; they do NOT read your bridge page's issues. **An AD ask filed on your own page is a note to yourself.** - A **wiki or CLI** bug goes to `adom/wiki`. A **sibling bridge's** bug goes to that bridge's page. **How (the CLI):** ```bash adom-wiki issue list adom/adom-bridge # FIRST: skim for a dup, comment if one exists adom-wiki issue create adom/adom-bridge \ --title ": " \ --category bug-report \ --body "$(cat your-writeup.md)" ``` **Write the body like a good bug report:** what you hit live (with the date and the AD version), the measured behavior, the AD-owned root cause if you found one, and a concrete ask. Separate clearly what is AD-core's to fix from what is yours, and say so explicitly, so the two are never conflated. **After you file:** the AD-core thread replies on that issue. Read the reply, it may change your plan (for example "fixed in AD X.Y, bump your pin"). That issue thread is the cross-repo channel; keep the loop closed there. **Why this matters most for AD:** AD-core spawns you, provisions your runtime, relays your verbs, and installs you, so AD is the repo you will file against most often. Get the destination right the first time. The established precedent all sits on `adom/adom-bridge`: #26 and #27 (pup to AD, Chrome for Testing), #16 (pup to AD, window-verb interception), #3 / #20 / #21 (Bridge SDK asks). --- ## Self-audit checklist — run this when asked to "audit against the SDK" When a maintainer says *"audit your code, skills, README, and wiki page against the Bridge SDK,"* **this is the checklist.** Each item names its section below; fix every miss, then re-check. **bridge.json** (the manifest in your zip): - [ ] `spawn.kind` ∈ `python|node|exe|external-http`, with **`entrypoint`** (NOT `process`/`cmd`/`args`); `healthEndpoint` is **inside `spawn`**; `port:0` lets AD pick. *(→ bridge.json)* - [ ] `updateManifestUrl` → YOUR page's manifest (durable auto-update); `docs` → your own page; **`homepage` is a `wiki.adom.inc` URL, NEVER `github.com`.** - [ ] `detect` declared iff you drive a HOST APP (KiCad/Fusion/Altium…); omitted if you bring your own runtime (pup). `prewarm.assets` declared for heavy downloads (e.g. `chrome-for-testing`). *(→ Cold-start tiers)* - [ ] **`timeouts`** declared if ANY verb can run longer than 60s (a big export/render/cloud-open) — with a matching **`statusVerb`** to poll. Third-party bridges were 60s-capped before v1.9.79; this is how you raise it. *(→ bridge.json)* **Artifacts & deps** (the two-artifact split — the #1 inconsistency) *(→ Where every file lives)*: - [ ] Your Release `.zip` is a **Release asset** (`release upload`), NOT a loose `/files` blob — and old version zips are NOT piling up on `/files` (audit for stray `*-v*.zip`). - [ ] The **server's** runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python). The **pkg's** `package.json` declares `dependencies:{"adom/adom-bridge":"^1.9.x"}` (so `pkg install` pulls the AD CLI + core skills) and does NOT list the server's npm deps. - [ ] A big runtime asset (Mesa, a browser) is a **`prewarm.asset`** or seed-bundled — NOT a loose `/files` blob. - [ ] Your **manifest** (`adom-bridge--manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob. - [ ] **PAYLOAD:** `unzip -l | sort -k1 -n -r | head` shows **runtime only** — no `.mp4`/`.png`/`.jpg`/screenshots/CHANGELOG/`.github`. A runtime zip is normally well under 1 MB; if yours is bigger, justify every large entry. `tar tzf ` shows **skills only** — zero media, zero binaries. Media belongs on the PAGE. *(→ Payload rules)* - [ ] **PAGE COPY:** your package `description` AND README each carry the one-sentence statement that `pkg install` installs the bridge's SKILLS for your container, not the bridge runtime. One sentence, not an essay. *(→ Artifact 2)* **Runtime** (Node/Python bridges) *(→ Runtime contract)*: - [ ] You bind **`ADOM_BIND_HOST`** (loopback default), never `0.0.0.0`. - [ ] You do **NOT** bootstrap your own Node/Python — no `winget`/`desktop_install_node`/self-download in code or skills. `spawn.kind` is the declaration; AD provisions it. - [ ] Release zip is **source-only** (no `node_modules`); you rely on AD's `npm install` (PATH-correct as of v1.9.69) + a lockstep bundled seed for instant spawn. You do NOT put the runtime on PATH yourself. **Verbs & output** (what the AI actually reads): - [ ] EVERY verb returns a rich **`_hint`** (+ `_next`/`related`/`pitfalls`). *(→ THE ONE PRINCIPLE)* - [ ] A `_describe` verb lists your whole catalog. *(→ Verb contract)* - [ ] No verb blocks on a heavy install/download — background it, report `installing`/`warming`; `_readiness` is read-only. *(→ Cold-start tiers)* - [ ] `/health` returns `led`/`summary`/`tooltip` truthfully. *(→ Health + status chip)* **Discovery** (can a plain request find you?): - [ ] **10+ user-task `discovery_triggers`** (everyday phrasings, NOT dev jargon). **No triggers = invisible.** *(→ Artifact 3)* - [ ] You ran `discover preview --json` on 5-7 real user queries and land **top-3** for each. - [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION. **Skills & docs** (what the container + humans read): - [ ] Your pkg ships **ONLY your USER skill(s)** — a real `skills//SKILL.md` (core user skill + user sub-skills) with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)* - [ ] **DEV + PUBLISH skills are in your source REPO, NOT the pkg** — not in `files[]`, not scoped in via `user-invocable:false`. A developer gets them by cloning the source; the normal user never needs them. Open-vs-closed source is irrelevant (it only sets repo visibility). *(→ Where every file lives)* - [ ] Your pkg's `package.json` declares `dependencies:{"adom/adom-bridge":"^1.9.x"}` so `pkg install` pulls the AD CLI + core skills the container needs. *(→ Where every file lives)* - [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)* - [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted). --- ## bridge.json — the manifest that ships INSIDE your zip ```jsonc { "manifest_version": 1, "name": "blender", // registry name → verb prefix "blender_" "displayName": "Blender", // in-app chip label (the tool's real name) "version": "1.2.0", // numeric; a newer CACHE copy supersedes the bundled seed "description": "Drive Blender headless + GUI", "author": "you", "license": "MIT", "docs": "https://wiki.adom.inc/adom/adom-bridge-blender-bridge", // your OWN page (drives skillPkg + hero) "hero": "https://.../hero.png", // optional; else AD uses your wiki page hero, else a monogram. Ship it at 1.6 aspect (≈2000×1250) — see "Card hero + update cost" "spawn": { "kind": "python", // python | node | exe | external-http (NOT "process") "entrypoint": "server.py", // the file/exe AD launches; AD AUTO-APPENDS `--port ` to argv "port": 0, // 0 = AD picks a STABLE port (recommended). Bind 127.0.0.1:. "persistent": true, // AD's supervisor respawns it if it dies "healthEndpoint": "/health", // INSIDE spawn. AD probes it for the chip (default /health) "stopMethod": "kill", // kill | sigterm | graceful_endpoint "killImageName": "python.exe" // image name for taskkill on stop (kind:python/node) }, "verbPrefixes": ["blender_"], // any verb with these prefixes routes to you "verbs": ["blender_render", "blender_status", "blender_describe"], // every verb (routing + Verbs tab) "statusVerb": "blender_status", // verb a caller polls after a long op times out "updateManifestUrl": "https://wiki.adom.inc/api/v1/pages/adom-bridge-blender-bridge/files/blender-manifest.json", "timeouts": { // v1.9.79 — per-verb HTTP budgets (seconds); see note below "default": 60, // fallback for any verb not matched (absent → AD's global 60s) "verbs": { "render": 600, "export_step": 360 }, // exact BARE verb names (no prefix) "prefixes": [ { "prefix": "export_", "seconds": 120 } ] // fallback rules, first match wins }, // v1.9.47 cold-start (see "Cold-start tiers" below): "detect": { // Tier 2 — how AD DETECTS your HOST APP. AD NEVER installs it. "hostApp": "Blender", // omit the whole `detect` block if your bridge brings its own runtime "appPathsExe": "blender.exe", // (e.g. pup ships its own browser → no host app) "paths": { "windows": ["%ProgramFiles%\\Blender Foundation\\*\\blender.exe"] } }, "prewarm": { "assets": [] } // Tier 1 — heavy runtime assets AD prewarms (e.g. ["chrome-for-testing"]) } ``` - **`spawn.kind`** is `python` | `node` | `exe` | `external-http` — there is **no `"process"` kind**, and no `cmd`/`args`/`cwd`. AD launches `spawn.entrypoint` and **automatically appends `--port `** to its argv; your server parses `--port`. (`external-http` = AD doesn't spawn, only probes a port you declare via a `discovery` block.) - **`spawn.port: 0`** → AD allocates a STABLE port (persisted across respawns + AD restarts) and passes it. Bind `127.0.0.1:`. NEVER hardcode a port (Hyper-V/Docker silently reserve ranges — see PORTS.md). - **`spawn.healthEndpoint`** lives **inside `spawn`** (not at the top level), default `/health`. - **`updateManifestUrl`** — the full URL of YOUR manifest on YOUR page. **Declare it in `bridge.json`** so it survives a republish; AD polls it (on launch + every 4h) and auto-updates users. (AD also remembers the install URL in `~/.adom/bridge-install-urls.json` as a fallback, but the declared field is the durable, author-intended path.) - **`docs`** — point at YOUR dedicated wiki page. AD derives your **skillPkg** (`adom/`) and your card hero from this. Don't point it at a shared/structural page. - **`homepage`** — a **`wiki.adom.inc`** URL (your own page, or `https://wiki.adom.inc/adom/adom-bridge` for the platform). **NEVER `github.com/...`** — GitHub is source-backup only; the wiki is the canonical home. (A `homepage: github.com/adom-inc/adom-bridge` is a stale default to fix.) - **`detect` / `prewarm`** — the v1.9.47 cold-start declarations (full rules in "Cold-start tiers" below). `detect` = your HOST APP (AD detects, never installs); `prewarm` = your heavy RUNTIME assets (AD prewarms/auto-installs). A node bridge that ships its deps still works without `prewarm`; declare `prewarm.assets` only for big *downloaded* assets like a browser. - **`timeouts`** (v1.9.79) — per-verb HTTP budgets (seconds) AD honors so a SLOW verb (a big export, a cloud open, a long render) isn't cut off before it finishes. Resolution: exact `verbs` (BARE names, no prefix) → first matching `prefixes` → `default` → AD's global 60s. A timeout is **NON-terminal**: AD returns `{stillRunning:true, statusVerb, timeoutSeconds}` and the caller polls your `statusVerb` (so ALSO declare `statusVerb`). **⚠ Before v1.9.79 a third-party bridge was hard-capped at 60s with no way to raise it** — if any of your verbs can run longer, declare `timeouts` (this is the fix). AD reads it with ZERO AD change; the two bundled EDA bridges keep a labeled built-in table only until they declare their own. --- ## Artifact 1 — the RUNTIME: publish your `.zip` as a RELEASE + a manifest This is the code AD streams onto the user's machine. Two files on your page: 1. **A versioned Release `.zip`** of your bridge dir (server + `bridge.json` at the zip ROOT + any assets). Ship it as a **Release** (the downloadable, version-pinned artifact), not a loose `/files` blob: ```bash adom-wiki release create adom/adom-bridge--bridge --title "..." --changelog "..." adom-wiki release upload adom/adom-bridge--bridge your-bridge-v.zip --platform any ``` (Node bridges: the zip carries SOURCE only — keep `node_modules` out; AD/the seed handle deps. See Prewarm.) 2. **The manifest JSON** (e.g. `blender-manifest.json`) — identity + where the zip is — POSTed to your page `/files`: ```jsonc { "name":"blender", "version":"1.2.0", "url":"https://wiki.adom.inc/download/adom/adom-bridge-blender-bridge/1.2.0/blender-v1.2.0.zip", // base-relative, extension-agnostic (.bin works where wiki blocks .zip) "sha256":"…", "size":123456, "verbPrefixes":["blender_"], "healthEndpoint":"/health", "updateManifestUrl":"https://wiki.adom.inc/api/v1/pages/adom-bridge-blender-bridge/files/blender-manifest.json" } ``` **Users install/update** with AD's `bridge_install {manifestUrl}` → AD downloads the zip, sha256-verifies, unzips into `%LOCALAPPDATA%\Adom Bridge\bridges-cache\\`, rescans, and remembers the URL for auto-update. **To ship a new version:** bump `version` in BOTH `bridge.json` (in the zip) and the manifest, re-`release upload` the zip, re-POST the manifest. Users auto-get it on the next 4h poll, or immediately via `refresh_bridges {name}`. **A bundled SEED** (a `plugins//` folder shipped in AD's NSIS) is the offline/first-run fallback; your published cache copy with a higher `version` supersedes it (cache-over-bundled, version-aware). ⚠ **A `release upload` REPLACES a same-platform asset ONLY when the FILENAME is IDENTICAL** — a different name (a version bump `-v1.2.0` → `-v1.3.0`) ADDS a second asset, leaving a stale zip on the release. Keep ONE asset per release: overwrite the same filename, or `adom-wiki release delete-asset ""` after a rename. (A stale extra won't break the manifest-URL install, but it clutters the release.) --- ## Artifact 2 — the SKILLS pkg: container-side docs (`.claude/skills` / `.codex/skills`) Your runtime runs on the user's DESKTOP; the AI driving it runs in a cloud/WSL2 CONTAINER. That container needs your **consumer SKILL.md** locally to know your verbs. Ship it as its own **`adom-wiki pkg`** (skills only, NO binaries): **Layout** (reference: `adom/adom-wiki-skillpack`): - **The pkg carries ONLY your USER skill(s).** Each is a real `skills//SKILL.md`. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words. Large surface → a core user skill + user sub-skills, but **every skill in the pkg is a *user* skill.** - **DEV + PUBLISH skills do NOT go in the pkg — they live in your source repo** (a developer gets them by cloning to edit the bridge). Do NOT list them in `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them and bloats every container install). - **Declare `dependencies:{"adom/adom-bridge":"^1.9.x"}`** in `package.json` — `pkg install` resolves it npm-style, so installing your bridge's skill pkg also pulls the AD CLI + core skills the container needs to drive you. - **Each sub-skill's body opens with a `Parent skill:` line** (first line after the frontmatter): `Parent skill: **adom-bridge--bridge**`. - **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill ` line each, kept in sync). The publish linter REQUIRES explicit listing. (The old "use `skills/**`" advice is dead.) ```bash # Stage dir: ROOT SKILL.md + skills//SKILL.md per USER skill (dev/publish stay in the repo), # package.json {name:"adom-bridge--bridge", version, discovery_triggers, # dependencies:{"adom/adom-bridge":"^1.9.x"}, # files:[ every USER-skill path, explicitly ], scripts:{install,uninstall}}. # TWO traps that still bite — verify each with `tar tzf` before publishing: # 1. ⚠ pkg pack/publish HONORS the stage dir's .gitignore — a gitignored skills/ ships # a 3 MB tarball with ZERO skills. Set .gitignore aside across pack+publish, restore after. # 2. ⚠ Keep the tarball LEAN — NO release zip, NO src/ tree, NO hero PNGs (it was 16 MB # before guards). Skills + docs only. adom-wiki pkg pack # then: tar tzf → every skills//SKILL.md # listed in files[] present, ZERO binaries adom-wiki pkg publish --org adom # publishes adom/adom-bridge--bridge ``` **`skill_count` on your page counts the USER skills your published PKG carries** — so it should be SMALL (1 for a single-skill bridge, a handful for a core + sub-skills). If it looks inflated, you probably shipped dev/publish skills that belong in the repo instead. The metric is NOT "SKILL.md files in the repo," so a `type:skill` page can read `skill_count: 0` while its repo holds many — don't chase parity across page types (wiki-side quirk). A container gets it **without anyone asking**: - `bridge_install` returns `skillPkg` + `installSkill` (AD derives `adom/` from your `docs`) and the `_hint` tells the AI to run it. - **`adom-bridge-cli sync_skills`** installs every connected desktop's bridge skillPkgs (the CLI also runs it once/day in the background), so a container that connects a week later self-heals your skill. - The wiki page's **Skills tab** lists the skills your pkg ships, so the page itself advertises them. **Install to BOTH agent homes.** A container may run Claude OR Codex — your pkg's `install.sh` must deploy the user skill to **`~/.claude/skills/`** AND **`~/.codex/skills/`** (Codex is a real second skills home now). `adom-wiki pkg update` keeps both fresh. ### ⭐ REQUIRED: say on your PAGE that `pkg install` gives SKILLS, not the bridge Your page carries **two artifacts that look interchangeable and are not**, and users (and AIs) reasonably assume `adom-wiki pkg install adom/` installs the bridge. **It does not.** Installing the package alone gives skills with no bridge; `bridge_install` alone gives a bridge whose calling AI has no skills. Most setups want both, and nothing on a default bridge page says so. **So state it, in ONE plain sentence, in both your package `description` and your README.** Keep this line, or something equivalent: > This package installs the bridge's SKILLS into your container so your AI knows how to drive it; Adom Bridge loads the bridge runtime itself from the release zip. **Keep it to one sentence.** The package `description` renders as your page subtitle AND the text under the Install card, so a multi-paragraph architecture essay there actively hurts: it buries the one fact a visitor needs. (AD-core overshot exactly this and had to trim it back.) The long version belongs in your README body, not the card. ⚠ **Empirically, neither card renders a per-item caption today** (verified in-page 2026-07-07): the release title/changelog does not surface on the Download card, and the package description surfaces only as the page subtitle, never at the Install card itself. Setting both fields is still correct hygiene, and they do show on the Releases tab, but do not assume the cards self-explain until the wiki exposes a caption slot (filed as `adom/wiki` #93). --- ## ⛔ Payload rules — both artifacts are RUNTIME-ONLY / SKILLS-ONLY. Media lives on the PAGE. This is the single easiest way to hurt every one of your users, and it is invisible from your machine. **The real case (fusion, caught 2026-07-19):** `adom/fusion-bridge`'s release zip was **16.7 MB, of which ~15.3 MB was demo MP4s, screenshots and repo docs**. Every user's machine streamed that on `bridge_install`, and again on every auto-update. Stripped to runtime-only it is **456 KB — 97% smaller — with zero functional change.** Nobody was careless. The zip was built from `git ls-files` (or by zipping the repo), which sweeps in exactly the things that legitimately belong on your WIKI PAGE: heroes, screenshots, demo videos, architecture diagrams, long-form docs. **Three destinations, three payloads:** | destination | carries | never carries | |---|---|---| | **Release `.zip`** (streamed to every user's machine) | server code, handlers, add-in/plugin code, `bridge.json`, resources the runtime READS AT EXECUTION TIME | media of any kind, screenshots, demo videos, README/CHANGELOG, `.github/`, tests, dev docs, `node_modules` | | **pkg tarball** (extracted into every container's `$HOME`) | `SKILL.md` + your USER `skills/**`, `install.sh`/`uninstall.sh`, `package.json`, `page.json` | media, the release zip, `src/`, dev/publish skills, binaries | | **the PAGE** (`/files`, served to browsers) | hero, screenshots, demo videos, diagrams, long-form docs | binaries (see the release/pkg split) | Media on the page is served to a browser when someone looks at it. Media in an artifact is **pushed to every machine that installs you**, forever, on every update. That is the whole distinction. **How to not do this:** 1. **Build the zip from an explicit whitelist**, or from `git ls-files` **minus** media and repo cruft: ```bash git ls-files | grep -viE '\.(mp4|webm|png|jpg|jpeg|gif|svg|zip)$' \ | grep -viE '^(screenshots|docs|demo|\.github)/' \ | grep -viE '(CHANGELOG|PUBLISHING)\.md$' | zip -@ my-bridge-v1.2.3.zip ``` 2. **Know your number.** A bridge runtime zip is normally **well under 1 MB**. If yours is bigger, that is not automatically wrong (a bridge with real runtime assets can be), but it IS your cue to **list the contents and justify every entry** before uploading. 3. **Inspect before you publish, every time — this is the step that actually catches it:** ```bash unzip -l my-bridge-v1.2.3.zip | sort -k1 -n -r | head -20 # biggest files first tar tzf my-pkg.tgz # zero media, zero binaries ``` Sorting by size is the trick: the offender is always at the top, and a glance tells you whether you are shipping code or a video. 4. **Keep `files[]` an explicit text-only list** (every USER-skill path, no broad globs). A glob is how images get in. **A publish-time lint would catch this automatically** and has been asked for: a warning when a release asset or pkg tarball contains video/image files, with the size breakdown. That lives in the wiki CLI, not in your bridge, so until it ships **the inspect step above is the only thing standing between you and a 15 MB download on every user's machine.** **Reference:** the AD-core pkg itself follows this — 18 files, zero `.png`/`.mp4`/`.exe`, and its `docs/**` images were removed from `files[]` in 2026-07-06 for exactly this reason (4.56 MB of PNGs, including a 1.38 MB hero, were shipping inside every container install). --- ## Artifact 3 — DISCOVERABILITY: `discovery_triggers` so a plain request finds you The wiki has an **auto-discover** index, and it is the difference between a usable bridge and an **invisible** one. Declare `discovery_triggers` (the phrases a user actually says) on your page, and a plain request matches them via `adom-wiki discover find` / the in-app discovery an AI runs. ```bash adom-wiki discover triggers adom/adom-bridge--bridge --add "open my pcb" "export gerbers" # add triggers adom-wiki discover preview --json "open my pcb design" # what would surface + the SCORE + WHY adom-wiki discover find "screenshot my website" # the live find an AI runs ``` **How scoring actually works (measured 2026-06-30 — know this or you'll guess wrong):** - `score = 3×(distinct triggers matched) + 1×(tags) + 1×(brief/text)`. **Trigger matches dominate (3× each);** tags/title/brief barely move it. - **NO TRIGGERS = INVISIBLE.** A bridge with a perfect title ("Adom Bridge - Blender Bridge") + a matching tag scored **ZERO** for the literal query *"blender"* — it never appeared in `discover preview`. The scorer ignores title/tags when there are no triggers. **Every shipped bridge MUST carry `discovery_triggers` or it cannot be found by the discovery an AI uses.** (`discover search` full-texts the readme, but that is NOT the path discovery takes.) - **More good triggers = higher rank.** Each match is +3, so 10 user-task phrasings beat 2. The healthy bundled bridges carry **30-40** triggers; a struggling one had 14 — all dev jargon — and lost EVERY user query. **The cardinal rule: triggers are USER-TASK phrasings, NOT dev jargon.** A real user types *"open my pcb design"* / *"export gerber files"* / *"design a circuit board"* — NOT *"reverse bridge"* / *"kicad_bridge_call"* / *"fork the kicad bridge"*. A trigger list full of architecture terms scores 0 on every real query (kicad's actual failure: 7/7 user queries missed, and the **Fusion** bridge out-ranked KiCad on PCB queries because Fusion happened to carry a couple of fuzzy "pcb"/"export" triggers). Put **10+ everyday task phrasings first**; technical aliases (verb names) are a small minority at the end. **VET it — never ship triggers you didn't test:** 1. Write **5-7 queries a typical user would type** to get your tool (these double as your page `sample_prompts`). 2. `adom-wiki discover preview --json ""` → read `data.scoring[]` (array order = rank). **You must land in the top 3.** (Rate-limited: space calls ~2 s; expect a 429 after ~25.) 3. For every query where you're NOT top-3, **add that exact phrasing as a trigger** and re-test. If a sibling bridge out-ranks you on a shared word (Fusion vs KiCad on "pcb"), add MORE exact phrasings so your 3×-per-trigger total wins. **Claim YOUR niche — don't poach a sibling's territory.** Discovery routes by whose triggers match; if two bridges match a query the user lands on whichever has *more* triggers, NOT whichever is actually right. So your triggers must describe what YOU are genuinely best at — and you must LEAVE OUT cases a sibling owns. **Canonical example: logging into a site / filling a form on a signed-in page is the native-browser extension's job — it drives the user's REAL browser with their REAL logins — NOT puppeteer's.** Pup is a fresh Chrome-for-Testing profile with no saved logins; it's for *non-login* automation (scraping, screenshots, testing, public pages). So pup must NOT carry `log in` / `fill a form on a site I'm signed into` triggers, and native-browser MUST. When a task needs a capability you DON'T have, make your `discovery_pitch` *point at the bridge that does* — and tell the user to install it (e.g. "for logged-in form-filling, install the native-browser extension") — rather than claim it and do it badly. - **`discovery_pitch`** is the one-liner the snippet quotes back to the AI — auto-generated from `discovery_triggers` + `discovery_pitch`, **no separate upload step.** Make it an INSTRUCTION, not a tagline. - **Make your `brief` / `discovery_pitch` an instruction** — it's what the AI reads from the find result. Tell it the next moves: *"…check `adom-bridge-cli bridge_list` to confirm the bridge is installed; if it is, drive its `_*` verbs. If the container lacks the skill, `adom-wiki pkg install adom/adom-bridge--bridge` (or `adom-bridge-cli sync_skills`)."* ### The end-to-end flow your three artifacts enable User says *"show me my app in pup"* → the AI: 1. `adom-wiki discover find "show me my app in pup"` → your bridge surfaces (Artifact 3). 2. `adom-bridge-cli bridge_list` → is your bridge installed in AD? If not, `bridge_install {your manifestUrl}` (Artifact 1). 3. Is your skill pkg installed in THIS container (`~/.claude/skills/` or `~/.codex/skills/`)? If not, `adom-wiki pkg install adom/` / `sync_skills` (Artifact 2). 4. Drive your verbs — guided by the **rich hints you return** (the principle at the top). --- ## Prewarm — make the first call instant A cold first call that pays multi-minute setup (npm install, downloading a runtime, a heavy import) blows the caller's timeout. Pay that cost in the background BEFORE the user asks: - **Bundle deps in your SEED.** Pup ships a bundled `node_modules/` in its NSIS seed so a fresh PC can spawn with no `npm install`. When you re-seed from a Release zip, keep the bundled deps. - **Idempotent warm-up.** Make spawning + a no-op health/setup pass idempotent so a background prewarm is a no-op once warm. - **AD prefetches for you on first launch — standalone AND embedded (HD-bundled) — gated on availability.** (Pup's Node + Chrome-for-Testing prefetch runs once per install in both modes as of AD v1.9.45.) If your bridge needs a heavy runtime, expose a cheap idempotent "ensure ready" path AD/your seed can trigger, and surface a clean `errorCode` (e.g. `node_not_found`) when a prereq is missing so the AI can install it (`desktop_install_node`) instead of hanging. - **`browser_readiness`-style verb.** Offer a fast verb that reports `{ready:true|false, …}` so a caller (or a fresh-PC test) can confirm warmth without triggering work. --- ## Card hero + update cost — two gotchas that bite **Hero: ship a 1.6-aspect image, or AD crops the OG-card fallback.** AD's bridge card renders the hero in a banner that is `aspect-ratio: 1.6` with `object-fit: cover`. So: - Ship a **1.6-aspect** hero (≈**2000×1250**), full-bleed — like pup & kicad. It fills the banner cleanly. - If you ship **no** hero (`bridge.json` has no `hero` AND your wiki page has no `hero_path`), AD falls back to your page's **auto-generated OG card** (1200×630 = **1.90** aspect, the social-card size). `cover` scales that wider image to the banner's height and **clips the sides** — the left text panel gets cut off. (That cropped, off-center look is the tell of a hero-less bridge — it's not an AD bug.) - Fix: publish a real hero at 1.6 (the `adom-wiki` page hero, or a `hero` URL in `bridge.json`). Verify by opening your card in AD — the title/text must not be clipped. **Update cost: keep the Release zip source-only; re-seed the NSIS bundle in lockstep.** When a user clicks the card's "↑ v…" update badge, AD downloads your Release zip into the cache and (for a node bridge) provisions deps: - **The Release zip MUST be source-only — no `node_modules`.** AD provisions node deps at spawn: it **reuses the bundled seed's `node_modules` via `NODE_PATH`** when the cache version ≤ the seed version (instant), and runs a real **`npm install`** only when the wiki version is *newer* than the bundled seed. - So a wiki version much newer than your bundled seed forces a **cold `npm install`** on the next spawn — slow for a heavy tree. **When you publish a new Release, bump the bundled NSIS seed in lockstep** (same version) so most users get the instant NODE_PATH reuse, not a cold install. - AD (**v1.9.52+**) never blocks the UI on this: the update downloads straight to cache (no wasteful seed re-copy — the old code deep-copied pup's 73 MB / 4698-file seed and then discarded it, the "updating… forever" hang), the badge shows live progress (`downloading…` → done) with a 30s "installing…" fallback, and your bridge **keeps serving the old version** until the new one is ready. A lean zip + a lockstep seed is what keeps it *fast*. --- ## Cold-start tiers, host-app detection & the `bridge_readiness` probe (v1.9.47) A bridge has TWO kinds of dependency, and **AD treats them OPPOSITELY.** Get this right or a first-install probe (e.g. HD's "what tools do I have") triggers a slow install at the worst moment. **Tier 1 — your RUNTIME (Node, Python, your own browser download): AD prewarms + auto-installs it.** This is your plumbing. On first boot AD **provisions** Node/Python in the background — a **portable, no-UAC** copy under `~/.adom/adom-runtimes/` (or a system install if one's on PATH), **NOT winget/MSI** (see **Runtime contract** above) — and prewarms heavy assets you declare. You may also download your own runtime asset (pup downloads Chrome-for-Testing) — fine, it's yours. **But do it in the BACKGROUND: a `*_status` / `*_readiness` / ANY probe verb must NEVER block on a heavy download.** Spawn your server fast (it usually doesn't need the asset to *start*), kick the download off detached, and report `state:"warming"` until ready. A synchronous-download-on-first-verb is the exact footgun this release fixed (pup's 150 MB Chrome fetch used to block the probe). **Tier 2 — the HOST APP (KiCad, Fusion, Altium, …): AD DETECTS it by default and installs it ON REQUEST — never pre-emptively, and NEVER by telling the user to do it themselves.** Two rules that sound opposed but aren't: - **Don't install it unasked.** A multi-GB app nobody asked for is rude, so by default AD only DETECTS presence (a machine with KiCad belongs to a KiCad user; EDA users are mono-tool — a Fusion user isn't a KiCad user). AD won't prewarm/spawn your bridge while the app is absent — a resource decision, not a "go away." - **But the cardinal Adom rule overrides everything: the AI does EVERYTHING for the user — it must NEVER tell the user to do something the AI can do itself.** So your bridge MUST know how to install the host app (`desktop_install_kicad` / winget / your own install verb) and just DO it the instant the user wants it. **Your "not installed" hint must OFFER to install it** ("KiCad isn't installed — want me to install it for you?"), then do it on a yes — it must NEVER say *"download it from kicad.org."* Pointing the user at a manual download is the breach. **Bridge install LEVELS — how eagerly each bridge gets onto the machine. The AI ALWAYS does the install; the level only sets the TIMING/CONSENT:** | Level | Bridge(s) | Behavior | |---|---|---| | **0 · Built-in / MUST** | Hydrogen Desktop (`hd`) | The platform itself — the editor AD lives in. Always present; not "installed" by AD. | | **1 · Fundamental — pre-emptive** | Puppeteer (`pup`) | Browser automation is foundational to Adom. AD pre-installs its RUNTIME (Node + Chrome-for-Testing) ASAP on first boot, no asking. | | **2 · Recommended — proactive offer** | native-browser (the browser EXTENSION half) | The user's REAL logged-in browser (login/forms). Since v1.9.142 the DESKTOP BRIDGE half ships bundled in the AD installer (0.2 MB, zero deps, `persistent:true` — its extension-free verbs like `nbrowser_open_os_window`/`nbrowser_profiles`/`nbrowser_os_windows` work day one). What remains level-2 is the in-browser EXTENSION: AD/the bridge proactively SUGGESTS it and it installs on a yes (a browser-extension step the user confirms), unlocking full in-page drive. | | **3 · On-request host app** | KiCad, Fusion, Altium, … | Detect by default; NEVER pre-install (huge app, rude unasked). The moment the user wants it, the AI installs it AUTOMATICALLY (winget / `desktop_install_*`) — NEVER tells the user to do it manually. | | **4 · Explicit third-party** | any `bridge_install`'d bridge | The user opts in by installing it. | The through-line: **the AI never makes the user do something it can do itself.** The only knob is *when* — pre-emptive (pup), proactively-offered (native-browser), or on-request (host apps). **Declare both in `bridge.json`:** ```json "detect": { // Tier 2 — how AD finds your HOST APP (detection only) "hostApp": "KiCad", "appPathsExe": "kicad.exe", // optional: Windows App Paths registry lookup (most reliable) "paths": { // optional: candidate paths, %VAR% expanded, one * = a version dir "windows": ["%ProgramFiles%\\KiCad\\*\\bin\\kicad.exe"], "macos": ["/Applications/KiCad/KiCad.app"], "linux": ["/usr/bin/kicad"] } }, "prewarm": { "assets": ["chrome-for-testing"] } // Tier 1 — heavy runtime assets AD prewarms + reports ``` A bridge that brings its OWN runtime (pup ships its own browser) **omits `detect`** — it has no external host app. AD infers the runtime from `spawn.kind` (node→Node, python→Python). **The read-only probe: `bridge_readiness`.** AD aggregates all of this into ONE side-effect-free verb the setup AI calls — it **never spawns a bridge, never installs/downloads**. Per bridge: `{hostApp, hostAppInstalled, runtime, runtimeReady, assets, state}` where `state` ∈ **`ready`** (use it) | **`warming`** (runtime ok, a heavy asset still downloading in the background — re-poll, don't trigger it) | **`needs-runtime`** (node/python installing) | **`no-app`** (host app not installed → not relevant here). Plus a top-level `edaToolsInstalled` list — the one-line answer to "what EDA tools do I have." **Tell your users (in your skill): for a "what do I have / is it ready" question call `bridge_readiness`, NOT your `*_status` verb** — a `*_status` may spawn your bridge; readiness never does. Your two own cold-start verbs (above) still apply: `_readiness` (read-only `{ready, installing, installProgressPct, lastError}`) + `_prewarm` (`{wait}`-able). Those drive YOUR bridge specifically; `bridge_readiness` is the AD-level aggregate that detects + summarizes across all bridges without spawning any. --- ## The SKILL SET you should ship (not one SKILL.md — a small library) Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader **and a different home** — the USER skill goes in the pkg; the DEV and PUBLISH skills stay in your source repo: 1. **A PUBLISH skill — lives in your source REPO** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong. 2. **A DEV skill — lives in your source REPO** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill. 3. **USER skill(s) — shipped in your pkg** → the container: how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + user sub-skills.) **Only the USER skill(s) go in your pkg** (Artifact 2), each a real `skills//SKILL.md`. **The DEV + PUBLISH skills stay in your source repo** — a developer gets them by cloning to edit the bridge; they are NOT in the pkg's `files[]`, and you do NOT "scope" them into the pkg with `user-invocable:false` (that still ships them and bloats every container install). Open-vs-closed source doesn't change this — it only sets whether your repo's dev/publish files are publicly readable. **Start from the templates — don't write these from scratch.** Fill-in-the-blanks files for each of the three skill kinds, generalized from pup's battle-tested set. **Fetch them from THIS page** (they used to be cited as a path inside AD's own repo, which is private, so the pointer was unfollowable for exactly the cloud authors it addressed — fixed 2026-07-25): ```bash BASE=https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files curl -fsSL $BASE/bridge-dev-template.md -o dev-skills/-dev.md curl -fsSL $BASE/bridge-publish-template.md -o dev-skills/-publish.md curl -fsSL $BASE/bridge-user-skill-template.md -o skills//SKILL.md ``` - **`bridge-dev-template.md`** — architecture, the rich-hints rule, caller-provenance handling (logging the thread, arbitrating sessions, forwarding on your own AD callbacks). - **`bridge-publish-template.md`** — the whole release/pkg/discovery dance and every trap (the `.gitignore` set-aside, the lean-tarball rule, release-and-pkg-ship-together). - **`bridge-user-skill-template.md`** — the consumer skill, already encoding all eight conventions below plus the `--ai-thread` identity line. Copy the one you need, swap ``/`` for your names, delete what doesn't apply. **How your skills reach a container in the first place** (the runtime installs on the desktop, the skills install in the container, and the two travel by different routes): [`docs/bridge-skill-propagation.md`](https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files/docs/bridge-skill-propagation.md) on this page. --- ## USER-skill conventions — what every consumer skill must teach (from pup's shape) These eight patterns are what make a cloud AI actually succeed with your bridge on the first try. The user-skill template encodes them; bake them into whatever you ship: 1. **Open with a "FIRST-TIME / COLD-START — read before you panic" section.** A fresh PC may lack your runtime or owe a one-time download, and the AI's default failure mode is to declare defeat. Lead with a **response → meaning → what-you-do** table that frames `*_installing` / `not_ready` as EXPECTED, keyed off `errorCode` (not prose). 2. **Standardize two cold-start verbs: `_readiness` and `_prewarm`.** `readiness` → `{ready, installing, installProgressPct, lastError}`; `prewarm` kicks off setup without real work and supports `{"wait":true}` to block. Gives every bridge a uniform "poll until ready, then proceed" loop. (Complements the runtime-side Prewarm section above.) 3. **End the `description:` frontmatter with a `Trigger words:` line** mixing verb names AND plain-English phrases a user would actually type ("take a screenshot of", "log into"). This is what makes a user-invocable skill activate — and it feeds your `discovery_triggers` (Artifact 3). 4. **Include a short "Core verbs" table** (Command | Description | Key args) for the 80% path, and point at `_describe '{}'` for the full machine-readable catalog. The AI reads the table to act fast; `describe` is the completeness escape hatch — don't bloat the skill with every verb. 5. **"Background by default — don't disrupt the user."** Your bridge drives the AI's workspace, not the user's screen: lower/un-focus after automation, never force-foreground except to SHOW the user something, nudge via a taskbar flash (`*_alert_window`) instead of stealing focus. Standardize `*_lower_os_window` / `*_raise_os_window` / `*_alert_window`. 6. **Teach "`ok:true` is not enough" — verify what you did.** Verbs that return on operation *start* (not completion) need a cheap post-check (an eval/read verb, else a screenshot) before reporting success — 404s, login walls, and empty states land silently. 7. **Sessions: reuse-don't-reopen + stable identifiers.** Tell the AI to `*_status` before opening a new session (especially after compaction), reuse a match, and pick a stable `profile` so logins/state persist across runs. Prevents duplicate windows and the lost-login footgun. 8. **"Surface `_hint` verbatim."** Every verb returns an actionable `_hint` on not-ready/failure; instruct the AI to relay it to the user unchanged, and branch on the stable `errorCode` (not the prose). This closes the loop with THE ONE PRINCIPLE at the top — the hint IS your UI. --- ## Verb contract (quick reference) - **Naming:** every verb is `_` (`blender_render`, `blender_status`). AD routes any verb with your prefix to you. - **Request:** AD POSTs `{ "command":"", "args":{…} }` to your port. **Response:** JSON with at least `success` (bool); human/AI output in `output`, errors in `error` (+ an `errorCode` for machine-actionable failures). AD relays everything else verbatim — so ALWAYS add `_hint`/`_next`/`related`/`pitfalls`. - **Long-running verbs:** return promptly with a job id + set `statusVerb`; the caller polls instead of blocking. On a timeout AD auto-returns `{stillRunning:true, statusVerb, timeoutSeconds}`. If a verb genuinely blocks past 60s (a synchronous export/render), **also declare a `timeouts` block** (v1.9.79) so AD's HTTP budget matches — otherwise AD cuts the connection at 60s (third-party bridges were hard-capped there before v1.9.79). - **`describe`:** return your full verb catalog (`{verbs:[{name,summary,input,output,timeoutSeconds,statusVerb,longRunning,example,hint,related,pitfalls}]}`). AD caches it (`~/.adom/bridge-verbs/.json`) and shows it in the GUI Verbs tab — but remember, `describe` is read rarely; the per-call hints are what carry the AI. - **Keyboard input: route through AD's `desktop_press_key` — do NOT reimplement chords.** AD's key verb already does full modifier chords (`"shift+s"`, `"ctrl+shift+p"`, `"alt+f4"` — modifiers held via SendInput, key tapped, modifiers released in reverse), foregrounds the target window first (`{window|titleContains|hwnd}`) so CEF/Qt apps like Fusion receive it, and every bridge inherits it via the `/command` desktop passthrough (`{"command":"press_key", ...}` on the desktop namespace). A bridge-local `*_send_key` that parses only single keys (the Fusion bridge's `fusion_send_key` circa v1.6.x — `"shift+s"` → "Unknown key") duplicates AD's work and drifts; keep such a verb only for SendMessage-to-exact-hwnd cases AD's focus-first model can't cover, and say so in its `describe`. - **Host-app-optional verbs (v1.9.76):** declare `detect.hostAppOptionalVerbs` (bare names, e.g. `["readiness","describe"]`) in `bridge.json` so AD forwards those verbs to your running bridge even when your host app is absent — AD's built-in read-only set {readiness, describe, get_app_state, status} is always forwarded. And declare **`detect.installVerb`** (e.g. `"kicad_upgrade"`) so `bridge_readiness` recommends YOUR installer over the generic winget fallback. ## Health + status chip Your `/health` (200) makes the chip green. Optionally return `led` (`green`/`yellow`/`red`), `summary` (short label), `tooltip` (full hover). AD owns the **offline** (gray) state when your endpoint is unreachable — you can never assert offline. ## Lifecycle verbs (AD gives these to USERS — know them to guide users) `bridge_install {manifestUrl}` · `bridge_list` · `bridge_info`/`bridge_detail {name}` · `bridge_log_read {name, sinceOffset?}` · `bridge_kill {name}` · `bridge_pause {name}` · `refresh_bridges {name?}` · `bridge_check_updates`. A bridge installed via `bridge_install` auto-updates with no further opt-in; `updateManifestUrl` in `bridge.json` makes it durable across republish. **"My bridge keeps exiting and I can't see why" (read this).** Your own stdout log truncates on every respawn, so a crash-then-restart erases its own cause. `bridge_log_read` therefore also tails **AD's lifecycle audit log** for your bridge, a separate append-only file (`~/.adom/bridge-logs/.ad.log`) that survives respawns, shown under an `===== AD bridge lifecycle =====` header. It records every spawn, reap, duplicate-collapse, and `bridge_kill` with the reason, so you can tell "AD reaped it as a duplicate" or "the `bridge_kill` verb stopped it" or "it was reaped before a fresh spawn" apart from "it crashed on its own." If the audit log shows AD never stopped it, the exit is inside your process. ## Logging: AD owns the FILE, you own the VOLUME Every bridge writes to stdout, AD captures it, and nobody asks the volume question until someone's log is a firehose. The split: - **AD owns the FILE.** AD spawns you and captures stdout/stderr, so the file and its rotation are AD's. A bridge cannot rotate a file another process holds open, and bounded logs have to be a platform guarantee rather than per-author boilerplate. - **You own the VOLUME.** How much you emit is the half a tidy platform cannot fix for you. *(READING the log is the section immediately above: `bridge_log_read` plus AD's separate lifecycle audit. This section is about what you WRITE.)* **Do NOT write your own parallel log file.** Two log files means two sources of truth and double the disk for the same bytes. pup built one (a rotated `pup.log`) and deliberately reverted it. If you think you need your own log, what you probably want is for AD to scope `bridge_log_read` to your bridge: file that against `adom/adom-bridge` (see "Filing issues against AD" above) instead of forking the log. **The five patterns that keep a bridge out of firehose territory:** 1. **Never log per-item inside a loop over live state.** This is the single biggest source of volume. A drag-detection check logged one line PER TAB per check, all of them saying "(same)", so a 12-tab window emitted 12 useless lines every time the check fired. **Log the exception (the tab that moved), never the roll call.** 2. **Collapse consecutive identical lines.** Wrap `console.log` once, hold the last message, and emit `^ last line repeated Nx` when it changes. A retry loop then costs 2 lines instead of 200. Collapse only EXACT consecutive repeats, so no distinct event is lost. About 15 lines of code. 3. **Log static facts once per session, not per call.** "no favicon on this page" was emitted on every taskbar-badge update. It is a property of the page, not an event, and because the repeats were not consecutive the collapser could not catch them. Gate it behind a per-session flag. 4. **DO log every incoming verb, one compact line.** This is the one place to ADD volume. A log that records what the bridge DID (park, identity, overlay) but never WHAT WAS ASKED of it cannot answer "what foregrounded this window?" after the fact. Include only the args that change behavior, and skip your own log-read verb so reading the log does not pollute it. Put the caller thread on this line too (the shape is in "Caller provenance" above): ``` [verb] browser_open_window session=parkedge url=https://example.com owner=parktest ``` 5. **Never let logging throw.** Wrap the whole path in try/catch. A logging failure must not take the bridge down. --- ## Publish checklist (the whole modern flow) 1. **Page** — `adom-wiki page create adom/adom-bridge--bridge` with a hero + an **instructional `brief`** + **`discovery_triggers`**. 2. **Runtime** — `release create` + `release upload` the versioned `.zip`; POST the manifest to `/files`; set `updateManifestUrl` in BOTH the zip's `bridge.json` and the manifest. **Before uploading: `unzip -l | sort -k1 -n -r | head` — runtime only, no media.** *(→ Payload rules)* 3. **Skills pkg** — stage ROOT SKILL.md + `skills//SKILL.md` (core USER skill + sub-skills) + `discovery_triggers`; `pkg pack` (**`tar tzf` it — skills only, zero media/binaries**) → `pkg publish --org adom` (mind the `.gitignore` trap). Your `description` carries the one-sentence "this installs SKILLS, not the runtime" line. *(→ Artifact 2)* 4. **Discovery** — `discover triggers` to confirm; `discover preview ""` to confirm you surface. 5. **Re-seed AD's bundled copy** (AD-core thread, not you) — extract your Release zip over `plugins//` keeping bundled deps; ships in the next NSIS as the offline fallback. 6. **Verify** — `bridge_install {manifestUrl}` on a desktop → `bridge_list` shows your `version` + `skillPkg`; `bridge_check_updates` reaches your page; a container `sync_skills` pulls your USER skill; `discover find ""` surfaces you with an instructional brief. **Reference bridge = pup** (`adom/adom-desktop-puppeteer-bridge`): live `discovery_triggers`, a skills pkg with a core + sub-skills, a Release zip + manifest with `updateManifestUrl`, a bundled seed with prewarmed `node_modules`, and rich per-verb hints. Copy its shape. (`scripts/sample-bridges/hello-python` + `hello-rust` are the minimal skeletons.) KiCad, Fusion, Blender, Puppeteer, and the **native-browser** bridge (in the `adom-browser-extension` repo) are cloud-owned — don't edit them from the AD repo. When an AD release changes a bridge-facing contract **— or when THIS SDK doc itself changes —** AD posts a migration notice to **each** of their wiki discussions (`adom-bridge-{kicad,fusion,blender,puppeteer}-bridge` + `adom-browser-extension`). **Author-facing takeaway: watch your bridge's own wiki DISCUSSION/issues list — that's where an "SDK changed, please re-audit against the billboard" notice lands, and where you reply with your plan or blockers.** It's the only channel AD uses to reach you; AD never edits your repo.