Ralph Test

@@ -1,9 +1,10 @@ --- name: ralph-loop-test+disable-model-invocation: true description: >-   The Adom "ralph test" (Ralph Wiggum loop) — a screenshot-driven fix loop for apps. Point it at the   user's running app (almost always a WEB APP in a webview / pup / the native browser, sometimes a-  DESKTOP APP driven via an adom-bridge-cli bridge): load it, screenshot it, feed the shot to the AI, the+  DESKTOP APP driven via an Adom Bridge (`adom-bridge`) bridge): load it, screenshot it, feed the shot to the AI, the   AI analyzes what's wrong and fixes it, then reload the page (or reload the file in the desktop app),   screenshot again, and loop until it's right. Covers every Adom screenshot surface — Hydrogen webview   (adom-cli), pup, the native Chrome/Edge extension (nbrowser_*), and desktop bridges — plus the@@ -18,7 +19,7 @@ description: >- In the Adom world a **ralph test** (a Ralph Wiggum loop) is a **visual fix loop**, not a code-build loop. You point it at the user's *running app* — almost always a **web app** (shown in a Hydrogen webview, in pup, or in the native Chrome/Edge browser), sometimes a **desktop app driven through an-adom-bridge-cli bridge** — and you grind this cycle:+Adom Bridge (`adom-bridge`) bridge** — and you grind this cycle:  1. **Load** the app on a surface you can screenshot. 2. **Screenshot** it.@@ -37,14 +38,14 @@ shotlog history**, not the context window. ## Where you're running The AI always runs from a **container**, and they all carry the same screenshot tools, so this loop works identically everywhere:-- **Hydrogen Web** — a Docker cloud container.-- **Hydrogen Desktop** — a WSL2 container (Windows), a Lima container (Mac), or an Ubuntu container-  (Ubuntu).+- **Hydrogen Cloud (hc)** — a Docker cloud container.+- **Hydrogen (ah)**, the desktop app's local workspace — a WSL2 distro (Windows), a Lima container+  (Mac), or an Ubuntu container (Ubuntu).  What changes per task is only **which surface** you load the app on. Pick it in Step 1. -> Targeting: The bridge CLI's verbs hit the user's laptop (`adom-bridge-cli`; `adom-bridge` on macOS). If more than one desktop is on the relay you-> MUST name one (`-t AdomLapper`) or it errors `ambiguous_target` (`adom-bridge-cli targets` lists them).+> Targeting: The bridge CLI's verbs hit the user's laptop (`adom-bridge`). If more than one desktop is on the relay you+> MUST name one (`--target AdomLapper`) or it errors `ambiguous_target` (`adom-bridge targets` lists them).  --- @@ -77,20 +78,20 @@ The loop opens browser surfaces on the user's real machine, so don't clutter or  - **One window per topic — use TABS for the rest.** Keep a pup or native-browser **window pinned to a   single topic**; when the task spans several pages, open them as **tabs in that same window**, not a-  new window each. `browser_open_tab {sessionId,url}` "adds a tab to the same Chrome window … avoids a+  new window each. `pup_open_tab {sessionId,url}` "adds a tab to the same Chrome window … avoids a   new taskbar icon" (native: `nbrowser_open_tab`). Editing five wiki pages? Five **tabs in one window**,-  then `browser_list_tabs` → `browser_switch_tab {tabId}` (or just screenshot a specific `tabId`) as you+  then `pup_list_tabs` → `pup_switch_tab {tabId}` (or just screenshot a specific `tabId`) as you   go. One taskbar button, not five. - **NEVER take over a window that's open for another reason.** Always open your OWN fresh window-  (`browser_open_window` / `nbrowser_open_window`). Navigating or reloading a window the user — or+  (`pup_open_window` / `nbrowser_open_window`). Navigating or reloading a window the user — or   another AI thread — already had open yanks their page out from under them; it's the rudest move the   loop can make, and the AI **drifts into it unless it stops to check first**. Open fresh, every time.-- **Clean up after yourself.** When done with a window, **close it** (`browser_close_window` /+- **Clean up after yourself.** When done with a window, **close it** (`pup_close_window` /   `nbrowser_close_window`; `close_tab` for stray tabs). Long loops otherwise leave a graveyard of stale   pup/native windows cluttering the taskbar — tidy as you go and again at the end. - **Use the taskbar FLASH to say "come look," gently.** Whenever the loop updates a window during a   ralph test (reloaded the page, applied a fix, grabbed a fresh shot), **flash its taskbar icon orange**-  — `browser_alert_window {sessionId}` (native: `nbrowser_flash {sessionId}`). It does **NOT** steal+  — `pup_alert_window {sessionId}` (native: `nbrowser_flash {sessionId}`). It does **NOT** steal   foreground; it just glows, so the user thinks *"oh, the AI updated that window — I'll peek if I want."*   That gentle nudge is the whole point: **never force a window to the foreground** to show progress —   that's rude and disruptive.@@ -107,31 +108,31 @@ adom-cli hydrogen screenshot panel --panel-id <id>   # just the app's panel  (id ``` Reload between iterations by reloading the webview — or just save a file if the app hot-reloads. -**Pro/con — `adom-cli` hydrogen screenshots are SMART but Web Hydrogen pays a price.** These are the+**Pro/con — `adom-cli` hydrogen screenshots are SMART but Hydrogen Cloud (hc) pays a price.** These are the only **smart** captures: they target a specific **webview / panel / tab** (not just an OS window), which Adom Bridge cannot do — it only targets window ids. The catch is the permission model, and it splits by environment: -- **Web Hydrogen (cloud):** the first `adom-cli hydrogen screenshot` makes the user approve the+- **Hydrogen Cloud (hc, in a web browser):** the first `adom-cli hydrogen screenshot` makes the user approve the   browser's native **screen-sharing prompt and pick the window** (a one-time browser security gate).   That also flips the machine into a **screen-share mode like a Google Meet**, with side effects the   user may not expect during a long loop: **displays won't sleep**, **screensavers won't fire**, a   **laptop panel won't turn off at the hardware level**, and (likely) **Windows suppresses   notifications**.-- **Hydrogen Desktop:** does **everything Web Hydrogen's smart targeting can** (webviews/panels/tabs),+- **Hydrogen (ah, the desktop app):** does **everything hc's smart targeting can** (webviews/panels/tabs),   but with **no permission prompt and none of the Google-Meet side effects** — it turns screenshotting   (and **screen recording**) **on and off on demand** because it never has to ask. - **pup** and the **native browser** (with the extension) also capture with **no prompt**, but they   target a window/page, not a Hydrogen panel. -So for an unattended ralph loop, prefer **Hydrogen Desktop / pup / native browser**; reach for **Web-Hydrogen's** smart panel targeting knowing it imposes the screen-share mode for the session.+So for an unattended ralph loop, prefer **Hydrogen (ah) / pup / native browser**; reach for **hc's**+smart panel targeting knowing it imposes the screen-share mode for the session.  ### B. Web app in pup (Puppeteer) — fast, scriptable ```bash-adom-bridge-cli -t AdomLapper browser_open_window '{"sessionId":"app","profile":"Default","url":"<url>"}'-adom-bridge-cli -t AdomLapper browser_screenshot  '{"sessionId":"app","fullPage":true}'   # → the screenshot cache (auto-pulled to ~/project/screenshots/adom-bridge/)-adom-bridge-cli -t AdomLapper browser_reload      '{"sessionId":"app"}'+adom-bridge --target AdomLapper pup_open_window '{"sessionId":"app","profile":"Default","url":"<url>"}'+adom-bridge --target AdomLapper pup_screenshot  '{"sessionId":"app","fullPage":true}'   # → the screenshot cache (auto-pulled to ~/project/screenshots/adom-bridge/)+adom-bridge --target AdomLapper pup_reload      '{"sessionId":"app"}' ``` Great for your own apps and open public pages. **But** pup is an empty controlled-Chromium: more and more sites **detect and block it** (e.g. `digikey.com`), and it's **logged in to nothing**. When that@@ -143,13 +144,14 @@ When a site **blocks pup** or **needs you logged in**, drive the user's **real C login walls and captchas that stop pup. This is your best friend for surfing the web (or local apps) with a full logged-in context. ```bash-adom-bridge-cli -t AdomLapper nbrowser_status                                         # confirm connected-adom-bridge-cli -t AdomLapper nbrowser_open_window '{"sessionId":"app","url":"<url>"}' # opens in the BACKGROUND-adom-bridge-cli -t AdomLapper nbrowser_screenshot  '{"sessionId":"app","toFile":true}' # → a laptop PNG path-adom-bridge-cli -t AdomLapper pull_file '{"filePaths":["<path>"],"saveTo":"/tmp"}'      # bring it into the container-adom-bridge-cli -t AdomLapper nbrowser_reload '{"sessionId":"app"}'+adom-bridge --target AdomLapper nbrowser_status                                         # confirm connected+adom-bridge --target AdomLapper nbrowser_open_window '{"sessionId":"app","url":"<url>"}' # opens in the BACKGROUND+adom-bridge --target AdomLapper nbrowser_screenshot  '{"sessionId":"app","toFile":true}' # → a laptop PNG path+adom-bridge --target AdomLapper pull_file '{"filePaths":["<path>"],"saveTo":"/tmp"}'      # bring it into the container+adom-bridge --target AdomLapper nbrowser_reload '{"sessionId":"app"}' ```-Rules that matter (full reference: the **driving-the-extension** skill):+Rules that matter (full reference: the **driving-the-extension** skill;+`adom-wiki pkg install adom/nb-bridge` ships it): - **One-time install — Adom Bridge installs it for you** (Step 1.5); it's not there by default. - **Never reuse a window the user is working in — always open a FRESH one**, and `nbrowser_close_window`   it when done. Yanking their live page is hostile.@@ -160,30 +162,30 @@ Rules that matter (full reference: the **driving-the-extension** skill): - Bonus: `nbrowser_login_state {url}` checks if you're signed in now; `nbrowser_fetch_url` grabs a file   behind a login using the real cookies — no clicking. -### D. Desktop app via an adom-bridge-cli bridge+### D. Desktop app via an Adom Bridge bridge If the "app" is a desktop program (KiCad, Fusion 360, …), reload the file through its bridge and screenshot the window: ```bash-adom-bridge-cli -t AdomLapper desktop_list_windows                                    # find the hwnd-adom-bridge-cli -t AdomLapper desktop_screenshot_window '{"hwnd":<hwnd>}'             # any native window-adom-bridge-cli -t AdomLapper kicad_screenshot_all '{}'                              # or fusion_screenshot_all+adom-bridge --target AdomLapper desktop_list_windows                                    # find the hwnd+adom-bridge --target AdomLapper desktop_screenshot_window '{"hwnd":<hwnd>}'             # any native window+adom-bridge --target AdomLapper kicad_screenshot_all '{}'                              # or fusion_screenshot_all ``` "Reload" = re-open / re-load the file in the app (e.g. `kicad_open_board` again after you edit it). `desktop_screenshot_window` captures the window **in the background** and returns an **array that includes child windows**, so a popped-up **error/dialog box is captured automatically** — exactly what a ralph loop needs to diagnose a failed reload. -## Step 1.5 — Installing the native browser extension (adom-bridge-cli installs it for you)+## Step 1.5 — Installing the native browser extension (Adom Bridge installs it for you) It isn't there by default, but **it largely self-installs — don't just hand the user manual steps.** Your container never talks to the extension directly; it drives **Adom Bridge (ab)** on the laptop and Adom Bridge does the setup. First-time flow (the extension page's `INSTALL-FLOW.md` walks every step): -1. **Get the skills + mechanics:** `adom-wiki skills install adom/adom-native-browser` — installs+1. **Get the skills + mechanics:** `adom-wiki pkg install adom/nb-bridge` (formerly adom/adom-native-browser) — installs    `driving-the-extension`, `native-browser-safety`, `driving-the-desktop`, the site recipes, etc. 2. **Adom Bridge installs the bridge** (one call) and registers the tiny **native-messaging host** on the laptop. 3. **The extension gets loaded into Chrome/Edge.** Chrome 137+ removed `--load-extension`, so this is a    one-time `chrome://extensions → Developer mode → Load unpacked`. **Adom Bridge can drive that OS-level flow for-   the user** — the **driving-the-desktop** skill owns the extension's whole install / uninstall / reload+   the user** — the **driving-the-desktop** skill (also in adom/nb-bridge) owns the extension's whole install / uninstall / reload    lifecycle with a proven, validated recipe. Production uses a Chrome Web Store force-install. 4. **Confirm:** `nbrowser_status` → connected, and the full `nbrowser_*` surface (navigate, screenshot,    reload, click, type, login_state, fetch_url…) is live.@@ -194,7 +196,7 @@ Adom-managed and Adom Bridge can't complete the OS step silently. ## Step 2 — Analyze → fix → reload - **Analyze:** read the screenshot. Compare against intent — what's broken, wrong, missing, or ugly. - **Fix:** edit the app's source / config / data file (or the desktop file).-- **Reload:** the matching reload for your surface — reload the Hydrogen webview, `browser_reload`,+- **Reload:** the matching reload for your surface — reload the Hydrogen webview, `pup_reload`,   `nbrowser_reload`, or re-open the desktop file. (Web apps with hot-reload refresh on save.)  ## Step 3 — shotlog: how you AND the user actually SEE every shot (do NOT skip)@@ -205,7 +207,7 @@ loop runs.** It is *not* mainly a phone thing — the phone is ~5% of why it mat  Two rules, every single iteration: 1. **Open a shotlog TAB in the topic's browser window — up front.** Add the channel's live gallery as a-   tab alongside your ralph-test tabs (`browser_open_tab {sessionId,url:"<shotlog gallery url>"}` /+   tab alongside your ralph-test tabs (`pup_open_tab {sessionId,url:"<shotlog gallery url>"}` /    `nbrowser_open_tab`) so every new shot appears right next to the app you're debugging. The AI    routinely forgets this — make it the **first** thing you do when a ralph test starts. 2. **Inject EVERY screenshot from EVERY surface.** Hydrogen, pup, native browser, desktop window — no@@ -226,7 +228,7 @@ Two rules, every single iteration: | App / situation | Load + screenshot | Reload | | --- | --- | --- | | User's own web app in their workspace | `adom-cli hydrogen screenshot workspace \| panel` | reload webview / hot-reload on save |-| Your web app or a public page (no login, allows automation) | pup: `browser_open_window` → `browser_screenshot` | `browser_reload` |+| Your web app or a public page (no login, allows automation) | pup: `pup_open_window` → `pup_screenshot` | `pup_reload` | | Site that blocks pup or needs login (DigiKey, vendor portals) | native: `nbrowser_open_window` → `nbrowser_screenshot` + `pull_file` | `nbrowser_reload` | | Desktop app (KiCad / Fusion / …) | `desktop_screenshot_window` / `kicad_screenshot_all` | re-open the file via its bridge |