Adom Hydrogen (Windows / WSL2)

@@ -0,0 +1,104 @@+---+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.+---++# HD Control API — Windows / WSL2 specifics++This is the Windows companion to the generic [[hd-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.++## Host-side port discovery++In addition to the in-workspace `~/.adom/hd-control-url` discovery file, you can+find the dynamic control port from the Windows host:++```bash+# From HD log+adom-desktop hd_log '{"tail":100}' | grep "control="++# From ports.json+type %APPDATA%\hydrogen-desktop\ports.json+```++**Loopback note:** WSL2 mirrored networking shares loopback with the Windows+host, so `http://127.0.0.1:<port>` is the same address from inside the+`Adom-Workspace` distro and on the Windows host. `/ports/all` reports+mirrored-mode info per port.++## WSL runtime endpoints (default runtime)++When HD runs the workspace as a WSL2 distro, it additionally exposes:++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/wsl/status` | — | WSL distro state (registered, running, code-server reachable) |+| GET | `/workspace/health` | — | Deep workspace health (distro + code-server + host reachability) |+| GET | `/virgin-reset-progress` | — | Live progress of an in-flight virgin reset |+| POST | `/workspace/terminal-profile` | — | Ensure the stable `Adom-Workspace` Windows Terminal profile (idempotent) |+| POST | `/workspace/terminal-profile/remove` | — | Remove the `Adom-Workspace` Windows Terminal profile(s) |+| POST | `/workspace/check-updates` | — | Check upstream for newer code-server + Claude extension; stage them |+| POST | `/workspace/apply-updates` | — | Apply staged code-server/extension updates + reload editor |++> ⛔ `POST /wsl/unregister` is **REFUSED as deprecated** — it was a headless+> destructive reset (deletes `/home/adom/project`). Use the Setup panel's Virgin+> Reset or `POST /setup/panel/run-virgin-reset` instead.++## Docker Desktop (legacy Docker runtime only — `HD_RUNTIME=docker`)++This `/docker/*` table applies only when HD is running the legacy Docker runtime.++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/docker/status` | — | Docker Desktop running state |+| GET | `/docker/version` | — | Docker engine version |+| GET | `/docker/containers` | — | List all Docker containers |+| GET | `/docker/images` | — | List all Docker images |+| POST | `/docker/start` | — | Launch Docker Desktop + start container |+| POST | `/docker/stop` | — | Stop Docker Desktop |+| POST | `/docker/restart` | — | Restart Docker Desktop |+| POST | `/docker/wait-ready` | — | Block until Docker daemon responds |+| POST | `/docker/install` | — | Install Docker Desktop (downloads ~730 MB) |+| POST | `/docker/uninstall` | — | Uninstall Docker Desktop |+| POST | `/docker/clean-reinstall` | — | Uninstall + reinstall Docker Desktop |+| GET | `/docker/install-progress` | — | Current install step + progress |++Also Docker-runtime only:++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/volume-delete` | — | Remove project volume (DESTRUCTIVE). No volume exists under WSL. |++## System (host OS reboot)++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/system/nonce` | — | Get nonce for authenticated reboot |+| GET | `/system/reboot-state` | — | Check reboot pending state |+| POST | `/system/reboot` | `{"nonce":"..."}` | Reboot Windows (nonce-authenticated) |+| POST | `/system/cancel-reboot` | — | Cancel pending reboot |++## WebView & VS Code (Windows specifics)++HD's webview is **WebView2** on Windows; `/cdp-eval`, `/cdp-info`, and+`/devtools` target the WebView2 DevTools (Chrome DevTools Protocol) endpoint.++## Diagnostics — dialog blocker catalog++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/test/probe-dialogs` | — | Enumerate visible windows, classify against the cascade-blocker catalog (UAC, WSL2 update, MSI installer, Docker EULA, …); returns `kind` + `is_blocking` per window |++(Gated behind `HD_TEST_API_ENABLED=1`, like the rest of `/test/*`.)

