Pup - the AI's own browser

@@ -1,351 +1,100 @@-# pup: the Puppeteer bridge+# pup: the AI's own browser -> **The mission: normal browsers are built for humans; pup is a browser built for the AI, your-> doppelganger on the web.** Chrome asks *you* to save a password, click a dialog, pick a saved-> login, foreground its window. pup handles all of that silently for your AI, because the AI acts-> *as* you (your shared identity, your logins) without needing the human-facing machinery a normal-> browser is made of. Every design choice defers to that: anything a human browser shows a human to-> click, pup does silently for the AI. The goal is an AI that can drive the web the way you would.+**pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you.** It opens real Chrome windows that never jump in front of your work, keeps one shared profile where your logins accumulate, fills saved passwords for the AI, and labels every window on the taskbar with the name of the AI thread that owns it. Ask your AI to "open it in pup" and it does. -**pup is the AI's own browser: a real, full Chrome/Edge window on the user's desktop that the AI drives-with complete programmatic control, but a _sandbox_.** It runs in a profile pup owns (the shared, durable-**adom-you** jar, or a throwaway one when asked), never the user's real signed-in browser, and opens in the-**background by default** so it never disrupts them. That trade is exactly why pup exists alongside **nb / nbe** (the native browser and its extension):-nb/nbe drive the user's _real_ browser, their cookies, SSO, saved logins, their identity, for when a-task needs to BE the user. pup is the opposite trade: no borrowed identity, but **total control**, a-real, disposable browser the AI owns end to end (open/close windows + tabs, navigate, screenshot, eval-JS, record). Logged out by design, it's the safe, fully-drivable default for automation, testing,-scraping public pages, and showing wiki pages; reach for nb/nbe only when you genuinely need the user's-real logins. pup runs its own browser build and keeps it current by itself; to the user, and in every reply-an AI writes, these are simply **pup windows**.+pup is one small signed Windows program (about 8 MB) that [Adom Bridge](https://wiki.adom.inc/adom/adom-bridge) installs and keeps up to date for you. This page holds its source, its AI skills, and the guides below. It is open source under the MIT license. -**The core goal: an AI-driven browser that can do everything it needs to for you - the best assistant-in the world.** By default every pup window surfs on the shared durable **adom-you** profile, and every-login made there enriches a shared credential store. Over time that store lets pup automatically enter-usernames and passwords on every site it has ever seen, which is what makes a truly self-sufficient-AI browser possible. Isolated throwaway profiles exist for the cases that need them (logged-out-testing, acting as another user), but they build nothing: adom-you is the default on purpose.+## Install -**How pup drives a window (September 2026).** Every pup window runs on pup's own **extension lane**: pup's-extension inside the browser polls the bridge and runs the commands, and there is **no debug port**, which is-what the vendor edges (st.com, mouser, arrow) detect and wall. That lane does everything now: trusted mouse-and keyboard input that lands inside cross-origin frames (it drives reCAPTCHA tiles), element and full-page-screenshots, recording through Bridge's native recorder, `pup_fetch_url`, HTTP Basic-Auth answered from the-vault, and one browser **per profile**, so `isolated:true` is a real throwaway jar that ends with its window.-The older DevTools (CDP) lane is **off by default** and opens only when a user enables it for a box. Windows are-born **behind your work and stay there**: a measured ship gate samples the screen twice a second through a-cold start, navigates and warm opens, and passes only when a pup window was never on top.--**Every open and navigate answers `landed`**: the final URL and title, whether it is a sign-in page, and-whether the shared profile is already signed in there, so an AI never asks you to sign in where you already-are. Passwords live in pup's own vault (one DPAPI-protected file per user, no Windows credential cap), captured-as you sign in on either lane, filled on return, importable from your Chrome/Edge in one consent, with-Google account discovery and sign-in as verbs.--> To drive the user's **real, signed-in** Chrome/Edge (their cookies, SSO, saved logins), that's the-> **Adom browser extension's `nbrowser_*` verbs**, a separate bridge, not pup.--Canonical page: **https://wiki.adom.inc/adom/pup-bridge**--## Install vs Download, which is which (and why the version numbers differ)--The page header shows **two** things, for two different places. Most people need only the first.--| On the page | What it is | Who runs it | You usually… |-|---|---|---|---|-| **Install**, `adom-wiki pkg install …` | The **AI skill pack**, the `pup` skills that teach a cloud/container AI how to drive the bridge. Docs only, no runtime; drops into `~/.claude/skills` + `~/.codex/skills`. | your **container / cloud AI** | **run this** (or it arrives via `sync_skills`) |-| **Download for your machine**, `adom-bridge-puppeteer-v<ver>.zip` | The **bridge runtime**, the actual Node program (browser detection + driving) that runs on the desktop. | **Bridge**, on the user's PC | **do nothing**, Bridge **auto-installs & auto-updates** it; the manual download is only for offline/manual installs |--**Why two different version numbers?** They're independent artifacts. The **Install (pkg)** version bumps-whenever the *skills/docs* change (often). The **Download (runtime)** version bumps only when the *bridge-code* changes (rarely). So it's normal to see e.g. Install `v1.8.27` and Download `v1.8.20`, nothing is-out of sync; they just version on their own clocks.--*(There's also a third copy, the runtime is **bundled inside the Bridge installer** as a first-run-seed, superseded by a newer cache copy via `updateManifestUrl`. You never touch it directly.)*--## Use it+On your desktop there is nothing to install by hand. Adom Bridge (bundled with Hydrogen) downloads pup the first time an AI asks for a browser, and updates it on its own. In an AI container, install the skills so the AI knows how to use it:  ```bash-# everyday: open + screenshot. Opens in the BACKGROUND automatically, no need to lower it,-# and it's fully drivable/screenshottable while hidden, so the user is never interrupted.-adom-bridge-cli pup_open_window '{"sessionId":"myapp-web","owner":"myapp","url":"http://localhost:3000"}'-adom-bridge-cli pup_screenshot  '{"sessionId":"myapp-web"}'--# readiness (use pup_readiness, NOT pup_status). On a box with Chrome or Edge this is-# instantly {ready:true} with no download. Only a box with no Chromium at all fetches Chrome for-# Testing in the background, poll until ready, then open.-adom-bridge-cli pup_readiness '{}'      # → {ready:true, browserKind:"chrome"|"edge"|...}-```--- **Task-prefix your `sessionId` + pass `owner`**, sessions are shared across every AI thread on the-  desktop; that lets pup protect your window from another thread navigating it away.-- **`foreground:true` is the only way to show a window**, sizing/positioning does not foreground it.--Full everyday usage (tabs, recording, window ownership, cold-start playbook) is in the `pup` skill-(`SKILL.md`).--## Window-type taskbar icons: read a pup window at a glance--![The pup window-type icon family](docs/icons/family-v1.png)--Every pup window's **taskbar icon states what kind of thing it is showing**. All five share the same-drawing (the teal Adom tile carrying a solid browser window) and differ only in the window's-*content*: a monochrome glyph on the 24x24 Adom house grid, per the brand icon law (single color,-no gradients, no emoji):--| Icon | Window content | Means |-|---|---|---|-| ![wiki](docs/icons/pup-cat-wiki.png) | open book | **Adom wiki, public view**: logged out, what the world sees |-| ![wiki signed in](docs/icons/pup-cat-wiki-in.png) | book + person | **Adom wiki, signed in**: the user's logged-in view (private source, drafts, owner cards) |-| ![adom app](docs/icons/pup-cat-app.png) | the Adom mark | **An Adom app**: localhost or a cloud-slug proxy URL |-| ![web](docs/icons/pup-cat-web.png) | globe | **The web**: any other site (ti.com, digikey, ...) |-| ![mixed](docs/icons/pup-cat-mixed.png) | two panes | **Mixed**: the window's tabs span more than one category |--- The category is derived from **all tabs** in the window; it updates **live** (add a digikey tab-  to a wiki window and the icon flips to *mixed* within about a second).-- The **overlay badge** riding the icon's corner is separate and sacred: it is the **active tab's-  own favicon**, so you always see which site you are looking at. In grouped-taskbar mode it shows-  window/tab counters instead.-- The **tab title** carries the same login signal in text: a solid dot (`●   Logged in`) or hollow dot-  (`○   Public`) leads the title of every Adom wiki tab.-- Under the hood, each window's identity (icon, name, Alt-Tab entry) rides a per-session Windows-  AppUserModelID that **carries the category**: the only way Win11 allows a taskbar tile to change-  live. Grouped mode instead keeps one stable, pinnable `Adom.Pup` identity.--### Using pup's icons in your own tool (HD browser picker, launchers, menus)--If you are building a surface that offers "open a pup window" (a browser picker, a launcher tile, a-menu item), **use pup's real icon, not a stand-in.** The canonical, self-describing asset set lives-in the wiki repo at [`assets/pup-icons/`](assets/pup-icons/), in three formats:--- **SVG** (`pup-cat-*.svg`), scalable, the right choice for a web/Tauri picker.-- **PNG** (`pup-cat-*-{32,48,128,256,512}.png`), raster fallback / retina.-- **ICO** (`pup-cat-*.ico`), Windows multi-size, for taskbar/shortcut contexts (256px frame is-  PNG-compressed, per the Vista+ rule, so it never renders as a generic document).--**For a launcher/picker item, use `pup-cat-default`**, the neutral teal browser-window tile. It is-what a pup window's taskbar button looks like before its content is known, so the picker previews the-real result. The five category icons above (`wiki`, `wiki-in`, `app`, `web`, `mixed`) are for-*showing an existing window's kind*, not for a generic "open pup" action.--Fetch any asset from the wiki without cloning:-+adom-wiki pkg install adom/pup-bridge ```-https://wiki.adom.inc/api/v1/pages/pup-bridge/files/assets/pup-icons/pup-cat-default.svg-https://wiki.adom.inc/api/v1/pages/pup-bridge/files/assets/pup-icons/manifest.json-```--[`assets/pup-icons/manifest.json`](assets/pup-icons/manifest.json) is machine-readable: it maps each-icon id to its meaning, its glyph, and its file in every format, and names-`recommended_for_launcher` so a tool can pick the right one programmatically. Brand rule if you ever-redraw one: teal tile `#00b8b0` + dark-teal window body `#003d40` + a single-color teal glyph, no-gradients, shadows, or emoji.--## Real windows, one per type--Full windows as pup opens them (title bar, tabs, page). Note the tab title glyphs on the wiki pair-and the signed-in header on the second:--**Adom wiki, PUBLIC** (tab: `○ Public`, page header shows Login):--![A pup window on the Adom wiki, public view](docs/screenshots/window-wiki-public.png)--**Adom wiki, SIGNED IN** (tab: `● Logged in`, page header shows the user's name):--![A pup window on the Adom wiki, signed in](docs/screenshots/window-wiki-signedin.png)--**An Adom app** (here: the shotlog viewer on a cloud slug URL):--![A pup window on an Adom app](docs/screenshots/window-adom-app.png)--**The web** (ti.com): -![A pup window on the open web](docs/screenshots/window-web.png)+## Quick start -**Mixed** (a digikey tab and a wiki tab in one window):--![A pup window with mixed content](docs/screenshots/window-mixed.png)--## Overlay badges: the corner of the taskbar icon--![The overlay badges pup places on its taskbar icons](docs/icons/overlays-v1.png)--The base icon states the window TYPE; the small overlay riding its lower-right corner carries-LIVE detail, composited exactly like this:--| Overlay | When | What it tells you |-|---|---|---|-| the active tab's **favicon** on a dark rounded plate | split mode, page serves a favicon | which site the active tab is on, at a glance |-| a **count badge** (white digit, dark plate) | split mode, 2+ tabs and no favicon | how many tabs the window holds |-| the **dual counter** (dark = windows, teal = total tabs) | grouped mode | how much is stacked under the single Adom Pup button |--The overlay never carries branding or state that belongs to the base icon: it is live per-window-detail only, and the favicon always wins the slot when one exists.--## The Adom wiki: logged-in vs public view, and the taskbar toggle--pup can show any Adom wiki page from **two viewpoints**, and both the AI and the user can switch:--- **Public (default)**: a fresh logged-out profile: exactly what the world sees. Use it to verify-  what a publish actually exposed.-- **Signed in**: `pup_open_window {..., wikiView:"authed"}` routes to a reserved persistent-  profile whose cookie jar holds the user's ~30-day SSO session. One login serves **every** AI-  thread on the machine. First use returns `wikiLoginNeeded:true`; the user signs in once, in that-  window.--**The user can flip a wiki window themselves**: right-click its taskbar button: the jump list-carries **"Adom wiki: switch to logged-in view"** (or "...switch to public view"). Clicking it-relaunches that same window under the other cookie jar, brings it to the front, and shows an-on-screen caption while it works ("Switching to the logged-in view of the Adom wiki", then-"Adom wiki: now the LOGGED-IN view (Their Name)"). The AI-side equivalent is the-`pup_wiki_set_view` verb, which exists for that jump-list click: AI threads should pass-`wikiView` on open instead.--## One session, one OS window--Every pup session gets its **own OS window**, even when sessions share a browser profile (as all-signed-in wiki windows share the authed cookie jar). This is what makes per-window identity-possible: a window's title belongs to its active tab, so windows that share sessions as tabs-cannot be found, branded, flashed, or given jump lists individually. Sharing a profile shares the-cookies; it never merges windows.--## Recording--pup can record what it drives, a **single tab/window** or the **whole desktop**, straight from the-cloud, with no HUD and no need to bring the window forward.--![Example pup recording, driving the Adom wiki, captured in the background](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.gif)--*Above: a GIF preview of a real `pup_record` capture (≈8.6 s, the tab navigating the Adom wiki, recorded in the background on a VM). The native capture is the WebM linked below, this GIF is just an inline preview.*--### High-FPS windows: recording something the user is not looking at--pup windows are backgrounded by design, and Chrome throttles a window that is occluded, so-recording one normally yields a **1-2 fps** video. pup can disable Chrome's power-saving to keep a-window painting at full rate, but a window in that mode can never idle down (three of them once-drained a laptop overnight, wiki issue #14).--So it is **opt-in and leased**:--- **Default** is Chrome's own power behaviour. Normal windows throttle when occluded and cost-  nothing in the background. Right for driving, scraping and screenshots.-- **`pup_open_window {highFps:true}`** renders at full rate while occluded, for background-  recording. It holds a lease (default 20 min), and **an active recording holds that lease open-  indefinitely, so a take is never cut off**. On lapse the window is *downgraded* back to normal-  power by relaunching with its tabs intact, never closed.-- **`pup_highfps_extend {sessionId, minutes}`** negotiates more time up front.--**Full details, defaults, activity signals, and rules of thumb: [RECORDING.md](RECORDING.md).**--### Two recorders, pick by what you're capturing--| Verb pair | Captures | How it works under the hood |-|---|---|---|-| **`pup_record_start` / `pup_record_stop`** | ONE pup **tab/window**, the page content | **Bridge's native recorder** (Windows Graphics Capture, hardware H.264 MP4; a covered window records live) keyed on the window; where that recorder is absent, the DevTools screencast (JPEG frames → ffmpeg VP9 `.webm`) is the fallback, and its encode is a pollable job (`artifactReady`), never a truncated file. |-| **`desktop_record_start` / `desktop_record_stop`** (ab-core's capability, served by pup on its behalf until adom-bridge#143 lands) | the WHOLE **desktop** (multiple apps, dialogs) | Screen capture via **MediaRecorder** → one `.webm`; ffmpeg remuxes it to stamp a proper Duration. |+Your AI addresses its windows by its own thread name, so there are no ids to track:  ```bash-adom-bridge-cli pup_record_start '{"sessionId":"demo-web"}'          # → { recordingId }-# ...drive the scene: navigate, click, type, scroll...-adom-bridge-cli pup_record_stop  '{"sessionId":"demo-web","recordingId":"<id>"}'   # → { path: "...webm" }+adom-bridge --ai-thread "my-thread" pup_open_window '{"url":"https://example.com"}'   # a real window, behind your work+adom-bridge --ai-thread "my-thread" pup_screenshot  '{}'                              # the image lands in the container+adom-bridge --ai-thread "my-thread" pup_navigate    '{"url":"https://wiki.adom.inc"}' # same window, next page+adom-bridge --ai-thread "my-thread" pup_my_windows  '{}'                              # everything this thread has open ``` -**ffmpeg** is required for recording. The bridge auto-detects it (a WinGet `Gyan.FFmpeg` install, PATH,-or common dirs) and re-checks **lazily on `record_start`**, so if it's missing you can-`winget install Gyan.FFmpeg` and just retry, no bridge restart. `pup_record_status` /-`pup_record_list` (and the `desktop_record_*` equivalents, which are ab's verbs pup only answers for now) report in-flight and finished captures.+Or just say it: "open my app in pup", "screenshot this site in pup", "record a clip of this page in pup". -### Formats, one native format, easy conversion+## Every window wears its thread's name -pup records to **one** format natively: **WebM (VP9)**, for both recorders. It doesn't offer a format-switch; instead, convert with the bundled ffmpeg when you need MP4 or GIF. Real numbers from the ≈8.6 s-demo above (1264×705):+![pup thread tiles on the Windows taskbar, each with its page's favicon badge](docs/img/taskbar-tiles.png) -| Format | Codec | Size | How you get it | Best for | Watch out for |-|---|---|---|---|---|---|-| **WebM** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.webm)) | VP9 | **143 KB** | pup's **native** output, no step | Chrome/Edge/Firefox, small + high quality, the source of truth | Older **Safari**, PowerPoint, and some chat apps don't accept VP9/WebM |-| **MP4** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.mp4)) | H.264 | **135 KB** | transcode (below) | **Universal**, Safari, iOS, PowerPoint, Slack/Teams, "send it to anyone" | H.264 needs **even width & height**, odd dims (like 705) fail at frame 0; the `scale` filter forces even |-| **GIF** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.gif)) |, | **192 KB** | transcode (below) | Auto-playing, looping **inline preview** in any README/chat/GitHub, no player, no click (like the one above) | No audio, capped colors, and it balloons fast at higher fps/resolution/length, keep it short + downscaled |--```bash-# → MP4 (H.264, universal). The scale filter forces EVEN dimensions (H.264 rejects odd w/h → frame 0).-ffmpeg -i rec.webm -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -crf 23 -pix_fmt yuv420p -movflags +faststart rec.mp4+Each AI thread gets one taskbar button, and its icon is the thread's name drawn on the Adom teal tile. All of that thread's windows group under it, so the taskbar reads as a list of your threads, not a row of identical browser icons. The small badge in the corner is the active tab's own favicon: above, spice-compare is on a Texas Instruments page, nsf-proposal on the Adom wiki, parts-search on GitHub, and my-app on an ordinary site. pup stamps the name before the window first appears, so a button never starts out as a plain browser icon and changes later. Details, the five other display modes, and how to switch: [Taskbar identity and jump lists](docs/taskbar-and-jump-lists.md). -# → GIF (silent, looping inline preview). Palette pass keeps colors clean; drop fps/scale to shrink.-ffmpeg -i rec.webm -vf "fps=12,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" rec.gif-```+## Right-click a tile for pup's tasks -**Rule of thumb:** keep **WebM** for archiving + web embeds; make an **MP4** the moment a human on Safari/-PowerPoint/phone needs it; make a short **GIF** only for an inline auto-play preview.+![The jump list on a pup wiki window: switch views, annotate, open the dashboard, close all](docs/img/jumplist.png) -## Skills: what the AI reads to know pup+Right-clicking a pup tile opens its jump list. Every window offers Annotate this page (draw on the page and the marked-up capture goes to the owning AI thread), Open pup dashboard, and Close ALL Adom Pup windows. An Adom wiki window adds Switch to logged-in view and Switch to public view, which flips the same window between what you see and what the public sees, the fastest way to check what a publish exposes. Each task runs pup's own signed program directly, with no script in between. -pup ships as an `adom-wiki` package; installing it drops these skills into the driving AI's-`~/.claude/skills/` so any AI thread knows the full capability surface. Everything published on this-page's **Files** tab.+## The dashboard shows every window, live -| Skill | What it teaches |-|---|---|-| **pup** (`SKILL.md`) | START HERE: the mental model, when to use pup vs nb/nbe, the cold-start playbook, and the map to everything else. Addressing (your `ai-thread` name is the handle, no hwnd hunting), the credential vault, page integrity. |-| **pup-settings** | The complete behavior reference: every Settings toggle and the feature behind it: taskbar identity (AUMID) + icon style + grouping, jump lists, the toolbar extension family, annotate/capture, foreground etiquette, the credential vault, in-page identity, recovery/safety. Read to know exactly what pup does on the machine and how to change any of it (`pup_configure` / the dashboard gear). |-| **pup-credentials** | How pup signs the user in AS THEM: the OS-keychain vault (auto-capture + background autofill, matched across a site's registrable domain), importing the user's own saved Chrome/Edge/Brave logins (`pup_import_browser_logins`, one consent + one UAC), and the not-pretty-but-it-works recovery of a CURRENT password from the browser's own password manager (drive it, eyeball, Windows Hello, read it) when a saved one has gone stale. |-| **pup-auto-mode** | THE operating reality: Adom users run their AI in Claude Code Auto mode. How pup stays a great doppelganger inside the safety check: structured verbs pass, the risky moments become clean human pauses, and the `autoMode.allow` allowlist Hydrogen ships. |-| **pup-doppelganger** | The mission and the one design rule it dictates: anything a human browser shows a HUMAN to click, pup handles silently for the AI. The tie-breaker for every feature decision. |-| **pup-page-integrity** | The boundary: pup never mutates a page's own content (title, DOM) to carry pup metadata, that belongs on pup-owned surfaces (taskbar, dashboard, extension, identity tile). |-| **login-recipes/** | A growing corpus of per-site login flows (one file per domain, e.g. `gusto.com.md`) documenting the exact Auto-mode-aware sequence to sign in: which steps auto-approve, which pause for the human, which fields need real keystrokes. **Any Adom user can contribute** the recipe for a site they hit. The goal: thousands of recipes so pup drives logins everywhere. |+![The pup dashboard: live windows grouped by AI thread, the taskbar mirror, and why each icon looks the way it does](docs/img/dashboard.png) -Maintainer/source-only skills (in `dev-skills/`, not installed) document the build, debugging, and-hard-won internal doctrine, read those only if you are extending pup itself.+The dashboard lists every pup window grouped by the AI thread that owns it, with each tab, whether it is signed in, which profile it surfs on, and a mirror of the taskbar buttons. Every icon carries a "how this icon was chosen" note, so a wrong icon is never a mystery. The Say it panel lists phrases you can paste into any AI thread, and the gear opens Settings. Open it from the dock bar card, the jump list, or by asking your AI for "your dashboard in pup". Full tour: [The dashboard](docs/dashboard.md). -## Source & development+## Feature guides -This bridge is cloud-owned here (extracted from `adom-bridge/plugins/puppeteer`, mirroring the-kicad/fusion bridges). Bridge ships a bundled seed and auto-pulls newer versions from this page.+| guide | what it covers |+|---|---|+| [How pup works](docs/how-pup-works.md) | One signed exe, the extension lane, windows born behind your work, the shared adom-you profile, restarts and upgrades, and what is never brought back. |+| [Taskbar identity and jump lists](docs/taskbar-and-jump-lists.md) | Thread tiles, favicon badges, the six display modes, jump list tasks, and the Start Menu anchor setting. |+| [The dashboard](docs/dashboard.md) | The live window map, the taskbar mirror, icon explanations, Say it, and the toolbar buttons. |+| [Settings](docs/settings.md) | Every setting in the Settings window, its default, and what it changes. |+| [Logins, passwords and cards](docs/logins-and-cards.md) | pup's own vault, auto-capture and fill, reason-gated sign-in, importing from Chrome or Edge, Google accounts, Basic-Auth, cards. |+| [Screenshots and recording](docs/screenshots-and-recording.md) | Window, element and full-page screenshots, recording with sound, and annotate. |+| [Install size and footprint](docs/install-and-footprint.md) | What lands on disk, measured, what cleans itself up, and how to remove pup completely. |+| [pup or native browser?](docs/pup-vs-native-browser.md) | When the AI should use pup, when it should drive your own browser, and why both exist. |+| [Open source: code and contributing](docs/open-source-and-contributing.md) | How the code is organized, how to build and test it, how to add a feature, and how to send it back. |+| [Why pup uses its own browser build](docs/WHY-CFT.md) | The dated record of that decision. |++## Talk to the AI++| you want | say |+|---|---|+| see your app | "open my app in pup" |+| check a page | "screenshot this site in pup" |+| a clip | "record a clip of this page in pup" |+| the public view of a wiki page | "show me the logged-out view in pup" |+| sign in | "log me into mouser in pup" |+| everything open | "what do you have open in pup?" |+| the dashboard | "open your dashboard in pup" | -- Clone the source: `adom-wiki repo clone adom/pup-bridge`-- Runtime: the Rust exe in `rust/` (12 crates; every Win32 call behind the traits in `host`), packaged by `tools/ship.sh`; the release zip is the exe + `bridge.json`. `src/` is the earlier Node shell, kept buildable for macOS until the Mac port of `host-mac` lands.-- Why pup runs its own browser build rather than the user's branded Chrome: [docs/WHY-CFT.md](/blob/app/pup-bridge/docs/WHY-CFT.md) (maintainer reasoning; users just see pup windows).-- **Maintainer skills** (`pup-bridge-dev`, `pup-bridge-publish`) are **source-only**, in `dev-skills/` +-  `publish-skills/`, not shipped in the pkg (per the Bridge SDK a pkg ships only user skills). Skill map:+## Dependencies -| Skill | Ships in pkg? | What it's for |+| dependency | required? | why | |---|---|---|-| `pup` (root SKILL.md) | ✅ user | Start here, mental model (pup's own browser on the extension lane, no debug port, rendered but born behind your work), when-vs-nb, quick start |-| `pup-lanes` | ✅ user | The extension lane (default, everything) versus the CDP lane (off by default); what still needs CDP and what to do instead |-| `pup-credentials` | ✅ user | The vault, capture and autofill, Basic-Auth, Google sign-in, importing your browser logins, `landed`, the per-site login recipes |-| `pup-windows-sessions-tabs` | ✅ user | sessionIds, window ownership (don't steal another thread's window), background-vs-foreground, many tabs in one window |-| `pup-screenshots-recording` | ✅ user | Screenshots (full-page/full-res) + recording; driving/verifying tricky pages (shadow DOM, nested scroll) |-| `pup-browsers-and-chrome` | ✅ user | Browser detection/launch, `pup_use`, installing Chrome/CfT (incl. UAC-notify), readiness, cold-start errors |-| `pup-adom-wiki` | ✅ user | Driving + verifying `wiki.adom.inc` pages in pup (view/screenshot/verify; the login situation) |-| `pup-bridge-dev` / `pup-bridge-publish` | ❌ source-only | MAINTAINERS: bridge internals + the publish/release recipe (in `dev-skills/`/`publish-skills/`, not shipped) |-- Ownership boundary: `CLAUDE.md`. Publish recipe: `PUBLISHING.md`. History: `CHANGELOG.md`.--## Extend pup, add your own pup skill (third parties)+| Windows 10 or 11 | yes | pup is a native Windows program. A Mac port is in progress; Macs run the older build for now. |+| Adom Bridge 2.1 or later | yes | It installs, updates and starts pup, and carries every command from your AI to it. Hydrogen includes it. |+| A browser build | automatic | pup downloads its own Chrome build once (about 200 MB, 428 MB unpacked) and uses your installed Chrome or Edge until that finishes. | -Built a skill that drives pup for a specific job (a site-specific scraper, a visual test flow, a-domain widget)? You don't need write access here, surface it from this page with a **breadcrumb**:+## Skills -1. **Publish your skill** to your own wiki page (see the `adom-wiki` / `wiki-skillpack` skills). Make it a-   normal user skill so `pkg install` drops it into a container's `~/.claude/skills`.-2. **Drop a breadcrumb on this page** pointing at it:-   ```bash-   adom-wiki breadcrumb post adom/pup-bridge \-     --label "Your skill name, one-line what it does" \-     --target-url "https://wiki.adom.inc/<owner>/<your-slug>" \-     --category "skill"-   ```-   It's **pending until the page owner approves it**, then it shows in this page's **Breadcrumbs** tab.-3. **Discovery is automatic:** an agent working with pup can list related third-party skills with-   `adom-wiki breadcrumb list adom/pup-bridge`, approved breadcrumbs are how pup finds-   community skills that build on it.+The skills teach any AI how to use pup well. The main `pup` skill is the start; the others load when a task needs them. -Keep breadcrumbs on-topic (they genuinely extend pup / browser-driving); off-topic ones get rejected.--## Related--- [Bridge SDK guide](https://wiki.adom.inc/adom/adom-bridge-sdk), `bridge.json` schema, packaging, lifecycle-- [KiCad bridge](https://wiki.adom.inc/adom/kicad-bridge) · [Fusion 360 bridge](https://wiki.adom.inc/adom/fusion-bridge)-- [Bridge (parent app)](https://wiki.adom.inc/adom/adom-bridge)--MIT licensed.+| skill | purpose |+|---|---|+| `pup` | Start here: the model, addressing by thread name, the everyday verbs, and the rules. |+| `pup-windows-sessions-tabs` | Windows, tabs, ownership and the zero-id forms. |+| `pup-screenshots-recording` | Every screenshot and recording option, and tricky pages. |+| `pup-credentials` | The vault, sign-in, imports and Google accounts. |+| `pup-lanes` | How pup drives a window and the rules that keep your closes final. |+| `pup-taskbar-states` | The six taskbar display modes, exactly. |+| `pup-settings` | Every setting, behavior by behavior. |+| `pup-adom-wiki` | Viewing wiki pages signed in or as the public. |+| `pup-vendor-login` | Signing into vendor portals. |+| `pup-browsers-and-chrome` | Readiness, the browser build and cold starts (maintainer detail). |++## Open source++The complete source is in this page's **Files** tab: one Rust workspace of twelve crates, with every Windows call kept in a single crate so the Mac port only implements one interface. [Open source: code and contributing](docs/open-source-and-contributing.md) walks through the layout, the build, the tests and the release gates, and how to send a change back as a pull request on this page. Issues and ideas are welcome in the **Issues** tab.