diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/README.md hydrogen-windows-bootstrap/README.md --- hydrogen-windows-bootstrap.orig/README.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/README.md 2026-10-22 14:35:30.580179739 -0500 @@ -5,7 +5,7 @@ specific to that runtime on top of the platform-generic `adom/hydrogen-bootstrap`. ``` -adompkg install adom/hydrogen-windows-bootstrap # the golden WSL2 image installs this +adom-wiki pkg install adom/hydrogen-windows-bootstrap # the golden WSL2 image installs this ``` ## The platform-layered bootstrap stack diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/install.sh hydrogen-windows-bootstrap/install.sh --- hydrogen-windows-bootstrap.orig/install.sh 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/install.sh 2026-10-22 14:33:12.001767323 -0500 @@ -22,6 +22,13 @@ for stale in hd-adom-auth-windows hd-api-windows hd-browser-picker hd-captions-windows hd-container hd-container-stats hd-container-stats-windows hd-container-windows hd-desktop-sse-windows hd-eda-discovery-windows hd-file-transfer hd-golden-image hd-networking hd-notifications-windows hd-permissions-windows hd-port-watcher hd-ports hd-recording hd-runtime-mode hd-screen-lock hd-setup hd-setup-steps hd-setup-steps-windows hd-setup-windows hd-skill-catalog hd-skill-loop hd-topology hd-volume hd-workspace-lifecycle hd-workspace-monitoring hd-workspace-monitoring-windows; do [ -d "$HOME/.claude/skills/$stale" ] && rm -rf "$HOME/.claude/skills/$stale" && log " pruned retired skill $stale" done + # 0.3.30: hydrogen-skill-catalog was removed (superseded by hydrogen-overview in + # adom/hydrogen-bootstrap). Prune it from both Claude and Codex skill dirs. + for stale in hydrogen-skill-catalog; do + for base in "$HOME/.claude/skills" "$HOME/.codex/skills"; do + [ -d "$base/$stale" ] && rm -rf "$base/$stale" && log " pruned retired skill $base/$stale" + done + done log "deploying bundled Windows/WSL2 skills (hydrogen-* windows layer)" install -d -m 0755 "$HOME/.claude/skills" count=0 diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/package.json hydrogen-windows-bootstrap/package.json --- hydrogen-windows-bootstrap.orig/package.json 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/package.json 2026-10-22 14:42:55.936205830 -0500 @@ -4,7 +4,7 @@ "type": "bootstrap", "title": "Adom Hydrogen (Windows / WSL2)", "brief": "The Windows (WSL2) platform layer for Hydrogen.", - "version": "0.3.29", + "version": "0.3.31", "description": "The Windows platform layer for Hydrogen, where the workspace runs in a WSL2 Ubuntu distro. Depends on adom/hydrogen-bootstrap (the platform-generic layer, which bundles the generic hydrogen-* skills) and adds everything specific to the WSL2 runtime: the WSL2/networking/lifecycle hydrogen-* skills (BUNDLED here by design, John+Kyle 2026-07-16) and the WSL2 code-server workbench seed. Sibling adom/hydrogen-mac-bootstrap carries the parallel mac skills. This is the package the golden WSL2 image installs.", "org": "adom", "tags": [ @@ -19,7 +19,7 @@ }, "dependencies": { "adom/hydrogen-bootstrap": "^0.5.0", - "adom/adom-shotlog": "^0.28.0", + "adom/adom-shotlog": "^0.29.0", "adom/adom-bridge": "^2.0.0" }, "files": [ @@ -30,5 +30,6 @@ ], "hero": { "path": "docs/hero.png" - } + }, + "changelog": "0.3.31: Pup verbs renamed browser_* -> pup_* (the puppeteer bridge 2.0.733 exposes only pup_*), and the adom/adom-shotlog range widened to ^0.29.0 so updates stop skipping it. 0.3.30: skill cleanup: shorter valid descriptions, retired names replaced, dead skill links fixed, hydrogen-skill-catalog removed, maintainer skills hidden." } diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/page.json hydrogen-windows-bootstrap/page.json --- hydrogen-windows-bootstrap.orig/page.json 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/page.json 2026-10-22 14:42:55.936205830 -0500 @@ -4,7 +4,7 @@ "slug": "hydrogen-windows-bootstrap", "title": "Adom Hydrogen (Windows / WSL2)", "brief": "The Windows (WSL2) platform layer for Hydrogen.", - "version": "0.3.29", + "version": "0.3.31", "author": { "name": "John Lauer", "email": "john@adom.inc" @@ -28,7 +28,7 @@ }, "dependencies": { "adom/hydrogen-bootstrap": "^0.5.0", - "adom/adom-shotlog": "^0.28.0", + "adom/adom-shotlog": "^0.29.0", "adom/adom-bridge": "^2.0.0" }, "files": [ @@ -36,5 +36,6 @@ "install.sh", "README.md", "skills/**" - ] -} \ No newline at end of file + ], + "changelog": "0.3.31: Pup verbs renamed browser_* -> pup_* (the puppeteer bridge 2.0.733 exposes only pup_*), and the adom/adom-shotlog range widened to ^0.29.0 so updates stop skipping it. 0.3.30: skill cleanup: shorter valid descriptions, retired names replaced, dead skill links fixed, hydrogen-skill-catalog removed, maintainer skills hidden." +} diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-adom-auth-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-adom-auth-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-adom-auth-windows/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-adom-auth-windows/SKILL.md 2026-10-22 14:42:47.147850900 -0500 @@ -1,26 +1,22 @@ --- name: hydrogen-adom-auth-windows -description: > - Windows/WSL2-specific details for Adom auth in HD — the exact %APPDATA% - app-data path table for the session/replay/Claude credential files, and how - to read the injected Adom API key from outside the WSL2 Adom-Workspace distro. - READ alongside the generic [[hd-adom-auth]] skill when you need the concrete - Windows file locations or the WSL2 cat command. Trigger words — - %APPDATA%, hydrogen-session.txt, replay-session.txt, - replay-claude-credentials.json, wsl Adom-Workspace, api-key path, windows - auth files, where is the session token on windows. +description: >- + Windows companion to hydrogen-adom-auth: the %APPDATA% paths of Hydrogen's + session and Claude credential files, and how to read the injected Adom API key + from outside the distro. Use when asked where is the session token on windows + or for hydrogen-session.txt. --- -# Hydrogen Desktop -- Auth (Windows / WSL2 specifics) +# Hydrogen -- Auth (Windows / WSL2 specifics) -This is the Windows companion to the generic [[hd-adom-auth]] skill. Read that +This is the Windows companion to the generic `hydrogen-adom-auth` skill. Read that first for the auth-intent flow, profile menu, login UI, and control-API auth endpoints. This page only carries the Windows-specific file paths and the WSL2-specific way to read the injected API key. ## Host app-data file table -On Windows, HD's app-data directory is `%APPDATA%\hydrogen-desktop\`. The +On Windows, Hydrogen's app-data directory is `%APPDATA%\hydrogen-desktop\`. The auth-related files the generic skill refers to live there: | File | Path | Purpose | diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-adom-bridge-triage/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-adom-bridge-triage/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-adom-bridge-triage/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-adom-bridge-triage/SKILL.md 2026-10-22 14:42:47.147850900 -0500 @@ -1,21 +1,10 @@ --- name: hydrogen-adom-bridge-triage -description: > - Triage Adom Bridge (ab) when it will not connect from a Hydrogen workspace — - especially the case where ab CRASHES ON BOOT because a bad release shipped, - which looks identical to "not installed" / "not signed in" from the container - side. Teaches the cheapest-first diagnostic ladder (read ab's crash.log BEFORE - touching any config), the two out-of-band channels that work while ab is dead - (Hydrogen's control API and WSL2 interop), how to compare the installed build - against the wiki and install the fix, and the config changes you must NOT make - while guessing. Read this when `adom-bridge ping` says no desktop client is - connected, when the user says the app "never actually starts", when it starts - and vanishes, or when hydrogen-doctor's adom-bridge / adom-bridge-direct check - fails. Trigger words: adom bridge won't start, ab won't connect, bridge not - connected, no desktop client connected, ab never starts, ab starts then - disappears, bridge offline, ab crash loop, ab crashing on boot, bad ab release, - connectedClients 0, adom-bridge-direct failed, bridge keeps dying, ab tray - missing. +description: >- + Triage Adom Bridge (ab) when a Hydrogen workspace cannot reach it, including + ab crashing on boot after a bad release: crash.log first, out-of-band checks, + reinstall. Use when ab won't connect, no desktop client connected, ab never + starts, or the bridge keeps dying. --- Parent skill: **hydrogen-adom-bridge** (works with **hydrogen-doctor**, **hydrogen-key-values**, **adom-bridge**) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-ai-threads/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-ai-threads/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-ai-threads/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-ai-threads/SKILL.md 2026-10-22 14:42:47.151851044 -0500 @@ -1,16 +1,10 @@ --- name: hydrogen-ai-threads -description: > - The AI Threads panel in Adom Hydrogen — the live tree of every AI conversation - open in the editor (Claude, Codex, Kimi): which is in front, which are busy, - drag to reorder, rename, tag, and terminal (TUI) threads that run an AI's full - CLI in an editor tab. Covers what the panel shows, the BETA on-startup setting - (off by default; nothing AI-Threads runs while it is off), opening it once from - Add Panel, TUI threads via the toolbar carets, and how the panel relates to the - /ai-threads API (see hydrogen-ai-threads-api for driving it from code). Trigger - words: ai threads, ai threads panel, thread tree, my ai conversations, which ai - is running, reorder threads, rename a thread, tui thread, claude in a terminal, - codex tui, kimi tui, ai threads beta, enable ai threads, ai threads setting. +description: >- + The AI Threads panel in Hydrogen: the live tree of open AI conversations + (Claude, Codex, Kimi), reorder, rename, tag, TUI threads, and the beta + on-startup setting. Use when asked about ai threads, my ai conversations, + which ai is running, rename a thread, or a tui thread. --- # hydrogen-ai-threads — the AI Threads panel diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-ai-threads-api/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-ai-threads-api/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-ai-threads-api/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-ai-threads-api/SKILL.md 2026-10-22 14:42:47.151851044 -0500 @@ -1,15 +1,10 @@ --- name: hydrogen-ai-threads-api -description: > - How to open and drive AI conversations in Hydrogen from your own app, panel, or script: - open a new thread (letting the user's preferred AI decide), list what is open, put text - in a chat box, send a prompt and confirm it landed, reopen a past conversation, and close - a tab. Plain HTTP on Hydrogen's control API, no Tauri IPC and no special privileges. - Read this before shelling out to a CLI or driving the editor UI yourself. Trigger words - - open an AI thread, new claude thread, new codex thread, new kimi thread, ai threads api, - send a prompt to an AI, put text in the chat box, list open AI conversations, reopen a - conversation, close an AI tab, default AI, which AI should I use, dock opens a thread, - run-prompt job status, background send, where did my prompt go, ai picker toast. +description: >- + Open and drive AI conversations in Hydrogen from code over the control API: + open a thread, list open ones, put text in a chat box, send a prompt and + confirm it landed, reopen or close. Use when asked to open a new claude/codex + thread, send a prompt to an AI, or list open AI conversations. --- # Driving Hydrogen's AI threads from your own app diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-annotate/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-annotate/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-annotate/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-annotate/SKILL.md 2026-10-22 14:42:47.151851044 -0500 @@ -1,17 +1,11 @@ --- name: hydrogen-annotate version: 1.1.0 -description: > - Annotate in Hydrogen Desktop: the pencil in the Title Bar (left of the bell), or Win+Alt+A from - any app, lets the human draw on top of the whole screen, any app (KiCad, a browser, a jump list, - Hydrogen), with a red circle, an arrow, a box, a text note or a plain snip, and puts the - marked-up area on the clipboard as a PNG, ready to paste into an AI thread. Covers the tools, Auto versus Multi capture, the keys, what the AI can do (POST - /annotate opens the overlay for the human; the AI itself takes screenshots with - POST /screenshot, not with annotate), and how to read what the user pasted. Trigger words: - annotate, annotation, draw on the screen, red circle, circle it, mark it up, markup, - pencil icon, pencil in the title bar, snip, snip a region, paste a screenshot into the chat, - /annotate, annotate overlay, arrow on the screenshot, box on the screenshot, win+alt+a, - annotate shortcut, annotate hotkey setting, annotate the desktop, draw over kicad, desktop annotate. +description: >- + Hydrogen's Annotate tool: the Title Bar pencil or Win+Alt+A lets the user draw + on the whole screen (circle, arrow, box, note, snip) and puts a PNG on the + clipboard for the AI thread. Use when asked to annotate, circle it, mark up + the screen, snip a region, or about POST /annotate. --- # Annotate: draw on the screen, paste it into your AI thread diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-api/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-api/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-api/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-api/SKILL.md 2026-10-22 14:42:47.155851188 -0500 @@ -1,19 +1,10 @@ --- name: hydrogen-api -description: > - Complete reference for Hydrogen control API endpoints. The control - API runs on a dynamic port (find it in the Hydrogen log or via port discovery). Use - these endpoints to drive Hydrogen programmatically: manage the workspace (the WSL2 `Adom-Workspace` distro), control - Claude Code, manipulate VS Code, manage workspace tabs, run setup steps, trigger - virgin reset, and more. The COMPLETE, always-current catalog is - GET /_manifest (every route with a category + description; curated entries are - richer). The API Explorer window (Adom menu > API Explorer, or POST /api-explorer/open) - renders it with a runnable Try per endpoint. GET /test/help lists the gated /test/* - diagnostics. NEVER blind-call destructive endpoints (see the Safety section). - Trigger words: Hydrogen API, control API, Hydrogen endpoint, container exec, claude api, - iframe eval, workspace tabs, setup run-all, workspace status, reload vscode, - browser profiles, open url, virgin reset api, reboot api, diagnostics, - ad health, test window-tree, ai cursor, setup panel, screenshot mode. +description: >- + Reference for Hydrogen's control API (port in ~/.adom/hd-control-url): + workspace, Claude, VS Code, tabs, setup, diagnostics, and safety rules for + destructive routes; GET /_manifest is the live catalog. Use when asked for a + Hydrogen API endpoint or how to drive Hydrogen from code. --- # Hydrogen Control API Reference @@ -108,7 +99,7 @@ - **Never hardcode the port.** It's dynamic (47084 is only the default and it auto-resolves conflicts). Read `~/.adom/hydrogen-control-url` from the workspace, or `GET /ports`. Hardcoding 47084 is what makes tools show Hydrogen as "down" when it's actually up on another port. -- **Calling from a REMOTE container (hw/cloud)? Use `adom-bridge hd_api`,** the relay's +- **Calling from a REMOTE container (hc/cloud)? Use `adom-bridge hd_api`,** the relay's pass-through verb: `hd_api {"method":"POST","path":"/...","body":{...}}`. It auto-discovers the port; never shell curl through the relay (quoting gets mangled). Long-blocking calls (typed injection) can outlive the relay timeout: the work still completes on Hydrogen's side, so diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-api-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-api-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-api-windows/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-api-windows/SKILL.md 2026-10-22 14:42:47.151851044 -0500 @@ -1,21 +1,15 @@ --- name: hydrogen-api-windows -description: > - Windows/WSL2-specific Hydrogen Desktop control-API surface — the /wsl/* - runtime endpoints, the legacy /docker/* (HD_RUNTIME=docker) endpoints, - /volume-delete, /system/* host-reboot ("Reboot Windows"), the - /test/probe-dialogs UAC/MSI/Docker-EULA blocker catalog, WebView2 CDP/DevTools - notes, host-side port discovery (HD log + %APPDATA%\hydrogen-desktop\ports.json), - and the WSL2 mirrored-networking loopback note. READ alongside the generic - [[hd-api]] skill on a Windows host. Trigger words — wsl status, docker status, - reboot windows, system reboot, probe-dialogs, UAC dialog, MSI installer, - Docker EULA, mirrored networking, ports.json, volume-delete, WebView2, - terminal-profile, virgin-reset-progress. +description: >- + Windows companion to hydrogen-api: the /wsl/* and legacy /docker/* endpoints, + /system reboot, /test/probe-dialogs, WebView2 CDP notes, and host-side port + discovery (ports.json). Use when asked about wsl status, reboot windows, + probe-dialogs, or ports.json. --- -# HD Control API — Windows / WSL2 specifics +# Hydrogen Control API — Windows / WSL2 specifics -This is the Windows companion to the generic [[hd-api]] skill. Read that first +This is the Windows companion to the generic `hydrogen-api` skill. Read that first for the platform-neutral endpoint groups (health, claude, setup, tabs, eval, ui). This page carries the runtime-specific and host-specific endpoints that were stripped out of the generic version. @@ -26,8 +20,8 @@ find the dynamic control port from the Windows host: ```bash -# From HD log -adom-desktop hd_log '{"tail":100}' | grep "control=" +# From Hydrogen log +adom-bridge hd_log '{"tail":100}' | grep "control=" # From ports.json type %APPDATA%\hydrogen-desktop\ports.json @@ -40,7 +34,7 @@ ## WSL runtime endpoints (default runtime) -When HD runs the workspace as a WSL2 distro, it additionally exposes: +When Hydrogen runs the workspace as a WSL2 distro, it additionally exposes: | Method | Path | Body | Description | |---|---|---|---| @@ -58,7 +52,7 @@ ## Docker Desktop (legacy Docker runtime only — `HD_RUNTIME=docker`) -This `/docker/*` table applies only when HD is running the legacy Docker runtime. +This `/docker/*` table applies only when Hydrogen is running the legacy Docker runtime. | Method | Path | Body | Description | |---|---|---|---| @@ -92,7 +86,7 @@ ## WebView & VS Code (Windows specifics) -HD's webview is **WebView2** on Windows; `/cdp-eval`, `/cdp-info`, and +Hydrogen's webview is **WebView2** on Windows; `/cdp-eval`, `/cdp-info`, and `/devtools` target the WebView2 DevTools (Chrome DevTools Protocol) endpoint. ## Diagnostics — dialog blocker catalog diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-bridges/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-bridges/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-bridges/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-bridges/SKILL.md 2026-10-22 14:42:47.155851188 -0500 @@ -1,15 +1,10 @@ --- name: hydrogen-bridges -description: > - Complete reference for the Hydrogen bridge ecosystem: the built-in KiCad, Fusion 360, - and Puppeteer bridges, plus the extensible wiki bridge catalog (e.g. Blender) - and the full set of Adom Bridge capabilities. How they connect through adom-bridge, the Bridge Manager - dialog, bridge status polling, and all bridge CLI commands. Use when the AI - needs to take screenshots, control KiCad/Fusion/browser, transfer files, - interact with the user's desktop, or check bridge status. Trigger words -- - screenshot, desktop screenshot, list windows, capture screen, kicad, fusion, - browser, puppeteer, pup, send file, pull file, notify, desktop, bridge, - bridge manager, bridge status, bridge install. +description: >- + Hydrogen's bridges: the built-in KiCad, Fusion 360 and Puppeteer bridges, the + wiki bridge catalog, the Bridge Manager dialog, bridge status, and the Adom + Bridge capabilities beneath them. Use when asked about bridges, bridge + manager, bridge status, or install a bridge. --- # Hydrogen -- Bridge Ecosystem @@ -52,9 +47,9 @@ |---|---|---| | `kicad` / `fusion360` / `browser` | the three built-in app bridges | this skill | | `screenshot` / `record` / `caption` | OS screenshots, screen/tab recording, recording captions | this skill (screenshots/recording); `caption` is recording-caption support | -| `files` | send_files / pull_file | **hydrogen-file-transfer**, **hydrogen-adom-desktop** | +| `files` | send_files / pull_file | **hydrogen-file-transfer**, **hydrogen-adom-bridge** | | `notify` | desktop toast notifications | this skill | -| `shell` | run a command on the user's PC (approval-gated) | **hydrogen-adom-desktop** | +| `shell` | run a command on the user's PC (approval-gated) | **hydrogen-adom-bridge** | | `usb` | USB passthrough to the workspace (e.g. workcell hardware over USBIP) | not yet covered — query `adom-bridge status`; future skill | > `.desktop.apps` also reports, per app: `bridgeRunning`, `installed`, `running`, @@ -194,23 +189,23 @@ ```bash # Open browser window -adom-bridge browser_open_window '{"url": "https://example.com"}' +adom-bridge pup_open_window '{"url": "https://example.com"}' # Screenshot current tab -adom-bridge browser_screenshot '{"sessionId": "default"}' +adom-bridge pup_screenshot '{"sessionId": "default"}' # Evaluate JavaScript -adom-bridge browser_eval '{"js": "document.title", "sessionId": "default"}' +adom-bridge pup_eval '{"js": "document.title", "sessionId": "default"}' # Navigate -adom-bridge browser_navigate '{"url": "https://...", "sessionId": "default"}' +adom-bridge pup_navigate '{"url": "https://...", "sessionId": "default"}' # List open windows/tabs -adom-bridge browser_list_windows +adom-bridge pup_list_windows # Record tab (CDP screencast, zero dialogs) -adom-bridge browser_record_start '{"sessionId": "default"}' -adom-bridge browser_record_stop '{"sessionId": "default"}' +adom-bridge pup_record_start '{"sessionId": "default"}' +adom-bridge pup_record_stop '{"sessionId": "default"}' ``` --- @@ -337,7 +332,7 @@ > **Tab-vs-desktop footgun.** `desktop_record_start` records the **whole screen** > and requires an explicit `confirmDesktopNotTabRecording:true` guard so you don't > accidentally capture the entire desktop when you meant one tab. To record a -> single Chrome tab, use `browser_record_start` instead (CDP screencast, served by +> single Chrome tab, use `pup_record_start` instead (CDP screencast, served by > the Puppeteer bridge, no whole-screen capture). ```bash @@ -346,8 +341,8 @@ adom-bridge desktop_record_stop # Record a single browser tab (CDP screencast, zero dialogs) — prefer this for one tab -adom-bridge browser_record_start '{"sessionId": "default"}' -adom-bridge browser_record_stop '{"sessionId": "default"}' +adom-bridge pup_record_start '{"sessionId": "default"}' +adom-bridge pup_record_stop '{"sessionId": "default"}' ``` --- diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-browser-picker/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-browser-picker/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-browser-picker/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-browser-picker/SKILL.md 2026-10-22 14:42:47.155851188 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-browser-picker -description: Hydrogen's Browser Picker — the canonical handler for EVERY URL that gets opened inside Hydrogen. Click a link anywhere (main page, code-server iframe, webview panel, PortMappingsDialog, OAuth redirect, localhost link, external link) and Hydrogen intercepts it via 5 layers (on_new_window / on_navigation / NewWindowRequested / AddScriptToExecuteOnDocumentCreated / ContextMenuRequested) and routes it through the BrowserProfileDialog so the user (or an AI driving automation) picks where it opens — native browser profile, Hydrogen tab, Hydrogen window, or Pup. 5-second auto-countdown so AIs don't block waiting on a click. Read BEFORE adding a URL-opening feature, debugging dead links, fixing `shell.open not allowed`, or automating browser interactions from Hydrogen. Trigger words — browser picker, BrowserProfileDialog, hydrogen-open-url, hydrogen-open-url-force, open with browser picker, shell.open not allowed, shell:default, shell:allow-open, plugin-shell, url interception, link click, target blank, claude auth url, adom auth url, oauth callback in browser, default browser, browser profile, AI browser automation, countdown picker, auto-timer, shift click force, right-click open with, context menu, webview links, on_new_window, hydrogen-links (legacy name). +description: >- + Hydrogen's Browser Picker: how every URL opened in Hydrogen is intercepted and + routed through the chooser (native profile, Hydrogen tab or window, Pup) with + an auto-countdown. Use when a link won't open, for shell.open not allowed, + oauth links, or adding a URL-opening feature. --- # Hydrogen — Browser Picker (URL Interception) @@ -440,8 +444,8 @@ adom-bridge shell_execute '{"command":"CTRL=\"$(cat ~/.adom/hydrogen-control-url)\"; curl -s -X POST -d {\"url\":\"https://example.com\"} \"$CTRL/open-url\""}' # 3. Within 5s, picker auto-routes to Pup (or saved pref) -# 4. Drive Pup with adom-bridge browser_* verbs -adom-bridge browser_eval '{"sessionId":"default","js":"document.title"}' +# 4. Drive Pup with adom-bridge pup_* verbs +adom-bridge pup_eval '{"sessionId":"default","js":"document.title"}' # Force a picker dialog (no auto-timer) adom-bridge shell_execute '{"command":"CTRL=\"$(cat ~/.adom/hydrogen-control-url)\"; curl -s -X POST -d {\"url\":\"https://example.com\",\"force\":true} \"$CTRL/open-url\""}' @@ -476,4 +480,4 @@ ## How Hydrogen skills get deployed (workflow note) -Hydrogen public skills (this one, hydrogen-open-url, hydrogen-monitor, etc.) live in the Hydrogen repo under `skills/public-facing/{shared,wsl2}//SKILL.md`. They're BUNDLED into the Hydrogen bootstraps (adom/hydrogen-bootstrap ships `shared/`, adom/hydrogen-windows-bootstrap ships `wsl2/`) and deployed flat into `~/.claude/skills//` at install/bake time. See `hydrogen-skill-catalog` (public) and `hydrogen-skills-structure` (dev-internal) for the full layout. +Hydrogen public skills (this one, hydrogen-open-url, hydrogen-monitor, etc.) ship in the Hydrogen bootstrap wiki packages (adom/hydrogen-bootstrap for the platform-generic ones, adom/hydrogen-windows-bootstrap for the Windows/WSL2 layer) and are deployed flat into `~/.claude/skills//` on install and on every `adom-wiki pkg update`. Their text is authored in the ah repo under `skills/public-facing/{shared,wsl2}//SKILL.md`; a fix made directly on the wiki must be back-ported there. See `hydrogen-overview` for the index of Hydrogen skills. diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-captions/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-captions/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-captions/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-captions/SKILL.md 2026-10-22 14:42:47.159851330 -0500 @@ -1,21 +1,10 @@ --- name: hydrogen-captions -description: > - Paint labeled caption text on the Hydrogen workspace for demos/walkthroughs — - captions are CAPTURED BY RECORDINGS so they show up in the finished video. Drive the - WORKSPACE caption with `adom-cli hydrogen caption` — THE default, identical on - web-Hydrogen AND Hydrogen (text positional; `-d` duration in SECONDS not ms; 30s auto-expire - by default, 5-min hard cap, newest-wins, `hide` to clear; a raw-HTTP - `POST .../current/caption` fallback exists for scripts hitting Hydrogen's API directly). - Distinct from toasts (notifications) and TTS (audio). NOTE: a full-DESKTOP overlay - (over every window, on top of other apps) exists as a platform-specific companion — - see [[hydrogen-captions-windows]] / [[hydrogen-captions-mac]]. Trigger words — caption, on-screen caption, workspace - caption, hydrogen caption, screen overlay, screen label, callout, annotate the screen, - step label, put text on screen, overlay text, caption command, adom-cli hydrogen - caption, walkthrough label, demo callout, status overlay, label the screen, hide - caption, clear captions, step 3 callout, caption duration, caption seconds, caption - auto-expire, caption stuck on screen, caption units, caption position, caption size, - persist caption. +description: >- + Paint caption text on the Hydrogen workspace with `adom-cli hydrogen caption` + (seconds, auto-expire, captured by recordings) for demos and walkthroughs. Use + when asked to put text on screen, add a caption or callout, label a demo step, + or clear a stuck caption. --- # Hydrogen — On-Screen Captions @@ -130,6 +119,6 @@ only the desktop overlay provides; see the platform companion. ## Related skills -- [hydrogen-adom-desktop](../hydrogen-adom-desktop/SKILL.md) — the relay that carries caption verbs to the host +- [hydrogen-adom-bridge](../hydrogen-adom-bridge/SKILL.md) — the relay that carries caption verbs to the host - `adom-tts` — *audio* narration to pair with on-screen captions (captions are visual-only) - [[hydrogen-captions-windows]] / [[hydrogen-captions-mac]] — the full-desktop always-on-top overlay caption surface diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-captions-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-captions-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-captions-windows/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-captions-windows/SKILL.md 2026-10-22 14:42:47.159851330 -0500 @@ -1,29 +1,22 @@ --- name: hydrogen-captions-windows -description: > - Windows-specific companion to [[hd-captions]]. The full-DESKTOP overlay caption on - Windows — `adom-desktop desktop_caption` — HD's built-in Win32 always-on-top, - click-through overlay that floats over ALL windows (above KiCad, Fusion, a browser, the - whole screen) and is captured by a full-screen/desktop recording. Covers the - desktop-overlay args (text, id, position top/center/bottom/corners, normalized x/y, - size/fontSize, duration in MILLISECONDS, action: hide|force-clear) and the id rule (same - id replaces, different ids coexist). For the cross-platform WORKSPACE caption - (`adom-cli hydrogen caption`, SECONDS units), see [[hd-captions]]. Windows-only. - Trigger words — desktop caption, desktop_caption, screen overlay, always on top text, - click-through overlay, corner caption, caption id, caption position corners, caption x y, - force-clear captions, full-screen caption, caption over other apps, win32 caption overlay. +description: >- + Windows companion to hydrogen-captions: the full-desktop overlay caption + (`adom-bridge desktop_caption`, milliseconds) over every app, with ids, + positions and force-clear. Use for a desktop caption or a caption over other + apps. --- -# Hydrogen Desktop — Desktop Overlay Caption (Windows) +# Hydrogen — Desktop Overlay Caption (Windows) -Windows-specific companion to **[[hd-captions]]**. The generic skill covers the +Windows-specific companion to **`hydrogen-captions`**. The generic skill covers the cross-platform **workspace** caption (`adom-cli hydrogen caption`, SECONDS units, rendered -inside the HD webview). This page covers the **full-desktop overlay** caption, which is +inside the Hydrogen webview). This page covers the **full-desktop overlay** caption, which is Windows-only. -## Desktop overlay caption — `adom-desktop desktop_caption` +## Desktop overlay caption — `adom-bridge desktop_caption` -HD's built-in **Win32 always-on-top, click-through overlay** — floats over every window, +Hydrogen's built-in **Win32 always-on-top, click-through overlay** — floats over every window, doesn't steal focus or intercept clicks (the user works "through" it). The full-featured surface (ids, corners, x/y, force-clear). It's captured by a **full-screen / desktop** recording (it's real screen pixels), but NOT by a workspace/panel webview capture (it's a @@ -31,12 +24,12 @@ ## Firing a caption -Source: `src-tauri/crates/hd-app/src/caption.rs` (`handle_caption`). The AD CLI verb is -**`desktop_caption`** (the internal message type is `caption`; `adom-desktop status` lists -the `caption` capability). Plain `adom-desktop caption` is NOT a verb — it errors. +Source: `src-tauri/crates/hd-app/src/caption.rs` (`handle_caption`). The `adom-bridge` CLI verb is +**`desktop_caption`** (the internal message type is `caption`; `adom-bridge status` lists +the `caption` capability). Plain `adom-bridge caption` is NOT a verb — it errors. ```bash -adom-desktop desktop_caption '{"text":"Step 3: approve the UAC dialog →","position":"center","size":"large","duration":6000}' +adom-bridge desktop_caption '{"text":"Step 3: approve the UAC dialog →","position":"center","size":"large","duration":6000}' ``` ### Arguments @@ -49,7 +42,7 @@ | `x` / `y` | float | **Normalized 0.0–1.0** screen coordinates (clamped). Use for precise placement instead of a named `position`. | | `size` | string | `large` / `medium` (default) / `small`. | | `fontSize` | int | Explicit pixel font height (also accepts `font_size`). Overrides `size`. | -| `duration` | int | **Milliseconds** on screen (default 4000), then a short fade-out. ⚠️ **NOTE: this surface is ms — the OPPOSITE of the workspace caption in [[hd-captions]], whose `-d` is SECONDS.** `4000` here = 4s; `4000` there = 66 min. | +| `duration` | int | **Milliseconds** on screen (default 30000: captions auto-expire; up to 10 min, or `persist:true` plus an explicit hide), then a short fade-out. ⚠️ **NOTE: this surface is ms — the OPPOSITE of the workspace caption in `hydrogen-captions`, whose `-d` is SECONDS.** `4000` here = 4s; `4000` there = 66 min. | | `action` | string | `hide` (dismiss this id, or all if id empty) or `force-clear` (destroy **all** captions regardless of id). | ### The id rule (this is the powerful part) @@ -60,17 +53,17 @@ ```bash # persistent status in the corner -adom-desktop desktop_caption '{"id":"status","text":"Recording…","position":"top-right","size":"small","duration":60000}' +adom-bridge desktop_caption '{"id":"status","text":"Recording…","position":"top-right","size":"small","duration":60000}' # step callouts in the center, each replacing the last (same id) -adom-desktop desktop_caption '{"id":"step","text":"Step 1: open the board","position":"center","duration":4000}' -adom-desktop desktop_caption '{"id":"step","text":"Step 2: run DRC","position":"center","duration":4000}' +adom-bridge desktop_caption '{"id":"step","text":"Step 1: open the board","position":"center","duration":4000}' +adom-bridge desktop_caption '{"id":"step","text":"Step 2: run DRC","position":"center","duration":4000}' # clear just the step callout -adom-desktop desktop_caption '{"id":"step","action":"hide"}' +adom-bridge desktop_caption '{"id":"step","action":"hide"}' # nuke everything -adom-desktop desktop_caption '{"action":"force-clear"}' +adom-bridge desktop_caption '{"action":"force-clear"}' ``` ## Patterns @@ -86,7 +79,7 @@ the screen of all captions at the end of a tour. ## Related skills -- [[hd-captions]] — the cross-platform workspace caption (`adom-cli hydrogen caption`, SECONDS units) -- [hd-recording](../hd-recording/SKILL.md) — captions are captured *into* screen recordings -- [hd-adom-desktop](../../hd-bootstrap/skills/hd-adom-desktop/SKILL.md) — AD carries the `caption` / `desktop_caption` verb to the host; verify the `caption` capability via `adom-desktop status` +- `hydrogen-captions` — the cross-platform workspace caption (`adom-cli hydrogen caption`, SECONDS units) +- [hydrogen-recording](../hydrogen-recording/SKILL.md) — captions are captured *into* screen recordings +- [hydrogen-adom-bridge](../hydrogen-adom-bridge/SKILL.md) — ab carries the `caption` / `desktop_caption` verb to the host; verify the `caption` capability via `adom-bridge status` - `adom-tts` — *audio* narration to pair with on-screen captions (captions are visual-only) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-container/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-container/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-container/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-container/SKILL.md 2026-10-22 14:42:47.163851478 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-container -description: Context for Claude Code running inside a Hydrogen workspace. Documents the exact OS (Ubuntu 24.04, code-server, the local workspace), explains how setup differs from Adom cloud containers (Hydrogen setup-steps NOT bootstrap.sh), what bridges are available, and how to use the relay. Trigger on startup, adom-cli errors, bridge commands, screenshot requests, container-platform questions, code-server / VS Code extension issues, or when the AI needs concrete facts about its environment instead of guessing. +description: >- + Facts about the Hydrogen workspace Claude runs in: Ubuntu 24.04, code-server, + the golden image, setup steps instead of bootstrap.sh, available bridges and + the relay. Use when asked what environment am I in, on adom-cli errors, + code-server or extension issues, or bridge and relay questions. --- # Hydrogen Workspace @@ -31,7 +35,7 @@ Hydrogen provisions this workspace through its own **setup-steps** flow, shown as the "Install Tools" panel in the Hydrogen UI. It is a **different code path** than cloud containers, which are provisioned by the Adom platform's own container bootstrap. -Most tooling is NOT installed by a step — it's BAKED into the golden image at image-build time (the Adom CLIs and skills from the wiki registry package adom/hydrogen-windows-bootstrap, the claude CLI + Code extension, code-server, VS Code settings, and all `hd-*` skills). The provisioning step imports the golden image if the workspace isn't already registered, and the relay is started by the `start-relay` step. See `[[hydrogen-setup-steps]]`. +Most tooling is NOT installed by a step — it's BAKED into the golden image at image-build time (the Adom CLIs and skills from the wiki registry package adom/hydrogen-windows-bootstrap, the claude CLI + Code extension, code-server, VS Code settings, and all `hydrogen-*` skills). The provisioning step imports the golden image if the workspace isn't already registered, and the relay is started by the `start-relay` step. See `[[hydrogen-setup-steps]]`. When debugging install issues here, the source of truth is Hydrogen's setup-steps code — its step IDs (`wait-codeserver`, `update-packages`, `activate-editor`, `set-env-vars`, `inject-api-key`, `configure-vscode`, `ensure-adom-bridge-cli`, `install-brand-fonts`, `start-relay`, `test-direct-connect`, `test-relay`, `test-adom-cli`, `install-claude-cli`, `claude-auth`, `ensure-sse`, `verify-workspace`, `welcome`, `verify-setup`, `open-welcome`) map 1:1 to what ran on this workspace. There is no `install-the Adom CLIs`, `install-claude-ext` or `write-vscode-settings` step: that work is baked into the image or done by `update-packages` and `configure-vscode`. There is no bootstrap.sh to chase bugs into. @@ -71,10 +75,10 @@ ### Browser automation (Puppeteer) ```bash -adom-bridge browser_open_window '{"url": "https://..."}' -adom-bridge browser_screenshot '{"sessionId": "default"}' -adom-bridge browser_eval '{"js": "document.title"}' -adom-bridge browser_navigate '{"url": "..."}' +adom-bridge pup_open_window '{"url": "https://..."}' +adom-bridge pup_screenshot '{"sessionId": "default"}' +adom-bridge pup_eval '{"js": "document.title"}' +adom-bridge pup_navigate '{"url": "..."}' ``` ### KiCad bridge diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-container-stats/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-container-stats/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-container-stats/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-container-stats/SKILL.md 2026-10-22 14:42:47.159851330 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-container-stats -description: Hydrogen's workspace stats indicator in the top-right of the title bar — two thin progress bars (CPU + RAM) labelled "Container" plus an info tooltip on hover that shows the workspace name, CPU vs total cores, RAM usage vs limit, disk usage, image, ID, and creation date. Polls once per second when running, every 5 seconds when stopped. Status badges show stopped / starting / restarting / restart-needed states. Use this skill when the user asks about CPU/RAM usage, the resource bars in Hydrogen's title bar, workspace disk usage, the "restart needed" badge, why bars are red/yellow, or what's in the tooltip. Trigger words — container stats, workspace stats, container cpu, container ram, container disk, resource bars, cpu bar, ram bar, container tooltip, container indicator, top bar stats, restart needed badge, container stopped badge, container starting, workspace_stats, workspace stats. +description: >- + Hydrogen's title-bar workspace stats indicator: the CPU and RAM bars, their + tooltip (cores, RAM, disk, image), polling, and the + stopped/starting/restart-needed badges. Use when asked about container stats, + the resource bars, workspace disk usage, or the restart needed badge. --- # Hydrogen Workspace Stats Indicator diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-container-stats-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-container-stats-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-container-stats-windows/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-container-stats-windows/SKILL.md 2026-10-22 14:42:47.159851330 -0500 @@ -1,11 +1,15 @@ --- name: hydrogen-container-stats-windows -description: Windows/WSL2-specific mechanism behind HD's title-bar CPU/RAM "Container" indicator — the `workspace_stats()` WSL health/stat probe of the `Adom-Workspace` distro, `wsl --terminate` as the "restart workspace" action, the benign `[docker] unhealthy` log line under WSL, the `[wsl]` real health signal, and WSL distro disk semantics. Companion to [[hd-container-stats]]. Trigger on workspace_stats WSL probe, wsl --terminate, [docker] unhealthy log, [wsl] unhealthy, WslDistroRuntime get_stats, distro disk, restart needed after Windows wake. +description: >- + Windows companion to hydrogen-container-stats: the WSL probe behind the + CPU/RAM indicator, `wsl --terminate` as restart, and why the `[docker] + unhealthy` log line is benign under WSL. Use for workspace_stats WSL probe or + restart needed after wake. --- -# HD Workspace Stats Indicator — Windows / WSL2 specifics +# Hydrogen Workspace Stats Indicator — Windows / WSL2 specifics -Companion to **[[hd-container-stats]]**. The bars, thresholds, polling cadence, tooltip fields, badges, CSS selectors, and control-API shape are all in the generic skill. This skill covers how the stats are actually gathered on Windows. +Companion to **`hydrogen-container-stats`**. The bars, thresholds, polling cadence, tooltip fields, badges, CSS selectors, and control-API shape are all in the generic skill. This skill covers how the stats are actually gathered on Windows. ## The backend probe @@ -25,7 +29,7 @@ ## The benign `[docker] unhealthy` log line -You will sometimes see this in HD's log even on the WSL2 path: +You will sometimes see this in Hydrogen's log even on the WSL2 path: ``` [docker] Container runtime unhealthy — exec failed, needs restart @@ -51,6 +55,6 @@ ## Related skills -- `[[hd-container-stats]]` — the platform-generic indicator this companion extends -- `[[hd-workspace-monitoring-windows]]` — distro + code-server health monitoring -- `[[hd-networking]]` — port 7380 code-server, host reachability +- `hydrogen-container-stats` — the platform-generic indicator this companion extends +- `hydrogen-workspace-monitoring-windows` — distro + code-server health monitoring +- `hydrogen-networking` — port 7380 code-server, host reachability diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-container-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-container-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-container-windows/SKILL.md 2026-10-22 14:26:53.456214680 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-container-windows/SKILL.md 2026-10-22 14:42:47.163851478 -0500 @@ -1,11 +1,15 @@ --- name: hydrogen-container-windows -description: Windows/WSL2-specific spine for the HD workspace — the `Adom-Workspace` WSL2 distro, how it's imported (`wsl --import` of the golden image), the distro user/exec model, code-server port 7380 auto-forward to Windows localhost, the Rust runtime source, and the Cloud-vs-WSL2 comparison table. Companion to [[hd-container]]. Trigger on Windows host, WSL2, Adom-Workspace distro, wsl --import, wsl exec, distro user, code-server 7380 forward, mirrored networking, golden image distro. +description: >- + Windows companion to hydrogen-container: the Adom-Workspace WSL2 distro, its + `wsl --import` from the golden image, the distro user and exec model, and + code-server 7380 forwarding. Use for Adom-Workspace distro, wsl exec, or + distro user questions. --- -# Hydrogen Desktop Workspace — Windows / WSL2 specifics +# Hydrogen Workspace — Windows / WSL2 specifics -Companion to **[[hd-container]]**. On Windows, HD hosts the workspace as a **WSL2 Ubuntu distro named `Adom-Workspace`**. Everything in the generic skill (Ubuntu 24.04, code-server, the relay, bridges, env vars, the "setup-steps not bootstrap.sh" rule) applies; this skill adds the WSL2-specific facts. +Companion to **`hydrogen-container`**. On Windows, Hydrogen hosts the workspace as a **WSL2 Ubuntu distro named `Adom-Workspace`**. Everything in the generic skill (Ubuntu 24.04, code-server, the relay, bridges, env vars, the "setup-steps not bootstrap.sh" rule) applies; this skill adds the WSL2-specific facts. ## The distro — exact facts (don't guess) @@ -21,7 +25,7 @@ ## How it's provisioned (vs the legacy Docker path) -HD provisions the distro through `setup_steps_wsl.rs` (runtime mechanics in `runtime/wsl.rs`). The WSL cascade is **16 steps** (state file `setup-steps-wsl.json`) vs the legacy Docker flow's 24. +Hydrogen provisions the distro through `setup_steps_wsl.rs` (runtime mechanics in `runtime/wsl.rs`). The WSL cascade is **16 steps** (state file `setup-steps-wsl.json`) vs the legacy Docker flow's 24. The Docker `pull-image` / `create-container` / `start-container` steps are collapsed into a single step 1, `ensure-workspace`, which runs `wsl --import` of `adom-golden.tar.gz` if the distro isn't already registered. (For the legacy Docker `setup_steps.rs` flow see the docker bucket.) @@ -45,7 +49,7 @@ ## What's different from Adom cloud containers (WSL2 detail) -| Feature | Adom Cloud | HD Local (WSL2) | +| Feature | Adom Cloud | Hydrogen local (WSL2) | |---------|-----------|-----------------| | Workspace provisioning | Adom platform API | `wsl --import` of `adom-golden.tar.gz` on the user's machine | | Relay connection | wss:// through Cloudflare | ws://localhost:8765 (direct, no TLS) | @@ -56,9 +60,9 @@ ## Golden-image specifics -The distro is imported from a full pre-baked image, then the update-packages step installs the Adom CLIs and skills from the wiki registry (adom/hydrogen-windows-bootstrap); the image itself carries the claude CLI + Code extension, code-server (pinned), VS Code settings, and all `hd-*` skills are baked in at image-build time, NOT installed by setup steps. +The distro is imported from a full pre-baked image, then the update-packages step installs the Adom CLIs and skills from the wiki registry (adom/hydrogen-windows-bootstrap); the image itself carries the claude CLI + Code extension, code-server (pinned), VS Code settings, and all `hydrogen-*` skills are baked in at image-build time, NOT installed by setup steps. ## Related skills -- `[[hd-container]]` — the platform-generic workspace context this companion extends -- `[[hd-container-stats-windows]]` — the WSL probe behind the title-bar CPU/RAM indicator +- `hydrogen-container` — the platform-generic workspace context this companion extends +- `hydrogen-container-stats-windows` — the WSL probe behind the title-bar CPU/RAM indicator diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-demo-recording/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-demo-recording/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-demo-recording/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-demo-recording/SKILL.md 2026-10-22 14:42:47.163851478 -0500 @@ -1,19 +1,13 @@ --- name: hydrogen-demo-recording -description: > - THE recipe for recording a demo video of Hydrogen: screen-record an AI prompt - being TYPED (visible human-jitter typing) into a Claude tab plus the AI's resulting - output, then speed the footage 10x to 30x in video-post and lay an adom-tts voiceover - on top, so a viewer sees exactly what using an app in Hydrogen feels like. Covers the whole - pipeline end to end: driving Hydrogen's control API (in-workspace OR from a remote container - via adom-bridge hd_api), the high-fps native recorder, multi-tab multi-prompt demos, - getting the mp4 out (streamed binary, never base64), and the post-production handoff. - Trigger words: demo video, record a demo, ah demo, demo recording, record the typing, - screen record ah, record ai prompt, app demo, demo pipeline, speedup demo, tts overlay - demo, show what the app feels like, hydrogen-demo-recording. +description: >- + Recipe for recording a Hydrogen demo video: human-typed prompt into a Claude + tab, the native recorder, getting the mp4 out, then 10-30x speedup and an + adom-tts voiceover. Use when asked to record a demo, make a demo video of an + app, or show what the app feels like. --- -# hydrogen-demo-recording: record an Hydrogen demo video, end to end +# hydrogen-demo-recording: record a Hydrogen demo video, end to end The canonical Adom demo: the viewer watches an AI prompt get TYPED into Hydrogen Desktop, watches the AI do the work, and hears a narrator explain it, all in a tight @@ -26,7 +20,7 @@ 2. Type the prompt into a Claude tab with VISIBLE typing (the sexy part) and submit. 3. Let the AI's output stream on camera. 4. Stop the recorder, collect the mp4. -5. Post-production: speed up 10x to 30x (video-post), overlay adom-tts narration. +5. Post-production: speed up 10x to 30x (adom-video-post), overlay adom-tts narration. ## Step 0: pick your calling transport @@ -40,7 +34,7 @@ curl -s -X POST "$CTRL/claude/inject" -H 'Content-Type: application/json' -d '{...}' ``` -**From a remote container** (hw, cloud): go through the adom-bridge relay's +**From a remote container** (hc, cloud): go through the adom-bridge relay's pass-through verb. Never curl through the relay (quoting gets mangled) and never hunt for the port (hd_api auto-discovers it): @@ -136,7 +130,7 @@ ## Step 5: post-production -- **Speedup**: the `video-post` skill owns this. The house style is 10x for demos +- **Speedup**: the `adom-video-post` skill owns this. The house style is 10x for demos where the output matters, 30x for long AI work sessions. Keep the typing segment readable (video-post can ramp: normal speed on the typing, fast on the waiting). - **Narration**: synthesize with `adom-tts say` (it pronounces Adom terms correctly @@ -173,4 +167,4 @@ ## Related [[hydrogen-api]] (transport + safety tiers), [[hydrogen-recording]] (recorder endpoint reference), -demo-recording (choreography), video-post (speedup + publish), adom-tts (narration). +demo-recording (choreography), adom-video-post (speedup + publish), adom-tts (narration). diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-desktop-sse/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-desktop-sse/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-desktop-sse/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-desktop-sse/SKILL.md 2026-10-22 14:42:47.167851622 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-desktop-sse -description: How Hydrogen's local workspace API + SSE works (a.k.a. the workspace API) — replaces Carbon for workspace commands so the workspace's adom-cli controls Hydrogen, not cloud Hydrogen. The workspace is the WSL2 Adom-Workspace distro. Covers the full pipeline, routing, env vars, field format differences, and hard-won lessons. Trigger words — Hydrogen SSE, workspace API, local API, adom-cli workspace, add-tab, move-tab, webview tab, EventSource, workspace_updated, ADOM_CARBON_URL, ADOM_HYDROGEN_URL. +description: >- + How Hydrogen's local workspace API and SSE stream work, so the workspace's + adom-cli controls Hydrogen instead of the cloud: routing, env vars, field + formats. Use for Hydrogen SSE, the workspace API, add-tab or move-tab, + EventSource, or ADOM_HYDROGEN_URL. --- # Hydrogen — Local Workspace API + SSE @@ -162,7 +166,7 @@ `add_FrameNavigationStarting` was blocking ALL external URLs in child iframes, including legitimate webview panel content. **Fix:** stop blocking frame navigations entirely — webview panels need external URLs. URL interception for window.open still works via `on_new_window`. ### Google showed "blocked" icon -Not an Hydrogen bug. Google sends `X-Frame-Options: SAMEORIGIN` which prevents iframe embedding. Sites that allow embedding (adom.inc, wiki) load fine. +Not a Hydrogen bug. Google sends `X-Frame-Options: SAMEORIGIN` which prevents iframe embedding. Sites that allow embedding (adom.inc, wiki) load fine. ## Port Discovery — How Any Client Finds Hydrogen diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-desktop-sse-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-desktop-sse-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-desktop-sse-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-desktop-sse-windows/SKILL.md 2026-10-22 14:42:47.167851622 -0500 @@ -1,18 +1,21 @@ --- name: hydrogen-desktop-sse-windows -description: Windows/WSL2-specific details for HD's local workspace API + SSE — mirrored-networking loopback sharing, the ports.json location under %APPDATA%, the HD_RUNTIME=docker vs WSL2 relay same-port-vs-host-mapping behavior, and hd-docker create_container env injection. Read alongside the platform-generic [[hd-desktop-sse]]. Trigger words — WSL2 SSE, mirrored networking, ports.json APPDATA, HD_RUNTIME docker, Adom-Workspace distro relay, same-port loopback. +description: >- + Windows companion to hydrogen-desktop-sse: mirrored-networking loopback, + ports.json under %APPDATA%, and the legacy Docker-runtime port behavior. Use + for WSL2 SSE, ports.json, or same-port loopback questions. --- -# Hydrogen Desktop — Local Workspace API + SSE (Windows / WSL2 specifics) +# Hydrogen — Local Workspace API + SSE (Windows / WSL2 specifics) -Platform companion to **[[hd-desktop-sse]]**. Everything here is Windows/WSL2-only; the +Platform companion to **`hydrogen-desktop-sse`**. Everything here is Windows/WSL2-only; the architecture, routing, env-var contract, REST field shapes, and the fixed discovery port (47080) all live in the generic skill. ## The workspace runtime on Windows On Windows the workspace is the **WSL2 `Adom-Workspace` distro** by default, or a **Docker -container under `HD_RUNTIME=docker`** (legacy). The workspace's adom-cli is what controls HD's +container under `HD_RUNTIME=docker`** (legacy). The workspace's adom-cli is what controls Hydrogen's UI via the local workspace API. ## Mirrored networking shares loopback with the Windows host @@ -20,10 +23,10 @@ Under WSL2 with **mirrored networking**, `127.0.0.1` is shared between the distro and the Windows host. That means: -- From inside the `Adom-Workspace` distro, `http://127.0.0.1:47083` reaches HD's proxy running +- From inside the `Adom-Workspace` distro, `http://127.0.0.1:47083` reaches Hydrogen's proxy running on the Windows host — no special host IP, no `/proxy/` hop needed for the host-loopback ports. - The same `127.0.0.1:` works identically from inside the distro and on Windows. -- The control URL HD writes to `~/.adom/hd-control-url` (`http://127.0.0.1:`) is the +- The control URL Hydrogen writes to `~/.adom/hd-control-url` (`http://127.0.0.1:`) is the Windows-host loopback, reachable from the distro because of mirrored loopback. ## Relay ports: same-port under WSL2 (no host 47081/47082) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-dock-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-dock-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-dock-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-dock-windows/SKILL.md 2026-10-22 14:42:47.167851622 -0500 @@ -1,7 +1,9 @@ --- name: hydrogen-dock-windows -description: > - Windows-only dock control: drive the dock from an AI thread through the control API (GET /dock/apps, POST /dock/launch, /dock/close, /dock/refresh, /dock/reset) — the ralph loop and back-to-defaults. Trigger words — dock launch, /dock/apps, relaunch dock app, dock reset, ralph loop. +description: >- + Windows companion to hydrogen-dock: drive the dock from an AI thread through + the control API (GET /dock/apps, POST /dock/launch, close, refresh, reset). + Use when asked to launch or relaunch a dock app or reset the dock. --- # hydrogen-dock-windows — Windows companion to hydrogen-dock diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-eda-discovery-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-eda-discovery-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-eda-discovery-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-eda-discovery-windows/SKILL.md 2026-10-22 14:42:47.167851622 -0500 @@ -1,13 +1,10 @@ --- name: hydrogen-eda-discovery-windows -description: > - Windows companion to hydrogen-eda-discovery: the ready-to-run probe for detecting - EDA tools that have NO bridge (Altium, OrCAD, Cadence/Allegro, EAGLE, DipTrace, - Eplan) on a Windows host via install-path scans and process listing through - adom-bridge run_script. The generic discovery playbook (branching, the - community pitch, etiquette) lives in hydrogen-eda-discovery. Trigger words: - detect altium windows, detect orcad windows, program files scan, eda probe - windows, no-bridge eda detection, powershell eda probe. +description: >- + Windows companion to hydrogen-eda-discovery: the ready-to-run probe that + detects EDA tools with no bridge (Altium, OrCAD, Cadence, EAGLE, DipTrace) via + install-path scans and process lists. Use when asked to detect altium or orcad + on windows. --- # EDA discovery on Windows: the no-bridge probe @@ -50,4 +47,4 @@ ## Related skills - `hydrogen-eda-discovery` (base): the full discovery and onboarding playbook -- `hydrogen-adom-desktop-windows`: Windows host specifics for run_script and installs +- `hydrogen-adom-bridge-windows`: Windows host specifics for run_script and installs diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-editor-state/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-editor-state/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-editor-state/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-editor-state/SKILL.md 2026-10-22 14:42:47.171851766 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-editor-state -description: The Editor State Machine (ESM) — HOW to know the true state of the VS Code editor and the Claude Code conversations inside Hydrogen, and the HARD typing invariants. Use BEFORE typing into a Claude conversation, driving setup-step threads, diagnosing "state unknown", empty split panels, tab spam, prompts landing in the wrong conversation, or any Claude tab/webview confusion. Trigger words — editor state, /editor/state, claude tab state, conversation state, which tab is active, empty editor group, split panel, double-type, typed into two boxes, prompt in wrong conversation, census, safe to type, stray text, disk verified, msg_count wrong, workbench unknown. +description: >- + Hydrogen's Editor State Machine: how to know the true state of the VS Code + editor and its Claude conversations, and the hard rules before typing into + one. Use before typing into a Claude tab, or when a prompt landed in the wrong + conversation, a split panel is empty, or the state is unknown. --- # hydrogen-editor-state — the Editor State Machine diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-embedded-bridge/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-embedded-bridge/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-embedded-bridge/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-embedded-bridge/SKILL.md 2026-10-22 14:42:47.171851766 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-embedded-bridge -description: How Hydrogen (ah) and Adom Bridge (ab) interact via "embedded mode". Use whenever the user asks about the system tray icon, why ab isn't visible, why two desktop apps are installed, the "Embedded · Hydrogen" footer pill, or how to make ab show up standalone. Trigger words — embedded mode, system tray, ab tray, why is adom desktop hidden, where's my tray icon, Hydrogen vs ab, both apps installed, why two installs, ab missing from tray, switch ab to standalone, ab won't show, run ab without Hydrogen, decouple ab from Hydrogen. +description: >- + How Hydrogen (ah) runs Adom Bridge (ab) in embedded mode: the hidden tray + icon, the Embedded footer pill, why two apps are installed, and how to run ab + standalone. Use when asked where is my tray icon, why ab is hidden, why two + installs, or to switch ab to standalone. --- # Hydrogen ↔ ab Embedded Mode @@ -83,7 +87,7 @@ - Evening: user quits Hydrogen → ab's next poll fails the Hydrogen probe → ab reverts to standalone → tray reappears - Next morning: user launches Hydrogen again → ab's next poll succeeds → ab re-embeds → tray hides -The same ab process can flip mode back and forth indefinitely across an Hydrogen-quit / Hydrogen-relaunch cycle. Transitions: +The same ab process can flip mode back and forth indefinitely across a Hydrogen-quit / Hydrogen-relaunch cycle. Transitions: | Current mode | Hydrogen probe says | What ab does | |---|---|---| diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-file-transfer/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-file-transfer/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-file-transfer/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-file-transfer/SKILL.md 2026-10-22 14:42:47.171851766 -0500 @@ -1,18 +1,10 @@ --- name: hydrogen-file-transfer -description: > - Move files BOTH WAYS between the Hydrogen WSL2 Ubuntu workspace (the Adom-Workspace - distro, where your code lives at /home/adom/project) and the user's Windows PC - — including their Desktop, Downloads, and any folder. Three methods: (1) the - auto-mounted C: drive at /mnt/c inside the distro, (2) the \\wsl$ network path - from Windows Explorer, and (3) the adom-bridge relay (send_files / pull_file) - relay. Use when the user asks "how do I - get this file onto my desktop", "copy this out of the workspace", "get a file - from my PC into the workspace", "move a file in/out", "where do my downloads - go", or "drag a file into the container". Trigger words: copy file out, copy - file in, move file to desktop, get file from desktop, file transfer, /mnt/c, - wsl$, \\wsl.localhost, send_files, pull_file, export file, import file, drag - into workspace, file to my pc, download to desktop, upload to workspace. +description: >- + Move files both ways between the Hydrogen WSL2 workspace and the user's + Windows PC: /mnt/c, the \\wsl$ path from Explorer, or adom-bridge + send_files/pull_file. Use when asked to copy a file to my desktop, get a file + from my PC, move a file in or out, or where my downloads go. --- # Move files between the workspace and the Windows PC diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-golden-image/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-golden-image/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-golden-image/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-golden-image/SKILL.md 2026-10-22 14:42:47.171851766 -0500 @@ -1,19 +1,10 @@ --- name: hydrogen-golden-image -description: > - Your Hydrogen workspace starts from a PRE-BAKED golden WSL2 image (v28-full): - the tarball already carries the Adom toolchain — adom/core, the Adom CLIs, the - hydrogen-* skills and the editor extensions including Claude Code — on top of - Ubuntu, systemd, code-server and the folder contract. Setup does NOT install - the ecosystem from scratch on a full image; its update-packages step converges - what is baked in to the latest published versions. READ THIS when a user asks - "where did these skills/CLIs come from", "why did first-run setup take a few - minutes", "how do I update the workspace", or "what's actually in the image". - Trigger words — golden image, full image, thin image, pre-baked, baked image, - adom-golden, adom-golden.tar.gz, wsl --import, tarball version, - adom-tarball-version, migrate tarball, install-hydrogen-skills, where did the - CLIs come from, how do I update the workspace, re-run setup, install on - demand, command not found, missing tool, apt-get install, is ffmpeg installed. +description: >- + What the pre-baked golden WSL2 image contains, how weekly images and the + update-packages step keep it current, and the tarball pin. Maintainer + reference for where the CLIs and skills came from. +disable-model-invocation: true --- # Hydrogen Workspace = a pre-baked golden image, kept current at setup diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-lightbulb/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-lightbulb/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-lightbulb/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-lightbulb/SKILL.md 2026-10-22 14:42:47.175851910 -0500 @@ -1,16 +1,10 @@ --- name: hydrogen-lightbulb -description: > - The LIGHTBULB menu (sample prompts) in Hydrogen's title bar — the 💡 - button just right of the Adom logo (top-left, 0.1.265+; it lived by the CPU/RAM - badges before). Each item opens a FRESH Claude AI thread and - types a curated demo prompt for the user (parts search, KiCad/Fusion, pup, - native browser, adom-tsci, shotlog, webviews, hands-free, "Speak Adom" - shorthand training). Covers: how items run, the samples-menu.open/close AI - commands, GET /claude/sample-prompts, and sample-prompts.json — the overlay - file that adds or rewords prompts WITHOUT a new Hydrogen release. Trigger words: - lightbulb, light bulb menu, sample prompts, samples menu, demo prompts, sample - threads, speak adom, add a sample prompt, sample-prompts.json. +description: >- + Hydrogen's lightbulb menu of sample prompts in the title bar: each item opens + a fresh Claude thread and types a demo prompt; sample-prompts.json adds or + rewords them without a release. Use when asked about the lightbulb, sample + prompts, demo prompts, or adding a sample prompt. --- # hydrogen-lightbulb — the sample-prompts (💡) menu diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-naming-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-naming-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-naming-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-naming-windows/SKILL.md 2026-10-22 14:42:47.175851910 -0500 @@ -1,12 +1,10 @@ --- name: hydrogen-naming-windows -description: > +description: >- Windows companion to hydrogen-naming: the Windows-specific frozen identifiers - and install-surface names for Adom Hydrogen and Adom Bridge. The naming - doctrine itself (Formal Names, the installer rule, shorthands, dead names) - lives in hydrogen-naming. Trigger words: appdata hydrogen-desktop, installer - filename windows, hydrogen exe name, wsl distro name, add remove programs - name, autostart registry name. + and install names for Hydrogen and Adom Bridge (appdata folder, installer and + exe names, WSL distro, autostart key). Use when asked for a Windows install + path or name. --- # Adom product naming: Windows frozen identifiers diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-networking/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-networking/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-networking/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-networking/SKILL.md 2026-10-22 14:42:47.175851910 -0500 @@ -1,14 +1,10 @@ --- name: hydrogen-networking -description: > - Port architecture, hostnames, and networking rules for Hydrogen. - MUST READ before adding ports, exposing a service to your Windows host, - referencing host URLs from inside the workspace, or wiring any service - communication. - Trigger words — Hydrogen port, Hydrogen network, port mapping, proxy, 127.0.0.1, loopback, - mirrored networking, hydrogen-control-url, - VSCODE_PROXY_URI, relay URL, code-server proxy, container networking, - ADOM_CARBON_URL, ADOM_HYDROGEN_URL, direct connect, 8770, 7380. +description: >- + Port architecture, hostnames and networking rules for the Hydrogen workspace: + loopback via mirrored networking, the control URL, code-server proxy, relay + ports. Read before adding a port or exposing a service to Windows. Use for + Hydrogen ports, loopback, proxy, or 7380/8770. --- # Hydrogen — Networking & Port Architecture diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-notifications/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-notifications/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-notifications/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-notifications/SKILL.md 2026-10-22 14:42:47.179852053 -0500 @@ -1,22 +1,10 @@ --- name: hydrogen-notifications -description: > - How Hydrogen reaches the user OUTSIDE the window — native OS toast - notifications + an OS-level attention request — so the AI can proactively tell the user a - long job finished or that it needs them (great for hands-free / away-from-keyboard - work). Covers Hydrogen's notify handler (levels info|warning|error|emergency, optional - buttons; emergency = a persistent attention request until the user looks) - and how to fire one with the `notify` desktop command / `adom-bridge notify_user`. - Also the in-app `/ui/toast` (a message INSIDE the Hydrogen window) and Pup's - browser_alert_window attention nudge. The native OS-toast backend is - platform-specific (see the platform companions [[hydrogen-notifications-windows]] / - [[hydrogen-notifications-mac]]); cross-platform behavior is documented here. Trigger words — notify the user, send a - notification, desktop notification, toast, os toast, native toast, taskbar flash, dock - bounce, get the user's attention, alert the user, notify_user, emergency notification, - urgent alert, notification actions, action buttons, ping the user, job done - notification, tell me when it's done, request attention, browser_alert_window, in-app - toast, ui toast, /ui/toast, show a toast in Hydrogen, toast inside the window, bell icon, - notification bell, enable notifications, browser notifications. +description: >- + How Hydrogen reaches the user outside the window: native OS toasts and + attention requests via `adom-bridge notify_user` (levels up to emergency, + action buttons), plus the in-app /ui/toast. Use when asked to notify me, send + a desktop notification, tell me when it's done, or show a toast. --- # Hydrogen — Notifications (reaching the user outside the window) @@ -106,17 +94,17 @@ status cue while they're working in Hydrogen. (Hydrogen's native recording uses this for its auto-stop notice — see [hydrogen-recording](../hydrogen-recording/SKILL.md).) -## Pup's attention nudge (`browser_alert_window`) +## Pup's attention nudge (`pup_alert_window`) For AI-driven browser work, Pup has its own attention nudge: ```bash -adom-bridge browser_alert_window '{"sessionId":"default"}' +adom-bridge pup_alert_window '{"sessionId":"default"}' ``` It **triggers the OS attention nudge** for that browser window (and brings the page to front within Chrome) **without stealing foreground focus** — a gentle "look here." (Use -`browser_focus_window` if you actually want to raise the window.) +`pup_focus_window` if you actually want to raise the window.) ## When you (the AI) should notify proactively @@ -131,6 +119,6 @@ (`adom-bridge ping`) before claiming you notified them. ## Related skills -- [hydrogen-adom-desktop](../hydrogen-adom-desktop/SKILL.md) — ab is what carries `notify_user` to the host; `ping`/`status` to verify the bridge and the `notify` capability -- [hydrogen-bridges](../hydrogen-bridges/SKILL.md) — the full ab capability list (`notify`, …) and Pup's `browser_alert_window` +- [hydrogen-adom-bridge](../hydrogen-adom-bridge/SKILL.md) — ab is what carries `notify_user` to the host; `ping`/`status` to verify the bridge and the `notify` capability +- [hydrogen-bridges](../hydrogen-bridges/SKILL.md) — the full ab capability list (`notify`, …) and Pup's `pup_alert_window` - [[hydrogen-notifications-windows]] / [[hydrogen-notifications-mac]] — the per-platform toast backends and attention mechanics diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-notifications-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-notifications-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-notifications-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-notifications-windows/SKILL.md 2026-10-22 14:42:47.179852053 -0500 @@ -1,28 +1,23 @@ --- name: hydrogen-notifications-windows -description: > - Windows-specific companion to [[hd-notifications]]. How HD's native toasts are delivered - on Windows — WinRT toasts routed through a PowerShell AUMID (so they may surface under an - "Adom" title), and the `emergency` level's persistent ORANGE TASKBAR FLASH via - request_user_attention(Critical) that keeps flashing until the user clicks the taskbar - icon. Source: notifications.rs. For the cross-platform `notify_user` / `/ui/toast` / - Pup-alert API, see [[hd-notifications]]. Windows-only. Trigger words — windows toast, - winrt toast, AUMID, Adom title toast, orange taskbar flash, request_user_attention, - taskbar attention, emergency notification windows, powershell toast, notifications.rs. +description: >- + Windows companion to hydrogen-notifications: WinRT toasts through a PowerShell + AUMID (an "Adom" title), and the emergency level's persistent orange taskbar + flash. Use for windows toast, AUMID, or taskbar flash questions. --- -# Hydrogen Desktop — Native Toasts on Windows +# Hydrogen — Native Toasts on Windows -Windows-specific companion to **[[hd-notifications]]**. The generic skill covers the +Windows-specific companion to **`hydrogen-notifications`**. The generic skill covers the cross-platform `notify_user` API, the `/ui/toast` in-app toast, and Pup's -`browser_alert_window`. This page covers how the native OS toast is delivered on Windows. +`pup_alert_window`. This page covers how the native OS toast is delivered on Windows. -> **Windows-only.** On macOS HD uses a more limited `osascript`-style notification; Linux -> has no native toast path. See [[hd-notifications]] for the platform-neutral story. +> **Windows-only.** On macOS Hydrogen uses a more limited `osascript`-style notification; Linux +> has no native toast path. See `hydrogen-notifications` for the platform-neutral story. ## WinRT toasts via a PowerShell AUMID -On Windows, HD's native toasts are **WinRT toasts** routed through a **PowerShell AUMID**. +On Windows, Hydrogen's native toasts are **WinRT toasts** routed through a **PowerShell AUMID**. The `` button labels from the `actions` payload render as buttons in the toast template. @@ -32,12 +27,12 @@ A side effect of the PowerShell AUMID: toasts may surface under an **"Adom"** identity/title rather than a per-app one. Relatedly, if the `title` field doesn't already -start with "Adom", HD prefixes it → `"Adom: "`. That's **expected** — don't treat an +start with "Adom", Hydrogen prefixes it → `"Adom: <title>"`. That's **expected** — don't treat an "Adom"-labeled toast as a bug. ## The `emergency` level — persistent orange taskbar flash -For `level:"emergency"`, in addition to the toast HD calls +For `level:"emergency"`, in addition to the toast Hydrogen calls **`request_user_attention(Critical)`** on the main window and shows/unminimizes it. On Windows this produces a **persistent ORANGE taskbar flash that keeps flashing until the user actually clicks the taskbar icon themselves** — it is *not* cleared by a programmatic @@ -45,5 +40,5 @@ hard to ignore. ## Related skills -- [[hd-notifications]] — the cross-platform `notify_user` / `/ui/toast` / Pup-alert API and the macOS/Linux fallback story -- [hd-adom-desktop](../../hd-bootstrap/skills/hd-adom-desktop/SKILL.md) — AD carries `notify_user` to the host +- `hydrogen-notifications` — the cross-platform `notify_user` / `/ui/toast` / Pup-alert API and the macOS/Linux fallback story +- [hydrogen-adom-bridge](../hydrogen-adom-bridge/SKILL.md) — ab carries `notify_user` to the host diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-open-url/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-open-url/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-open-url/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-open-url/SKILL.md 2026-10-22 14:42:55.924205334 -0500 @@ -1,19 +1,10 @@ --- name: hydrogen-open-url -description: > - The decision guide for "open a URL / open a website" inside Hydrogen. - When the user says "open ti.com" / "pull up the datasheet page" / "show me - that site", Hydrogen has SIX distinct ways to do it — a Hydrogen webview tab, an Hydrogen - browser window, Pup (AI-drivable Chrome), a native desktop browser profile, - the Browser Picker chooser, or headless curl/fetch — each with different - trade-offs. READ THIS to pick the right one and to explain the options back to - the user instead of silently guessing. For the interception/plumbing behind the - picker see hydrogen-browser-picker; to drive Pup see pup; for webview tabs see - adom-workspace-control. Trigger words — open url, open website, open the site, - open ti.com, open a link, pull up the page, show me the website, view this url, - open in browser, which browser, how do I open, open the datasheet page, open in - a tab, open in pup, open in chrome, headless fetch, ways to open a url, open - link options, wv, open in wv, open as wv, webview tab, wv tab. +description: >- + Decision guide for opening a URL from Hydrogen: webview tab, Hydrogen browser + window, Pup, a native browser profile, the Browser Picker, or a headless + fetch, and when to use each. Use when asked to open a website, open a link, + pull up a page, open in a tab, or which browser to use. --- # Hydrogen — Opening a URL (your options) @@ -111,12 +102,12 @@ On `/open-url`, `fresh` pre-seeds that toggle (the picker still shows; add `direct:true` to skip it); `/open-in-profile` opens fresh directly. See `hydrogen-browser-picker`. -**3. Pup** — open and then drive it with `adom-bridge browser_*` verbs -(`browser_open_window`, `browser_navigate`, `browser_screenshot`, `browser_eval`, -`browser_reload`, …). Either open the URL directly via Pup, or let the picker -route to Pup. See the `pup` skill for the full verb set. +**3. Pup** — open and then drive it with `adom-bridge pup_*` verbs +(`pup_open_window`, `pup_navigate`, `pup_screenshot`, `pup_eval`, +`pup_reload`, …). Either open the URL directly via Pup, or let the picker +route to Pup. See the `hydrogen-pup` skill for the full verb set. ```bash -adom-bridge browser_eval '{"sessionId":"default","js":"document.title"}' +adom-bridge pup_eval '{"sessionId":"default","js":"document.title"}' ``` **6. Headless content** — if you only need to *read* the page, skip the browser @@ -139,7 +130,7 @@ | Use case | Open it in | How (bypass the picker) | |---|---|---| | **Login-likely site** — vendor/account/portal/cart: TI, Mouser, DigiKey, any "my…"/sign-in | the user's **native browser + WORK profile** (their saved login/cookies live there) | `GET /browser-profiles` → find the work profile (non-gmail) → `POST /open-in-profile {url, browser, profileDir, fresh:true}` | -| **Building/testing their own app**, or you need to drive/screenshot/scrape the page | **Pup** (AI-drivable) | open via Pup (`browser_*`) / route `/open-url {url, direct:true}` to Pup | +| **Building/testing their own app**, or you need to drive/screenshot/scrape the page | **Pup** (AI-drivable) | open via Pup (`pup_*`) / route `/open-url {url, direct:true}` to Pup | | **Glance at content alongside their work** | **Hydrogen webview tab** | `adom-workspace-control` add web-view tab | | **Genuinely ambiguous, OR an OAuth/sign-in the user must complete themselves** | let them choose | `POST /open-url {url, force:true}` — the one time the picker is right | @@ -194,6 +185,6 @@ ## Related skills - [hydrogen-browser-picker](../hydrogen-browser-picker/SKILL.md) — the interception layers + picker dialog behind #2/#4/#5 -- `pup` — driving Pup browser windows (#3): navigate, screenshot, eval, reload +- `hydrogen-pup` — driving Pup browser windows (#3): navigate, screenshot, eval, reload - `adom-workspace-control` — adding/managing Hydrogen webview tabs (#1) - [hydrogen-runtime-mode](../hydrogen-runtime-mode/SKILL.md) — none of this changes across workspace runtimes diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-permissions/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-permissions/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-permissions/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-permissions/SKILL.md 2026-10-22 14:42:47.183852200 -0500 @@ -1,20 +1,10 @@ --- name: hydrogen-permissions -description: > - Hydrogen AUTO-GRANTS every webview permission — microphone, camera, - clipboard-read, geolocation, notifications, sensors — so inside Hydrogen a webview app NEVER - shows a "this site wants to use your microphone/camera/clipboard/location" prompt. READ - THIS before building or debugging a webview app that uses getUserMedia / clipboard / - geolocation: do NOT tell the user to click "Allow" — there is no prompt to click; it's - suppressed by design. Distinguish this browser-permission auto-grant from the SEPARATE - in-app screen-share / mic consent the AI itself requests (that one IS user-approved — see - hydrogen-capture-share). Hydrogen's webview engine is platform-specific; the per-engine - implementation detail lives in the platform companion skills (see - [[hydrogen-permissions-windows]] / [[hydrogen-permissions-mac]]). Trigger words — permission, permissions, webview permission, - allow microphone, allow camera, allow clipboard, clipboard read, getUserMedia, mic - permission, camera permission, geolocation permission, notifications permission, sensors - permission, site wants to use, permission prompt, click allow, no permission prompt, - auto-grant, auto granted, why no prompt, permission denied webview. +description: >- + Hydrogen auto-grants every webview permission (mic, camera, clipboard, + geolocation, notifications), so a webview app never shows an Allow prompt; the + AI's screen-share consent is separate. Use when building a webview app with + getUserMedia or clipboard, or asked why there is no permission prompt. --- # Hydrogen auto-grants every webview permission diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-permissions-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-permissions-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-permissions-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-permissions-windows/SKILL.md 2026-10-22 14:42:47.183852200 -0500 @@ -1,28 +1,23 @@ --- name: hydrogen-permissions-windows -description: > - Windows-specific companion to [[hd-permissions]]. How HD's webview-permission auto-grant - is implemented on Windows: the WebView2 `PermissionRequested` handler that returns - `COREWEBVIEW2_PERMISSION_STATE_ALLOW` for every permission kind (mic, camera, - clipboard-read, geolocation, notifications, sensors), with lib.rs code evidence. For the - cross-platform policy + what it means when building webview apps, see [[hd-permissions]]. - Windows-only. Trigger words — webview2 permission, PermissionRequested, - COREWEBVIEW2_PERMISSION_STATE_ALLOW, lib.rs permission handler, windows webview - auto-grant, webview2 allow, permission auto-grant windows. +description: >- + Windows companion to hydrogen-permissions: the WebView2 PermissionRequested + handler that allows every permission kind. Use for webview2 permission or + PermissionRequested questions. --- -# HD WebView2 permission auto-grant (Windows) +# Hydrogen WebView2 permission auto-grant (Windows) -Windows-specific companion to **[[hd-permissions]]**. The generic skill covers the policy -(HD auto-grants every webview permission so users never see an Allow prompt) and what it +Windows-specific companion to **`hydrogen-permissions`**. The generic skill covers the policy +(Hydrogen auto-grants every webview permission so users never see an Allow prompt) and what it means when building webview apps. This page covers the Windows/WebView2 implementation. -> **Windows-only.** On other platforms HD uses a different webview engine (e.g. WebKit) but -> applies the same allow-everything policy — see [[hd-permissions]]. +> **Windows-only.** On other platforms Hydrogen uses a different webview engine (e.g. WebKit) but +> applies the same allow-everything policy — see `hydrogen-permissions`. ## The WebView2 `PermissionRequested` handler -On Windows, HD's webview is **WebView2**. HD registers a `PermissionRequested` handler that +On Windows, Hydrogen's webview is **WebView2**. Hydrogen registers a `PermissionRequested` handler that returns **ALLOW for every permission kind** — clipboard-read, mic, camera, geolocation, notifications, sensors, etc. @@ -37,15 +32,15 @@ hd_log::hd_log!("[perm] auto-granted permission kind {:?}", kind); ``` -Every request is unconditionally set to `COREWEBVIEW2_PERMISSION_STATE_ALLOW`. In the HD log +Every request is unconditionally set to `COREWEBVIEW2_PERMISSION_STATE_ALLOW`. In the Hydrogen log you'll see lines like `[perm] auto-granted permission kind …` and, at startup, `[perm] Registered PermissionRequested auto-grant handler`. -This is WebView2/Windows-specific behavior baked into HD's webview host — it's not something +This is WebView2/Windows-specific behavior baked into Hydrogen's webview host — it's not something the web page or the user configures. If a webview app *isn't* getting mic/camera data on Windows, note that the OS-level Windows privacy toggle for the camera/mic can still be off -for the app entirely (that's an OS setting, not a denied WebView2 prompt — HD never denies). +for the app entirely (that's an OS setting, not a denied WebView2 prompt — Hydrogen never denies). ## Related skills -- [[hd-permissions]] — the cross-platform auto-grant policy + webview-app guidance -- `hd-capture-share` — the SEPARATE, user-approved screen-share / mic consent the AI requests +- `hydrogen-permissions` — the cross-platform auto-grant policy + webview-app guidance +- `hydrogen-capture-share` — the SEPARATE, user-approved screen-share / mic consent the AI requests diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-port-watcher/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-port-watcher/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-port-watcher/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-port-watcher/SKILL.md 2026-10-22 14:42:47.183852200 -0500 @@ -1,17 +1,10 @@ --- name: hydrogen-port-watcher -description: > - Port reachability in Hydrogen — and why you do NOT need to set up - port forwarding. Under WSL2 networkingMode=mirrored (Hydrogen's default, which the - setup cascade hard-targets), the distro SHARES the Windows loopback, so every - port a service binds in the workspace — including `127.0.0.1`-only OAuth - callback servers from VS Code extensions (Codex, Copilot, GitLens) — is - reachable at the same `localhost:<port>` on Windows automatically. No daemon, - no proxies, no manual mapping. The old port-watcher daemon was a Docker/NAT-era - mechanism and is not used under mirrored networking. Trigger words: port - forward, dynamic port, OAuth callback, Codex auth, extension auth, port mapping, - localhost port, port watcher, port proxy, does port forwarding work, why can't - I reach my port. +description: >- + Why you don't need port forwarding in Hydrogen: under WSL2 mirrored networking + every port the workspace binds, including 127.0.0.1 OAuth callbacks, is + reachable on Windows localhost. Use when asked about port forwarding, OAuth + callback ports, Codex or extension auth, or why can't I reach my port. --- # Hydrogen Port Watcher — you don't port-watch anymore (mirrored networking does it) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-ports/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-ports/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-ports/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-ports/SKILL.md 2026-10-22 14:42:47.183852200 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-ports -description: How Hydrogen does port forwarding between your WSL2 workspace and your Windows machine — WSL2's automatic `0.0.0.0` localhost-forwarding (no port map to declare), the code-server `/proxy/<port>/` URL pattern that exposes any internal port, the port-forward registry for `127.0.0.1`-only services that WSL2 won't auto-forward, and the PortMappingsDialog UI. Use when the user asks "why isn't my server reachable", "how do I expose port X", "what's localhost:7380", "register a port", "auto-forward a port", or "the dynamic port dialog". Trigger words — port forwarding, ports, ah ports, container port, proxy port, code-server proxy, /proxy/, port mappings dialog, port hints, auto forward, expose port, register port, host port, dynamic port, ports.json, PortConfig, port resolver, localhost port not working. +description: >- + How ports reach Windows from the Hydrogen WSL2 workspace: WSL2 localhost + forwarding, the code-server /proxy/<port>/ URL, the port-forward registry for + 127.0.0.1-only services, and the Port Mappings dialog. Use when asked why my + server isn't reachable, how to expose a port, or what localhost:7380 is. --- # Hydrogen Ports — forwarding workspace services to your Windows host @@ -80,7 +84,7 @@ ``` Visibility options: -- `external` — bind `localhost:5555` on Windows via an Hydrogen-managed proxy AND +- `external` — bind `localhost:5555` on Windows via a Hydrogen-managed proxy AND keep the `/proxy/` URL working. Best for OAuth callbacks, native clients, loopback-only servers. - `internal` — proxy URL only, no host binding. Best for webview panels that @@ -251,7 +255,7 @@ ```bash adom-bridge kicad_open_board '{"path":"..."}' # adom-bridge routes to the right port -adom-bridge browser_eval '{"js":"..."}' +adom-bridge pup_eval '{"js":"..."}' ``` This means **old code or skill examples that hardcoded fixed bridge ports diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-project-workspaces/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-project-workspaces/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-project-workspaces/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-project-workspaces/SKILL.md 2026-10-22 14:42:47.187852344 -0500 @@ -1,11 +1,15 @@ --- name: hydrogen-project-workspaces -description: The Project workspaces menu in Hydrogen Desktop (the icon right of the Adom logo) and its control API, the desktop side of shared workspaces (hydrogen/workspace.json benches a project ships). Read this when a user says - project workspaces, shared workspace, apply a bench, unload a bench, workspace.json, hydrogen/workspace.json, save as project workspace, the layout a project ships, this project ships a workspace, apply / not now card, workspace offer, the icon next to the Adom logo, /workspaces/apply, /workspaces/benches, ztest-bench, bench placeholder, connect adom bridge for a bench, open the same layout as Colby. For the file format, the WORKSPACE_* hints and adom-cli export/apply use the wiki-workspaces skill; for the pane API (tabs, splits, moves) use adom-workspace-control; this skill covers only what Hydrogen Desktop adds. +description: >- + Hydrogen's Project workspaces menu (icon right of the Adom logo) and its API: + apply or unload the bench layout a project ships in hydrogen/workspace.json. + Use when asked about project workspaces, apply a bench, workspace.json, or the + workspace offer card. --- # hydrogen-project-workspaces: the desktop side of shared workspaces -A project can ship its Hydrogen layout as `hydrogen/workspace.json` (or `hydrogen/workspaces/<name>.json`) in its page repo. The platform pieces are shared with Hydrogen Cloud and documented in the **wiki-workspaces** skill (file, hints, `adom-cli hydrogen workspace export|apply|teardown`) and **adom-workspace-control** (the pane routes). Hydrogen Desktop (ah) adds a menu, a one-time offer, placeholder tabs that know the bridge state, and a control API for all of it. Use the API; never click for the user. +A project can ship its Hydrogen layout as `hydrogen/workspace.json` (or `hydrogen/workspaces/<name>.json`) in its page repo. The platform pieces are shared with Hydrogen Cloud and documented in the **wiki-workspaces** skill (file, hints, `adom-cli hydrogen workspace export|apply|teardown`) and **adom-workspace-control** (the pane routes). Hydrogen (ah) adds a menu, a one-time offer, placeholder tabs that know the bridge state, and a control API for all of it. Use the API; never click for the user. ## The menu @@ -36,7 +40,7 @@ - Placeholder tabs ("X (not available)" / "(not started)", or `panelState.placeholder`) show the Adom Bridge state (GET /ab/health) with Connect and Re-apply; re-apply is idempotent in merge mode. - The workspace API on the proxy (47083) serves the cloud's granular routes plus `GET /api/panels/catalog`, `POST .../current/apply` (replace mode, keeps the VS Code leaf), and forwards `.../shared[/...]` to Hydrogen Cloud with the desktop session. Every tree mutation bumps a revision; a `PUT /current` whose `_rev` is behind gets 409, so an external apply cannot be erased by the browser's echo. - `POST /splits` seeds the new pane with the placeholder tab adom-cli sends (`panelType`, `displayName`, `position`, `ratio`); adom-cli deletes it as tabIndex 0 after adding the bench's tabs. -- No 3D panel on the desktop: a `3d-viewer` tab renders as "not available on Hydrogen Desktop". +- No 3D panel on the desktop: a `3d-viewer` tab renders as "not available on Hydrogen Desktop" (the UI's own wording). - `hydrogen://edit?workspace=<ref|identity|path>` is a registered scheme (installer + every start): a second launch forwards the link to the running ah, which applies the bench once the list loads. Test it with `Start-Process "hydrogen://edit?workspace=kcknox/ztest-bench-lite"` on the box. - The VS Code pane is never created, removed or replaced by any of this. diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-recording/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-recording/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-recording/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-recording/SKILL.md 2026-10-22 14:42:47.187852344 -0500 @@ -1,32 +1,10 @@ --- name: hydrogen-recording -description: > - How to record screen + window video from Hydrogen. In Hydrogen the recorder is - NATIVE: Windows.Graphics.Capture (per-window, "record kicad") + DXGI full-screen, - hardware H.264 (default, universally playable) or H.265 (smaller, not web-playable) - → mp4 in ~/project/recordings/, with NO picker, NO "you're sharing" banner, real - 30-60fps, and NO display wake-lock. Driven by `adom-cli hydrogen recording - start/stop` (which routes to the native control API) or the control endpoints - directly (POST /recording/native/start|stop, GET /recording/native/status|sources). - A server-side max-duration cap (default 600s) auto-stops + toasts. Read for codec - choice, source selection, the cap+reason, and the "● Recording" indicator. Also - covers AUDIO-ONLY / narration capture (`adom-cli hydrogen audio` → WebM/Opus in - ~/project/audio/), ab host desktop recording (desktop_record_start, Windows-only), - the tab-vs-desktop footgun, and what `--mic` does. TWO ENGINES: wgc (GPU, real - displays) and gdigrab (ffmpeg GDI — the ONLY engine that records on VMs / virtual - / indirect displays / VNC); engine:"auto" probes and falls forward; GET - /recording/native/capabilities reports what THIS box supports. Multi-monitor: - screen:1..N or screen:all. Trigger words — record, - recording, screen recording, record my screen, record kicad, record a window, - record whole screen, record the workspace, record a demo, record with mic, record - no audio, mic on, mic off, voiceover, record audio, audio-only, record a narration, - record my voice, narrate, narration track, record a voice track, h264, h265, hevc, - mp4, webm, opus, codec, recordings folder, audio folder, ffmpeg, stitch clips, - max duration, recording indicator, desktop_record_start, browser_record_start, - start recording, stop and save, record on a vm, virtual display, indirect display, - headless recording, vnc recording, 0 frames, zero frames, gdigrab, gdi capture, - recording engine, capture engine, record all monitors, record second monitor, - multi-monitor recording, recording capabilities, can this machine record. +description: >- + Record the screen, a window or audio from Hydrogen with the native recorder + (`adom-cli hydrogen recording`): H.264/H.265 mp4, wgc or gdigrab engines, + multi-monitor, duration cap. Use when asked to record my screen, record kicad, + record narration, or why a recording has 0 frames. --- # Hydrogen — Screen & Window Recording @@ -72,7 +50,7 @@ says "prefer Hydrogen's `recording start --share screen`" — this is for the parallel-with-an-Hydrogen-capture case, not the default. 4. **A single Chrome tab** (AI-driven Pup browser — a clean per-tab clip): `adom-bridge - browser_record_start {sessionId}` / `browser_record_stop`. CDP screencast, ~50fps, no HUD, + pup_record_start {sessionId}` / `pup_record_stop`. CDP screencast, ~50fps, no HUD, no wake-lock, coexists with everything. 5. **Just audio — a voice / narration track, no video** ("record a narration", "record my voice"): **`adom-cli hydrogen audio start/stop`** → `~/project/audio/<name>.webm` (Opus). @@ -86,7 +64,7 @@ | `adom-cli hydrogen recording` (ah) | — (use control API) | ✅ `--share screen` | ✅ `--share tab` | native WGC/DXGI | **NO** | mp4 → `~/project/recordings/` | | Hydrogen native control API | ✅ `source:"window:X"` | ✅ `source:"screen"` | — | native WGC/DXGI | **NO** | mp4 → `~/project/recordings/` | | ab `desktop_record_start` | ❌ **none** | ✅ whole desktop | ❌ | Chrome `getDisplayMedia` | **YES** | `.webm` → ab cache | -| pup `browser_record_start` | — | ❌ | ✅ one tab | CDP screencast | **NO** | tab clip | +| pup `pup_record_start` | — | ❌ | ✅ one tab | CDP screencast | **NO** | tab clip | So: **per-window recording = Hydrogen-native only; whole-desktop = Hydrogen-native (no wake-lock) preferred over ab (wake-lock); single tab = pup.** When someone says "record a window," that's #2 (Hydrogen @@ -257,7 +235,7 @@ - ✅ **Coexist with a recording** (use these while recording): CDP `POST /screenshot` (Hydrogen-native, the default), `adom-bridge desktop_screenshot_window` (ab per-window), - `adom-bridge desktop_screenshot_screen` (ab host GDI), pup `browser_screenshot`. + `adom-bridge desktop_screenshot_screen` (ab host GDI), pup `pup_screenshot`. - ⚠️ **The ONE exception** — `adom-cli hydrogen screenshot panel|workspace|screen` (the SSE path, `PATCH /current/screenshot`). The moment a native recording is active this returns **`{ok:false, error:"capture_busy", retry_after_ms, alternatives:[...], _hint}`** instead of @@ -385,7 +363,7 @@ ``` If `record` isn't listed, the host/runtime doesn't support it — fall back to the -in-app recorder (for the workspace) or `browser_record_start` (for a tab). +in-app recorder (for the workspace) or `pup_record_start` (for a tab). --- @@ -396,7 +374,7 @@ | **Record whole screen (ah)** | `adom-cli hydrogen recording start --share screen …` or `POST /recording/native/start {source:"screen"}` | **h264 mp4** → `~/project/recordings/` | | **Record a window (ah), e.g. "record kicad"** | `POST /recording/native/start {source:"window:KiCad"}` | **h264 mp4** → `~/project/recordings/` | | **Smaller archival recording (ah)** | `POST /recording/native/start {source:…, codec:"h265"}` | **h265 mp4** (not web-playable) | -| Record one AI browser tab | `adom-bridge browser_record_start` (pup) | tab screencast | +| Record one AI browser tab | `adom-bridge pup_record_start` (pup) | tab screencast | | Record host desktop via ab (Hydrogen busy) | `adom-bridge desktop_record_start '{"confirmDesktopNotTabRecording":true}'` | host recording | | Record the workspace (web-Hydrogen) | In-app Recording dropdown (or `promptRecording()`) | `.webm` → container `recordings/` | @@ -404,5 +382,5 @@ - [hydrogen-screen-lock](../hydrogen-screen-lock/SKILL.md) — native capture holds NO display wake-lock; the max-duration cap + "● Recording" indicator - [hydrogen-self-screenshot](../hydrogen-self-screenshot/SKILL.md) — native CDP screenshots (the 90% "ralph test the webview" case); the capture-contention matrix — which screenshot methods coexist with a recording and which (`adom-cli` SSE) return `capture_busy` - [hydrogen-capture-share](../hydrogen-capture-share/SKILL.md) — the (web-Hydrogen) screen-share + AI-consent flow incl. the cancelable CountdownToast -- [hydrogen-bridges](../hydrogen-bridges/SKILL.md) — `browser_record_start` (Pup tab recording) and the ab capability list (`record`, `screenshot`, …) +- [hydrogen-bridges](../hydrogen-bridges/SKILL.md) — `pup_record_start` (Pup tab recording) and the ab capability list (`record`, `screenshot`, …) - `pup` — driving the Pup browser windows you'd record per-tab diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-runtime-mode/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-runtime-mode/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-runtime-mode/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-runtime-mode/SKILL.md 2026-10-22 14:42:47.187852344 -0500 @@ -1,19 +1,15 @@ --- name: hydrogen-runtime-mode -description: > - Which workspace runtime your Hydrogen Desktop is using — a WSL2 Ubuntu distro - (default) or a legacy Docker container (HD_RUNTIME=docker) — how to tell which - one you're in, what changes between them, and which runtime-specific skills to - trust. READ THIS FIRST when anything about the workspace's container/distro, - networking, volumes, ports, or setup steps seems contradictory: the answer - almost always depends on the runtime. Trigger words — runtime, wsl, wsl2, - docker mode, HD_RUNTIME, Adom-Workspace, which runtime, container or distro, - workspace runtime, container runtime unhealthy, am I in docker or wsl. +description: >- + Which runtime hosts your Hydrogen workspace: the WSL2 Adom-Workspace distro + (default) or a legacy Docker container (HD_RUNTIME=docker), how to tell, and + what differs. Use when asked am I in docker or wsl, which runtime, or when + workspace networking, ports or setup advice conflicts. --- -# HD Runtime Mode — WSL2 (default) vs Docker (legacy) +# Hydrogen Runtime Mode — WSL2 (default) vs Docker (legacy) -Hydrogen Desktop hosts your workspace one of two ways. Everything Claude knows +Hydrogen hosts your workspace one of two ways. Everything Claude knows about "the container" — its filesystem, networking, ports, stats, and setup steps — depends on which one is active. **Check the runtime before trusting any runtime-specific advice.** @@ -24,7 +20,7 @@ | `docker` | DockerDesktop — legacy fallback | Docker container (Docker Desktop) | 24 steps | `setup-steps.json` | WSL2 is the default — you only get Docker if `HD_RUNTIME=docker` was set before -HD launched. The selector is `runtime/mod.rs::select_runtime()`; the WSL setup +Hydrogen launched. The selector is `runtime/mod.rs::select_runtime()`; the WSL setup executor is `setup_steps_wsl.rs`, the Docker one is `setup_steps.rs`. Both paths are kept alive on purpose: the Docker runtime is a pristine fallback in case a machine can't run WSL2. @@ -33,11 +29,11 @@ 1. **Startup log line:** `[app] Active workspace runtime: WslDistro` (or `DockerDesktop`). This is the single source of truth. -2. **WSL only:** `wsl -l -v` shows `Adom-Workspace Running`; HD logs +2. **WSL only:** `wsl -l -v` shows `Adom-Workspace Running`; Hydrogen logs `[wsl-trigger] backend poller armed (...setup-trigger-wsl.json)` and `[run_all_wsl] ...`. 3. **Docker only:** a `hydrogen-*` container appears in `docker ps`. -4. From inside the workspace, ask HD: `GET "$(cat ~/.adom/hd-control-url)/wsl/status"` +4. From inside the workspace, ask Hydrogen: `GET "$(cat ~/.adom/hd-control-url)/wsl/status"` (loopback `http://127.0.0.1:<dynamic>`) succeeds (with distro info) on the WSL runtime. ### ⚠️ Benign noise: `[docker] Container runtime unhealthy — exec failed, needs restart` @@ -54,28 +50,31 @@ | Run a command in it | `wsl -d Adom-Workspace -u adom -- <cmd>` | `docker exec <container> <cmd>` | | Your files | `/home/adom/project` in the distro's ext4 fs (no volume); browse from Windows at `\\wsl$\Adom-Workspace\…` | Docker named volume; copy out via `docker cp` | | Ports | code-server binds `0.0.0.0:7380`; WSL2 auto-forwards `0.0.0.0` listeners to Windows `localhost` | single `-p 7380:8080` map; other ports via `/proxy/<port>/` | -| Reach the host | `127.0.0.1` (WSL2 mirrored networking shares loopback with the Windows host); HD's live control URL is in `~/.adom/hd-control-url` | `host.docker.internal` (Docker-provided) | +| Reach the host | `127.0.0.1` (WSL2 mirrored networking shares loopback with the Windows host); Hydrogen's live control URL is in `~/.adom/hd-control-url` | `host.docker.internal` (Docker-provided) | | Wipe/reset | `wsl --unregister Adom-Workspace` (only that distro) | `docker rm` + volume/image removal | ## Which skills to trust -HD only installs the skills for the **active** runtime (plus the shared ones), so -in most workspaces you'll already have the right set. The runtime-specific skills -exist in two buckets in the HD repo — `wsl2/` and `docker/` — and share names: - -- `hd-networking`, `hd-ports`, `hd-port-watcher`, `hd-volume`, `hd-container`, - `hd-topology`, `hd-container-stats`, `hd-setup`, `hd-setup-steps` -- WSL-only workspace skills: `hd-workspace-lifecycle`, `hd-workspace-monitoring` -- Docker-only skills: `hd-docker-desktop`, `hd-docker-lifecycle`, - `hd-docker-monitoring` +Hydrogen only installs the skills for the **active** runtime (plus the shared +ones), so in most workspaces you'll already have the right set. The +runtime-specific skills exist in two buckets in the ah repo — `wsl2/` and +`docker/` — and share names. This package ships the WSL2 set: + +- `hydrogen-networking`, `hydrogen-ports`, `hydrogen-port-watcher`, + `hydrogen-volume`, `hydrogen-container`, `hydrogen-topology`, + `hydrogen-container-stats`, `hydrogen-setup`, `hydrogen-setup-steps` +- WSL-only workspace skills: `hydrogen-workspace-lifecycle`, + `hydrogen-workspace-monitoring` +- The Docker-only skills (the ah repo's `docker/` bucket) are not shipped in + this package; on the Docker runtime, use the Docker column above. If you ever see Docker-specific advice (`docker exec`, named volumes, `-p` port maps) while check #1 says `WslDistro`, you're reading the wrong bucket — defer to the WSL2 mechanics above. ## Switching runtimes (rare; usually a dev/support action) -HD reads `HD_RUNTIME` from its environment at process start. -- → WSL2 (default): ensure `HD_RUNTIME` is unset or `wsl2`, relaunch HD. If a +Hydrogen reads `HD_RUNTIME` from its environment at process start. +- → WSL2 (default): ensure `HD_RUNTIME` is unset or `wsl2`, relaunch Hydrogen. If a prior run set Docker: `setx HD_RUNTIME wsl2` then relaunch. -- → Docker (fallback): `setx HD_RUNTIME docker`, relaunch HD (requires Docker +- → Docker (fallback): `setx HD_RUNTIME docker`, relaunch Hydrogen (requires Docker Desktop running). diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-screen-lock/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-screen-lock/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-screen-lock/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-screen-lock/SKILL.md 2026-10-22 14:42:47.191852488 -0500 @@ -1,17 +1,10 @@ --- name: hydrogen-screen-lock -description: > - Hydrogen screen capture (screenshots + recording) and the display wake-lock. A browser - getDisplayMedia capture asserts ES_DISPLAY_REQUIRED, which blocks the user's - screensaver and stops the display turning off → burn-in. Hydrogen is NATIVE: its - screenshots use CDP and its recording uses Windows.Graphics.Capture (WGC) / - DXGI — neither holds the display wake-lock — so Hydrogen does not have the web leak. - Hydrogen still must start→capture→release per op, cap recordings, and show a "● - recording" indicator so a forgotten recording is never silent. Read before - adding or using Hydrogen screenshot / screen-recording features. Trigger words: ah - screenshot, ah recording, screen capture, wake lock, screensaver blocked, - display won't sleep, ES_DISPLAY_REQUIRED, release capture, burn-in, powercfg - requests, getDisplayMedia, recording auto-stop, max duration. +description: >- + Hydrogen screen capture and the display wake-lock: why native screenshots and + recordings don't block the screensaver, and the start, capture, release and + cap rules. Use when the display won't sleep, the screensaver is blocked, or + before adding a screenshot or recording feature. --- # Hydrogen screen capture & the display wake-lock @@ -63,7 +56,7 @@ 1. `powercfg /requests` (elevated) — read the `DISPLAY:` section for the holder. 2. If it's a **browser** (`msedge.exe`/`chrome.exe — screen capture`), that's a `getDisplayMedia` leak from web Hydrogen or a pup tab capture — stop that capture - (close the tab / `browser_record_stop`), not an Hydrogen problem. + (close the tab / `pup_record_stop`), not a Hydrogen problem. 3. If it's **Hydrogen**, that's unexpected (native capture holds no lock) — capture the `powercfg` output and treat it as a bug to file against the recorder. @@ -75,7 +68,7 @@ Distinct from the wake-lock: when one AI thread is recording, another thread's **screenshot** must not silently fail. Hydrogen handles this without holding any lock — CDP `POST /screenshot`, ab `desktop_screenshot_window`/`_screen`, and pup -`browser_screenshot` all **coexist** with a live recording; only the `adom-cli` SSE +`pup_screenshot` all **coexist** with a live recording; only the `adom-cli` SSE screenshot path returns **`capture_busy`** (with `alternatives`) so the caller switches methods instead of getting an empty frame. Pre-flight with `GET /capture/availability`. This is a *contention* guard, not a power-state one — full detail in @@ -86,4 +79,3 @@ - [hydrogen-recording](../hydrogen-recording/SKILL.md) — native WGC/DXGI recording, the max-duration cap + reason, the "● Recording" indicator - [hydrogen-self-screenshot](../hydrogen-self-screenshot/SKILL.md) — native CDP screenshots (no wake-lock) - [hydrogen-notifications](../hydrogen-notifications/SKILL.md) — OS toasts + the in-app `/ui/toast` -- the `screen-capture-wake-lock` skill (ships in the adom-wiki packages) — the **web-Hydrogen** side of this issue (where the leak actually happens) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-self-screenshot/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-self-screenshot/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-self-screenshot/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-self-screenshot/SKILL.md 2026-10-22 14:42:47.191852488 -0500 @@ -1,29 +1,10 @@ --- name: hydrogen-self-screenshot -description: > - Screenshot Hydrogen from inside the workspace — a panel/webview (the welcome page, a - tab), the whole workspace, OR the whole screen/desktop — using the BUILT-IN - `adom-cli hydrogen screenshot`. It saves a PNG into the container's - `screenshots/` folder and prints the path to Read. THE answer for "take a - screenshot of the welcome page", "screenshot the webview", "screenshot this - panel", "screenshot the editor", "screenshot my whole screen / the desktop", - "show me what Hydrogen looks like", or verifying a UI change (ralph loop). Use this - even for "my whole screen / my desktop / my monitor" — that's the `screen` - scope. You do NOT need any image resizer. For a SPECIFIC element/region (a CPU - meter, a menu, a dialog, a toolbar) or an inline-b64 PNG, use the canonical - `POST /screenshot` control endpoint with a CSS `selector` (it ALWAYS region-clips - to that element) — and combine it with the UI command bus (`hydrogen-ui`: `ui/invoke` - to open a menu/dialog, then `/screenshot` its selector). Identical across web - Hydrogen and Hydrogen. Trigger words — screenshot Hydrogen, screenshot the welcome page, - screenshot the webview, screenshot a panel, screenshot a tab, screenshot the - workspace, screenshot the editor, screenshot my screen, screenshot the whole - screen, screenshot the desktop, capture my monitor, full screen capture, - screenshot everything on screen, what does Hydrogen look like, adom-cli hydrogen - screenshot, capture panel, capture workspace, capture screen, screenshot a region, - clip to selector, screenshot an element, screenshot a menu, screenshot a dialog, - region screenshot, b64 screenshot, POST /screenshot, /shot, screenshot without flash, - no-flash screenshot, which screenshot tool, verify visually, ralph loop, shotlog, - image resizer, resize screenshot. +description: >- + Screenshot Hydrogen from inside the workspace: a panel, the whole workspace, + or the whole screen with `adom-cli hydrogen screenshot`, or one element with + POST /screenshot and a CSS selector. Use when asked to screenshot the welcome + page, a webview, a menu, my whole screen, or to verify a UI change. --- # Hydrogen — Screenshot a panel / webview / the workspace / the screen @@ -43,7 +24,7 @@ DEFAULT — reach for it first.** It's the *same* command in web Hydrogen and Hydrogen (Hydrogen is meant to behave like web Hydrogen, and `adom-cli` is the one surface that's identical on both), saves a PNG to your container's `screenshots/`, and you just `Read` it. Don't lead - with an Hydrogen-only endpoint. + with a Hydrogen-only endpoint. - **Hydrogen-only enhancement / power path — `POST /screenshot {target, selector, b64, silent}` (CDP).** Use ONLY when you need something `adom-cli` doesn't give you: a precise CSS `selector` region-clip, an inline-base64 PNG (`b64`), or a `silent` (no-flash) grab — see diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-setup/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-setup/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-setup/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-setup/SKILL.md 2026-10-22 14:42:47.195852632 -0500 @@ -1,12 +1,10 @@ --- name: hydrogen-setup -description: > - Hydrogen setup panel: the install-step cascade, Run All, Rollback All, Virgin Reset - with toggles, and automated testing patterns. MUST READ before running setup, - testing steps, or doing virgin resets. Covers the step list, the virgin - reset toggle panel, how to keep auth during resets, and how Run All handles - failures. Trigger words — setup panel, install steps, run all, virgin reset, - rollback, step failed, wipe, reset workspace, keep auth, test setup. +description: >- + Hydrogen's setup panel: the install-step cascade, Run All, Rollback All, + Virgin Reset with its toggles, keeping auth during resets, and test patterns. + Read before running setup or a virgin reset. Use when asked about the setup + panel, run all, a failed step, or reset workspace. --- # Hydrogen -- Setup Panel & Virgin Reset @@ -21,10 +19,10 @@ The Hydrogen setup process targets ZERO manual clicks for the user. The heavy lifting is already done at image-build time: the golden workspace image ships with code-server, the Adom CLIs (installed from the wiki registry package adom/hydrogen-windows-bootstrap by the update-packages step), the claude CLI + Code extension, VS -Code settings, and all `hd-*` skills BAKED IN. Setup just provisions that +Code settings, and all `hydrogen-*` skills BAKED IN. Setup just provisions that image, injects the user's session, wires up the relay, and walks the single human auth gate. If something is missing, Hydrogen downloads it — never tell the -user to install something manually. See the `hydrogen-golden-image` skill for the +user to install something manually. Read `~/.claude/skills/hydrogen-golden-image/SKILL.md` for the baked-image model. ## The Install Steps @@ -61,7 +59,7 @@ These ids no longer exist as steps: their work is baked into the golden image or folded into `update-packages` (wiki registry install of adom/hydrogen-windows-bootstrap) and `configure-vscode`: `install-the Adom CLIs`, `install-hd-skills`, `verify-adom-bridge`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`, `ensure-workspace`, `install-adom-vscode`. Do not list or "run" them. The live step list, in order, is `wait-codeserver`, `update-packages`, `activate-editor`, `set-env-vars`, `inject-api-key`, `configure-vscode`, `ensure-adom-bridge-cli`, `install-brand-fonts`, `start-relay`, `test-direct-connect`, `test-relay`, `test-adom-cli`, `install-claude-cli`, `claude-auth`, `ensure-sse`, `verify-workspace`, `welcome`, `verify-setup`, `open-welcome`. The Adom CLIs (wiki registry), the Adom CLIs, the claude CLI + Code extension, code-server, settings, and all -`hd-*` skills are baked into the golden image. See `hydrogen-golden-image`. +`hydrogen-*` skills are baked into the golden image. Read `~/.claude/skills/hydrogen-golden-image/SKILL.md`. ## Panel Buttons @@ -179,8 +177,8 @@ if the Welcome tab doesn't appear. > Note: the Adom CLIs (wiki registry package adom/hydrogen-windows-bootstrap), the claude CLI + Code extension, VS Code -> settings, and `hd-*` skills are NOT setup steps — they are baked into the -> golden image. See `hydrogen-golden-image`. +> settings, and `hydrogen-*` skills are NOT setup steps — they are baked into the +> golden image. Read `~/.claude/skills/hydrogen-golden-image/SKILL.md`. ## Workspace Recreation diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-steps/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-setup-steps/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-steps/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-setup-steps/SKILL.md 2026-10-22 14:42:47.195852632 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-setup-steps -description: What Hydrogen's setup steps did to prepare your workspace — the install sequence that provisions the golden workspace image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, ah setup, claude code extension install, the Adom CLIs install, ah workspace ready. +description: >- + What Hydrogen's setup steps did to prepare the workspace: provision the golden + image, inject the Adom session, wire the relay, walk the Claude auth gate. Use + when asked what did setup do, why is X installed, re-run a setup step, why did + step N fail, or what a virgin reset is. --- # Hydrogen Setup Steps — what was done to prepare your workspace @@ -12,11 +16,11 @@ When you first launched Hydrogen (or after a virgin reset), Hydrogen ran an install sequence to turn a blank machine into a fully-tooled Adom workspace. The heavy tooling (code-server, the Adom CLIs from the wiki registry package adom/hydrogen-windows-bootstrap, the claude CLI + Code -extension, VS Code settings, and all `hd-*` skills) is already BAKED into the +extension, VS Code settings, and all `hydrogen-*` skills) is already BAKED into the golden image; setup just provisions that image, injects your Adom session, wires up the relay, and walks the Claude auth gate. This skill explains what each phase did so you can help the user understand their environment, re-run -failed steps, or wipe and rebuild. See `hydrogen-golden-image` for the baked-image +failed steps, or wipe and rebuild. Read `~/.claude/skills/hydrogen-golden-image/SKILL.md` for the baked-image model. The cascade is halt-on-failure, resume-not-restart, with per-step 3x @@ -33,7 +37,7 @@ | set-env-vars | Set `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `ADOM_HD_CONTROL_URL`, `VSCODE_PROXY_URI`, `ADOM_DESKTOP_MODE` | | inject-api-key | Write the Adom session token into the workspace so adom-cli works | | configure-vscode | settings.json / trusted-domains / activity-bar are BAKED; re-asserts theme + workbench backstops idempotently, and applies the per-session layout | -| ensure-adom-bridge | Verify the Adom Bridge companion app is running (the relay's desktop bridge) | +| ensure-adom-bridge-cli | Verify the Adom Bridge companion app is running (the relay's desktop bridge) | | start-relay | Start the adom-bridge relay inside the workspace | | test-direct-connect | Prove the fast workspace→desktop command path | | test-relay | Register the relay with Adom Bridge for file streaming (file transfer + shell exec) | @@ -48,12 +52,12 @@ These ids no longer exist as steps: their work is baked into the golden image or folded into `update-packages` (wiki registry install of adom/hydrogen-windows-bootstrap) and `configure-vscode`: `install-the Adom CLIs`, `install-hd-skills`, `verify-adom-bridge`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`, `ensure-workspace`, `install-adom-vscode`. Do not list or "run" them. The live step list, in order, is `wait-codeserver`, `update-packages`, `activate-editor`, `set-env-vars`, `inject-api-key`, `configure-vscode`, `ensure-adom-bridge-cli`, `install-brand-fonts`, `start-relay`, `test-direct-connect`, `test-relay`, `test-adom-cli`, `install-claude-cli`, `claude-auth`, `ensure-sse`, `verify-workspace`, `welcome`, `verify-setup`, `open-welcome`. If a user asks "what installed the Adom CLIs / the Claude extension / my skills / VS Code settings", the answer is: **baked -into the golden image at build time, not a setup step.** See `hydrogen-golden-image`. +into the golden image at build time, not a setup step.** Read `~/.claude/skills/hydrogen-golden-image/SKILL.md`. ## Common user questions **"Why is X installed in my workspace?"** → If X is an Adom CLI, the -claude CLI, the Claude Code extension, VS Code settings, or an `hd-*` skill, it +claude CLI, the Claude Code extension, VS Code settings, or a `hydrogen-*` skill, it was **baked into the golden image** — not run as a setup step. The setup steps only provision the image, inject your session, wire the relay, and walk Claude auth. The setup panel (Hydrogen UI → bottom) lists every step with its current @@ -126,7 +130,7 @@ ## Related skills - your platform bootstrap's `hydrogen-setup-steps` — the concrete per-platform cascade, provisioning/wipe commands, state file, and the golden tarball -- `hydrogen-golden-image` — the baked-image model: what's pre-installed vs. what setup does +- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — the baked-image model: what's pre-installed vs. what setup does - `hydrogen-setup` — the setup-panel UX and virgin-reset toggles - `hydrogen-browser-picker` — used by claude-auth for the Claude auth OAuth flow - `hydrogen-adom-auth` — how the Adom session token (inject-api-key) gets injected diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-steps-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-setup-steps-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-steps-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-setup-steps-windows/SKILL.md 2026-10-22 14:42:47.191852488 -0500 @@ -1,24 +1,20 @@ --- name: hydrogen-setup-steps-windows -description: > - Windows/WSL2-specific details for what HD's setup did — the concrete 16-step - `setup_steps_wsl.rs` cascade, the `wsl --import Adom-Workspace` provisioning - step, the `wsl --unregister` virgin-reset mechanics, `setup-steps-wsl.json`, - and the golden `adom-golden.tar.gz` tarball. READ alongside the generic - [[hd-setup-steps]] skill when you need the exact WSL2 steps or file paths. - Trigger words — setup_steps_wsl, 16 steps wsl, wsl import, wsl unregister, - Adom-Workspace, setup-steps-wsl.json, adom-golden.tar.gz, golden distro, - ensure-workspace. +description: >- + Windows companion to hydrogen-setup-steps: the WSL2 step cascade, the `wsl + --import Adom-Workspace` step, `wsl --unregister` virgin-reset mechanics, + setup-steps-wsl.json and the golden tarball. Use for the exact WSL2 steps or + file paths. --- -# HD Setup Steps (Windows / WSL2 specifics) +# Hydrogen Setup Steps (Windows / WSL2 specifics) -This is the Windows companion to the generic [[hd-setup-steps]] skill. Read +This is the Windows companion to the generic `hydrogen-setup-steps` skill. Read that first for the user-facing Q&A ("what did setup do", "why is X installed", re-running steps, the virgin reset, and the setup-panel APIs). This page carries only the concrete WSL2 cascade, commands, and file paths. -HD runs on Windows (WSL2), Mac, and Ubuntu; on Windows the workspace is the +Hydrogen runs on Windows (WSL2), Mac, and Ubuntu; on Windows the workspace is the `Adom-Workspace` WSL2 distro. The legacy 24-step Docker cascade (`HD_RUNTIME=docker`) is in the docker/ bucket. @@ -39,16 +35,16 @@ | 4 | set-env-vars | Set `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `ADOM_HD_CONTROL_URL`, `VSCODE_PROXY_URI`, `ADOM_DESKTOP_MODE` | | 5 | inject-api-key | Write the Adom session token into the distro at `/var/run/adom/api-key` (mode 644) so adom-cli works | | 6 | configure-vscode | settings.json / trusted-domains / activity-bar are BAKED; re-asserts theme + workbench backstops idempotently, and applies the per-session layout via :8821 | -| 7 | ensure-adom-desktop | Verify the Adom Desktop companion app is running on Windows (the relay's desktop bridge) | -| 8 | start-relay | Start the adom-desktop relay inside the workspace (ports 8765 WS / 8766 HTTP) | +| 7 | ensure-adom-bridge-cli | Verify Adom Bridge (ab) is running on Windows (the relay's desktop bridge) | +| 8 | start-relay | Start the adom-bridge relay inside the workspace (ports 8765 WS / 8766 HTTP) | | 9 | test-direct-connect | Prove the fast container→desktop command path | -| 10 | test-relay | Register the relay with Adom Desktop for file streaming (file transfer + shell exec) | +| 10 | test-relay | Register the relay with Adom Bridge for file streaming (file transfer + shell exec) | | 11 | test-adom-cli | GATE: carbon path + hydrogen-proxy reachability via adom-cli (6 retries) | | 12 | claude-auth | The single human gate — restore Claude creds or drive the in-editor Claude.ai sign-in via the native browser Browser Picker; runs LAST before the payoff steps | | 13 | ensure-sse | GATE: confirm the editor browser SSE session is connected so Welcome's webview-open doesn't 409 | | 14 | verify-workspace | GATE: battery confirming the proxy holds a real layout | | 15 | welcome | Open Claude Code, authenticate if needed, send the first prompt | -| 16 | open-welcome | GATE (final): open welcome.html in HD's right pane; hard-fails if the Welcome tab doesn't appear | +| 16 | open-welcome | GATE (final): open welcome.html in Hydrogen's right pane; hard-fails if the Welcome tab doesn't appear | ## The WSL import step (step 1) @@ -81,21 +77,21 @@ The `tarball` toggle (legacy key `image`) deletes the cached `adom-golden.tar.gz` (full-image re-download). The `webview_storage` / -`vscode_state` wipes are queued and flushed at the next HD launch +`vscode_state` wipes are queued and flushed at the next Hydrogen launch (restart_required), not immediate. ## Setup state file Setup writes its state to `%APPDATA%\hydrogen-desktop\setup-steps-wsl.json` (one entry per step with -`status: pending|running|done|failed`, output text, percent complete). HD reads +`status: pending|running|done|failed`, output text, percent complete). Hydrogen reads this on launch to decide whether the setup panel auto-opens. (The legacy Docker runtime uses `setup-steps.json`.) ## Related skills -- [[hd-setup-steps]] — the generic user-facing setup-steps Q&A and APIs -- `hd-golden-image` — what's baked into `adom-golden.tar.gz` vs. what setup does -- `hd-workspace-lifecycle` — import/export/unregister/terminate, the never-touch-global-WSL rule -- `hd-networking` — port 7380 code-server, how the distro reaches the host, port forwarding -- `hd-volume` — where files live in the distro and what survives a virgin reset +- `hydrogen-setup-steps` — the generic user-facing setup-steps Q&A and APIs +- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — what's baked into `adom-golden.tar.gz` vs. what setup does +- `hydrogen-workspace-lifecycle` — import/export/unregister/terminate, the never-touch-global-WSL rule +- `hydrogen-networking` — port 7380 code-server, how the distro reaches the host, port forwarding +- `hydrogen-volume` — where files live in the distro and what survives a virgin reset diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-setup-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-setup-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-setup-windows/SKILL.md 2026-10-22 14:42:47.195852632 -0500 @@ -1,24 +1,20 @@ --- name: hydrogen-setup-windows -description: > - Windows/WSL2-specific details for HD setup — the concrete 16-step WSL2 install - cascade (setup_steps_wsl.rs), the ensure-workspace `wsl --import` of the golden - distro, the `wsl --unregister Adom-Workspace` virgin-reset mechanics, the - setup-steps-wsl.json state file, and the never-touch-global-WSL rule. READ - alongside the generic [[hd-setup]] skill when you need the exact WSL2 steps, - commands, or file paths. Trigger words — 16 steps, setup_steps_wsl, wsl import, - wsl unregister, Adom-Workspace, setup-steps-wsl.json, adom-golden.tar.gz, WSL2 - cascade, ensure-workspace, virgin reset wsl. +description: >- + Windows companion to hydrogen-setup: the WSL2 install cascade, the + ensure-workspace import, `wsl --unregister Adom-Workspace` virgin reset, + setup-steps-wsl.json, and the never-touch-global-WSL rule. Use for exact WSL2 + setup commands or file paths. --- -# Hydrogen Desktop -- Setup (Windows / WSL2 specifics) +# Hydrogen -- Setup (Windows / WSL2 specifics) -This is the Windows companion to the generic [[hd-setup]] skill. Read that +This is the Windows companion to the generic `hydrogen-setup` skill. Read that first for the setup-panel UX, Run All / Rollback All, the virgin-reset toggle panel, the keep-auth testing pattern, and the control-API triggers. This page carries only the concrete WSL2 cascade, commands, and file paths. -HD runs on Windows (WSL2), Mac, and Ubuntu; on Windows the workspace is the +Hydrogen runs on Windows (WSL2), Mac, and Ubuntu; on Windows the workspace is the `Adom-Workspace` WSL2 distro. The legacy 24-step Docker cascade (`HD_RUNTIME=docker`) is in the docker/ bucket. @@ -40,16 +36,16 @@ | 4 | set-env-vars | ADOM_CARBON_URL / ADOM_HYDROGEN_URL / ADOM_HD_CONTROL_URL / VSCODE_PROXY_URI / ADOM_DESKTOP_MODE | ✓ | | 5 | inject-api-key | Write the Adom session token to `/var/run/adom/api-key` (mode 644) | ✓ | | 6 | configure-vscode | settings.json / trusted-domains / activity-bar are BAKED; re-assert theme + workbench backstops idempotently; apply per-session layout via :8821 | ✓ | -| 7 | ensure-adom-desktop | Verify the Adom Desktop companion app is running on Windows | ✗ | -| 8 | start-relay | Start the adom-desktop relay inside the workspace (8765/8766) | ✓ | +| 7 | ensure-adom-bridge-cli | Verify Adom Bridge (ab) is running on Windows | ✗ | +| 8 | start-relay | Start the adom-bridge relay inside the workspace (8765/8766) | ✓ | | 9 | test-direct-connect | Prove the fast container→desktop command path | ✗ | -| 10 | test-relay | Register the relay with Adom Desktop for file streaming | ✗ | +| 10 | test-relay | Register the relay with Adom Bridge for file streaming | ✗ | | 11 | test-adom-cli | GATE: carbon path + hydrogen-proxy reachability via adom-cli (6 retries) | ✗ | | 12 | claude-auth | The single human gate; restore creds or drive in-editor Claude.ai sign-in; runs LAST before payoff | ✓ | | 13 | ensure-sse | GATE: editor browser SSE session connected so Welcome's webview-open doesn't 409 | ✗ | | 14 | verify-workspace | GATE: battery confirming the proxy holds a real layout | ✗ | | 15 | welcome | Opens Claude Code, authenticates if needed, sends the first prompt | ✗ | -| 16 | open-welcome | GATE (final): opens welcome.html in HD's right pane; hard-fails if the Welcome tab doesn't appear | ✗ | +| 16 | open-welcome | GATE (final): opens welcome.html in Hydrogen's right pane; hard-fails if the Welcome tab doesn't appear | ✗ | ## Step 1 — ensure-workspace (WSL2 import) @@ -83,19 +79,19 @@ The `tarball` toggle (legacy key `image`) deletes the cached `adom-golden.tar.gz`, forcing a full-image re-download. The `webview_storage` / -`vscode_state` wipes are queued and flushed at the next HD launch +`vscode_state` wipes are queued and flushed at the next Hydrogen launch (restart_required); there is no reboot for the wipe. ## Setup state file Setup writes its state to `%APPDATA%\hydrogen-desktop\setup-steps-wsl.json` (one entry per step with -`status: pending|running|done|failed`, output text, percent complete). HD +`status: pending|running|done|failed`, output text, percent complete). Hydrogen reads this on launch to decide whether the setup panel auto-opens. (The legacy Docker runtime uses `setup-steps.json`.) ## Related skills -- [[hd-setup]] — the generic setup-panel UX, buttons, virgin-reset toggles, and control-API triggers -- `hd-golden-image` — what's baked into `adom-golden.tar.gz` -- `hd-workspace-lifecycle` — import/export/unregister/terminate mechanics and the never-touch-global-WSL rule +- `hydrogen-setup` — the generic setup-panel UX, buttons, virgin-reset toggles, and control-API triggers +- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — what's baked into `adom-golden.tar.gz` +- `hydrogen-workspace-lifecycle` — import/export/unregister/terminate mechanics and the never-touch-global-WSL rule diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-skill-catalog/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-skill-catalog/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-skill-catalog/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-skill-catalog/SKILL.md 1969-12-31 18:00:00.000000000 -0600 @@ -1,118 +0,0 @@ ---- -name: hydrogen-skill-catalog -description: The catalog of skills available to your Claude inside this Hydrogen workspace. Lists every public `hd-*` skill that ships with Hydrogen and explains what each one is for, so you can pick the right skill before doing anything Hydrogen-related. READ THIS FIRST when you're in a fresh Hydrogen workspace and want to know what Claude knows. Trigger words — hd skills, what skills do I have, hd catalog, skill index, skill list, what can claude do in hd, hd-* skills, browser picker, hd setup, hd container info, hd networking, hd volume, hd ports. ---- - -# Hydrogen Skill Catalog - -You're running inside a Hydrogen workspace: the **WSL2 Ubuntu distro -`Adom-Workspace`**. Hydrogen ships a curated catalog of public skills (all -named `hd-*`) so your Claude knows about Hydrogen's own interface, networking, setup -flow, and gotchas. They are BUNDLED into the Hydrogen bootstraps (adom/hydrogen-bootstrap ships the shared/ set, adom/hydrogen-windows-bootstrap the wsl2/ set) and deployed **flat into -`~/.claude/skills/<name>/SKILL.md`** automatically. - -## How the catalog is bucketed (and what you actually have) - -The public skills live in two buckets in the Hydrogen repo under -`skills/public-facing/`: - -- **`shared/`** — topics that do not depend on the workspace's internals. -- **`wsl2/`** — the topics that are specific to the `Adom-Workspace` distro. - -The bootstraps deploy both buckets: `shared/` rides adom/hydrogen-bootstrap and the -`wsl2/` set rides adom/hydrogen-windows-bootstrap. You get the whole catalog. - -## Shared skills (always present) - -| Skill | What it covers | -|-------|----------------| -| `hydrogen-skill-catalog` | This file — read first to know what's available. | -| `hydrogen-golden-image` | Your workspace starts from a PRE-BAKED golden image (v27-full): the Adom toolchain (skills, CLIs, editor extensions) ships INSIDE the tarball; setup converges it to the latest published versions rather than installing from scratch. Read it before claiming what is or is not in the image. | -| `hydrogen-skill-loop` | (Maintainers) The loop to fix a wrong/stale Hydrogen skill: verify vs the live Hydrogen, fix it live, write it back to the repo, bake it into the next image. | -| `hydrogen-who-am-i` | Answer "who am I / what can I do here" — the auto-question Hydrogen injects on first launch. | -| `hydrogen-adom-auth` | Adom login/logout, auth intent flow, session token, profile menu. | -| `hydrogen-claude-auth` | How Claude Code signs in: OAuth via Browser Picker, credential backup, the `claude-auth` step. | -| `hydrogen-api` | Control API reference (`127.0.0.1:47084`). | -| `hydrogen-desktop-sse` | Hydrogen's local workspace API + SSE — adom-cli inside the workspace talks to Hydrogen, not cloud Hydrogen. | -| `hydrogen-monitor` | Watch the workspace in real-time via SSE; composes with Claude's Monitor tool. | -| `hydrogen-ui` | Hydrogen's menus, dialogs, panels, programmatic UI control via CDP, CSS selectors. | -| `hydrogen-open-url` | The decision guide for "open a website": the six ways to open a URL (webview tab, Hydrogen window, Pup, native browser, picker, headless curl) and when to pick each. | -| `hydrogen-browser-picker` | Every URL Hydrogen opens routes through a 5-layer interception into a picker dialog (AI-friendly 5s countdown). | -| `hydrogen-wiki-review` | After editing any wiki.adom.inc page, load it in pup so the user can review the rendered result (don't just report the commit). | -| `hydrogen-claude-management` | First-class API for the Claude conversation tabs: list/open/close/switch, read per-conversation state + on-disk session GUID, type into a SPECIFIC conversation (instant/animated) + submit, and turn on Remote Control for a claude.ai/mobile cloud URL. Address by stable context id. | -| `hydrogen-permissions` | Why mic/camera/clipboard/notifications "just work" — Hydrogen auto-grants WebView2 permissions, so webview apps see no Allow prompts. | -| `hydrogen-adom-bridge` | What Hydrogen and Adom Bridge (ab) are + how they work together — ab is your reach onto the user's real OS (create files/folders, run shell, OS screenshots, launch apps, browsers, KiCad/Fusion). | -| `hydrogen-bridges` | Built-in KiCad/Fusion/Puppeteer bridges + extensible wiki catalog (e.g. Blender) + full ab capability list (usb, caption, record…). | -| `hydrogen-eval` | Inject JS into ANY Hydrogen surface (shell/workbench/wiki/Claude) via POST /eval-in; build add-ons, overlays, highlights. | -| `hydrogen-adom-menu` | The upper-left Adom logo menu: Settings, Ports, API Explorer, Doctor, Run Wake Check, DevTools, Setup Steps, Virgin Reset, About dialog, version readout. | -| `hydrogen-doctor` | The Doctor (Adom menu + GET/POST /doctor): 18 end-to-end health checks with plain-English hover explanations, a safe one-click fix, and a confirm-gated workspace restart. | -| `hydrogen-key-values` | The user's cloud KV store (hydrogen.* / bridge.* keys): read/write API, conventions (no secrets, scalar values), runtime-discovery entries, and the profile-menu viewer. | -| `hydrogen-settings` | Hydrogen's Settings dialog + the full preferences tree (theme, vim mode, 3D control style, launch-on-boot, ab window behavior). | -| `hydrogen-dock` | The app launcher rail: the adom-curated global list + user-added wiki apps, the dock block apps declare so Hydrogen can launch them, and the free orbital loading screen. | -| `hydrogen-file-transfer` | Move files BOTH ways between the WSL2 workspace and the Windows PC (/mnt/c, \\wsl$, adom-bridge relay). | -| `hydrogen-tab-icons` | Webview tab icon customization (displayIcon API, brand colors, MDI/SVG). | -| `hydrogen-profile-menu` | The avatar dropdown: profile/repos/molecules links and logout. | -| `hydrogen-embedded-ad` | Hydrogen ↔ Adom Bridge embedded mode: tray, hidden ab, footer pill. | -| `hydrogen-self-screenshot` | How Claude screenshots Hydrogen panels + any host window (window control, multi-monitor), ralph loops, resize-before-Read rule. | -| `hydrogen-capture-share` | The screen-share + "AI wants access" approval + countdown the AI triggers to capture the editor; tab/screen scopes, Webview/Pup window mode. | -| `hydrogen-recording` | Record screen/window — Hydrogen's NATIVE WGC/DXGI recorder (h264/h265 mp4 → `recordings/`, no picker/banner, "record kicad"/"record whole screen", max-duration cap), plus ab desktop recording + the tab-vs-desktop footgun. | -| `hydrogen-screen-lock` | Hydrogen screen capture and the display wake-lock: Hydrogen's native screenshots (CDP) + recording (WGC/DXGI) hold NO wake-lock, so Hydrogen has no burn-in leak; the cap + "● Recording" indicator; `powercfg /requests` to diagnose. | -| `hydrogen-notifications` | Reach the user — OS Windows toasts + emergency taskbar flash via `notify_user`, AND the in-app `POST /ui/toast` (toast inside the Hydrogen window). | -| `hydrogen-captions` | Paint labeled text on the user's screen — a Win32 always-on-top caption overlay for demos / step callouts. | -| `hydrogen-welcome` | The static welcome page shown after setup completes. | -| `hydrogen-overview` | Master skill index, grouped by category. | - -## Workspace skills (the `wsl2/` bucket) - -| Skill | What it covers | -|-------|----------------| -| `hydrogen-container` | This workspace's spec — Ubuntu 24.04, code-server 4.112.0, what's pre-installed, env vars. | -| `hydrogen-topology` | The three layers and how commands route to reach the workspace. | -| `hydrogen-networking` | Port architecture, hostnames, code-server proxy, host access, NEVER-do-these rules. | -| `hydrogen-ports` | Forwarding workspace services to Windows. | -| `hydrogen-port-watcher` | The dynamic port-forward daemon for extension OAuth callbacks. | -| `hydrogen-volume` | Where your code lives, what persists, what a reset wipes, how to copy files out. | -| `hydrogen-container-stats` | The title-bar CPU/RAM indicator and how its stats are gathered. | -| `hydrogen-setup` | The setup panel UI — Run All, Rollback, Virgin Reset toggles. | -| `hydrogen-setup-steps` | What each setup step did to tool your workspace. | -| `hydrogen-workspace-lifecycle` | Starting, stopping, restarting and repairing the `Adom-Workspace` distro. | -| `hydrogen-workspace-monitoring` | Frontend monitoring of the workspace distro's health. | -| `hydrogen-wake-repair` | Recovering the workspace after the laptop sleeps or wakes. | -| `hydrogen-annotate` | Annotate: the Title Bar pencil / Win+Alt+A screen overlay — draw, snip, share the capture with the AI. | -| `hydrogen-editor-state` | The Editor State Machine — the true VS Code / Claude conversation state and the hard typing invariants (`/editor/*`). | -| `hydrogen-lightbulb` | The 💡 sample-prompts menu in the title bar and sample-prompts.json. | -| `hydrogen-project-workspaces` | The Project workspaces menu (benches from `hydrogen/workspace.json`) and its `/workspaces/*` API. | -| `hydrogen-widget` | Title Bar widgets (Claude/Codex/Antigravity usage, clock, your own): build, list, open, drive. | -| `hydrogen-webview-windows` | hbw, Hydrogen's standalone browser window (`/hbw/open`). | -| `hydrogen-dock-windows` | Driving the dock from an AI thread (`/dock/*`) and resetting it to the defaults. | -| `hydrogen-adom-bridge-triage` | Adom Bridge won't connect: the crash.log-first ladder, comparing and reinstalling the Windows build, WSL2 interop. | - -## What's NOT in your workspace — internal dev skills - -The Hydrogen repo also has skills under `skills/dev-internal-facing/` (hydrogen-debug, hydrogen-dev, -hydrogen-pitfalls, hydrogen-settings, an internal hydrogen-setup-steps deep-dive, -hydrogen-vm-test, and more). These are **Adom-employee-only development skills** — Hydrogen -build pipeline, debugging the Tauri/WebView2 source, internal architecture, -postmortems. They live in the Hydrogen repo but are **NEVER** deployed to user -workspaces. - -The split is enforced by the bootstrap bundling, which only ships -`skills/public-facing/{shared,wsl2}/hd-*/` — never `dev-internal-facing/`. - -| Folder | Audience | Deployed to user workspaces? | -|--------|----------|------------------------------| -| `public-facing/shared/` | End users of Hydrogen | **Yes** | -| `public-facing/wsl2/` | End users of Hydrogen | **Yes** | -| `dev-internal-facing/` | Adom employees who develop Hydrogen | **No** (repo-only) | - -## How to use this catalog - -1. In a fresh Hydrogen workspace, scan this table for the most relevant `hd-*` skill - before answering an Hydrogen-related question. -2. Skill descriptions are loaded automatically by skill-pilot at session start. -3. If a topic seems missing, it may be a dev-internal-facing skill (repo-only) — - ask the user to check the Hydrogen repo. - -## When skills get refreshed - -Skills are deployed by the bootstrap postinstall at install/bake time. To refresh after a skills change, the workspace picks up new bootstrap versions via `adom-wiki pkg update` (the `adom/hook` prompt hook) — or a fresh golden image. There is no `install-hd-skills` setup step (removed). diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-skill-loop-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-skill-loop-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-skill-loop-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-skill-loop-windows/SKILL.md 2026-10-22 14:42:47.195852632 -0500 @@ -1,25 +1,22 @@ --- name: hydrogen-skill-loop-windows -description: > - The maintainer loop for making HD's own hd-* skills perfect: when a skill is - wrong, stale, or confusing, verify the truth against the RUNNING HD, fix the - skill live in the workspace, then write the corrected file back into the core - hydrogen-desktop repo so the next golden-image bake ships it. These skills are - the ONLY thing the in-workspace AI knows about HD — a wrong one confuses every - Adom user. For Adom devs improving HD. Trigger words — this skill is wrong, - stale skill, fix the hd skill, update a skill, the AI got confused by a skill, - improve hd skills, skill is inaccurate, debug a skill, skill loop, write skill - back to repo, bake skills, golden image skills, skill feedback loop, perfect - the skills, skill says X but it actually does Y. +description: >- + Maintainer loop (Windows/ah) for fixing a wrong Hydrogen skill: verify against + the running Hydrogen, fix the live copy, fix the text source (ah repo for + hydrogen-* bootstrap skills, else the wiki page repo), publish. Companion to + hydrogen-skill-loop. Use when a skill is wrong or stale. +disable-model-invocation: true --- -# HD Skill Loop — verify → fix live → write back to the repo → bake +# Hydrogen Skill Loop (Windows) — verify → fix live → fix the source → publish -HD's `hd-*` skills are baked into the WSL2 golden image and are the **only** way -the in-workspace AI knows anything about HD. So a wrong skill silently breaks +Windows companion to `hydrogen-skill-loop` (the generic loop; this page adds +the ah-repo checkout and laptop specifics). Hydrogen's `hydrogen-*` skills ship +in the bootstrap wiki packages (and are baked into the WSL2 golden image) and +are the **only** way the in-workspace AI knows anything about Hydrogen. So a wrong skill silently breaks every user's AI (it curls a dead hostname, hunts a command that doesn't exist, claims it needs a tool that isn't installed…). This skill is the loop to find -those and make them perfect *before* the next bake. +those and make them perfect. ## Cardinal rule: TEST, don't assert @@ -28,14 +25,27 @@ code. Observe the real return shape. If you can't test a claim, don't state it as fact. (Most skill bugs are confident, untested assertions.) -## Where skills live — two copies +## Where skills live — the text source depends on the package | Copy | Path | Role | |---|---|---| -| **Live (ephemeral)** | `~/.claude/skills/<name>/SKILL.md` (flat) | What the running AI reads NOW. Editing here fixes THIS session and lets you test — but it's wiped on virgin reset / replaced by the next image. | -| **Canonical (baked)** | repo `skills/public-facing/{shared,wsl2,docker}/<name>/SKILL.md` | What the golden image is built from. On the laptop the repo is auto-mounted at `/mnt/c/Github/hydrogen-desktop/...` (the same tree the install step reads). The bake pulls from `origin`. | +| **Live (ephemeral)** | `~/.claude/skills/<name>/SKILL.md` (flat) | What the running AI reads NOW. Editing here fixes THIS session and lets you test — but the next `adom-wiki pkg update` (or a virgin reset) replaces it. | +| **Shipped (wiki package)** | the package's wiki page repo (`adom-wiki repo clone adom/<pkg>`) | What every workspace installs. A fix isn't live for users until it is published here. | +| **Text source for `hydrogen-*` bootstrap skills** | ah repo `skills/public-facing/{shared,wsl2}/<name>/SKILL.md` (on the laptop: `/mnt/c/Github/hydrogen-desktop/...`) | Where the adom/hydrogen-bootstrap and adom/hydrogen-windows-bootstrap skill text is authored. `scripts/publish-skills-to-bootstrap.sh <name>…` clones the bootstrap wiki repo and refuses to clobber lines that exist only on the wiki. | + +So: +- **`hydrogen-*` bootstrap skills:** the ah repo is the text source. A direct + fix in the wiki page repo is safe (the publish script will not overwrite + wiki-only lines; it aborts and prints them) but must be back-ported into + `skills/public-facing/` or the next publish from the repo has to merge it by + hand. Note: the script publishes adom/hydrogen-bootstrap and refuses skills + that live in the Windows layer, so a Windows-layer skill is published from a + clone of adom/hydrogen-windows-bootstrap and then back-ported to `wsl2/`. +- **Every other package:** the source is that package's wiki page repo; fix + it there and publish (see `hydrogen-skill-loop`). -A fix isn't done until it's in the **canonical** copy and pushed. +A fix isn't done until it's published AND (for `hydrogen-*` bootstrap skills) +back in the ah repo. ## The loop @@ -45,18 +55,19 @@ ### 2. Get ground truth from the LIVE system - **Run the real command** and read its `--help` and actual output: `adom-cli hydrogen <verb> --help` → then run it → note the EXACT return shape - (e.g. HD's `screenshot` returns a `dataUrl` inline when `uploadFailed:true`, + (e.g. Hydrogen's `screenshot` returns a `dataUrl` inline when `uploadFailed:true`, not a saved path). - **Read the live env**, never hardcode: `cat ~/.adom/hd-control-url` (the real control URL — `http://127.0.0.1:<dynamic-port>`, NOT `host.docker.internal`, NOT a fixed 47084), `env | grep ADOM_`, `adom-cli hydrogen probe`. -- **Read the HD source** for the endpoint/behavior (the repo checkout). -- **Not inside HD?** `adom-cli` is the SAME binary in web Hydrogen — test there. - Or reach the user's running HD through Adom Desktop: +- **Read the Hydrogen source** for the endpoint/behavior (the ah repo checkout). +- **Not inside Hydrogen's workspace?** `adom-cli` is the SAME binary in hc + (Hydrogen Cloud) — test there. Or reach the user's running Hydrogen through + Adom Bridge: ```bash - adom-desktop ping && adom-desktop status # confirm AD is on the right host - # run anything inside the HD distro: - adom-desktop wsl_exec '{"distro":"Adom-Workspace","user":"adom","scriptB64":"<base64 of your script>"}' + adom-bridge ping && adom-bridge status # confirm ab is on the right host + # run anything inside the Hydrogen distro: + adom-bridge wsl_exec '{"distro":"Adom-Workspace","user":"adom","scriptB64":"<base64 of your script>"}' ``` ### 3. Fix it live + re-test @@ -65,39 +76,50 @@ ### 3b. GRADE the fix (don't just eyeball it) Re-running the action by hand proves little. If you're an Adom maintainer, run the -**`hd-skill-test`** grader (dev-internal): add/update a case encoding the *correct* +grader from the ah repo's dev-internal `hd-skill-test` skill +(`skills/dev-internal-facing/hd-skill-test/`, `scripts/skill-test/`; not installed in workspaces): add/update a case encoding the *correct* behavior plus the anti-pattern that was the bug (e.g. `must_not_appear: host\.docker\.internal`), then grade against the live (fixed) skill via a fresh headless `claude` session. PASS means the fix actually changed model behavior, not just the prose. Gate the write-back/commit on a green battery so fixing skill A -can't silently regress skill B. (See the `hd-skill-test` skill.) +can't silently regress skill B. ### 4. Pick the bucket Runtime-neutral → `shared/`; runtime-specific → `wsl2/` (+ keep `docker/` -pristine). `name:` must equal the dir; skills install flat. (See the dev skill -`hd-skills-structure` for the full rules.) +pristine). `name:` must equal the dir; skills install flat. (The ah repo's +dev-internal `skills/dev-internal-facing/hd-skills-structure/` has the full rules.) -### 5. Write the corrected file back to the repo -Copy the same corrected SKILL.md into the canonical bucket: +### 5. Fix the source and publish +For a `hydrogen-*` skill in adom/hydrogen-bootstrap, copy the corrected file +into the ah repo and run the publish script: ```bash cp ~/.claude/skills/<name>/SKILL.md \ /mnt/c/Github/hydrogen-desktop/skills/public-facing/<bucket>/<name>/SKILL.md +bash scripts/publish-skills-to-bootstrap.sh <name> # from the ah repo root ``` -If you added / renamed / removed a skill, also update the indexes -`hd-overview` and `hd-skill-catalog` (both in `shared/`). +For a Windows-layer skill (this package), clone adom/hydrogen-windows-bootstrap, +apply the same edit, bump the version, `adom-wiki pkg publish`, push the page +repo (`adom-wiki repo push`), then copy the file into the ah repo's +`skills/public-facing/wsl2/<name>/`. For any other package, follow +`hydrogen-skill-loop` step 4. + +If you added / renamed / removed a skill, also update the index skill +`hydrogen-overview` (in adom/hydrogen-bootstrap). A package update does not +prune skills an older version delivered: add the old name to the prune list in +the package's `install.sh`. -### 6. Commit + push so the next bake ships it +### 6. Commit + push the ah repo From the laptop checkout (it has git + credentials), via the relay: ```bash -adom-desktop run_script '{"interpreter":"powershell","scriptB64":"<base64 of: - cd C:\Github\hydrogen-desktop; git add skills; git commit -m \"skills: fix <name> (verified vs live HD)\"; git push>"}' +adom-bridge run_script '{"interpreter":"powershell","scriptB64":"<base64 of: + cd C:\Github\hydrogen-desktop; git add skills; git commit -m \"skills: fix <name> (verified vs live Hydrogen)\"; git push>"}' ``` The next **golden-image bake** (`golden-image-bake`) pulls `origin` and bakes the -corrected skills into the image, so the fix reaches every user's next HD. +corrected skills into the image, so new installs start with the fix. ## Validation checklist before you commit a skill - [ ] Every command in the skill was actually RUN and produced the documented output. -- [ ] No `host.docker.internal` anywhere — HD reaches the host at `127.0.0.1` / +- [ ] No `host.docker.internal` anywhere — Hydrogen reaches the host at `127.0.0.1` / `$(cat ~/.adom/hd-control-url)` (WSL2 mirrored networking; ports are dynamic). - [ ] No invented CLI verbs — each confirmed with `--help`. - [ ] No tool assumed present that isn't in the golden image (ImageMagick `convert`, @@ -107,14 +129,14 @@ - [ ] `name:` matches the directory. ## Why this matters -The skills ARE HD's self-knowledge for the AI. Ship them wrong and every Adom +The skills ARE Hydrogen's self-knowledge for the AI. Ship them wrong and every Adom user's AI is confidently wrong with them. Treat "the skill is inaccurate" as a product bug and run this loop until the validation checklist is clean. ## Related skills -- `hd-skill-test` (dev-internal) — the automated GRADE step (step 3b): headless-`claude` battery that asserts tool choices / forbidden patterns -- `hd-skills-structure` (dev-internal) — bucket rules, naming, the deploy/bake mechanism -- [hd-golden-image](../hd-golden-image/SKILL.md) — the baked-image model these skills ship in -- `golden-image-bake` — the tooling that rebuilds the image from the repo -- [hd-self-screenshot](../hd-self-screenshot/SKILL.md) — a skill fixed via this loop (the `adom-cli hydrogen screenshot` / `dataUrl` truth) -- [hd-desktop-sse](../hd-desktop-sse/SKILL.md) — the adom-cli → HD-proxy → SSE interception model you test against +- `hydrogen-skill-loop` — the generic loop (wiki package as the shipped source, both wiki surfaces) +- `hydrogen-golden-image` — the baked-image model these skills ship in +- `golden-image-bake` — the tooling that rebuilds the image from the repo (ah repo, dev-internal) +- `hydrogen-self-screenshot` — a skill fixed via this loop (the `adom-cli hydrogen screenshot` / `dataUrl` truth) +- `hydrogen-desktop-sse` — the adom-cli → Hydrogen proxy → SSE interception model you test against +- ah repo dev-internal (not installed): `hd-skill-test` (the automated GRADE step 3b), `hd-skills-structure` (bucket rules, naming, deploy/bake) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-topology/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-topology/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-topology/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-topology/SKILL.md 2026-10-22 14:42:47.199852775 -0500 @@ -1,20 +1,41 @@ --- name: hydrogen-topology -description: > - MUST READ before ANY Hydrogen work. Explains the three-layer topology: cloud - Docker (where Claude runs), Windows machine (where Hydrogen + Adom Bridge run), - and the Hydrogen local WSL2 workspace (the Adom-Workspace distro). Every command - you run goes through the relay to Windows. You CANNOT directly access the - WSL2 distro — you must shell through Windows. Trigger words — Hydrogen topology, - cloud vs local, wsl exec, where am I, which workspace, adom-bridge - relay, test from container, three tiers, architecture, windows machine. +description: >- + Where Claude runs relative to Hydrogen: inside the local Adom-Workspace WSL2 + distro, or in a cloud container driving the user's PC through the relay, and + how to reach Windows and the workspace from each. Use when asked where am I, + cloud vs local, wsl exec, reach the workspace, or adom-bridge relay. --- -# Hydrogen — Topology (READ FIRST) +# Hydrogen — Topology WSL2-runtime version (default). Legacy Docker container runtime (`HD_RUNTIME=docker`) is in the docker/ bucket. -## You are NOT on the user's machine +Up to three environments are involved in Hydrogen work: the user's **Windows +PC** (where Hydrogen (ah) and Adom Bridge (ab) run), Hydrogen's **local WSL2 +workspace** on that PC (the `Adom-Workspace` distro), and optionally an **Adom +cloud container** (hc). Where YOU run decides how you reach the other two, so +check first: `adom-context` prints a "Where:" line that says which case you +are in. + +## Case 1: you run inside the local workspace (the default on ah) + +You (Claude) run inside the `Adom-Workspace` distro on the user's own PC. + +- Your shell, `/home/adom/project` and your git repos are in the distro. +- Hydrogen's control API is local: `$(cat ~/.adom/hd-control-url)` (WSL2 + mirrored networking shares loopback with Windows). +- Windows files are directly reachable at `/mnt/c` (read and copy them with + ordinary shell tools; no relay needed). +- Windows commands, apps, windows and screenshots go through Adom Bridge: + `adom-bridge <verb>` reaches ab on this PC through the workspace's local + relay (second chain under "The Relay Chain" below). When `adom-context` + lists more than one machine, pass `--target <name>`. +- You are already in the distro: run workspace commands directly, never + `wsl -d Adom-Workspace …`. Terminating or restarting the distro kills your + own shell, so do it only when the user asks. + +## Case 2: you run in a cloud container, driving the user's PC You (Claude) run inside an **Adom cloud Docker container**. The user's Windows machine is a remote target you reach through the `adom-bridge` @@ -29,7 +50,7 @@ ### 2. Windows Machine (user's desktop) - **Adom Bridge** — relay client app, listens on port 8770 (direct connect) -- **Hydrogen** — the Tauri app you're building +- **Hydrogen** — the Tauri desktop app - **WSL2** — hosts the `Adom-Workspace` distro - You reach this via `adom-bridge shell_execute '{"command":"..."}'` - Commands run in `cmd.exe` on Windows @@ -42,6 +63,10 @@ ## Command Patterns +These are written for case 2. In case 1, run workspace commands directly +(drop the `wsl -d Adom-Workspace -u adom --` wrapper) and read Windows files +from `/mnt/c`; the `adom-bridge` verbs work the same from both. + ### Run something on Windows ```bash adom-bridge shell_execute '{"command":"dir C:\\Github"}' @@ -63,12 +88,12 @@ adom-bridge desktop_screenshot_window '{"hwnd":HWND}' ``` -### Pull file from Windows to cloud +### Pull file from Windows to cloud (case 1: just `cp` from `/mnt/c`) ```bash adom-bridge pull_file '{"filePaths":["C:\\path\\file"],"saveTo":"/tmp"}' ``` -## The WSL2 distro ≠ Your Container +## The WSL2 distro ≠ Your Container (case 2) - If the `Adom-Workspace` distro on Windows goes down, YOUR cloud container is fine - You can still talk to Adom Bridge, screenshot windows, run shell commands @@ -115,10 +140,13 @@ ## NEVER Do These +Rules 1-3 are for case 2 (cloud container); 4-5 apply in both cases. + 1. **NEVER confuse your cloud Docker with the Hydrogen local WSL2 workspace.** `curl http://127.0.0.1:8766/health` hits YOUR relay, not the workspace's. 2. **NEVER try to `wsl -d Adom-Workspace` from your shell.** - The distro lives on Windows WSL2, not here. + From a cloud container the distro lives on Windows WSL2, not here; from + inside the distro you are already in it. 3. **NEVER assume the workspace's status affects your container.** They're completely independent. 4. **NEVER run a global `wsl --shutdown` or `wsl --unregister` of anything @@ -128,5 +156,5 @@ ## Related skills -- `hydrogen-container` — facts about the `Adom-Workspace` distro you run inside +- `hydrogen-container` — facts about the `Adom-Workspace` distro (where you run in case 1) - `hydrogen-volume` — where your files live and how to back up / copy out the distro diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-ui/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-ui/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-ui/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-ui/SKILL.md 2026-10-22 14:42:47.199852775 -0500 @@ -1,15 +1,10 @@ --- name: hydrogen-ui -description: > - Hydrogen's user interface: menus, dialogs, panels, login/logout, profile menu, - workspace layout, setup panel — and how to DRIVE them from the workspace via - the UI command bus (GET /ui/actions → POST /ui/invoke), the first-class way to - open/close/toggle any Hydrogen menu or dialog (no CDP clicking). READ when the user - asks you to open/close a dialog or menu, operate Hydrogen's UI, or you need to know - where a UI element is. Trigger words — Hydrogen menu, Hydrogen dialog, Hydrogen panel, open - dialog, open menu, close dialog, drive UI, ui/actions, ui/invoke, command bus, - ports.open, settings.open, about dialog, profile menu, login, logout, settings, - setup panel, Adom menu, Hydrogen UI. +description: >- + Hydrogen's interface (menus, dialogs, panels, profile menu, setup panel) and + how to drive it from the workspace via the UI command bus (GET /ui/actions, + POST /ui/invoke) instead of clicking. Use when asked to open or close a + Hydrogen dialog or menu, or where a UI element is. --- # Hydrogen — UI Reference @@ -134,7 +129,7 @@ ``` 3. **Not in the list?** That absence is the signal: the element isn't wired to the bus yet. It needs a 2-line `registerUiAction(...)` in its Svelte component (a dev change in the - hydrogen-desktop repo — see that repo's `hydrogen-ui-actions` skill). Don't fall back to clicking; + ah repo, hydrogen-desktop). Don't fall back to clicking; wire it. The response's `_hints.if_missing` says the same. Common ids (always `GET /ui/actions` for the live set): `adom-menu.open`/`.close`, diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-volume/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-volume/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-volume/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-volume/SKILL.md 2026-10-22 14:42:47.199852775 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-volume -description: How Hydrogen's WSL2 workspace storage is laid out — what's persistent, what's ephemeral, where your work lives, what survives a workspace restart vs a virgin reset, and how to access your workspace files from your Windows host. Use when the user asks "where are my files", "did I lose my work", "how do I copy a file out of the workspace", or "what happens to my code if I virgin reset". Trigger words — wsl filesystem, hd volume, where are my files, workspace files, persistent storage, lost my work, /home/adom/project, distro filesystem, wsl export, copy file out of workspace, where is my code, workspace backup, wsl unregister. +description: >- + Where files live in Hydrogen's WSL2 workspace, what survives a restart versus + a virgin reset, and how to reach them from Windows. Use when asked where are + my files, did I lose my work, how do I copy a file out, or what happens to my + code if I virgin reset. --- # Hydrogen Workspace Storage — what persists, what doesn't @@ -112,4 +116,4 @@ - `hydrogen-container` — the `Adom-Workspace` distro whose filesystem holds your work - `hydrogen-topology` — the three-tier topology; tier 3 is this WSL2 distro -- `hydrogen-golden-image` — what's baked into `adom-golden.tar.gz` (extensions, settings, skills) vs. what setup does +- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — what's baked into `adom-golden.tar.gz` (extensions, settings, skills) vs. what setup does diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-wake-repair/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-wake-repair/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-wake-repair/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-wake-repair/SKILL.md 2026-10-22 14:42:47.203852922 -0500 @@ -1,18 +1,10 @@ --- name: hydrogen-wake-repair -description: > - How Hydrogen automatically repairs the workspace connection after the - laptop wakes from sleep: the wake-heal cascade, the header wake indicator with - its live info tooltip, the Settings > Desktop > Wake section (heal toggle, - indicator toggle, linger slider), and the /wake/* control API endpoints. Read - this when the user reports Hydrogen did not reconnect after sleep, sees a "cannot - reconnect" dialog, asks what the sunrise/sync icon in the header is, or wants - to test or configure wake behavior. - Trigger words: wake from sleep, laptop sleep, lid close, sleep resume, resume - from sleep, reconnect after sleep, wake repair, wake heal, wake indicator, - sunrise icon, cannot reconnect, workspace stuck after wake, wake status, - wake simulate, wake settings, run wake check, wake check menu, backend - banner, workspace stopped responding, reconnect button. +description: >- + How Hydrogen repairs the workspace connection after the laptop wakes from + sleep: the wake-heal cascade, the header wake indicator, Settings > Desktop > + Wake, and the /wake/* API. Use when Hydrogen didn't reconnect after sleep, a + cannot reconnect dialog appears, or asked about the sunrise icon. --- # Hydrogen Wake Repair (reconnect after laptop sleep) diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-webview-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-webview-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-webview-windows/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-webview-windows/SKILL.md 2026-10-22 14:42:47.203852922 -0500 @@ -1,7 +1,9 @@ --- name: hydrogen-webview-windows -description: > - Windows-only webview surface: hbw, Hydrogen's standalone built-in browser window (POST /hbw/open). Trigger words — hbw, hydrogen browser window, standalone browser window, /hbw/open. +description: >- + Windows companion to hydrogen-webview: hbw, Hydrogen's standalone built-in + browser window (POST /hbw/open). Use when asked for a hydrogen browser window + or a standalone browser window. --- # hydrogen-webview-windows — Windows companion to hydrogen-webview diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-widget/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-widget/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-widget/SKILL.md 2026-10-22 14:26:53.460214847 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-widget/SKILL.md 2026-10-22 14:42:47.203852922 -0500 @@ -1,10 +1,14 @@ --- name: hydrogen-widget -description: "Build, list, open and drive Hydrogen Widgets: small live panels in Hydrogen Desktop's Title Bar (Claude usage, Codex usage, a clock, or your own), each served by a binary inside the workspace and mounted in a sandboxed slot. Covers the hydrogen-widget.json facet a wiki repo carries (alone, or next to its dock manifest and project workspace), the per-widget page the pulldown links to, the launch contract (HYDROGEN_WIDGET_ID / _PORT / _SLOT / HYDROGEN_PROXY_PORT, the health URL, the explicit takeover, stop-first relaunch), the tall and compact layouts, vendor marks, private repos (read with the user's session), the curated list on adom/hydrogen-bootstrap, the Hydrogen Widgets pulldown, and the control API (GET /widgets, POST /widgets/open|close|navigate|refresh|menu, GET /widgets/status) so an AI can do all of it with no mouse. Trigger words: hydrogen widget, hydrogen-widget, title bar widget, widgets pulldown, widget slot, claude usage widget, codex usage widget, tokens left widget, usage meter in the title bar, hydrogen-widget.json, /widgets/open, make a widget, add a widget to hydrogen, private widget, widget SDK." +description: >- + Build, list, open and drive Hydrogen Widgets, small live panels in the Title + Bar (Claude usage, Codex usage, your own): the hydrogen-widget.json facet, + launch contract, and /widgets API. Use when asked to make a widget, add a + title bar widget, or about the usage meter widget. version: 1.5.7 --- -# hydrogen-widget: small live panels in Hydrogen Desktop's Title Bar +# hydrogen-widget: small live panels in Hydrogen's Title Bar The bar across the top of the Hydrogen window is the **Title Bar**: the Adom menu, the widgets, the CPU/RAM/GPU meter, the bell, your avatar and the window controls. Its short form diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-lifecycle/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-workspace-lifecycle/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-lifecycle/SKILL.md 2026-10-22 14:26:53.464215014 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-workspace-lifecycle/SKILL.md 2026-10-22 14:42:47.203852922 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-workspace-lifecycle -description: WSL2 distro (`Adom-Workspace`) lifecycle management for Hydrogen on Windows. Import/export/unregister/terminate, code-server-as-Hydrogen-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run global WSL operations; touch ONLY Adom-Workspace so a co-installed Docker Desktop WSL integration stays safe. MUST READ before any workspace operation. Trigger words — wsl, workspace, distro, Adom-Workspace, restart workspace, terminate distro, unregister, wsl --import, wsl --unregister, code-server, workspace broken, workspace unhealthy, wsl hung, fix workspace, /wsl/status. +description: >- + Lifecycle of Hydrogen's Adom-Workspace WSL2 distro: import, export, + unregister, terminate, code-server as Hydrogen's child, recovery after sleep, + and the rule to never run global WSL commands. Read before any workspace + operation. Use when the workspace is broken, unhealthy, or needs a restart. --- # Hydrogen — WSL2 Workspace Lifecycle @@ -57,7 +61,7 @@ Log proof: `[wsl-tarball] downloaded … SHA256 OK` → `[setup] WSL setup_and_start completed` and `wsl -l -v` shows `Adom-Workspace Running 2`. -### code-server is an Hydrogen-OWNED CHILD process +### code-server is a Hydrogen-OWNED CHILD process code-server (`CODE_SERVER_CHILD` in `runtime/wsl.rs`) runs as a child of Hydrogen, deliberately tied to Hydrogen's lifetime — **NOT a detached `nohup`** (a detached process dies when WSL tears down the session anyway). Consequence: every Hydrogen restart (rebuild / crash / @@ -114,7 +118,7 @@ ## Diagnosing Workspace Problems ### "Workspace unhealthy" / editor stuck on "Starting AI Environment" -- **Cause**: code-server child was orphaned by an Hydrogen restart, or the distro went +- **Cause**: code-server child was orphaned by a Hydrogen restart, or the distro went unreachable after sleep. - **Check**: `[wsl] Workspace unhealthy …` in the Hydrogen log (the real signal). NOTE: a `[docker] Container runtime unhealthy …` line under WSL is **benign noise** — a diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-monitoring/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-workspace-monitoring/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-monitoring/SKILL.md 2026-10-22 14:26:53.464215014 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-workspace-monitoring/SKILL.md 2026-10-22 14:42:47.207853067 -0500 @@ -1,15 +1,10 @@ --- name: hydrogen-workspace-monitoring -description: > - How Hydrogen monitors and manages the local workspace and code-server. - Covers the 15s workspace state poll, the two health levels (runtime available, - workspace Running + code-server reachable), the floaty states, auto-start via - setup_and_start, auto-reload of the VS Code iframe, and the lifecycle dialog - system. Read BEFORE touching PanelVisualStudioCode.svelte, - ContainerLifecycleDialog.svelte, or any workspace state handling code. Trigger - words: workspace stopped, workspace monitoring, workspace poll, workspace floaty, - start workspace, code-server reachable, lifecycle dialog, workspace state, - workspace running. +description: >- + How Hydrogen monitors the local workspace and code-server: the 15 s state + poll, health levels, the status floaty, auto-start, iframe auto-reload, and + the lifecycle dialog. Use when asked why the workspace stopped, about the + workspace floaty, or before changing workspace state code. --- # Hydrogen Workspace Monitoring @@ -30,7 +25,7 @@ code-server reachable on its host port? The second level is a real reachability check, not just "is the workspace -present." A resume reality-check (after sleep, or after an Hydrogen rebuild/relaunch) +present." A resume reality-check (after sleep, or after a Hydrogen rebuild/relaunch) requires code-server to actually answer before Hydrogen trusts the workspace as healthy — a workspace can be Running while code-server is dead. diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-monitoring-windows/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-workspace-monitoring-windows/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-workspace-monitoring-windows/SKILL.md 2026-10-22 14:26:53.464215014 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-workspace-monitoring-windows/SKILL.md 2026-10-22 14:42:47.207853067 -0500 @@ -1,24 +1,20 @@ --- name: hydrogen-workspace-monitoring-windows -description: > - Windows/WSL2-specific details for HD workspace monitoring — the "WSL2 Not - Available" floaty, the `wsl --terminate Adom-Workspace` stop command, the - code-server-on-host-7380 reachability check, and the no-daemon framing (WSL - has no always-on daemon to launch). READ alongside the generic - [[hd-workspace-monitoring]] skill when you need the concrete WSL2 states, - commands, or ports. Trigger words: wsl not available, Adom-Workspace running, - wsl terminate, code-server 7380, no daemon, distro stopped, WSL2 floaty. +description: >- + Windows companion to hydrogen-workspace-monitoring: the WSL2 Not Available + floaty, `wsl --terminate Adom-Workspace`, the code-server 7380 check, and why + WSL has no daemon. Use for WSL2 workspace states, commands or ports. --- -# HD Workspace Monitoring (Windows / WSL2 specifics) +# Hydrogen Workspace Monitoring (Windows / WSL2 specifics) -This is the Windows companion to the generic [[hd-workspace-monitoring]] +This is the Windows companion to the generic `hydrogen-workspace-monitoring` skill. Read that first for the monitoring architecture, the ContainerStatus struct, the 15s poll, the lifecycle dialog, the Tauri commands, the menu items, and the Settings toggles. This page carries only the WSL2-specific states, commands, and ports. -HD runs on Windows (WSL2), Mac, and Ubuntu. Under the WSL2 runtime the +Hydrogen runs on Windows (WSL2), Mac, and Ubuntu. Under the WSL2 runtime the workspace is the **`Adom-Workspace` distro** (imported via `wsl --import`), not a Docker container. The legacy Docker equivalent (`HD_RUNTIME=docker`) is in the docker/ bucket. @@ -94,6 +90,6 @@ ## Related skills -- [[hd-workspace-monitoring]] — the generic monitoring UX, struct, poll, lifecycle dialog, and commands -- `hd-workspace-lifecycle` — import/export/unregister/terminate, the never-touch-global-WSL rule, control endpoints -- `hd-networking` — port 7380 code-server, control port 47084 +- `hydrogen-workspace-monitoring` — the generic monitoring UX, struct, poll, lifecycle dialog, and commands +- `hydrogen-workspace-lifecycle` — import/export/unregister/terminate, the never-touch-global-WSL rule, control endpoints +- `hydrogen-networking` — port 7380 code-server, control port 47084 diff -ruN -x '._*' hydrogen-windows-bootstrap.orig/skills/hydrogen-wslg/SKILL.md hydrogen-windows-bootstrap/skills/hydrogen-wslg/SKILL.md --- hydrogen-windows-bootstrap.orig/skills/hydrogen-wslg/SKILL.md 2026-10-22 14:26:53.464215014 -0500 +++ hydrogen-windows-bootstrap/skills/hydrogen-wslg/SKILL.md 2026-10-22 14:42:47.207853067 -0500 @@ -1,6 +1,10 @@ --- name: hydrogen-wslg -description: WSLg (Linux GUI apps from the Hydrogen workspace) is OFF by default. How to check it, turn it on or off from inside the workspace through Hydrogen's control API, apply it with a workspace restart, and what to do about the "RemoteApp security warning" dialog. Trigger words - wslg, linux gui app, gui app from wsl, x11, wayland, display not set, cannot open display, guiApplications, turn on wslg, enable gui apps, remoteapp security warning, unknown publisher dummy-entry. +description: >- + WSLg (Linux GUI apps from the Hydrogen workspace) is off by default: check it, + turn it on or off through Hydrogen's control API, apply with a workspace + restart, and handle the RemoteApp security warning. Use when asked about wslg, + a linux gui app, cannot open display, or enable gui apps. --- # WSLg in the Hydrogen workspace