NB - Native Browser Bridge

@@ -0,0 +1,53 @@+# DEV skill (source-only, dev-skills/) — architecture + the rich-hints rule++> Reader: **whoever edits this bridge.** NOT shipped to containers. Bridge SDK:+> https://wiki.adom.inc/adom/adom-desktop-bridges++## ⭐ THE loudest rule: the AI reads your verb OUTPUT, not this file+AD relays every field of a verb response verbatim to the calling AI. A verb that returns+`{success:true}` and nothing else makes the AI guess and retry-loop. EVERY `nbrowser_*` response MUST+carry a rich **`_hint`** (what just happened + the obvious next verb + the trap) plus `_next` /+`related` / `pitfalls`. This is the single highest-leverage thing in the whole bridge.++Mechanism in `server.js`: a single **`VERB_META`** table is the source of truth. It feeds BOTH+`nbrowser_describe` (per-verb hint/related/pitfalls) AND a `decorateHint(verb, r)` wrapper that stamps+top-level `_hint`/`related`/`_next` onto EVERY dispatch response. Add a verb → add its VERB_META entry+in the same commit, or it ships hint-less.++## The 3 components (know which one you're touching)+1. **The bridge** (`bridge/server.js`) — AD spawns it (`spawn.kind:"node"`), so **AD provisions Node**+   (v1.9.63 runtime contract; you never install Node for it). Binds `127.0.0.1:0` on+   `process.env.ADOM_BIND_HOST || '127.0.0.1'` (never `0.0.0.0` → no firewall prompt). Writes a+   discovery file `~/.adom/bridges/native-browser/host.json` + `node-path.txt`. Serves `/status`+   (health chip: led/summary/tooltip) + `/command` for AD, plus a loopback TCP listener the host dials.+2. **The native-messaging host** (`host/native-host.js` via `native-host.bat`) — **Chrome launches it**,+   NOT AD, so it does NOT inherit AD's managed-runtime PATH. It reuses AD's Node via+   `node-path.txt` (published by the bridge = `process.execPath`, backslash-normalized) and falls back+   to PATH `node`. This is the ONLY place system-Node dependence could bite a fresh machine — keep the+   `.bat`'s two-branch resolution intact.+3. **The MV3 extension** (`extension/`) — runs inside Chrome/Edge, no runtime. SW `connectNative` →+   host → bridge loopback. Deterministic ID (`manifest.json` pins `key`) so the host manifest's+   `allowed_origins` is known ahead of time.++Data path: container → relay → AD → bridge `/command` → loopback → host stdio → extension SW → CDP/native.++## Verb contract+Request `{command, args}`; response `{success, output(JSON string), error?, errorCode?}` + the hints.+`nbrowser_readiness` is READ-ONLY (never spawns/installs) — mirror `bridge_readiness`. Long ops: return+a job id + `statusVerb`, don't block. `nbrowser_describe` returns the full catalog.++## Test locally+`node -c bridge/server.js` (syntax). Run `server.js` standalone → it binds ephemeral + writes the+discovery file; `GET 127.0.0.1:<port>/status` → led/summary/tooltip. End-to-end: `nbrowser_readiness`+through AD (`--target <laptop>`), then open bg window → screenshot → close.++## The boundary with AD (don't file bridge bugs as AD bugs)+AD owns: spawn/reap, stable port, supervisor, cache install + auto-update, status classification, the+GUI card. YOU own: verbs + hints, `/status`, `nbrowser_describe`, the wiki page + triggers, the+manifest + zip, the skills pkg. A generic missing capability (new lifecycle verb, relay field) → file+against AD; a misbehaving `nbrowser_*` verb → fix here.++## Safety invariants (never regress — one wiped a user's other AI threads)+Only ever drive a window YOU opened; NEVER navigate/reload/close the user's existing window/tab (incl.+OS `desktop_navigate`). Background by default; foreground is the user's choice. `nbrowser_credentials`+read-only, never returns passwords; auto-login gated on `confirm:true`+`host:`. Honor the blocklist.

