adom-desktop nbrowser_readiness      # THIS bridge: {ready,state,extensionConnected,profiles}

---
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`.