adom-desktop browser_readiness '{}'          # is the bridge ready? which browser?
adom-desktop browser_open_window '{"url":"http://localhost:<port>/...","sessionId":"<task-name>"}'
adom-desktop browser_screenshot '{"sessionId":"<task-name>"}'   # verify what's on screen

---
name: hd-pup
description: >
  PUP — what "pup" means in Hydrogen Desktop and exactly how to open one. When
  the user says "show me in pup", "open it in pup", "pup window", "in pup", or
  asks to demo/drive ANY page "in pup", it means a real, AI-drivable Chrome/Edge
  window opened by Adom Desktop's Puppeteer bridge (auto-installed with HD) on
  THIS machine — never a webview (see hd-webview), never the user's personal
  signed-in browser (that's nbrowser). CRITICAL HD DIFFERENCE: in HD, localhost
  URLs are the NORM for pup (everything binds localhost on the same machine) —
  the cloud-container rule "pup can't see localhost" is INVERTED here. Trigger
  words — pup, open in pup, show me in pup, in pup, pup window, puppeteer,
  pup browser, drive a browser, show the page in pup.
---

# hd-pup — "pup" is a real drivable browser window on this machine

**pup** = Adom Desktop's Puppeteer bridge driving a fresh, isolated Chrome (or
Edge) process. HD embeds Adom Desktop and auto-installs the bridge, so pup is
always available — no setup questions, just check readiness and go.

## ⚠️ THE LOCALHOST RULE IS INVERTED IN HD (do not import cloud instincts)

- **Web Hydrogen (cloud container):** pup runs on the *user's desktop*, so the
  container's `localhost` is unreachable — the bridge sanity-checks localhost
  URLs because they're almost always a mistake, and pages get slug/proxy URLs
  (`vscode_proxy_uri` style) instead.
- **Hydrogen Desktop (here):** the workspace, HD, and pup all live on the SAME
  machine. **~95% of pup URLs are `http://localhost:<port>` and that is
  CORRECT.** Never rewrite a localhost URL to a slug/proxy URL, and never
  refuse it — HD binds its web servers to localhost by design.

## ✅ How to open a page in pup (from the workspace)

```bash
adom-desktop browser_readiness '{}'          # is the bridge ready? which browser?
adom-desktop browser_open_window '{"url":"http://localhost:<port>/...","sessionId":"<task-name>"}'
adom-desktop browser_screenshot '{"sessionId":"<task-name>"}'   # verify what's on screen
```

- Reuse ONE window per task via a stable `sessionId` — open tabs in it rather
  than spawning window after window.
- pup opens in the background by default; pass `foreground:true` only when the
  user should see it appear right now.
- Verify by screenshot, not by assumption: if `browser_screenshot` doesn't show
  your page, it isn't open.

## ⛔ Never confuse the three browser surfaces

| Ask | Surface | Skill |
|---|---|---|
| "show me in **webview**" | native Hydrogen webview tab | `hd-webview` |
| "show me in **pup**" / drive it | isolated Puppeteer Chrome (this skill) | `pup` for deep driving |
| use **my** logins / my real browser | user's signed-in Chrome/Edge | nbrowser / adom-browser-extension |

For deep pup driving (tabs, sessions, recording, eval), the full `pup` skill
applies — this skill exists so the word "pup" always routes correctly in HD.