Hydrogen Desktop Bootstrap for Windows (apps + skills)

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.

Windows/WSL2-specific details for HD's reach onto the host via Adom Desktop — the C:\ / %USERPROFILE% / %APPDATA% paths, host control-port discovery via ports.json, the WSL2 0.0.0.0:8765 → host-loopback relay forwarding, the cmd /C shell, winget auto-install verbs (KiCad / Node), the wsl_exec --distro Adom-Workspace runner, and the taskkill warning. READ alongside the generic [[hd-adom-desktop]] skill when acting on a Windows host. Trigger words — windows host, WSL2, cmd /C, taskkill adom-desktop, ports.json, winget, desktop_install_kicad, desktop_install_node, wsl_exec, Adom-Workspace, mirrored networking, host loopback, %APPDATA%, C:\Users.

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.

HD's Browser Picker — the canonical handler for EVERY URL that gets opened inside HD. Click a link anywhere (main page, code-server iframe, webview panel, PortMappingsDialog, OAuth redirect, localhost link, external link) and HD 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, HD 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 HD. Trigger words — browser picker, BrowserProfileDialog, hd-open-url, hd-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, hd-links (legacy name).

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.

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.

HD'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/distro, 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 HD'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, distro stats, wsl stats.

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.

Context for Claude Code running inside a Hydrogen Desktop WSL2 workspace distro. Documents the exact OS (Ubuntu 24.04, code-server 4.112.0, the Adom-Workspace distro), explains how setup differs from Adom cloud containers (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.

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.

Windows-specific EDA detection probe for the post-setup discovery pass — how to find no-bridge EDA tools (Altium, OrCAD, Cadence/Allegro, EAGLE, DipTrace, Eplan) by scanning C:\Program Files / C:\Program Files (x86) and Get-Process via a PowerShell run_script. Read alongside the platform-generic [[hd-eda-discovery]]. Trigger words — detect altium windows, scan program files, powershell eda probe, Get-Process altium, orcad install path, run_script eda detect.

How Hydrogen Desktop (HD) and Adom Desktop (AD) interact via "embedded mode". Use whenever the user asks about the system tray icon, why AD isn't visible, why two desktop apps are installed, the "Embedded · HD" footer pill, or how to make AD show up standalone. Trigger words — embedded mode, system tray, AD tray, why is adom desktop hidden, where's my tray icon, HD vs AD, both apps installed, why two installs, ad missing from tray, switch AD to standalone, AD won't show, run AD without HD, decouple AD from HD.

Move files BOTH WAYS between the HD 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-desktop relay (send_files / pull_file) which also works on the legacy Docker runtime. 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.

Your Hydrogen Desktop workspace is a PRE-BAKED golden WSL2 image, not a machine that installed itself step-by-step. gallia, the 8 Adom CLIs, the `claude` CLI + Claude Code VS Code extension, code-server, the VS Code settings / trusted-domains / activity-bar config, AND all the hd-* self- awareness skills are BAKED at image-build time — none of them were installed by a setup step. READ THIS when a user asks "why is X already here", "how do I update gallia", "re-run install-hd-skills / install-gallia / install-claude", or "where did these skills/CLIs come from": the answer is the image, and updates come from a tarball-version bump, NOT a setup step. Trigger words — golden image, pre-baked, baked image, adom-golden, adom-golden.tar.gz, hd-wsl2- image, wsl --import, tarball version, adom-tarball-version, migrate tarball, update gallia, reinstall gallia, install-hd-skills, install-gallia, install- claude-cli, install-claude-ext, verify-adom-desktop, why is gallia here, where did the CLIs come from, how do I update the workspace, re-run setup, lightweight image, install on demand, command not found, ffmpeg not installed, install a tool, apt-get install, missing tool, is ffmpeg installed, install imagemagick/pandoc.

Port architecture, hostnames, and networking rules for Hydrogen Desktop. 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 — HD port, HD network, port mapping, proxy, 127.0.0.1, loopback, mirrored networking, hd-control-url, VSCODE_PROXY_URI, relay URL, code-server proxy, container networking, ADOM_CARBON_URL, ADOM_HYDROGEN_URL, direct connect, 8770, 7380.

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.

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.

Port reachability in Hydrogen Desktop — and why you do NOT need to set up port forwarding. Under WSL2 networkingMode=mirrored (HD'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.

How HD does port forwarding between your WSL2 workspace and your Windows machine — WSL2's automatic `0.0.0.0` localhost-forwarding (no Docker `-p` map), 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, hd 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.

How to record screen + window video from Hydrogen Desktop. In HD 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/), AD host desktop recording (desktop_record_start, Windows-only), the tab-vs-desktop footgun, and what `--mic` does. 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.

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.

HD 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. HD is NATIVE: its screenshots use CDP and its recording uses Windows.Graphics.Capture (WGC) / DXGI — neither holds the display wake-lock — so HD does not have the web leak. HD 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 HD screenshot / screen-recording features. Trigger words: hd screenshot, hd 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.

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.

What HD's setup steps did to prepare your workspace — the 28-step cascade that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, walks the Claude auth gate, and then opens 9 named AI-thread conversations. 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, hd setup, claude code extension install, gallia install, hd workspace ready.

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.

HD setup panel: 27 install steps, 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, 28 steps, wipe, reset workspace, keep auth, test setup.

The catalog of skills available to your Claude inside this Hydrogen Desktop workspace. Lists every public `hd-*` skill that ships with HD and explains what each one is for, so you can pick the right skill before doing anything HD-related. READ THIS FIRST when you're in a fresh HD 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.

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.

MUST READ before ANY HD work. Explains the three-layer topology: cloud Docker (where Claude runs), Windows machine (where HD + Adom Desktop run), and the HD 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 — HD topology, cloud vs local, wsl exec, where am I, which workspace, adom-desktop relay, test from container, three tiers, architecture, windows machine.

How HD'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.

WSL2 distro (`Adom-Workspace`) lifecycle management for Hydrogen Desktop on Windows. Import/export/unregister/terminate, code-server-as-HD-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.

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.

How Hydrogen Desktop monitors and manages the local WSL2 workspace distro (`Adom-Workspace`) and code-server. Covers the 15s workspace state poll, the two health levels (WSL2 available, distro Running + code-server reachable), the floaty states (WSL not available, distro stopped), 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, wsl not available, workspace monitoring, distro poll, workspace floaty, start workspace, code-server reachable, lifecycle dialog, workspace state, Adom-Workspace running.