@@ -0,0 +1,92 @@+---+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.+---++# Hydrogen Desktop — Desktop Overlay Caption (Windows)++Windows-specific companion to **[[hd-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+Windows-only.++## Desktop overlay caption — `adom-desktop desktop_caption`++HD'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+separate OS window). **Windows-only** (non-Windows no-ops).++## 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.++```bash+adom-desktop desktop_caption '{"text":"Step 3: approve the UAC dialog →","position":"center","size":"large","duration":6000}'+```++### Arguments++| Arg | Type | Meaning |+|---|---|---|+| `text` | string | The caption text. Omit (with no `action`) to hide. |+| `id` | string | Caption identity. **Same id → replaces** that caption; **different ids → coexist.** Defaults to `_default`. |+| `position` | string | `top`, `bottom` (default), `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`. |+| `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. |+| `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)++Captions are keyed by `id`. **Reuse an id to update a caption in place**; **use different+ids to show several at once.** That lets you run, e.g., a persistent status caption in a+corner *and* a moving center callout simultaneously:++```bash+# persistent status in the corner+adom-desktop 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}'++# clear just the step callout+adom-desktop desktop_caption '{"id":"step","action":"hide"}'++# nuke everything+adom-desktop desktop_caption '{"action":"force-clear"}'+```++## Patterns++- **Walkthrough / demo callouts over other apps** — drop a `center` caption per step (same+  `id` so each replaces the last). Combine with a full-screen recording so the callouts end+  up in the finished video. Pair with TTS for narration.+- **Status corner** — a long-`duration` small caption in a corner (`top-right`), separate+  `id`, while you drive the rest of the screen.+- **Point at a thing** — use normalized `x`/`y` to sit a label next to a button or dialog+  you're about to act on.+- **Cleanup** — `action:"hide"` per id when a step is done; `action:"force-clear"` to wipe+  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`+- `adom-tts` — *audio* narration to pair with on-screen captions (captions are visual-only)

@@ -0,0 +1,81 @@+---+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.+---++# HD Runtime Mode — WSL2 (default) vs Docker (legacy)++Hydrogen Desktop 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.**++| `HD_RUNTIME` | Runtime | What the workspace is | Setup cascade | State file |+|---|---|---|---|---|+| unset / `wsl2` | **WslDistro — DEFAULT** | WSL2 Ubuntu distro `Adom-Workspace` (`wsl --import`) | 16 steps | `setup-steps-wsl.json` |+| `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+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.++## Which runtime am I in? (authoritative checks)++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+   `[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"`+   (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`+This line can appear **even on the WSL2 path** — a legacy `hd-docker` heartbeat+polls for a Docker container that doesn't exist and logs "unhealthy". It is+cosmetic and does NOT mean you're in Docker mode. The real WSL health signal is+`[wsl] Workspace unhealthy …`. Confirm the runtime via check #1, never by this line.++## What actually differs between the runtimes++| Concern | WSL2 (default) | Docker (legacy) |+|---|---|---|+| Workspace | `Adom-Workspace` distro, imported from the pre-baked `adom-golden.tar.gz` | container from a ~390 MB image |+| 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) |+| 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`++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+  prior run set Docker: `setx HD_RUNTIME wsl2` then relaunch.+- → Docker (fallback): `setx HD_RUNTIME docker`, relaunch HD (requires Docker+  Desktop running).

@@ -0,0 +1,101 @@+---+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.+---++# HD Setup Steps (Windows / WSL2 specifics)++This is the Windows companion to the generic [[hd-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+`Adom-Workspace` WSL2 distro. The legacy 24-step Docker cascade+(`HD_RUNTIME=docker`) is in the docker/ bucket.++The cascade is executed by `setup_steps_wsl.rs` (`step_defs_wsl()` /+`run_all_wsl()`). `run_all_wsl` is halt-on-failure, resume-not-restart, with+per-step 3x auto-retry. In-distro work runs via+`wsl -d Adom-Workspace -u adom -- <cmd>` (the distro's DEFAULT user is `adom`+per `wsl.conf default=adom`, home `/home/adom`; root via `-u root`). There is+NO `docker exec` and NO Docker image anywhere in this flow.++## The 16 steps (in order)++| # | Step | Purpose |+|---|---|---|+| 1 | ensure-workspace | Install WSL2 if needed (one auto-reboot), `wsl --import Adom-Workspace` from the golden image `adom-golden.tar.gz` (full pre-baked image from the `adom-inc/hd-wsl2-image` GitHub release), create the `adom` user, start code-server, verify host loopback on 7380. SUBSUMES the old Docker pull-image / create-container / start-container steps. |+| 2 | wait-codeserver | Host TCP probe of the code-server port (default 7380), 120s |+| 3 | install-adom-vscode | "Activate editor extensions" — installs NOTHING (binary + extension are baked); waits for Adom sign-in, reloads the editor iframe, and proves the :8821 editor-control API answers |+| 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) |+| 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) |+| 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 |++## The WSL import step (step 1)++`ensure-workspace` installs WSL2 if needed (one auto-reboot), then+`wsl --import Adom-Workspace` from the full pre-baked golden image+`adom-golden.tar.gz` (pulled from the `adom-inc/hd-wsl2-image` GitHub release).+It creates the `adom` user, starts code-server, and verifies host loopback on+port 7380. This single step replaces the old Docker pull-image /+create-container / start-container trio.++## Platform-specific failure causes++Most common WSL2 failures:+- **Step 1** — WSL2 unavailable / the Virtual Machine Platform feature is off,+  or the `adom-golden.tar.gz` download failed.+- **Step 11** (test-adom-cli) — carbon / hydrogen-proxy not reachable yet.+- **Step 12** (claude-auth) — Claude credentials expired.++## Virgin reset — WSL distro wipe++The `container` toggle does a PRISTINE `wsl --unregister Adom-Workspace` ++reimport — it deletes the distro AND everything in it, including+`/home/adom/project`. It backs up Claude creds first UNLESS `claude_token` is+checked.++CRITICAL: the WSL reset ONLY ever runs `wsl --unregister Adom-Workspace`+(+ reimport). It never runs global `wsl --shutdown` or `wsl --uninstall`+(those would kill the user's other distros, including any Docker Desktop WSL+integration), and it performs NO Docker actions and NO reboot for the wipe.++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+(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+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

