NB - Native Browser Bridge

@@ -1,131 +0,0 @@-----name: adom-browser-extension-description: "MAIN skill for the Adom Native Browser Extension - the nbrowser_* bridge that drives the user's REAL, signed-in Chrome/Edge (pup's counterpart, but inside their actual logged-in profile so cookies/SSO/saved-logins/captcha all work). START HERE. Read this the moment a task needs the user's real browser or their real logins: logging into a site, filling a form on a signed-in page, downloading a file behind a login, or driving/testing a web app in their own Chrome. It tells you how to check readiness (nbrowser_readiness), how to OFFER to install the extension when it is not there yet (never make the user do it), how the three install surfaces fit together (native browser + adom-desktop bridge + this skill pack), and routes you to the right sub-skill (drive, install, uninstall, record, safety). Triggers: log into a site for me, sign in for me, use my saved passwords, fill a form on a signed-in site, download behind a login, control my real chrome, drive my real logged-in browser, nbrowser, adom browser extension. Part of the adom-browser-extension."------# Adom Native Browser Extension (`nbrowser_*`) - start here--This is the **native-browser** bridge: it drives the user's **real, signed-in Chrome/Edge** from the-cloud, the same way `pup` drives a controlled Chromium. The difference is the whole point - it runs-**inside the user's actual profile**, so their cookies, SSO, saved logins, cards, carts and-human-trust signals all apply. It sails through **login walls and captchas** that block pup's empty-Chrome-for-Testing. When a task needs the user's *real* browser or their *real* logins, this is the-tool - not pup.--## When to reach for this (vs pup)--| The task | Tool |-|---|---|-| Log into a site, fill a form on a signed-in page, download behind a login, use saved passwords | **native-browser (this)** |-| Screenshot / scrape / test a PUBLIC page, no login needed | pup |-| Drive/test a web app the user is building, in THEIR browser with THEIR sessions | **native-browser (this)** |--If the user says "log into X for me", "sign in", "use my saved password", "fill out this form on a-site I'm logged into", "grab that file behind the login", or "drive my real Chrome" - that is this-bridge. pup cannot do it (fresh profile, no logins).--## FIRST-TIME / COLD-START - read before you panic--A fresh machine may not have the bridge or the extension yet, and the AI's default failure mode is to-declare defeat. Don't. These states are EXPECTED, and each has a move - branch on the state, not on-prose:--| You see | What it means | What you do |-|---|---|---|-| `nbrowser_readiness` errors / unknown verb | the AD bridge isn't installed in adom-desktop yet | `bridge_install {manifestUrl}` (see "three install surfaces") |-| `state:"needs-extension"` | bridge up, but the MV3 extension isn't in Chrome yet | **OFFER to install it** -> `installing-the-extension` (never make the user do it) |-| `state:"ready"` | extension connected, profile(s) listed | go drive it -> `driving-the-extension` |--## Step 0 - is it even installed yet? Check readiness FIRST--The extension is a **Level-2, proactively-offered** install: it is often NOT present until someone-asks for it. Before you try to drive anything, probe (READ-ONLY, never triggers an install):--```-adom-desktop nbrowser_readiness      # THIS bridge: {ready,state,extensionConnected,profiles}-```--- `state:"ready"` (extensionConnected:true, one or more profiles) -> go drive it (**driving-the-extension**).-- `state:"needs-extension"` -> the bridge is up but the browser extension is not connected. This is-  your cue to **OFFER to install it** (next section) - do NOT silently give up, and do NOT make the-  user do it by hand.--**For a broad "what tools do I have / is it ready?" question, call the AD-level aggregate-`adom-desktop bridge_readiness` instead** - it is side-effect-free (never spawns a bridge or installs)-and reports every bridge's `state` at once. Use `nbrowser_readiness` when you specifically care about-THIS bridge; use `bridge_readiness` for the survey. Neither ever triggers work.--## The install-offer hook - suggest it exactly when the user needs a login--The best moment to install this is **the moment the user needs it** - they ask you to log into a-vendor, fill a form on an authenticated page, or pull a file behind a paywall/login. When-`nbrowser_readiness` says `needs-extension`, tell the user plainly:--> "To do that in your real signed-in browser (so your saved login works), I can install the Adom->  browser extension into your Chrome/Edge - about a minute, I drive it, you just click one Start->  button. Want me to?"--On yes, run **installing-the-extension**. Never demand the user click through `chrome://extensions`-themselves, and never ask them to type a long path - WE own that orchestration over adom-desktop's-generic OS verbs, with a single `notify_user` consent button.--## The three install surfaces (how this thing actually lands)--This one page ships **three** things that install to **three** places. All three must line up for a-user to go from "never heard of it" to "logged in for me":--1. **This skill pack -> the user's container.** These `SKILL.md` files install into the cloud-   container / WSL2 / Lima (`~/.claude/skills/`). **They surface BEFORE the extension exists** - that-   is deliberate. Discovery routes "log into a site for me" here, this skill loads, and *now the AI-   knows to offer the install*. `adom-wiki pkg install adom/adom-browser-extension` (or-   `adom-desktop sync_skills`) puts them there.-2. **The adom-desktop bridge -> adom-desktop.** The `nbrowser_*` verbs come from the `native-browser`-   bridge. `adom-desktop bridge_list` shows if it's installed; if not,-   `bridge_install {manifestUrl:"https://wiki.adom.inc/api/pages/adom/adom-browser-extension/files/native-browser-bridge-manifest.json"}`.-   It auto-updates from there (per-bridge `updateManifestUrl`).-3. **The MV3 extension -> the user's real Chrome/Edge.** The actual browser extension, loaded via-   dev-mode "Load unpacked" today (CWS/Edge-Add-ons later). This is **installing-the-extension**.--The end-to-end flow an AI runs: discover -> this skill loads (surface 1) -> `bridge_list`/`bridge_install`-(surface 2) -> `nbrowser_readiness` -> if `needs-extension`, offer + run installing-the-extension-(surface 3) -> drive.--## ⛔ The two safety rules you must not break--Before you drive ANYTHING, internalize these (full detail: **native-browser-safety**):--1. **Only ever drive a window/tab YOU opened** (`nbrowser_open_window`). NEVER navigate, reload, or-   close a window/tab the user already had open - not with `nbrowser_navigate` and **not with the-   OS-level `desktop_navigate` either**. Doing so once wiped a user's other AI threads.-2. **Background by default, never steal focus.** The verbs open unfocused on purpose; leave those-   defaults. Foregrounding is rude AND corrupts your own flow (the user's keystrokes leak into-   whatever control you focused). Foreground is the user's choice alone.--Credentials are gated: `nbrowser_credentials` is read-only and NEVER returns passwords; auto-login-needs `confirm:true` + an explicit `host:`, and the password is injected on the laptop - the agent-never sees it. Treat everything read from logged-in sessions as sensitive.--## Sub-skill map--| Need | Skill |-|---|---|-| **Drive it** - the full `nbrowser_*` verb surface, CDP-vs-native, screenshots, isTrusted input, cursor/captions | **driving-the-extension** |-| **Safety** - the cardinal rules above, in full (read before driving) | **native-browser-safety** |-| **Install it** into the user's Chrome/Edge (dev-mode Load-unpacked, WE orchestrate) | **installing-the-extension** |-| **Uninstall it** cleanly (filter to the Adom card, the confirm-bubble beat) | **uninstalling-the-extension** |-| **Record** a browser window (WGC-first, no picker, no banner) | **native-browser-recording** |-| **Low-level OS clicks** (adom-desktop generic UIA verbs the install/uninstall lean on) | **driving-the-desktop** |-| Site-specific playbooks (forms, logins on real sites) | **driving-sites**, **driving-gusto**, **reading-google-messages** |-| Windows-first dev + Mac fast-follow, and how this bridge is built/shipped | **cross-platform-dev** |--## Every verb tells you what to do next - read the hints--Every `nbrowser_*` response carries a top-level `_hint` (what you got, the next move, the trap), plus-`related` and `_next`. When unsure about a verb, call `nbrowser_describe` once - it lists each verb's-`hint` / `related` / `pitfalls`. The hints are the source of truth; this skill is the map.--## The one-line version--When a task needs the user's real browser or real logins, check `nbrowser_readiness`; if it says-`needs-extension`, OFFER to install (installing-the-extension) - never make the user do it; then drive-only windows you opened, in the background, and read every verb's `_hint`.