Pup - Puppeteer Bridge

Drive a browser on the user's desktop from the cloud: the Puppeteer 'pup' bridge (pup_* verbs via the adom-bridge-cli CLI). To the user these are PUP WINDOWS, full stop: never name the browser build or how pup drives it unless they ask. pup runs its own browser in a pup-managed DURABLE profile (logins/localStorage persist and are shared across pup windows), driven through pup's own extension channel with no debug port, which is the lane every vendor site loads on and the ONLY lane pup opens unless you pass lane:'cdp' for a CDP-only feature (see the pup-lanes skill), in the BACKGROUND so it never disturbs the user; NOT the user's real signed-in profile (that is the Adom extension's nbrowser_* verbs), NOT headless (a real rendered window, so screenshots/recording are true-to-life). Open/close windows + tabs, navigate, screenshot, eval JS, record. This is the START-HERE skill: the mental model + when-to-use + the skill map; deeper topics route to the sub-skills. For 'is it ready' use pup_readiness (not pup_status). Trigger words: pup, puppeteer, browser window, open in pup, open my app in pup, browser screenshot, browser eval, browser reload, visual debug, headful chrome, pup_open_window, pup_screenshot, pup_readiness, pup_prewarm, chrome for testing, open in browser, open my web app, show my app in the browser, preview my app, open the app I just built, view my app, open localhost, show my dev server, pup_login, log into a site in pup, autofill password, saved login, durable profile, isolated window.

Driving the Adom wiki (wiki.adom.inc) inside a pup window — the common case of loading, viewing, and VERIFYING wiki pages with the pup_* verbs. Use when the user says show me the wiki / open my wiki page in pup / verify my page rendered / check the hero/version/download card / does my published page look right. Covers: pup shows the RENDERED page (use the adom-wiki CLI for API tasks like publish/search/releases — NOT pup); wiki pages are component-heavy with nested scroll, so use the shadow-DOM-survey + scroll-the-element techniques; and the LOGIN situation — every pup window shares ONE durable profile (v1.9.162), so once the user signs into the wiki once it stays logged in everywhere; wikiView:"public" is the explicit logged-OUT view for publish-visibility checks. Trigger words: adom wiki, wiki.adom.inc, show me the wiki, open the wiki in pup, open my wiki page, verify my wiki page, check my hero, wiki version chip, download card, wiki page rendered, is my page live, wiki login pup, log into the wiki.

MAINTAINER detail, not for a user's ears: how pup picks and launches its browser, and every cold-start / readiness case. A user hears 'pup window'; the build behind it (installed Chrome, Edge, or pup's own automation build) is answered only when asked (pup-bridge#114). Covers: the installed-browser-first architecture (launches a FRESH CDP-driven process of installed Chrome → else Edge → else cached Chrome for Testing, spawn-verified with fallthrough, caches the winner as default); pup_use to pin chrome/edge/cft/auto; INSTALLING real Google Chrome on an Edge-only box (pup_use install:true) including the UAC-approval-notify flow on locked-down machines; installing/prewarming Chrome for Testing; pup_readiness (READ-ONLY — the right 'is it ready / which browser' probe, NOT pup_status); the cold-start error table (node_not_found, bridge_restarting, chrome_for_testing_installing, chrome_install_no_disk, CfT 'skipped' is not a failure); AD-managed Node provisioning (no install needed on AD >=1.9.63); and the shell-approval gate. Read on any browser-pick question, a fresh/first-run PC, an install/prewarm, a not-ready error, or a shell-approval prompt. Trigger words: pup_readiness, pup_use, pup_prewarm, chrome for testing, install chrome, chrome_for_testing_installing, node_not_found, bridge_restarting, chrome_install_no_disk, cold start pup, which browser, edge only box, UAC approve chrome, request_shell_approval, shell command approval, adom runtimes, pup not ready.

How pup signs the user into sites AS THEM: pup's OS-keychain credential vault (auto-capture on login + silent autofill on return, matched across a site's whole registrable domain), importing the user's OWN saved Chrome/Edge/Brave passwords into the vault (pup_import_browser_logins — the SYSTEM-elevated decrypt behind one consent + one Windows UAC), and — when a saved password is STALE (a login that 'Fail to authenticate's) — recovering the CURRENT username+password straight from the user's browser password manager by driving it with Bridge desktop verbs, clicking the eyeball, waiting for the user's Windows Hello, and reading the revealed value. It is not pretty, but it works (proven end to end: recovered a live password, fixed a wrong username, logged into a gated CAD portal, downloaded a real library). Read before trying to log a user into any site pup does not already have a working credential for. Trigger words: pup vault, saved password, autofill login, import my passwords, import browser logins, pup_import_browser_logins, decrypt browser credentials, credential_set, pup_credentials, stale password, fail to authenticate, wrong password, recover my password, password manager, chrome://password-manager, show password eyeball, windows hello, get my username and password, log me in as me, seed adom-you logins, google login, sign into google, log into gmail, google account, which google account, work or personal google, pup_google_signin, pup_google_accounts.