@@ -0,0 +1,101 @@+---+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.+---++# Hydrogen Desktop -- Setup (Windows / WSL2 specifics)++This is the Windows companion to the generic [[hd-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+`Adom-Workspace` WSL2 distro. The legacy 24-step Docker cascade+(`HD_RUNTIME=docker`) is in the docker/ bucket.++## The 16 Install Steps (WSL2)++The WSL cascade is executed by `setup_steps_wsl.rs` (`step_defs_wsl()` /+`run_all_wsl()`). `run_all_wsl` is halt-on-failure, resume-not-restart, with+per-step 3x auto-retry. State is tracked in `setup-steps-wsl.json` (the Docker+flow uses `setup-steps.json`). The Docker-only `pull-image` /+`create-container` / `start-container` steps are SUBSUMED into step 1,+`ensure-workspace`, which imports the golden distro via `wsl --import+Adom-Workspace`.++| # | ID | Label | Rollback? |+|---|---|---|---|+| 1 | ensure-workspace | Install WSL2 if needed (one auto-reboot), import golden distro, create `adom` user, start code-server, verify host loopback (7380) | ✓ |+| 2 | wait-codeserver | Host TCP probe of code-server port (default 7380), 120s | ✗ |+| 3 | install-adom-vscode | "Activate editor extensions" — installs NOTHING (binary+extension baked); waits for Adom sign-in, reloads editor iframe, proves the :8821 editor-control API answers | ✓ |+| 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) | ✓ |+| 9 | test-direct-connect | Prove the fast container→desktop command path | ✗ |+| 10 | test-relay | Register the relay with Adom Desktop 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 | ✗ |++## Step 1 — ensure-workspace (WSL2 import)++Installs WSL2 if needed (one auto-reboot), then `wsl --import Adom-Workspace`+from the full pre-baked golden image `adom-golden.tar.gz` (pulled from the+`adom-inc/hd-wsl2-image` GitHub release — NOT a thin ~30 MB tarball, NOT a+390 MB Docker image), creates the `adom` user, starts code-server, and+verifies host loopback on port 7380. This single step replaces the old Docker+pull-image / create-container / start-container trio.++The distro's DEFAULT user is `adom` (`wsl.conf default=adom`), NOT root;+in-distro exec = `wsl -d Adom-Workspace -u adom --` (root via `-u root`) —+NEVER `docker exec`.++WSL2 auto-forwards code-server's port 7380 to Windows `localhost:7380` —+there is no Docker port-mapping layer, so the port-conflict / stale-mapping+class of bug that affected the Docker runtime does not apply here. Other+services tunnel through the code-server `/proxy/{port}/` path.++## Virgin Reset — WSL2 distro mechanics++The `container` toggle does a PRISTINE `wsl --unregister Adom-Workspace` ++reimport — it deletes the distro AND everything in it, including+`/home/adom/project`. It backs up Claude creds first UNLESS `claude_token` is+checked.++CRITICAL — the WSL virgin reset only ever touches `Adom-Workspace`. It runs+`wsl --unregister Adom-Workspace` — NEVER global `wsl --shutdown` or+`wsl --uninstall`, which would knock out the user's other distros (e.g. a+pre-existing Docker Desktop integration). There are NO Docker actions.++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+(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+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

