DEPRECATED: Bridge SDK (moved into Adom Bridge)

← All Pull Requests

Porting a bridge to macOS — FINAL: adds the host-embedded runtime category + how the bug actually presents #28

Approved and ready to merge.

Diff

--- a//private/tmp/claude-501/-Users-kbergs-adom/cbec19bb-ee20-430e-bc27-fd36b366c57a/scratchpad/README.md+++ b//private/tmp/claude-501/-Users-kbergs-adom/cbec19bb-ee20-430e-bc27-fd36b366c57a/scratchpad/README.md@@ -0,0 +1,645 @@+---+name: adom-desktop-bridge-sdk+description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. 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-desktop}], 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 Desktop++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/<slug>` / `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/<name>/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-desktop":"^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-desktop":"^1.9.x"}`** — `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-desktop 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/<slug>/<ver>/<file>.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-<name>-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/<slug>/<ver>/<file>.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-desktop 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 `<prefix>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 <ADOM_DIRECT_API_URL>/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 <ADOM_DIRECT_API_URL>/commands` lists the full set so you can capability-probe (don't hardcode).++- **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"<verb>","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":"<clientName>"` (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:"<laptop clientName>"` 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":"…"}}'+```++---++## 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-desktop-window-identity` skill** (`https://wiki.adom.inc/api/v1/pages/adom-desktop/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.<sessionId>`) 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`.++---++---++## Porting a bridge to macOS (and staying cross-platform)++Adom Desktop runs on Windows AND macOS, and a well-built bridge should too. This section is the distilled, hard-won field guide from porting the Puppeteer (pup) bridge — Windows-authored — to full mac parity. Every item bit us; each is reusable for any bridge that drives windows, records, or talks back to AD.++**The golden rule: gate platform-specific code by `process.platform` (`'win32'` | `'darwin'`), never assume Windows.** A bridge that early-returns on non-win32 (the common Windows-first pattern) *runs* on mac but is silently headless — its window/recording/OS verbs no-op with `applied:false`. Audit every `if (process.platform !== 'win32') return` and add a `darwin` branch.++### 1. Window presentation is platform-specific — you cannot reuse the Win32 approach++Windows bridges background/hide/raise windows via Win32 z-order (`SetWindowPos`, `HWND_BOTTOM`, off-screen coordinates) or AD's `desktop_set_window_state`. **None of that works the same on mac:**++- **AppKit clamps windows onto a visible screen**, so the Windows "launch off-screen at −32000" background trick fails — the window snaps back on-screen.+- The mac primitive is the **app-level hide** (the Cmd+H state) via `osascript` → System Events: `tell application "System Events" to set visible of (first process whose unix id is <pid>) to false`. Windows created by an already-hidden app are **born hidden** — so on a detached launch, hide the process *before its first window exists* (e.g. launch with `--no-startup-window`, hide the pid, then create the window). Raise = `set visible … to true` + `set frontmost … to true`.+- **Consequence for design:** hide/raise is often **per-process** on mac, not per-window (one browser process = one hide target). If your bridge spawns one process per session that's fine; if it shares one process across sessions, document that hide/show is a group action.++### 2. Two TCC permission surfaces gate automation — and they key on the *responsible process identity*++macOS gates automation behind TCC (Transparency, Consent & Control). Two surfaces matter to bridges, and both are granted **per app identity**, not per user:++- **Screen Recording** (`kTCCServiceScreenCapture`) — gates `screencapture` AND a browser's `getDisplayMedia`. A bridge that records the whole desktop via a `getDisplayMedia` HUD **fails with "Could not start video source" if its recorder process lacks this grant.** Measured: real Google Chrome had the grant, Chrome-for-Testing did not, so a CfT-based desktop recorder can't capture.+- **Apple Events / Automation** (`kTCCServiceAppleEvents`) — gates `osascript` → System Events (i.e. every window hide/raise from §1). Granted to `inc.adom.desktop`, so a bridge's osascript calls made through AD's identity work; a bridge spawning its own osascript under a different identity may not.++**Two rules that fall out of this:**++- **Prefer CDP-internal capture — it is TCC-immune.** `Page.captureScreenshot` and `Page.startScreencast` render inside the browser process and need NO Screen Recording grant. Tab-scoped recording/screenshotting works on any mac with zero TCC setup; full-desktop `getDisplayMedia`/`screencapture` does not. Make the CDP path your default and treat desktop capture as the fallback that may need a grant.+- **Dev/unsigned builds are a SEPARATE TCC identity.** An ad-hoc-signed dev build of your host app (or AD, or HD) does **not** inherit the grants of the installed signed app — its screencapture/automation silently fails even though the signed app works. When a capture fails only in dev, suspect this before you suspect your code.++**Preflight the grant instead of failing mid-op.** Check `CGPreflightScreenCaptureAccess()` (Screen Recording) and `AXIsProcessTrusted()` (Accessibility/Automation) *before* attempting capture or input, and return `errorCode: "permission_required"` naming the exact pane when absent. **Which identity holds the grant?** For a bundle-less python/node bridge (no `.app` of its own), TCC attaches the grant to the **spawning app** — AD, or HD when HD spawns you — so your osascript/CGEvent calls inherit whatever that app was granted. This is why a bridge driven under the signed AD works while the same bridge under an unsigned dev build does not.++Degrade honestly: on a missing grant, return a clear `errorCode` + `_hint` naming the exact Settings pane (Screen Recording / Automation) — never throw, never hang.++### 3. The AD callback base is not always AD — verify before you trust `ADOM_DIRECT_API_URL`++Your outbound channel is AD's loopback direct-API, and the SDK tells you to resolve it from `ADOM_DIRECT_API_URL`. **But when your bridge is spawned by an embedding host (Hydrogen Desktop), that env var points at the HOST's control API, not AD's** — and the host may not serve the verb you need (`notify_user`, etc.). Resolve a **verified** base:++1. Probe each candidate's `GET /commands` for the verb you actually need, in trust order: `ADOM_DIRECT_API_URL` → `~/.adom/direct-api-port` (the host:port file AD itself writes) → the documented default.+2. Use the first base that serves your verb; fall back to the port file when the env base doesn't.++This is cross-platform hygiene but bites hardest under mac hosting where HD owns the relay seat. (Same failure mode exists on Windows under HD; mac just surfaced it.)++### 4. Wrapping a signed host binary requires re-signing (Chrome, and any signed app you relaunch)++If you relaunch a *signed* mac app under your own bundle (e.g. to rebrand its Dock icon, or to isolate a profile), you must re-sign or the OS kills it on launch ("quit unexpectedly"):++- **Clonefile the framework, do not symlink it.** `cp -c -R TheApp.app/Contents/Frameworks dest` (APFS copy-on-write: instant, near-zero real disk, a REAL directory). A **symlink** to the framework gets **sandbox-blocked** when the app's helper processes `dlopen` it by relative path.+- **Not under `/private/tmp`** — that path is sandbox-blocked for framework loads; use `~/Library/Caches/<yourns>/`.+- **`codesign --force --sign - <binary>` then `<app>` after assembling.** Relocating the signed main binary + editing `Info.plist` invalidates the app's seal; an ad-hoc re-sign restores launchability (Team stays absent; that's fine for a local wrapper).++### 5. THE PATH TRAP: `which` alone is never a sufficient resolver for ANY executable on macOS++**This is the single most-hit macOS porting bug in the Adom fleet — SIX instances across five components (node interpreters, python interpreters, and a CLI lookup).** If you read only one item in this section, read this one. It applies to *any* executable you resolve: an interpreter, a helper binary, a CLI, or a path you read from a state file.++**How you will actually meet it — this is the part to memorise.** The first instance was not found by an audit; it arrived as a **user report: "the bridge won't start, it says Node isn't installed" — on a Mac that plainly had Node installed.** The class does not announce itself as a PATH bug. It announces itself as *"the runtime/tool isn't there"* on a machine where it demonstrably is. If you ever hear that sentence about a GUI-launched app, suspect this before anything else. (Five more instances then fell out of one afternoon of deliberate auditing across the fleet — so once you find one, sweep for the rest.)++**The mechanism.** Anything launched by Finder, launchd, or `open` — which includes every GUI-launched host app, and therefore every bridge that host spawns — inherits a *minimal* PATH that does **not** include `/opt/homebrew/bin` (Apple-silicon Homebrew), `/usr/local/bin` (Intel Homebrew), or `/opt/local/bin` (MacPorts). So `which node` / `command -v python3.12` **reports "not found" on a machine where the interpreter is very much installed.** Your bridge then fails with "no runtime" on a perfectly-provisioned Mac.++**Why it survives testing:** in a terminal you have a login shell with the full PATH, so it works. Worse, `launchctl getenv PATH` may itself contain `/opt/homebrew/bin` on a developer box, masking the bug locally while it still fires for every stock user. **Do not trust `launchctl getenv PATH` as evidence you are safe.** Test against the real stock floor:++```sh+env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin sh -c 'command -v node'   # must still resolve via your fallthrough+```++**Rule 1 — always fall through to absolute dirs.** After PATH lookup misses, probe explicitly: `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/usr/bin`, `~/.local/bin`, your host's managed-runtime tree, and (node) the highest `~/.nvm/versions/node/*/bin/node`.++**Rule 2 — ORDER matters more than coverage; a wrong-but-executable hit is worse than a miss.** A probe list that reaches a *wrong* interpreter before the right one produces a **silent wrong pick**, not a clean failure — dramatically harder to diagnose. Real case: after the `which python3.1x` probes missed, the next branch was an EDA app's **bundled python 3.9**, which always exists on exactly the machines running that bridge. The bridge then failed with an opaque `TypeError: unsupported operand type(s) for |` (PEP-604 annotations under 3.9) instead of an honest "no modern python found". So: **version-check each candidate (`--version` >= your floor) and take the first that PASSES — never first-match**, and put bundled/vendored interpreters LAST. State the intended precedence in a comment so the next porter doesn't casually reorder it.++**Rule 3 — ONE resolver, every call site.** Two resolvers that disagree produce either a deadlock (one call site says ready, another says missing) or a silent wrong pick — both far harder to diagnose than "not found". When a codebase had a clean node resolver and a `which`-only python resolver, the *inconsistency* was the whole defect. Delegate every lookup to the rich one.++**Rule 4 — reject implausible values before trusting a cached path.** If you read an interpreter path from a state file, validate it: a value containing a backslash can never be executable on mac (real bug: a Windows-only writer left `\opt\homebrew\...\node` in a shared state file). A resolver with a proper fallthrough is *also* your resilience against a stale or corrupt cached path.++**Rule 5 — BEST: don't resolve a binary at all.** Prefer a **published-endpoint handshake** over locating an executable. A host that publishes a loopback port file (Adom Desktop writes `~/.adom/direct-api-port`) lets you POST to it instead of hunting a CLI: a port file can be stale — and you validate it on connect anyway — but it can *never* be "invisible because launchd gave you a short PATH", and it doesn't care where the `.app` bundle put things. Three bridges are structurally immune to this entire bug class for exactly this reason. When a bridge only needs to *call* the host, the endpoint is the more robust contract. (If you must find the host CLI on mac, note it lives *inside* the bundle — `/Applications/Adom Desktop.app/Contents/Resources/adom-desktop-cli` — and is never symlinked onto PATH; check `os.access(X_OK)` too, since a copied-not-installed bundle can lose the exec bit.)++**Rule 6 — bare names are acceptable ONLY for guaranteed `/usr/bin` + `/bin` system binaries.** `osascript`, `screencapture`, `sips`, `hdiutil`, `ditto`, `open`, `ps` all resolve under the stock floor. Anything Homebrew- or user-installed must be absolute-probed. A bridge whose mac layer uses only OS-guaranteed binaries plus in-process system APIs (ctypes/CoreGraphics) has no resolver surface at all — the most robust design of the three.++**Rule 7 — VERSION-GATE, don't enumerate: candidate lists have a shelf life.** A hardcoded list (`python3.13, 3.12, 3.11, 3.10`) is correct only until the next release ships. Real case: the reference Mac's *only* modern python was **3.14** — every list topping out at 3.13 scored zero hits and fell through to a stock 3.9. Discover candidates, then accept the first that `--version`-verifies at or above your floor; the explicit list becomes an optimization rather than a correctness dependency. **If you must choose between fixing the list and adding the gate, add the gate** — it is correct for every future release without edits.++**Rule 8 — collect ALL matches, then pick the best QUALIFYING one.** Taking the first hit per candidate is what turns a bare `python3` tail into a silent 3.9. Collecting every match across PATH *and* the absolute dirs, then version-gating each, is what makes the same tail resolve a Homebrew 3.14 instead. Same list, opposite outcome — the gate is the difference.++**Which strategy is right — and the FIRST question is not "what version?" but "do I even choose this runtime?"** Getting this wrong gives you a silent-old-interpreter, a brand-new-runtime break, or a bug no amount of resolver hardening can reach:++| Your situation | Correct strategy |+|---|---|+| Doesn't need to spawn a binary at all | **Rule 5** — published-endpoint handshake, resolve nothing. The whole class becomes structurally impossible. |+| Resolver-chosen; stdlib-only, version-insensitive | "Newest executable wins" is fine — *only while that stays true*. The day you add a native dep, add a floor/ceiling check. |+| Resolver-chosen; version-sensitive syntax and/or deps | Collect-all + `--version` gate, **no ceiling**; bundled/vendored interpreters last. |+| **HOST-EMBEDDED — you do NOT choose it** | You cannot resolve, gate, or provision your way out. **Target the host's floor and stay compatible.** |++**That fourth row is the one people miss, and a resolver-hardening sweep structurally cannot reach it.** If part of your bridge runs *inside* a host's own runtime — a plugin payload executing in an EDA app's embedded Python, or extension code running in the browser's JS engine — nothing you do at spawn time applies. Its floor is set by the vendor, not you. Severity depends entirely on one property:++- **Auto-updating host** (e.g. a browser): the floor rises on its own, users are dragged forward, risk decays. Declare the minimum you support and move on.+- **PINNED host** (e.g. an app's bundled interpreter): the floor is frozen at whatever the vendor shipped and can stay years old *regardless of what the machine has installed*. Here compatibility isn't defense-in-depth, it **is** the mechanism — write to the old floor and keep writing to it.++A single bridge can span rows: one real bridge has a resolver-chosen server (row 3) *and* a plugin payload inside the host's pinned 3.9 (row 4). Audit them separately — claiming the bridge is "audited" after covering only the half you choose is the easy mistake.++**Rule 9 — a wrong answer can poison more than the caller.** If your host derives "the system interpreter" from the same resolver, a bad 3.9 answer doesn't just pick the wrong interpreter — it can *suppress the host's own provisioning* of a good one ("system python already present"), so the managed runtime never downloads. Second-order effects like this are why the resolver must return **None** rather than something-wrong when nothing qualifies.++**Rule 10 — audit the FALLBACK CHAIN, not just each resolver.** Two independently fail-safe failures compose into a hard outage that neither exhibits alone. Real case: a bridge's direct-API discovery was Windows-only (silently dead on mac) *and* its CLI fallback couldn't resolve the bundled binary — each degraded quietly, but together the bridge had **no route to the host at all**, and nothing ever surfaced. Trace every fallback path end-to-end on the target platform. Three corollaries, each from a real bug:++- **A chain needs a live leg AND a re-discovery trigger.** A first leg that is a cached or frozen value (an env var, a memoised base URL) is correct right up until the thing it points at *moves* — and hosts move: they self-update and restart, rotating their port. Invalidate and re-resolve on connection failure, bounded to one retry. Two bridges shipped this bug; in one, a stale port was hammered for hours with nothing surfacing.+- **"Returns Ok" is not "succeeded"** when the Ok carries a nothing-happened message. A both-legs-empty path that returns success-with-a-string logs as INFO and is indistinguishable from working. **Put the honest signal in the TYPE, not the string.** Best-effort helpers that return null on failure have the same defect: "it failed" and "there was nothing to do" become the same value.+- **Whoever holds a compatibility FLOOR should record its reasoning at the code site.** A floor enforced in one component and a compatibility fix made in another can silently cancel out. Document *why* the floor exists where the check lives — otherwise a future engineer re-derives a plausible-but-wrong reason to lower it. (Watching this happen in review, and getting talked out of it, is what produced this line.)++**The tooling half of the same trap:** the identical PATH problem hits external tools — probe `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin` explicitly when locating things like `ffmpeg`, and make your "not found" hint say `brew install <x>` on mac (not the Windows `winget`/`choco` line).++### 6. The MIRROR-IMAGE audit: Windows calls left ungated on the mac path++Porting sweeps naturally hunt "the mac path can't find its tool". The same files accumulate the opposite defect — a **Windows-only call left ungated on the mac path** — and it hides *better*, precisely because it **fails safe**: `powershell.exe`/`taskkill` returns ENOENT, control lands in the error branch, and that branch produces the same answer the mac path wanted anyway. No error ever surfaces; you just pay for a doomed process spawn on every call, forever. Grep every `spawn`/`execFile`/`Command::new` for a platform guard — it takes minutes and every bridge that ran it found something.++- **Check the CALLERS, not just the call sites.** A grep shows scary hits; what matters is whether each is reachable on darwin. Guards frequently live one or two frames up (an early-return in the enclosing handler, or a mac branch that dispatches away before the Windows path). Conversely a *gated* call site can sit behind an *ungated* helper — so also ask which primitive actually spawns.+- **Guard the PRIMITIVE, not just today's callers.** If one function is your only `powershell.exe` spawn point, give *it* the platform check returning the shape callers expect. Every caller being gated today is a property you can't maintain; you don't own who calls you next. (Same defense-in-depth as making a module import-safe under the wrong interpreter.)+- **Compiled hosts get this for free; script bridges don't.** Rust `#[cfg(windows)]` makes the whole class compile-time-impossible — the code isn't in the mac binary. A JS/Python bridge can only fail at *runtime*, so the audit is genuinely necessary there and cheap for compiled hosts.+- **Beware false-green verification.** Proving a module is safe under an old interpreter requires actually **importing** it, not compiling it: PEP-604 annotations (`int | None`) *compile* fine on Python 3.9 and raise `TypeError` at def-execution time, so `compile()`/`py_compile` reports success on a file that will die on first import. The general rule: verify at the stage where the failure actually occurs.+- **Watch for a Windows marker used as a source of truth.** The nastiest variant isn't a spawn at all: a completeness/detection check keyed on `Something.exe` returns `false` on *every* Mac — including a perfectly installed one — and anything short-circuiting on it (readiness, install-progress, "is it installed") is then permanently wrong. Real case: a bridge reported its app *permanently installing* on every Mac. **Fix the completeness/root marker BEFORE the streaming/progress marker** — a partial fix here is worse than the bug.++### 7. Native-app bridges (not just browsers): background launch, input, and AX++Browser bridges get input/capture "for free" via CDP. A bridge driving a **native mac app** (KiCad, Fusion, Blender, any Cocoa/Qt/wx app) needs the OS primitives — and they differ from Windows:++- **Launch without stealing focus** with `open -g -a <App> <args>` (the `-g` = "background"; the app opens but does not come to the foreground) — the mac analog of a background/minimized Windows launch.+- **Deliver input focus-free** with `CGEventPostToPid(pid, event)` (Quartz, reachable from stdlib `ctypes` in Python — no extra deps). Unlike `CGEventPost` to the global tap, posting to a specific pid drives a background app **without raising it**, and full modifier chords (`cmd+shift+s`, etc.) are reliable. Foreground-first fallback only when the target genuinely requires it.+- **Click by AX attribute, never by name.** System Events resolves a process by BOTH its executable name and its display name (either may be what the app registers). And many toolkits — **wx especially** — expose **nameless** buttons to the Accessibility tree, so name-based clicks silently miss. Target the semantic attributes instead: `AXCloseButton`, `AXDefaultButton`, `AXCancelButton`. Modal dialogs may also be **sheets** attached to a parent window, not top-level windows — walk the AX tree accordingly.++### 8. Process enumeration must be case-insensitive++Windows process names are lowercase (`chrome.exe`); mac executables are not (`.../MacOS/Google Chrome`). A `line.includes('chrome')` scan silently misses every mac process. Match case-insensitively (`/chrome|msedge|Microsoft Edge/i`) so your recovery/rescan/kill paths find their targets on mac.++### 9. Self-audit additions for cross-platform bridges++- [ ] Every `process.platform !== 'win32'` guard has a `darwin` branch OR a documented, honest no-op (never a silent dead verb).+- [ ] Capture defaults to CDP-internal (TCC-immune); any `getDisplayMedia`/`screencapture` path returns a grant-naming `errorCode` on failure.+- [ ] The AD callback base is verified via `GET /commands` before use; falls back to `~/.adom/direct-api-port`.+- [ ] Could you use a published endpoint instead of resolving a binary at all? (Rule 5 — the most robust option.)+- [ ] Does ANY part of your bridge run inside a runtime you don't choose (host-embedded plugin payload, extension code)? If so it is audited SEPARATELY: target the host's floor, and verify by real import — resolver hardening cannot reach it.+- [ ] Executable resolution NEVER relies on `which`/PATH alone: absolute-dir fallthrough, version-checked (not first-match) selection with bundled interpreters LAST, ONE resolver shared by every call site, cached paths validated — verified under `env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin`. Process scans are case-insensitive; "install X" hints are platform-correct.+- [ ] Mirror-image audit done: every `spawn`/`execFile`/`Command::new` of a Windows binary is guarded (check CALLERS and the spawning PRIMITIVE), and no Windows-only marker is used as a cross-platform source of truth.+- [ ] Native-app bridges preflight `CGPreflightScreenCaptureAccess`/`AXIsProcessTrusted`, launch with `open -g`, drive input via `CGEventPostToPid`, and click by AX attribute (`AXCloseButton`/`AXDefaultButton`) — never by button name.+- [ ] You tested EVERY verb on a real mac — window/record/OS verbs especially — with semantic assertions (e.g. read the OS hide state back via System Events), not just `success:true`.++## 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 <your-slug>` (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-desktop-bridges` (or `curl -s https://wiki.adom.inc/api/v1/pages/adom-desktop-bridges/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.++---++## 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-desktop":"^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-<name>-manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob.+- [ ] **PAYLOAD:** `unzip -l <your zip> | 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 <your tgz>` 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 `<prefix>_describe` verb lists your whole catalog. *(→ Verb contract)*+- [ ] No verb blocks on a heavy install/download — background it, report `installing`/`warming`; `<prefix>_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/<name>/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-desktop":"^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-desktop-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 <port>` to argv+    "port": 0,                              // 0 = AD picks a STABLE port (recommended). Bind 127.0.0.1:<that port>.+    "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-desktop-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 <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:<port>`. 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/<slug>`) 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-desktop` for the platform). **NEVER `github.com/...`** — GitHub is source-backup only; the wiki is the canonical home. (A `homepage: github.com/adom-inc/adom-desktop` 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-desktop-<bridge>-bridge <version> --title "..." --changelog "..."+   adom-wiki release upload adom/adom-desktop-<bridge>-bridge <version> your-bridge-v<version>.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-desktop-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-desktop-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 Desktop\bridges-cache\<name>\`, 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/<name>/` 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 <owner/slug> <ver> "<old-filename>"` 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/<name>/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-desktop":"^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-desktop-<bridge>-bridge**`.+- **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` 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/<name>/SKILL.md per USER skill (dev/publish stay in the repo),+# package.json {name:"adom-desktop-<bridge>-bridge", version, discovery_triggers,+#               dependencies:{"adom/adom-desktop":"^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 <tgz> → every skills/<name>/SKILL.md+                                         #   listed in files[] present, ZERO binaries+adom-wiki pkg publish --org adom         # publishes adom/adom-desktop-<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/<slug>` from your `docs`) and the `_hint` tells the AI to run it.+- **`adom-desktop 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/<your-bridge>` 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 Desktop 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/adom-desktop-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-desktop-<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 Desktop - 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 "<each query>"` → 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-desktop bridge_list` to confirm the bridge is installed; if it is, drive its `<prefix>_*` verbs. If the container lacks the skill, `adom-wiki pkg install adom/adom-desktop-<bridge>-bridge` (or `adom-desktop 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-desktop 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/<slug>` / `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: `<prefix>_readiness` (read-only `{ready, installing, installProgressPct, lastError}`) + `<prefix>_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/<name>/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.** `skills/bridge-templates/` in the AD repo has a fill-in-the-blanks file for each of the three skill kinds, generalized from pup's battle-tested set: **`bridge-dev-template.md`** (architecture + the rich-hints rule), **`bridge-publish-template.md`** (the whole release/pkg/discovery dance + every trap), **`bridge-user-skill-template.md`** (the consumer skill, already encoding all eight conventions below). Copy the one you need, swap `<bridge>`/`<prefix>` for your names, delete what doesn't apply.++---++## 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: `<prefix>_readiness` and `<prefix>_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 `<prefix>_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 `<name>_<verb>` (`blender_render`, `blender_status`). AD routes any verb with your prefix to you.+- **Request:** AD POSTs `{ "command":"<verb>", "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).+- **`<prefix>describe`:** return your full verb catalog (`{verbs:[{name,summary,input,output,timeoutSeconds,statusVerb,longRunning,example,hint,related,pitfalls}]}`). AD caches it (`~/.adom/bridge-verbs/<name>.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/<name>.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.++---++## Publish checklist (the whole modern flow)++1. **Page** — `adom-wiki page create adom/adom-desktop-<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 <zip> | sort -k1 -n -r | head` — runtime only, no media.** *(→ Payload rules)*+3. **Skills pkg** — stage ROOT SKILL.md + `skills/<slug>/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 "<a real user phrase>"` to confirm you surface.+5. **Re-seed AD's bundled copy** (AD-core thread, not you) — extract your Release zip over `plugins/<name>/` 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 "<phrase>"` 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-desktop-{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.+

Reviews

Comments

Log in to comment.