---
name: hd-overview
description: >
  Master index for all Hydrogen Desktop skills. Start here to find the right
  skill for any HD topic. Skills are split into a runtime-neutral "shared" set
  plus a runtime-specific set (WSL2 by default, Docker as legacy fallback).
  Trigger words: HD skills, hydrogen desktop, what skills, find skill, HD help,
  HD overview, skill index, HD reference.
---

# Hydrogen Desktop — Skill Index

Hydrogen Desktop (HD) is Adom's standalone Tauri v2 app that runs the full
Hydrogen experience locally. One exe manages your workspace, VS Code,
Claude Code, the bridges, and the Adom Wiki — zero cloud dependency.

## ⚠️ First: know your runtime — **`hd-runtime-mode`**

HD hosts your workspace one of two ways: a **WSL2 Ubuntu distro `Adom-Workspace`**
(the default) or a **Docker container** (legacy, `HD_RUNTIME=docker`). Almost every
fact below — container vs distro, files, ports, stats, setup steps — depends on
which is active. **Read `hd-runtime-mode` first** to confirm your runtime, then use
the matching runtime-specific skill. HD only installs the skills for the active
runtime, so in a given workspace you'll usually have exactly the right set.

## Shared skills (runtime-neutral — always installed)

| Skill | What it covers |
|---|---|
| **hd-runtime-mode** | WSL2 vs Docker runtime: how to tell which you're in and what differs. Read first. |
| **hd-golden-image** | Your workspace is a pre-baked golden WSL2 image — gallia, the CLIs, claude, code-server, settings, and these skills are baked in (not installed by setup steps); how updates work. **Lightweight by design: tools like ffmpeg/imagemagick aren't baked — install on demand (`sudo apt-get install`) rather than refusing.** |
| **hd-skill-loop** | (Maintainers) The loop to fix a wrong/stale HD skill: verify vs the live HD, fix it live, write it back to the repo, bake it into the next image. |
| **hd-who-am-i** | Answer "who am I / what can I do here" — identity, resources, environment intro. |
| **hd-adom-auth** | Adom login/logout, session token, profile menu, how auth feeds setup. |
| **hd-claude-auth** | How Claude Code signs in: OAuth via Browser Picker, credential backup, the `claude-auth` step. |
| **hd-api** | Control API reference (`127.0.0.1:47084`). Runtime-neutral endpoints + runtime-specific notes. |
| **hd-desktop-sse** | Local workspace API + SSE — how adom-cli inside the workspace controls HD (replaces Carbon locally). |
| **hd-monitor** | Real-time SSE event stream + Monitor-tool patterns for watching workspace mutations. |
| **hd-ui** | HD's UI: menus, dialogs, panels, CDP-driven navigation, brand/CSS conventions. |
| **hd-open-url** | The decision guide for "open a website" — the six ways (webview tab, HD window, Pup, native browser, picker, headless curl) and when to pick each. |
| **hd-browser-picker** | URL interception — every link routes through the Browser Profile Dialog. |
| **hd-permissions** | Why mic/camera/clipboard/notifications "just work" in HD — WebView2 permissions are auto-granted, so webview apps see no Allow prompts. |
| **hd-tab-icons** | Webview tab icon system — `displayIcon`, icon resolution, SVG data URLs. |
| **hd-profile-menu** | The avatar dropdown: profile/repos/molecules links and logout. |
| **hd-adom-desktop** | What HD and Adom Desktop (AD) are and how they work together — AD is your hands on the user's real OS (files, shell, OS screenshots, app launch, bridges). |
| **hd-bridges** | Built-in KiCad/Fusion/Puppeteer bridges + extensible wiki catalog (e.g. Blender) + AD capability list. |
| **hd-eval** | Inject JS into any HD surface (shell/workbench/wiki/Claude) via /eval-in — add-ons, overlays, highlights, drive UI. |
| **hd-adom-menu** | The upper-left Adom logo menu (Settings, Ports, API Explorer, DevTools, Setup/Virgin Reset) + About dialog + version readout. |
| **hd-settings** | HD's Settings dialog + the full preferences tree (theme, vim mode, 3D control style, launch-on-boot, AD window behavior). |
| **hd-file-transfer** | Move files both ways between the WSL2 workspace and the Windows PC. |
| **hd-embedded-ad** | HD ↔ Adom Desktop embedded mode: the tray, why AD is hidden, the footer pill. |
| **hd-self-screenshot** | How the AI screenshots HD panels + any host window (window control, multi-monitor), injects to shotlog, runs visual self-checks. |
| **hd-capture-share** | The screen-share + "AI wants access" approval + countdown the AI triggers to capture the editor; tab/screen scopes, Webview/Pup window mode. |
| **hd-recording** | Record the screen/mic — the in-app `.webm` recorder (→ `recordings/`) and AD desktop recording, with the tab-vs-desktop footgun. |
| **hd-notifications** | Reach the user outside the window — native Windows toasts + emergency taskbar flash via `notify_user`. |
| **hd-captions** | Paint labeled text on the user's screen — a Win32 always-on-top caption overlay for demos / step callouts. |
| **hd-welcome** | The static welcome page shown after setup completes. |
| **hd-self-update** | How HD updates itself: the "Restart to update (vX→vY)" banner (UpdateBanner.svelte) plus the AI-first update path. |
| **hd-staying-current** | How workspace skills/packages stay current — registry-native updates (`adom-wiki pkg update` + `adom/hook`); the old workspace-updater daemon is retired. |
| **hd-skill-catalog** | The catalog of skills your Claude has in this workspace. |
| **hd-overview** | This index. |

## Runtime-specific skills (you get the WSL2 *or* the Docker variant)

These topics exist in two parallel implementations — `wsl2/` (default) and
`docker/` (legacy) — with the same skill names. Trust the one for your active
runtime (see `hd-runtime-mode`).

| Skill | What it covers |
|---|---|
| **hd-container** | Context for Claude running inside the workspace: relay, direct connect, bridge commands, env vars. |
| **hd-topology** | The three-layer architecture and how to reach the workspace (WSL2: `wsl -d Adom-Workspace`; Docker: `docker exec`). |
| **hd-networking** | Port architecture, host access (`127.0.0.1` / mirrored networking), code-server proxy. Canonical port behavior. |
| **hd-ports** | Forwarding workspace services to Windows (WSL2 auto-forward vs Docker `-p` + `/proxy/`). |
| **hd-port-watcher** | The dynamic port-forward daemon for extension OAuth callbacks. |
| **hd-volume** | Where your files live, what persists, how to copy out, what a reset wipes. |
| **hd-container-stats** | The title-bar CPU/RAM "Container" indicator and how its stats are gathered. |
| **hd-setup** | The setup panel, Run All, Rollback, Virgin Reset. |
| **hd-setup-steps** | What each setup step did to prepare your workspace. |

### WSL2-only
| Skill | What it covers |
|---|---|
| **hd-workspace-lifecycle** | WSL distro lifecycle: import/export/terminate/unregister, code-server as an HD-owned child, the never-global-WSL rule. |
| **hd-workspace-monitoring** | Distro + code-server health monitoring, floaty states, the 15s poll, auto-start. |

### Docker-only (legacy `HD_RUNTIME=docker`)
| Skill | What it covers |
|---|---|
| **hd-docker-desktop** | Silently install/upgrade/start/monitor Docker Desktop as invisible infrastructure. |
| **hd-docker-lifecycle** | Docker Desktop + container lifecycle: WSL2 recovery, restart/stop rules, health checks. |
| **hd-docker-monitoring** | Frontend monitoring of the Docker container and Docker Desktop. |