Adom Bridge

@@ -127,6 +127,40 @@ adom-wiki pkg install adom/adom-bridge  Then ask your AI to build the bridge. That is the intended workflow: you describe the app you want reachable, and the AI does the rest against these skills. +## The one line you must not cross++Adom Bridge is closer to an operating system than an app. It provides generic, app-agnostic primitives (windows, screenshots, input, files, shell, taskbar and window identity, jump lists, notifications) and it loads, unloads, reloads and updates bridges on the fly. Your bridge is an app running on that OS: its own process, its own skills, its own page, its own release cadence.++So the rule is simple, and it is the most important one here: **a bridge never modifies Adom Bridge itself. The correct amount of ab-core change for a bridge feature is zero.** When your bridge needs the desktop to do something, it calls one of ab's existing generic verbs. It does not extend the host to do it.++Three ways people cross that line without noticing:++1. **Rebuilding something ab already has.** Window identity, taskbar icon and overlay, jump lists, screenshots, input, files and notifications are already generic verbs. Search the verb surface before writing any desktop capability. Most "I need a new verb" turns out to be "there is already a generic one".+2. **Putting your app's name into ab.** If ab ends up carrying your app's name, a forced identity namespace, or your labels, the logic is in the wrong place. Every app-specific value is an argument your bridge passes into a generic verb.+3. **Moving app-aware logic up into the host.** This is the subtle one. Strict window binding, meaning "act only on the exact window I launched, verified by handle and owning process", feels like host work because it is about windows. It is not: doing it well requires knowing how your app creates its windows, which is precisely the knowledge ab must not carry. Resolve and verify inside your bridge, then hand ab a resolved handle for its generic paint verbs.++If you genuinely need a new generic primitive that does not exist, that is welcome. What is gated is the content, not the channel: it has to pass two tests first, namely could a completely unrelated app use this verb unchanged, and can ab implement it knowing nothing app-specific. If either answer is no, it belongs in your bridge. Once it passes, the Adom team can simply send a PR; third-party authors open a discussion on the `adom-bridge` page.++When you do send a PR, keep it on a branch and leave it there for review. Do not merge your own change into `main`. Adom Bridge ships to a whole fleet from `main`, and the thread that owns ab builds, signs and publishes releases from it, so an unreviewed merge quietly becomes everyone's next auto-update. It also collides with whatever release is in flight: two branches that both bump the version produce two different builds carrying the same version number, which the updater can never heal. A branch costs nothing and keeps both problems impossible.++The payoff for staying on your side of the line is not abstract. A pure bridge is installed with one command and tried in a minute, and it ships and updates from your own page with no ab release involved. A feature that lives in ab-core can only be evaluated by building and running a modified core, which almost nobody will do just to try something out.++## Make it runnable, and make it visible++Two failure modes sink otherwise good bridges, and both are about other people rather than code.++**Runnable.** Ship at least one qualified, updater-eligible release with its runtime zip, so `bridge_install` resolves and anyone can install it. A page whose every release is a development candidate cannot be installed by a normal user.++**Visible.** Put screenshots in your README. This is the highest-leverage thing on your page, and the easiest to skip because you can already see your bridge working on your own machine. A reviewer or a user will not build and run your bridge to find out what it does. The page is the only window into your work. Capture the real outcome your verbs produce, and for anything visual, taskbar tiles, jump lists, overlays, rendered output, show it before and after, because prose cannot convey it and nobody can verify it otherwise. For reference, pup's README carries 13 images and kicad's 8, plus demo videos. `desktop_screenshot_window` returns a window plus its owned popups, so capturing these states is scriptable.++## Your keyword++Pick one short, speakable word that a user says to reach your bridge, the way people say "pup" or "kicad". It is not your product name; it is what someone types in chat.++Declare it in all four places or it does not exist: your `bridge.json` name, your verb prefix (`<keyword>_...`), your discovery triggers, and the first section of your README ("Say `pw` to the AI to reach this bridge"). A keyword agreed in conversation but written nowhere cannot be resolved by an AI, and that is the only thing that matters.++The `adom-bridge-sdk` skill carries the full version of all of this, including a pitfalls section of real failures written as symptom, cause and fix. The `adom-bridge-sdk-audit` skill is a checklist you can run against your own bridge before publishing, including a boundary lint that catches every problem described above.+ ## Naming and where your page lives  Bridge pages follow one convention: `<name>-bridge`, with no prefix. So `kicad-bridge`, `fusion-bridge`, `pup-bridge`, `rustdesk-bridge`. Your bridge gets its own wiki page, which is where your release zip, your manifest, your hero art and your discovery triggers live.