@@ -0,0 +1,58 @@+# PUBLISH skill (source-only, dev-skills/) — how to cut a native-browser bridge release++> Reader: **this bridge's own cloud/dev thread.** NOT shipped to user containers (it is not a+> `SKILL.md`, and it is not in `package.json` `files[]`). Keeps future-me from getting the publish+> dance wrong. Bridge SDK: https://wiki.adom.inc/adom/adom-desktop-bridges++## What "the bridge" actually is (3 artifacts, 3 places)+1. **Runtime** — `bridge/` (server.js + bridge.json) shipped as a `.bin` payload + a manifest on the+   wiki page. AD streams it to `bridges-cache/native-browser/` and spawns it.+2. **Skills pkg** — the `SKILL.md`s, published via `adom-wiki pkg publish --org adom`, installed into+   the container's `~/.claude/skills` + `~/.codex/skills`.+3. **Discovery** — `discovery_triggers` + `discovery_pitch` on `page.json`.++## Release the RUNTIME — the exact, proven sequence+Deps: none (core `http`/`net`), so the payload is source-only (no `node_modules`).++1. **Bump the version in THREE places, together** (they drift if you don't):+   - `bridge/bridge.json` `version` (what AD reads + reports),+   - `bridge/package.json` `version`,+   - `bridge/BRIDGE_VERSION`.+   `server.js` reads `VERSION` from `bridge.json` (authoritative) so it can't drift — keep it that way.+2. **Build the zip with files at the ROOT** (there is no `zip` binary — use Python `zipfile`):+   members = `bridge.json`, `package.json`, `server.js`, `BRIDGE_VERSION`. Name it+   `native-browser-bridge-v<ver>.bin` (⚠ `.bin`, NOT `.zip` — the wiki SILENTLY rejects `.zip`+   uploads: returns `ok:true, commit:null` and stores nothing).+3. **sha256 + byte size** → write `native-browser-bridge-manifest.json`+   `{manifest_version:1, version, url:"native-browser-bridge-v<ver>.bin", sha256, size, released_at}`.+4. **Upload the `.bin`** via the base64 files API (repo push drops binaries):+   `adom-wiki api -X POST /api/pages/adom/adom-browser-extension/files --body '{"files":[{"path":"...bin","content":"<b64>","encoding":"base64"}],...}'` (CLI `--body` cap ~128 KB; the ~28 KB zip is fine).+5. **Push manifest + source as TEXT** with `adom-wiki repo push adom-browser-extension --files native-browser-bridge-manifest.json bridge/bridge.json bridge/package.json bridge/server.js bridge/BRIDGE_VERSION ...`.+6. **Land it on a laptop:** `refresh_bridges {name:"native-browser"}` (self-reaps, AD 1.9.27+), then+   verify with `bridge_check_updates` → `current==latest==<ver>, updateAvailable:false`.++## ⚠ Two traps that WILL waste an hour (both hit live)+- **Orphaned bridge process blocks the new code.** `refresh_bridges`/`bridge_pause`/`resume` do NOT+  always reap a stuck persistent process — it keeps holding the port so your new code never runs+  (tell-tale: `host.json` `version` stays old while `bridge_list` shows the new cache version). Read+  the LIVE version from `~/.adom/bridges/native-browser/host.json`, not `bridge_list`. If stuck:+  `tasklist /FI "PID eq <pid>"` to confirm it's the bridge node.exe, then **targeted** `taskkill /PID+  <pid> /F` (one PID — never a broad `taskkill /IM node.exe`, that kills the user's other node). Then+  poke `nbrowser_status` to respawn fresh.+- **Version drift.** `VERSION` must read `bridge.json` (not `package.json`, which is easy to forget to+  bump). Confirm the live `host.json` version matches after every release.++## Publish the SKILLS pkg+`adom-wiki pkg publish --org adom`. Ship ONLY user `SKILL.md`s; keep `dev-skills/*.md` (this file, the+DEV skill) OUT of `package.json` `files[]` — the wiki indexes every `SKILL.md` in the tarball as an+installable user skill (Artifact 2 trap #1). `install.sh` must deploy to BOTH `~/.claude/skills` and+`~/.codex/skills`.++## Discovery+Edit `page.json` `discovery_triggers` (30+ user-task phrasings, login/forms niche — pup can't do+logins) + `discovery_pitch` (an INSTRUCTION). Push `page.json` **LAST** (a pkg publish clobbers it and+drops the hero). Verify: `adom-wiki discover preview --json "<7 real user queries>"` → land top-3.++## After ANY wiki change: show John in pup (standing rule)+Open the live page in a maximized pup window + shotlog + hand him the phone URL. Never just report+"published."