Parent skill: pup. The two ways pup drives a pup window (never name the browser build to a user), the extension lane (DEFAULT, every vendor site loads, no debug port) and the CDP lane (opt-in ONLY via lane:'cdp', full DevTools control but detectable and walled by vendor edges). Pros and cons of each, exactly which verbs need CDP, what lane:'cdp' costs (it takes adom-you away from the extension lane and closes its windows), and the rule: never open a CDP window unless the task specifically needs a CDP-only feature. Read before passing lane, isolated, profile, highFps or webSecurity to pup_open_window, and whenever a verb answers lane_needs_cdp or cdp_lane_required. Trigger words: pup lane, extension lane, cdp lane, lane:cdp, lane_needs_cdp, cdp_lane_required, which lane, remote-debugging-port, debug port detected, site blocks pup, pup_open_window lane, isolated:true refused, highFps refused, three icons vs four icons.

Parent skill: pup. WHEN and HOW to paint the Windows taskbar progress bar on a pup window during long multi-stage work — site crawls, login→search→download loops, batch harvesting of datasheets/STEP files/libraries. Teaches the judgment call (multi-stage = yes, single page open = no), the pup_progress verb (indeterminate / value / off + stage notes), and clearing hygiene. Trigger words: progress bar, taskbar progress, pup_progress, long crawl, show progress, crawling indicator, harvesting progress, download progress pup.