@@ -0,0 +1,120 @@+---+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.+---++# HD Skill Loop — verify → fix live → write back to the repo → bake++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+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.++## Cardinal rule: TEST, don't assert++Never write a skill claim from memory, old skill text, or docs — **verify it+against the running system first.** Run the command. Read the live env. Read the+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++| 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`. |++A fix isn't done until it's in the **canonical** copy and pushed.++## The loop++### 1. Reproduce / notice+A skill made the AI do the wrong thing. Name the skill and the exact wrong claim.++### 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`,+  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:+  ```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>"}'+  ```++### 3. Fix it live + re-test+Edit `~/.claude/skills/<name>/SKILL.md` to match what you verified. Re-read it,+then **re-run the failing action** to confirm the fix actually works.++### 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*+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.)++### 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.)++### 5. Write the corrected file back to the repo+Copy the same corrected SKILL.md into the canonical bucket:+```bash+cp ~/.claude/skills/<name>/SKILL.md \+   /mnt/c/Github/hydrogen-desktop/skills/public-facing/<bucket>/<name>/SKILL.md+```+If you added / renamed / removed a skill, also update the indexes+`hd-overview` and `hd-skill-catalog` (both in `shared/`).++### 6. Commit + push so the next bake ships it+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>"}'+```+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.++## 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` /+      `$(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`,+      Pillow, `jq`…) — test it in the distro before relying on it.+- [ ] Step counts / endpoint paths / ports match CURRENT code (they drift fast).+- [ ] Cross-links use sibling skill names that resolve flat at deploy.+- [ ] `name:` matches the directory.++## Why this matters+The skills ARE HD'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

@@ -0,0 +1,99 @@+---+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.+---++# HD Workspace Monitoring (Windows / WSL2 specifics)++This is the Windows companion to the generic [[hd-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+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.++## The two WSL2 health levels++The generic two-level model maps onto WSL2 as:++1. **WSL2 available** — is WSL2 itself installed and responding on this+   machine?+2. **Workspace healthy** — is `Adom-Workspace` registered AND Running AND is+   code-server reachable on host port **7380**?++A workspace can be `Running` while code-server is dead, so the level-2 check is+a real host-loopback reachability probe of port 7380, not just "is the distro+registered."++## WSL2 floaty states++The old Docker floaties ("Docker Desktop not installed/running") become these+WSL/distro states under this runtime.++### 1. WSL2 Not Available (red dot)+- **When**: WSL2 itself is not installed / not responding (level-1 health+  fails)+- **Message**: "WSL2 is required but not available."+- **Action**: "Run Setup Steps" button → dispatches `hd-show-setup` event+  (which walks the user through enabling WSL2)++### 2. Workspace Stopped / Not Ready (red dot)+- **When**: WSL2 is available but `Adom-Workspace` isn't Running, or it's+  Running but code-server isn't reachable on :7380 (`container_running ==+  false`)++### No "daemon not running" middle state++There is no separate "daemon not running" middle state like Docker had — WSL+has no always-on daemon to launch. Either WSL2 is available or it isn't+(state 1), and the workspace is either healthy or it isn't (state 2). There is+no `launch_docker_desktop` equivalent under WSL.++## Auto-Start specifics++Under WSL mode, `setup_and_start` delegates to+`WslDistroRuntime::setup_and_start`:+- If the distro isn't present yet, `fresh_import` = download the golden+  `adom-golden.tar.gz` (from the `adom-inc/hd-wsl2-image` release) ++  `wsl --import Adom-Workspace` + start code-server.+- If the distro is present but code-server is down, it just (re-)starts+  code-server.++The re-ensure-on-launch log line is+`[wsl-startup] re-ensured code-server on launch`.++## VS Code Auto-Reload target++After the `done` lifecycle event, the dialog reloads all iframes whose src+points at `localhost:7380` (the host-side code-server port).++## WSL2-specific Tauri command mappings++| Command | WSL mode behavior |+|---|---|+| `get_container_status` | WSL available, distro present/registered, Running + code-server reachable on :7380 |+| `setup_and_start` | `WslDistroRuntime::setup_and_start` — `fresh_import` + start code-server, up to 10 min timeout |+| `stop_container` | Stops the workspace via `wsl --terminate Adom-Workspace` |++## WSL2-specific menu behavior++- **Restart Workspace** — `wsl --terminate Adom-Workspace` + re-ensure+  code-server+- **Stop Workspace** — `wsl --terminate Adom-Workspace`++## 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