Capturing pup (Puppeteer bridge) windows: SCREENSHOTS (pup_screenshot — lossless PNG, full-page vs viewport, full-resolution via pup_screenshot_full_res, and how to actually READ the image) and RECORDING (pup_record_start/stop records ONE pup window through ab's native recorder, MP4, extension lane included; desktop_record_start/stop records the WHOLE desktop across apps). Covers framing a window at an exact size for a clean shot WITHOUT foregrounding it, and why pup shots are true-to-life (real rendered window, not headless). Read when screenshotting a page, capturing full-page vs above-the-fold, recording a demo/walkthrough of an app, or choosing the window-recorder vs the desktop-recorder. Trigger words: pup_screenshot, pup_screenshot_full_res, full page screenshot, screenshot the page, read the screenshot, pup_record_start, pup_record_stop, desktop_record_start, desktop_record_stop, record my app, record a demo, screen recording, walkthrough video, pup screenshot, pup recording.

The complete reference to pup's behavior: every Settings toggle and the feature behind it, taskbar identity (AUMID), jump lists, the toolbar extension family, annotate/capture, foreground etiquette, the credential vault (auto-capture + autofill), in-page identity, and recovery/safety. Read to know exactly what pup does on the user's machine and how to change any of it. Change settings live with pup_configure {key:value} or the dashboard gear (Settings dialog).

Parent skill: pup. How pup signals it is WORKING on a window — a DETERMINATE progress bar painted right on the window's Windows taskbar button, sized to how long that operation usually takes, INSTEAD of the old orange flash. pup keeps a running average of every operation's duration (persisted) and fills the bar over that estimate: the bar starts at the EARLIEST point of the operation and ends at the LATEST. Built-in cases: applying a window's taskbar icon (from open until the icon actually lands) and taking a screenshot; any operation can be wrapped. Controlled by the `taskbarActivity` setting (progress | flash | off, default progress). Read this to understand the taskbar bar you see, to change/disable it, or to wrap a new operation with a bar. Trigger words: taskbar progress bar, progress bar on taskbar, taskbar activity, replace the flash, orange flash, taskbarActivity, verb timing, average duration, how long a screenshot takes, icon apply progress, progress instead of flash, pup progress bar, determinate progress.

Parent skill: pup. The definitive reference for the SIX taskbar identity states (taskbarMode tiles|aumid|plain, each with overlay badges on|off): exactly what each state looks like on the Windows taskbar, where every pixel comes from, the grouping semantics per mode, and how to switch (pup_configure or clicking a cell in the Settings matrix). Trigger words: taskbar states, taskbar identity, taskbarMode, tiles vs aumid vs plain, overlay badges, thread tiles state, taskbar matrix, six states, what does plain mode look like.

How to sign a user into a third-party vendor portal (Autodesk, Fusion, Mouser, DigiKey, and other SSO sites) inside a pup window, so the login PERSISTS and later visits are automatic. Covers the autonomous 'Continue with Google/Microsoft' path that needs no typed password (it reuses the profile's existing Google session), the OAuth-popup behaviour pup shows, driving Google's FedCM account chooser (which rejects ALL programmatic clicks — needs a real desktop_hover-then-click), which profile to use for crash-isolation, and the hard limit that some heavy account-admin SPAs (Autodesk's Kepler/React portal) JAM CDP so pup cannot drive the in-portal admin UI. Read this before opening any vendor login in pup. Trigger words: log into autodesk, autodesk sign in, sign into fusion, continue with google, vendor login, portal login, sso login in pup, log into mouser, digikey login, assign a license, autodesk account, manage.autodesk.com, store my login, oauth popup, account chooser.

Parent skill: pup. MAINTAINER detail (a user hears 'pup window'; do not volunteer the build, pup-bridge#114): WHY pup drives its own automation build of Chrome instead of installed Chrome/Edge, the five dated reasons (automation banner, --load-extension removal being the forcing one, version determinism, none of the consumer chrome, binary isolation), the honest trade-offs (~160 MB first fetch, the window title, no Widevine), and what did NOT change (profiles/logins are pup-owned either way). The policy flipped twice; docs/WHY-CFT.md on the wiki page is the dated canonical record and this skill is its AI-discoverable form. Read before questioning the browser choice, proposing native-first, or explaining a 'Google Chrome for Testing' window title to a user. Trigger words: why chrome for testing, why CfT, why not real chrome, why not installed chrome, why not edge, chrome for testing reasons, automation banner, controlled by automated test software, load-extension removed, browser policy pup, native-first, cft vs chrome, what is chrome for testing, google chrome for testing in task manager, widevine pup, drm pup.

pup (Puppeteer bridge) windows, sessions, and tabs: how sessionIds work and why to task-prefix them, WINDOW OWNERSHIP so you never steal another AI thread's window (owner + session_owned_by_another_thread + takeover), the BACKGROUND-by-default rule (foreground:true is the only way to show a window; sizing/positioning does NOT foreground), running MANY TABS in one window instead of many windows, switching/listing/closing sessions and tabs, and verifying what you actually opened. Read when opening/reusing pup windows, managing tabs, deciding background vs foreground, or seeing errorCode session_owned_by_another_thread. Trigger words: pup sessionId, pup_open_window owner, session_owned_by_another_thread, takeover window, pup background, foreground:true, pup_open_tab, pup_switch_tab, pup_list_tabs, pup_switch_window, pup_list_windows, pup_close_window, pup tabs, many tabs one window, don't steal window, pup_lower_os_window, pup_raise_os_window, pup_alert_window.

The complete decision history on AUMID / taskbar identity in pup - what was tried, what it broke, the settled NO-AUMID decision, and the process rule that prevents silently reversing it again. READ BEFORE touching anything involving AppUserModelID, taskbar grouping, window identity, or "separate taskbar icons".

THE operating reality: Adom users run their AI in Claude Code AUTO mode (Hydrogen places them there; Anthropic removed the bypassPermissions menu option). pup must be a great doppelganger INSIDE Auto mode, never assume bypass. The design rule: expose rich structured verbs so the safety check passes, make the genuinely-risky moments clean human-approval pauses. Read before adding any verb or any flow that touches credentials, the OS, or destructive actions.

DEV skill (source-only). What to do when a site serves pup a bot wall / CAPTCHA / 'Verification Required' instead of the page, identifying WHICH wall it is (DataDome vs Cloudflare vs Akamai vs Imperva), what pup already does about each, the sourcing ladder that avoids the fight entirely (official API → nb → pup), and how to hand a challenge to the human who is driving. Read this before touching the consumer-UA override, before adding retries to a crawl, and before anyone proposes fingerprint spoofing. Trigger words: bot wall, captcha, verification required, datadome, cloudflare challenge, just a moment, akamai, imperva, incapsula, blocked by mouser, blocked by digikey, chip-fetcher blocked, crawl blocked, are you spoofing the user agent, pup user agent, scraping blocked, access denied, 403 on a vendor site.

DEVELOPER debugging playbook for a MISBEHAVING Puppeteer (pup) bridge — read this the moment pup feels broken, BEFORE re-diagnosing from scratch. Covers: pup verbs time out / hang, the AD bridge LED is dim, browser.bridgeRunning:false, the bridge keeps restarting / respawning every ~60s, opens succeed but the window vanishes or pup_list_windows is empty seconds later, a cold-start that never finishes, 'Chrome process exited immediately' storms, and how to tell a pup self-crash from AD reaping. Encodes the 2026-07-19 root causes (concurrent-launch wedge, crash-poison recovery loop, restart-reap-vs-respawn) so nobody re-derives them. Trigger words: pup timing out, pup verbs hang, pup not responding, pup bridge down, dim LED, bridgeRunning false, pup keeps restarting, pup respawn loop, bridge flapping, spawned with no reap, bridge_log_read, cold start stuck, Chrome exited immediately, window disappears, list_windows empty, pup wedged, recoverSessions crash, SingletonLock collision, pup diagnose.

DEVELOPER skill for building, publishing, and maintaining the Puppeteer (pup) bridge. NOT needed by general users — they want the `pup` skill. Read this when editing the bridge code, cutting a new version, publishing to the wiki, wiring the cold-start Chrome-for-Testing self-heal, or understanding the pkg-vs-release-vs-bundled artifact model. Trigger words: pup bridge dev, publish pup bridge, build puppeteer bridge, bridge_install pup, pup-bridge, cold-start self-heal, pup_readiness internals, pup release, pup manifest, ship pup bridge.

The standard pup test scenarios (source-only, maintainer skill). Run these after ANY pup change instead of asking John to spell out a test. Covers: the up-gate, smoke, the 5-thread simulation (the John test), the heavy-load matrix, the 3-phase open/reload/fg-sweep, the parallel-open concurrency proof, one-flash, strand-rescue, login persistence, and cross-thread pollution. Every scenario states its EXPECTED output — a run without expectations is not a test.

DEV skill (source-only). The MODEL of how websites tell one browser from another and one driving MODE from another, and use those differences to block a page load. Read this to understand WHY a site loads in one pup lane / a real browser but not another, before you touch UA/brands overrides, the debug port, the browser version, or propose fingerprint spoofing. Covers the eight detection layers in the order a site applies them (TLS ClientHello/JA4, HTTP2 fingerprint, HTTP headers, the CDP debug port, the JS environment, sensor EXECUTION, IP/ASN reputation, poisoned cookies), which layer each pup lane exposes, which vendor uses which wall, and the measured facts from the analog.com investigation (2026-09-14): a stale Chrome-for-Testing version breaks Akamai's sensor, and egress IP reputation is a separate stacked cause. Companion to pup-bot-walls (what to DO when blocked). Trigger words: why does this site load in nb but not pup, browser fingerprint, JA3, JA4, TLS fingerprint, ClientHello, akamai, bmak, datadome, sensor, sec-ch-ua brands, chrome for testing version, cft version, navigator.webdriver, debug port detection, remote-debugging-port, why blocked, access denied, bot detection, extension lane vs cdp lane, consumer identity, egress IP reputation, _abck.

How to import a user's existing Chrome logins (passwords, cookies/sessions) into pup's profiles to seed the adom-you profile - the App-Bound Encryption (ABE) wall, the admin/SYSTEM path that defeats it, and the hard-measured reality of what actually imports vs what is blocked. Includes the reverse-engineered playbook from OpenAI Codex Desktop's "Import from Chrome" flow. READ BEFORE building or debugging any Chrome-data import, credential-vault seeding, or "get the user's logins into pup" feature.

The hard rules for handling the Chrome DevTools Protocol (CDP) in the pup bridge WITHOUT choking. pup drives Chrome over CDP on a SINGLE Node event loop; the moment a page throws thousands of CDP events at a naive handler, the loop starves, the bridge stops answering AD on :64230, and it looks like "pup crashed." This has been the #1 recurring misery for MONTHS. READ THIS before you enable a CDP domain, add a page event listener, createCDPSession, wire a console/network/DOM/screencast handler, or do ANY per-event work. Never be lazy about CDP again.

How to tell whether a "the page crashed/hung pup" problem is really pup's bug (almost always) and not the page or Chrome, by running the SAME page through nb (the Adom extension driving real Chrome) or a plain headful Chrome and watching it behave. A heavy or hostile page must NEVER crash, hang, or starve the pup bridge; if it does, the fault is in pup's CDP handling. READ THIS before you blame a page ("it's a giant Babylon.js bundle", "it floods the console", "it's a WebGL hog") for bridge instability. John's rule: prove it's your bridge first.

THE mission of pup, and the design rule that flows from it. Normal browsers are built for humans; pup is a browser built for the AI — the human's doppelganger on the web. Every design call defers to this: anything a human browser shows a HUMAN to click, pup handles SILENTLY for the AI. Read before adding any user-facing prompt, dialog, foreground, or gesture-dependent behavior.

DEV skill (source-only, never shipped in the pkg) - how to rebuild, tweak, and publish pup's wiki hero image. The full recipe: the parameterized build script, the design constants matched to Bridge's hero, the hero-studio human-generate gate, and every trap that bit us (gitignore whitelist, stale studio slugs, overlay defaults, other threads' studios).

DEVELOPER-only (user-invocable:false). What to DO when John says 'audit your taskbar icons' — it is never a request for a report. It means: detect whether pup's AUMID/icon tracking has drifted from the shell, find out WHY, FIX THE CODE so that class can never drift again, then REAPPLY every AUMID icon so the glass is right, and prove it with red-boxed pixels. The end state John is paying for: he never has to ask, because pup audits and heals itself. Trigger words: audit your taskbar icons, audit the icons, icon audit, aumid tracking, are your icons right, taskbar drift, check your icons, reapply aumids, self-heal icons.

Why the pup DASHBOARD taskbar strip keeps "not matching" the real Windows taskbar, and the rules that actually keep them consistent. This is the single most-repeated complaint from John ("how many times are we going to go through this same issue, over and over"). READ THIS before touching the dashboard's taskbarButtons/baseIcon logic, the overlay-match LED, or anything that claims the dashboard mirrors the taskbar.

How pup taskbar jump lists work AND the one bug John has reported ~10 times that keeps not getting fixed - the FIRST right-click shows the menu for a blip then it vanishes, and you must right-click a SECOND time ~1s later for it to stay. Cause, the 2nd-click workaround, and the real fix. READ THIS before touching updateWikiJumplist, any desktop_set_window_jumplist call, or any code that re-commits a jump list on a timer/stamp/nav.

DEVELOPER-only (user-invocable:false). THE ralph loop for taskbar identity state switching: tools/mode-ralph.sh drives the real Settings endpoint through tiles/aumid/plain plus RAPID double-click race rounds, then verifies the GLASS three ways per round (UIA button names, UIA-rect red-box screenshot crops, a teal-fraction pixel classifier on the button under test). Born 2026-08-16 after TWO name-only 'GREEN' runs shipped while the Chrome-for-Testing group button still wore pup's teal icon. Trigger words: mode ralph, taskbar state test, plain mode broken, aumid not removed, red box screenshot, pixel gate, ralph the mode switching.

DEV skill (source-only) - HARD RULE: pup must NEVER cause a Windows Firewall / Windows Security dialog ('Do you want to allow public and private networks to access this app?') to pop at an Adom user, and must never NEED any firewall feature. Every socket pup or its Chrome opens must be LOOPBACK-ONLY. Documents the measured 2026-08-23 root cause (three stacked --disable-features flags: Chrome honors only the LAST, silently re-enabling MediaRouter's 0.0.0.0:5353 mDNS bind) and the merge rule that prevents it. Read BEFORE adding any Chrome launch flag, any --disable-features/--enable-features entry, any listener/server/socket, or when a user reports a firewall prompt naming chrome.exe or node. Trigger words: firewall, Windows Firewall, windows security dialog, allow public and private networks, firewall prompt, mDNS, 5353, MediaRouter, 0.0.0.0 bind, non-loopback, disable-features, enable-features, duplicate flag, launch flags, chrome flags, new listener, bind host.

DEV skill (source-only) - THE ABSOLUTE BAN on the 'wiggle' window-identification technique. pup must NEVER identify which OS window belongs to a session by enumerating windows, matching them by geometry/bounds, and nudging/moving a window to see which CDP window's bounds change. John has banned this THREE times (it keeps getting reintroduced as a fallback and keeps causing stolen windows, wrong taskbar icons, and off-screen strands). Read this BEFORE touching ANY window-identification, hwnd-resolution, taskbar-identity, park, or placement code, and BEFORE adding ANY fallback for a lost window handle. If you are about to enumerate top-level windows and pick one by size/position, STOP - that is the banned technique. Trigger words: which window is this, resolve hwnd, hwnd resolution, wiggle, bestSessionHwnd, resolveSessionHwndByBounds, geometry match, bounds match, EnumWindows, window identification, birth handle lost, 2 wiggle-matches, cannot disambiguate windows, park could not confirm, stole another pup window, wrong taskbar icon, off-screen strand, adom-you shared profile windows.

DOCTRINE: pup never mutates user-visible page content to carry pup metadata — no document.title rewriting, no DOM text injection into the page's own UI. Where ownership/metadata signals belong instead. Read before adding ANY feature that touches what a page shows.

DEV skill (source-only) - HARD RULE: every image shown to a user (settings example images, README/wiki screenshots, skill illustrations) must be a REAL SCREENSHOT of the real feature running, never generated/drawn/mocked art (PIL, SVG mockups, hand-drawn taskbar buttons). John's words: 'never fucking make fake windows taskbar icons. these look like dog shit. ONLY screenshot real icons... you can make a progress bar for a windows icon and screenshot it, crop it, then use it.' Read BEFORE adding ANY image to the dashboard settings dialog, a SKILL.md, the wiki README, or docs. Trigger words: settings example image, example screenshot, settings-ex, imgBy, illustration, mockup image, PIL image, generate an image, draw a taskbar button, fake icon, example img, dashboard settings image, anncapbar, tbactprogress, toolbarext.

DEV skill (source-only) - how to RALPH-TEST whether a BACKGROUND (occluded) pup window actually PAINTED its content, vs sitting BLANK. The trap: a normal screenshot (CDP Page.captureScreenshot, or PrintWindow PW_RENDERFULLCONTENT) FORCES a fresh render, so it shows content even when the live window is blank - it masks the exact bug you are testing for. The ground-truth signal is the Windows DWM taskbar THUMBNAIL (what you see hovering a taskbar icon): DWM generates it from the window's last COMPOSITED surface without forcing a render, so a blank thumbnail means the window never painted. Read this before claiming a background window renders, before touching the occlusion/focus-emulation/park code, or when a user reports 'pup windows are blank'. Trigger words: blank pup window, window not rendering, background window blank, did it paint, taskbar thumbnail, DWM thumbnail, requestAnimationFrame not firing, visibilityState hidden, occluded window blank, setFocusEmulationEnabled, one rAF, render test, ralph render, prove it rendered.

DEVELOPER-only (user-invocable:false). THE standing self-test discipline for the pup bridge: run tools/selftest.sh after EVERY ship+respawn, plus the manual PIXEL GATES the script cannot automate (badge content, tile text, matrix accuracy). Born 2026-08-16 after John had to catch a broken Settings dialog, generic-globe badges, a starved jump list, and enum spam himself — each one findable by this checklist. Trigger words: selftest, self test, test yourself, pup regression, did you ralph yourself, verify pup, post-ship checks.

DEV skill (source-only) - how pup maps each window to its OS taskbar button (AUMID tile + overlay badge), the hard-won architecture, and the RALPH TEST you must run before claiming any taskbar-identity fix works. Read before touching birth-hwnd capture, resolveSessionHwndByBounds, hwndBelongsToPup, stampPupIdentity, or applyAppOverlay.

What pup is FOR, in John's own words, and the standing rules that follow from it. Read this BEFORE any pup work and before answering him about pup. The goal: pup makes his life easier, it signs him in so he never types passwords, it never puts a window in front of him, and it gets finished rather than deferred. Trigger words: pup goal, why pup exists, pup purpose, make pup perfect, pup standing rules, password typing, shoving windows, foreground rude, pup doctrine, before touching pup.

DEV skill (source-only) - THE doctrine for the user-raise vs pup-demotion fight. John clicks a pup taskbar button and the window must come up INSTANTLY and STAY up; pup's parks and re-asserts must never yank it back down. Revisited ~20 times before this was written; read this BEFORE touching any park, re-assert, z-order, foreground, or occlusion code, and BEFORE adding ANY new demotion path.

THE LAW for how pup finds a session's OS window for any Bridge window verb - ALWAYS by its resolved HANDLE (hwnd), NEVER by title. Title lookup is unreliable (titleTag is off by default and pages rewrite their own <title>) and it has independently broken the overlay paint, the park, the taskbar flash, the AUMID stamp, AND the jump list - the same bug, over and over. READ THIS before adding or touching ANY chrome.adCommand('desktop_*') call that acts on a window, or before adding a desktop_find_window resolver.

DEVELOPER skill — the exact, battle-tested recipe for publishing a new version of the Puppeteer (pup) bridge to wiki.adom.inc, plus every gotcha hit live. NOT for general users. Read before cutting a release: which artifact goes where (pkg=skills, release=bridge zip), version-lockstep, the `files` allowlist, keeping the tarball lean (NO zip / NO src / NO heroes / NO node deps), the pkg ships ONLY the pup USER skill (dev/publish skills are source-only in dev-skills/ + publish-skills/, never in the pkg — open-vs-closed source doesn't matter), the skillpack package.json declaring dependencies:{ adom/adom-bridge } to pull the AD CLI + core skills, deploying skills to .claude AND .codex, scrubbing stale retired-wiki (wiki-ufypy5dpx93o.adom.cloud) URLs, user-first discovery triggers, sha matching, and verify steps. Trigger words: publish pup bridge, ship pup bridge, release pup, pkg publish, repo push, adom-wiki release, bridge manifest, pup version bump, no zip in tarball, dev skill source only, scrub old wiki url, codex skills, discovery triggers, pup-bridge publish.