Adom Hydrogen (Windows / WSL2)

@@ -0,0 +1,154 @@+---+name: hd-container-stats+description: 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.+---++# HD Workspace Stats Indicator++> This is the WSL2-runtime version (default). The legacy Docker equivalent+> (`HD_RUNTIME=docker`) is in the docker/ bucket.++The top-right of HD's title bar (next to the audio/video icons and your profile avatar) shows a tiny `Container` block with two horizontal progress bars — CPU% and RAM% — that animate in real-time. Hovering brings up a tooltip with the full workspace details. Under the WSL2 runtime these numbers now reflect the **`Adom-Workspace` distro**, not a Docker container — but the UI is unchanged, so the header still reads "Container".++## How often it polls++There's an active polling loop in HD's title bar that asks the runtime for fresh stats on a timer:++- **Every 1 second** when the workspace is `running` — for live, smooth bar animation+- **Every 5 seconds** when it's `stopped`, `starting`, `restarting`, or `restart needed` — saves cycles when nothing's changing++Each poll calls Tauri `invoke('get_container_stats')`. This command no longer reaches into Docker directly — it dispatches through the runtime trait: `WorkspaceRuntime::get_stats` → `WslDistroRuntime::get_stats` → `workspace_stats()`, a WSL health/stat probe of the `Adom-Workspace` distro. (Under `HD_RUNTIME=docker` the same command routes to the Docker impl instead.) The probe runs with short timeouts so a hung WSL subsystem can't freeze the UI.++If you ever want to lighten the load (e.g. on a battery-constrained laptop), the relevant code is in `EditorNav.svelte`'s `pollStats()` closure — adjust the `pollInterval` ternary.++## What the bars show++| Bar | What it measures | Source |+|-----|------------------|--------|+| CPU | % of the distro's available CPU being consumed (1.0 = 1 full vCPU). Capped at 100% display | `workspace_stats()` WSL probe |+| RAM | % of the distro's memory in use vs its limit | `workspace_stats()` WSL probe |++Both bars share the same color-threshold rules:+- **Teal / green** — ≤ 50% usage (normal)+- **Yellow** (`warn` class) — 51-80% usage+- **Red** (`danger` class) — > 80% usage++## What the tooltip shows++When you hover over the bars, a tooltip appears with:++| Line | Example |+|------|---------|+| Container | `Adom-Workspace` (the distro name) |+| CPU + RAM totals | `CPU: 1.7% of 16 cores | RAM: 0.7 GB / 16.0 GB` |+| Disk | `Disk: 1.3 GB` (distro disk usage) |+| Image | `Image: Ubuntu 24.04 (Adom-Workspace)` (the imported distro) |+| ID | `Adom-Workspace` (the registered distro identifier) |+| Created | `5/24/2026, 3:18:09 PM` (locale-formatted) |++If the workspace is in a non-healthy state, the tooltip shows a single red line instead:+- `Workspace is stopped — start from the menu` (when stopped)+- `Workspace runtime is broken — restart from the menu` (when the distro/code-server is unreachable, e.g. after sleep/hibernate)++## Status badge in the header++The `Container` text in the section header gets an inline status badge depending on state:++| Badge | Meaning | Color |+|-------|---------|-------|+| (no badge) | Running normally | normal |+| `stopped` | Distro registered but not running | red |+| `starting` | HD is starting the distro / code-server | yellow |+| `restarting` | HD is restarting the distro | yellow |+| `restart needed` | The distro or code-server is unreachable (usually a WSL2 hiccup after Windows wake) | red |++When `restart needed` shows, open the Adom menu → Restart Workspace (see the `hd-ui` skill for the Adom menu). A "Restart" here is `wsl --terminate Adom-Workspace` + re-ensure code-server — NOT `docker restart`.++## How it works under the hood++- **Polling frequency**: see "How often it polls" above — 1s when running, 5s when not.+- **Backend command**: Tauri `invoke('get_container_stats')` → `WorkspaceRuntime::get_stats`. In WSL mode that is `WslDistroRuntime::get_stats` → `workspace_stats()`. NO `docker exec`, NO cgroup file reads, NO bollard `stats()` — those were the Docker-runtime mechanism and do not run under WSL.+- **Two health levels** (`workspace_stats()` checks both): (1) is WSL2 itself available; (2) is `Adom-Workspace` registered + Running with code-server reachable on host port 7380. If either fails, the probe returns a needs-restart signal instead of stats and the UI shows the red "restart needed" badge.+- **Rate-limited error logging**: the "needs restart" log line is printed at most once every 30 seconds, even though the frontend polls every 1s, so the log stays readable.++### The benign `[docker] unhealthy` log line++You will sometimes see this in HD's log even on the WSL2 path:++```+[docker] Container runtime unhealthy — exec failed, needs restart+```++**Under WSL this is BENIGN NOISE.** It's a leftover hd-docker heartbeat with no container bound to it — there is no Docker container in WSL mode, so "exec failed" is expected and meaningless. It does NOT mean your workspace is broken.++The real WSL health signal to watch for is:++```+[wsl] Workspace unhealthy …+```++That line (not the `[docker]` one) reflects the actual `Adom-Workspace` distro state. And the authoritative "which runtime am I on" line is `[app] Active workspace runtime: WslDistro`.++## API access++If you want the same stats data your AI can hit directly via the control API:++```bash+# From inside the distro — query the control API on the host+curl -s "$(cat ~/.adom/hd-control-url)/container-stats"+```++(Reach the control API at `127.0.0.1` — WSL2 mirrored networking shares loopback with the Windows host. The port is **dynamic per launch**; read the live URL from `~/.adom/hd-control-url` rather than hardcoding it.)++Returns JSON like:+```json+{+  "ok": true,+  "container_name": "Adom-Workspace",+  "container_id": "Adom-Workspace",+  "container_created": "2026-05-24T20:18:09Z",+  "image": "Ubuntu 24.04 (Adom-Workspace)",+  "cpu_percent": 1.7,+  "cpu_cores": 16,+  "mem_usage_mb": 716,+  "mem_limit_mb": 16384,+  "mem_percent": 4.4,+  "disk_usage_mb": 1300+}+```++Or if the workspace is in a broken state:+```json+{ "ok": false, "needs_restart": true, "error": "Workspace needs restart" }+```++## CSS selectors++| Element | Selector |+|---------|----------|+| The whole indicator block | `.resource-bars` |+| Header with title + status badge | `.resource-bars-header` |+| Title text ("Container") | `.resource-bars-title` |+| One bar row (CPU or RAM) | `.resource-bar-item` |+| Bar fill | `.resource-bar-fill` (modifier classes: `.warn`, `.danger`) |+| Bar percentage label | `.resource-bar-value` |+| Hover tooltip container | `.resource-bars-tooltip` |+| One tooltip line | `.resource-bars-tooltip-row` |++## Common questions++**"Why is CPU showing 200% / 1600%?"** It's not — the displayed % is capped at 100 for the bar fill, but the tooltip shows the real number. CPU of `100% of 16 cores` means 1 full vCPU pegged.++**"Why does RAM stay constant at ~4% even when I'm doing nothing?"** Code-server, the relay, gallia, the adom-vscode HTTP API, etc. all run in the distro all the time. ~700 MB baseline is normal.++**"The 'restart needed' badge appeared — what happened?"** Almost always a WSL2 hiccup after Windows wake/sleep, leaving the distro or code-server unreachable. Click Restart Workspace in the Adom menu (top-left). HD will `wsl --terminate Adom-Workspace`, re-ensure code-server, and the badge clears.++**"The log says `[docker] … unhealthy` — is my workspace broken?"** No. Under WSL that line is a benign leftover heartbeat with no container bound. Look at `[wsl] Workspace unhealthy …` for the real signal. See "The benign `[docker] unhealthy` log line" above.++**"Disk is 1.3 GB — does that include my project files?"** Yes — under WSL there is no separate Docker volume; `/home/adom/project` lives inside the distro, so the `Disk:` figure is the distro's on-disk size including your project.++## Related skills++- [hd-workspace-monitoring](../hd-workspace-monitoring/SKILL.md) — the 15s state poll + floaty states behind these badges+- [hd-workspace-lifecycle](../hd-workspace-lifecycle/SKILL.md) — start/stop/restart/unregister of the distro+- [hd-networking](../hd-networking/SKILL.md) — port 7380 code-server, host reachability, control port 47084

@@ -0,0 +1,132 @@+---+name: hd-container+description: 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.+---++# Hydrogen Desktop Workspace (WSL2)++WSL2-runtime version (default). Legacy Docker container runtime (`HD_RUNTIME=docker`) is in the docker/ bucket.++You are running inside the **`Adom-Workspace` WSL2 distro** managed by Hydrogen Desktop (HD). HD is the flagship Adom desktop app — it manages your WSL2 workspace, bridges to desktop apps, and provides VS Code + Claude Code.++## The workspace — exact facts (don't guess)++| Field | Value |+|-------|-------|+| Distro name | `Adom-Workspace` (fixed — there is no random container suffix) |+| Imported from | golden image `adom-golden.tar.gz` (full pre-baked image) via `wsl --import` |+| Base | Ubuntu 24.04 |+| Architecture | matches host (`dpkg --print-architecture`) — almost always `linux-x64` on Windows hosts, can be `linux-arm64` on Apple Silicon hosts |+| code-server | 4.112.0 (pinned via setup step) |+| code-server binary | `/usr/lib/code-server/bin/code-server` |+| Extensions dir | `~/.local/share/code-server/extensions/` |+| Settings | `~/.local/share/code-server/User/settings.json` |+| Distro default user | `adom` (`wsl.conf [user] default=adom`) — in-distro exec via `wsl -d Adom-Workspace -u adom --`; root via `-u root` |+| Work user | `adom` (UID 1001, passwordless sudo, home `/home/adom`) |+| Workspace | `/home/adom/project` (lives directly in the distro's ext4 filesystem) |+| Pre-installed | Node 18 + npm, Python 3.12, git, gh, curl, wget, jq, build-essential, cmake, pkg-config, libssl-dev |+| Code-server runs as | `code-server --bind-addr 0.0.0.0:7380 --auth none --disable-telemetry /home/adom/project` (WSL2 auto-forwards 7380 to Windows `localhost:7380`) |+| Runtime source | `hydrogen-desktop/src-tauri/crates/hd-app/src/runtime/wsl.rs` (selector `runtime/mod.rs::select_runtime()`) |++If you ever need to confirm: `cat /etc/os-release`, `uname -m`, `/usr/lib/code-server/bin/code-server --version`. Don't speculate about alpine/arm64 — Ubuntu 24.04 matches the cloud container.++## Setup is via HD's setup-steps, NOT gallia bootstrap.sh++HD provisions this distro through its own **setup-steps** flow (Rust code in `hydrogen-desktop/src-tauri/crates/hd-app/src/setup_steps_wsl.rs`, with the runtime mechanics in `hydrogen-desktop/src-tauri/crates/hd-app/src/runtime/wsl.rs`), shown as the "Install Tools" panel in the HD UI. It is a **different code path** than cloud containers, which run `gallia/scripts/bootstrap.sh`.++The WSL cascade is **16 steps** (state file `setup-steps-wsl.json`) vs the legacy Docker flow's 24. Most tooling is NOT installed by a step — it's BAKED into `adom-golden.tar.gz` at image-build time (gallia, the 8 Adom CLIs, the claude CLI + Code extension, code-server, VS Code settings, and all `hd-*` skills). 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. The relay is started by the `start-relay` step. See `hd-golden-image`.++When debugging install issues here, the source of truth is `setup_steps_wsl.rs` (and `runtime/wsl.rs`) — its step IDs (`ensure-workspace`, `install-adom-vscode`, `set-env-vars`, `inject-api-key`, `start-relay`, `claude-auth`, etc.) map 1:1 to what ran on this distro. There is NO `install-claude-ext` / `install-claude-cli` / `install-gallia` / `write-vscode-settings` step anymore — those are baked. Do NOT chase bugs into `bootstrap.sh` first — that script lives in the baked image but HD itself never invokes it. (For the legacy Docker `setup_steps.rs` flow see the docker/ bucket.)++## VS Code extension caveats++- The Claude Code extension and `code-server` settings (including `extensions.autoUpdate: true` / `extensions.autoCheckUpdates: true`) are BAKED into the golden image — there is no `write-vscode-settings` or `install-claude-ext` setup step. Auto-update **must** stay on so every installed extension auto-updates from the marketplace; the image bakes it on. Do not regress this.+- Bare `code-server --install-extension <id>` (no version pin) historically resolves to the **universal** target-platform build. For some extensions (notably `anthropic.claude-code` after 2.1.89), Anthropic stopped shipping universal builds — so bare install permanently sticks at 2.1.89 even when newer `linux-x64` builds exist. The golden-image bake installs the latest `linux-x64` build pinned, so the workspace ships current. It also heals orphan `extensions.json` entries (entries pointing to deleted dirs cause a permanent "Invalid extensions detected" banner).+- Marketplace: code-server uses **Open VSX** (open-vsx.org), not Microsoft Marketplace. No `EXTENSIONS_GALLERY` env override is set; `product.json` has no gallery URL — it falls through to Open VSX defaults.++## adom-cli is authenticated++HD auto-injects the user's session token on every launch. To verify:+```bash+adom-cli carbon user get+```+If this returns user data, all adom-cli commands work (containers, repos, orgs, wiki, etc.). If it fails, the user needs to log in via HD's login page.++## Relay server is running++The adom-desktop relay runs on ports 8765 (WebSocket) / 8766 (HTTP) inside this distro. The `start-relay` setup step launches it.++Check health: `curl -sf http://127.0.0.1:8766/health`+Check desktop connection: `adom-desktop ping`++The Windows host control API is reachable from inside the distro at `127.0.0.1` — WSL2 mirrored networking shares loopback with the Windows host. The port is dynamic per launch, so read the live URL from `~/.adom/hd-control-url` (`http://127.0.0.1:<dynamic>`): `BASE="$(cat ~/.adom/hd-control-url)"; curl "$BASE/health"`.++## Available bridge commands (when desktop is connected)++### Screenshots (zero dialogs, instant)+```bash+adom-desktop desktop_screenshot_screen                    # full screen capture+adom-desktop desktop_screenshot_screen '{"maxWidth":1500}' # resized for Claude vision+adom-desktop desktop_screenshot_window '{"hwnd": N}'       # capture specific window+adom-desktop desktop_list_windows                          # list all windows with HWNDs+```+Default to `maxWidth: 1500, format: "png"` for UI screenshots. Use `"jpeg"` for natural photos, `"webp"` for smaller files.++### Browser automation (Puppeteer)+```bash+adom-desktop browser_open_window '{"url": "https://..."}'+adom-desktop browser_screenshot '{"sessionId": "default"}'+adom-desktop browser_eval '{"js": "document.title"}'+adom-desktop browser_navigate '{"url": "..."}'+```++### KiCad bridge+```bash+adom-desktop kicad_open_board '{"path": "C:\\path\\to\\board.kicad_pcb"}'+adom-desktop kicad_screenshot_all+adom-desktop kicad_run_drc '{"path": "..."}'+adom-desktop kicad_window_info+```++### Fusion 360 bridge+```bash+adom-desktop fusion_start+adom-desktop fusion_import_step '{"path": "..."}'+adom-desktop fusion_export_step '{"path": "..."}'+```++### File transfer+```bash+adom-desktop send_files '{"files": [{"path": "/home/adom/file.txt"}]}'+adom-desktop pull_file '{"remotePath": "C:\\Users\\john\\file.txt", "localPath": "/tmp/file.txt"}'+```++### Desktop interaction+```bash+adom-desktop notify_user '{"message": "Build complete", "duration_ms": 3000}'+adom-desktop desktop_open_url '{"url": "https://..."}'+adom-desktop desktop_open_folder '{"path": "C:\\Users\\john\\project"}'+```++## What's different from Adom cloud containers++| Feature | Adom Cloud | HD 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) |+| Bridge latency | ~50-100ms (internet round-trip) | <1ms (localhost) |+| VSCODE_PROXY_URI | Coder proxy URL | http://localhost:7380/proxy/{{port}}/ |+| Socket.IO (collab) | Connected to iron.adom.inc | Disabled (single-user) |+| Service containers | Adjacent containers | Remote via Adom cloud |++## Environment variables++- `ADOM_DESKTOP_MODE=local` — indicates HD local mode+- `HD_RUNTIME=wsl2` — indicates the WSL2 runtime (default); `docker` selects the legacy container runtime+- `GALLIA_SERVICE=local` — tells gallia this is a local workspace+- `VSCODE_PROXY_URI=http://localhost:7380/proxy/{{port}}/` — code-server's proxy++## Related skills++- `hd-topology` — the three-tier topology; tier 3 is this WSL2 distro+- `hd-volume` — where your files live, what persists, and how to back up / copy out the distro

@@ -0,0 +1,92 @@+---+name: hd-setup-steps+description: What HD's setup steps did to prepare your workspace — the 16-step install sequence that imports the Adom-Workspace golden 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, hd setup, claude code extension install, gallia install, hd workspace ready.+---++# HD Setup Steps — what was done to prepare your workspace++WSL2-runtime version (default). The legacy 24-step Docker cascade+(`HD_RUNTIME=docker`) is in the docker/ bucket.++When you first launched Hydrogen Desktop (or after a virgin reset), HD ran a 16-step install sequence to turn a blank machine into a fully-tooled Adom workspace — the `Adom-Workspace` WSL2 distro. The heavy tooling (code-server, gallia, the 8 Adom CLIs, the claude CLI + Code extension, VS Code settings, and all `hd-*` skills) is already BAKED into the golden image; setup just imports that image, injects your Adom session, wires up the relay, and walks the Claude auth gate. This skill explains what each step did so you can help the user understand their environment, re-run failed steps, or wipe and rebuild. See `hd-golden-image` for the baked-image model.++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 3× 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 |++### Steps that NO LONGER EXIST (baked into the golden image)++These are NOT setup steps anymore — they are baked at image-build time: `install-gallia`, `install-hd-skills`, `verify-adom-desktop`, `install-claude-cli`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`. If a user asks "what installed gallia / the Claude extension / my skills / VS Code settings", the answer is: **baked into the `adom-golden.tar.gz` golden image at build time, not a setup step.** See `hd-golden-image`.++## Common user questions++**"Why is X installed in my workspace?"** → If X is gallia, an Adom CLI, the claude CLI, the Claude Code extension, VS Code settings, or an `hd-*` skill, it was **baked into the golden image** — not run as a setup step. The setup steps only import the image, inject your session, wire the relay, and walk Claude auth. The setup panel (HD UI → bottom) lists every step with its current status.++**"Setup failed at step N"** → The setup panel shows the error. Most common failures: step 1 (WSL2 unavailable / Virtual Machine Platform feature off, or the `adom-golden.tar.gz` download), step 11 (test-adom-cli — carbon/hydrogen-proxy not reachable yet), step 12 (Claude credentials expired). Each step has a retry button (and the cascade already retried it 3×).++**"Re-run a single step"** → In the setup panel, click the step row and use the Re-run action. Or via API: `POST http://127.0.0.1:47084/setup/step/<id>` (optional body `{"continue_after":true}` to keep going after it).++**"Re-run all steps"** → Click "Run All" in the setup panel; it resumes from the first not-done step. (The old headless `POST /setup/run-all` is now REFUSED.)++## Virgin reset++Virgin reset wipes parts of your workspace so setup can rebuild them cleanly. The ONLY programmatic trigger is `POST /setup/panel/run-virgin-reset`. Toggle which artifacts to delete (option keys in parentheses):++| Toggle (key) | What gets wiped | When to use |+|--------|----------------|-------------|+| Install step state (`install_state`) | Marks all steps as pending (`setup-steps-wsl.json`) so they re-run | Always (default on) |+| WSL2 distro (`container`) | PRISTINE `wsl --unregister Adom-Workspace` + reimport — deletes the distro AND everything in it, including `/home/adom/project` | Always (default on); your work in `/home/adom/project` is GONE |+| Distro tarball (`tarball`, legacy `image`) | Deletes the cached `adom-golden.tar.gz` (full-image re-download) | Rarely — only if the tarball is corrupted |+| Webview storage (`webview_storage`) | Queued wipe, flushed at next HD launch (restart_required) | Rarely |+| VS Code state (`vscode_state`) | Queued wipe, flushed at next HD launch (restart_required) | Rarely |+| Adom session token (`adom_token`) | Deletes `hydrogen-session.txt`; forces re-login | Rarely |+| Claude credentials (`claude_token`) | Deletes the host-side Claude creds backup; forces Claude re-auth | When Claude auth is stuck |++`confirmed_destructive` must be set. After toggling, hit "Wipe Selected", then "Run All" to rebuild. The distro reset backs up Claude creds first UNLESS `claude_token` is checked; the `webview_storage` / `vscode_state` wipes are queued and flushed at the next HD launch (restart_required), not immediate.++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.++## Setup panel APIs (useful for AI automation)++| Endpoint | What it does |+|----------|--------------|+| `GET /setup/state` | Current state — `never-run`, `in-progress`, `complete`, or `error` |+| `POST /setup/step/<id>` | Re-run a single named step (optional `{"continue_after":true}`) |+| `POST /setup/panel/run-virgin-reset` | Trigger virgin reset with the supplied toggle options |+| `POST /setup/panel/show` | Open the setup panel from anywhere |++All on HD's control API at `http://127.0.0.1:47084`.++**DEPRECATED — now REFUSED, do not use:** `POST /wsl/unregister`, `POST /setup/virgin-reset`, `POST /setup/run-all`, `POST /setup/run-step`. Use `POST /setup/panel/run-virgin-reset` and `POST /setup/step/<id>` instead.++## 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-golden-image` — the baked-image model: what's pre-installed in `adom-golden.tar.gz` vs. what setup does+- `hd-container` — the WSL2 distro and runtime that setup configures+- `hd-networking` — how the distro reaches the host (`127.0.0.1` via WSL2 mirrored networking; live control URL in `~/.adom/hd-control-url`) and how ports forward+- `hd-browser-picker` — used by step 12 (claude-auth) for the Claude auth OAuth flow+- `hd-adom-auth` — how the Adom session token (step 5) gets injected+- `hd-volume` — where your files live in the distro and what survives a virgin reset (or doesn't)

@@ -0,0 +1,196 @@+---+name: hd-setup+description: >+  HD setup panel: 16 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, 16 steps, wipe, reset workspace, keep auth, test setup.+---++# Hydrogen Desktop — Setup Panel & Virgin Reset++WSL2-runtime version (default). The legacy 24-step Docker cascade+(`HD_RUNTIME=docker`) is in the docker/ bucket.++## Zero-Click Goal++The HD setup process targets ZERO manual clicks for the user. The heavy+lifting is already done at image-build time: the `Adom-Workspace` golden+image ships with code-server, gallia, the 8 Adom CLIs, the claude CLI + Code+extension, VS Code settings, and all `hd-*` skills BAKED IN. Setup just+imports that image, injects the user's session, wires up the relay, and walks+the single human auth gate. If something is missing, HD downloads it — never+tell the user to install something manually. See the `hd-golden-image` skill+for the baked-image model.++## The 16 Install Steps++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 3× 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 | ✗ |++### Steps that NO LONGER EXIST (baked into the golden image)++These are NOT setup steps anymore — they are baked at image-build time and+must not be listed or "run": `install-gallia`, `install-hd-skills`,+`verify-adom-desktop`, `install-claude-cli`, `install-claude-ext`,+`write-vscode-settings`, `set-trusted-domains`, `clean-layout`. gallia, the 8+Adom CLIs, the claude CLI + Code extension, code-server, settings, and all+`hd-*` skills are baked into the `adom-golden.tar.gz` image. See+`hd-golden-image`.++## Panel Buttons++- **Run All** — executes all pending steps sequentially. STOPS on first failure.+- **Rollback All** — rolls back all completed steps in reverse order.+- **Virgin Reset ▾** — opens the toggle panel (see below).+- **Run** (per-step) — runs a single step.+- **Rollback** (per-step) — rolls back a single step.++## CRITICAL: Run All Stops on Failure++If any step fails, Run All ABORTS (halt-on-failure in `run_all_wsl()`, after+the per-step 3× auto-retry is exhausted). Remaining steps are NOT executed.+`run_all_wsl` resumes — it does NOT restart from step 1 — so to recover after+a failure: fix the issue, then either:+- Click "Run All" again (it resumes from the first not-done step)+- Click "Run" on the failed step to retry just that one++## Virgin Reset Toggle Panel++Click "Virgin Reset ▾" to expand the wipe options. Each toggle has a+live status badge showing the current state. The ONLY programmatic trigger is+`POST /setup/panel/run-virgin-reset` (see below).++| Toggle (option key) | What it wipes | Status badges |+|---|---|---|+| Install step state (`install_state`) | Resets all 16 steps to pending (`setup-steps-wsl.json`) | CLEAN / EXISTS |+| WSL2 distro (`container`) | PRISTINE `wsl --unregister Adom-Workspace` + reimport (ONLY that distro) | GONE / RUNNING / EXISTS |+| Distro tarball (`tarball`, legacy `image`) | Deletes cached `adom-golden.tar.gz` (full image re-download) | CACHED / GONE |+| Webview storage (`webview_storage`) | Queued wipe, flushed at next HD launch (restart_required) | CLEAN / EXISTS |+| VS Code state (`vscode_state`) | Queued wipe, flushed at next HD launch (restart_required) | CLEAN / EXISTS |+| Adom session token (`adom_token`) | Deletes `hydrogen-session.txt` | CLEAN / EXISTS |+| Claude credentials (`claude_token`) | Deletes the host-side Claude creds backup | CLEAN / EXISTS |++`confirmed_destructive` must be set for the reset to proceed. **"Wipe+Selected"** at the bottom executes the reset for all checked toggles.++The distro reset is a PRISTINE `wsl --unregister` + reimport — it backs up+Claude creds first UNLESS `claude_token` is checked. The `webview_storage` /+`vscode_state` wipes are queued and flushed at the next HD launch+(restart_required), NOT immediate; there is no reboot for the wipe.++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 is NO Docker actions.++## Automated Testing Pattern++For AI-driven ralph loop testing, keep auth tokens so steps don't fail:++```+Checked:   install_state, container+Unchecked: tarball (cached, saves the full-image re-download),+           adom_token, claude_token+```++This gives a freshly-imported distro while keeping auth working — step 5+(inject-api-key) and step 12 (claude-auth) won't fail.++### Programmatic triggers (the ONLY supported headless paths)++```bash+# Virgin reset — the ONE allowed programmatic trigger+curl -X POST http://127.0.0.1:47084/setup/panel/run-virgin-reset \+  -H Content-Type:application/json \+  -d '{"confirmed_destructive":true,"install_state":true,"container":true,+       "tarball":false,"webview_storage":false,"vscode_state":false,+       "adom_token":false,"claude_token":false}'++# Re-run a single step (optional continue_after to keep going)+curl -X POST http://127.0.0.1:47084/setup/step/test-direct-connect \+  -H Content-Type:application/json -d '{"continue_after":true}'+```++DEPRECATED — do NOT use these; they are now REFUSED (deprecated headless+triggers): `POST /wsl/unregister`, `POST /setup/virgin-reset`,+`POST /setup/run-all`, `POST /setup/run-step`.++## Key Steps Explained++### Step 1 — ensure-workspace+The big one. 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`.++### Step 5 — inject-api-key+Writes the Adom session token into the distro at `/var/run/adom/api-key`+(mode 644) so adom-cli works. Requires the user to be signed in. Keep the+`adom_token` toggle UNCHECKED during automated test resets.++### Step 9 — test-direct-connect+Proves the fast container→desktop command path. The CLI auto-probes the host+control API (wired to the WSL gateway IP by `/etc/init-host-internal.sh`) and+routes through Adom Desktop's direct connect API.++### Step 10 — test-relay (register relay)+Registers the relay (started by step 8, `start-relay`) with Adom Desktop for+file streaming via the code-server proxy path. This enables `pull_file`,+`send_files`, and `shell_execute`.++### Step 12 — claude-auth+The single human gate. Restores / validates Claude creds in the distro+(backed up host-side) and, when needed, drives the in-editor Claude.ai sign-in+via the native browser Browser Picker. Runs LAST before the payoff steps.++### Steps 13-16 — the final gates+`ensure-sse` confirms the editor browser SSE session is connected (so the+Welcome webview-open doesn't 409); `verify-workspace` confirms the proxy holds+a real layout; `welcome` opens Claude Code and sends the first prompt; the+final `open-welcome` gate opens welcome.html in HD's right pane and HARD-FAILS+if the Welcome tab doesn't appear.++> Note: gallia, the Adom CLIs, the claude CLI + Code extension, VS Code+> settings, and `hd-*` skills are NOT setup steps — they are baked into+> `adom-golden.tar.gz`. See `hd-golden-image`.++## Distro Recreation++When the distro is unregistered and re-imported (step 1), the new distro is a+fully pre-baked Ubuntu from `adom-golden.tar.gz`. 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.

@@ -0,0 +1,152 @@+---+name: hd-workspace-monitoring+description: >+  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.+---++# HD Workspace Monitoring++> This is the WSL2-runtime version (default). The legacy Docker equivalent+> (`HD_RUNTIME=docker`) is in the docker/ bucket.++## Architecture++Under the WSL2 runtime the workspace is the **`Adom-Workspace` distro** (imported via+`wsl --import`), not a Docker container. HD monitors workspace health at two levels:++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**?++The second level is a real reachability check, not just "is the distro registered."+A resume reality-check (after sleep, or after an HD rebuild/relaunch) requires+code-server to actually answer before HD trusts the workspace as healthy — a distro+can be `Running` while code-server is dead.++The VS Code panel (`PanelVisualStudioCode.svelte`) polls workspace state every 15s+and shows appropriate UI for each state. These frontend components survive unchanged+from the Docker era; they now front the WSL runtime via the runtime trait.++## Workspace State Poll++`PanelVisualStudioCode.svelte` calls `get_container_status` (Tauri command) every 15s.+The command dispatches through the runtime trait to the WSL impl. Returns a status+struct shaped like:+```rust+pub struct ContainerStatus {+    pub docker_available: bool,    // under WSL: is WSL2 available?+    pub image_pulled: bool,        // is the Adom-Workspace tarball/distro present?+    pub container_exists: bool,    // is the distro registered (Running or Stopped)?+    pub container_running: bool,   // is it Running AND code-server reachable on :7380?+    pub container_id: Option<String>,+    pub error: Option<String>,+}+```+The field names are inherited from the Docker era; under WSL they map onto the two+health levels above (WSL availability, then distro-registered → distro-Running ++code-server-reachable).++## Floaty States++All floaties appear INSIDE the VS Code panel only — not as full-app modals.+They are draggable (grab header to move). The rest of the app (wiki tab, menu, etc.)+remains fully interactive. The old Docker floaties ("Docker Desktop not installed/+running") become 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)+- **Color**: Red dot in header++### 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`)+- **Message**: "The Adom workspace is not running."+- **Action**: "Start Workspace" button → calls `setup_and_start` Tauri command+- **Lifecycle dialog**: Shows the draggable lifecycle dialog with live setup output+- **Auto-reload**: After the distro + code-server come up, waits for code-server+  health, then reloads the VS Code iframe++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).++## Auto-Start via `setup_and_start`++The "Start Workspace" path calls Tauri `setup_and_start`, which (in WSL mode)+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.++Importantly, code-server runs as an **HD-owned child process** (not a detached+`nohup`) — it dies with HD. So HD also **re-ensures code-server on every launch**+(look for `[wsl-startup] re-ensured code-server on launch` in the log). Without that,+a freshly relaunched HD would show the distro Running but the editor stuck on+"Starting AI Environment" forever, because the previous HD's code-server child was+orphaned. See [hd-workspace-lifecycle](../hd-workspace-lifecycle/SKILL.md) for the+full lifecycle detail.++## Lifecycle Dialog++`ContainerLifecycleDialog.svelte` — a draggable floating card (no background blur)+that shows live command output for start/stop/restart operations on the distro.++### Events+Listens for `hd-container-lifecycle` CustomEvents on `window`:+- `action: 'restart' | 'stop' | 'start'` — opens dialog, starts spinner+- `action: 'step', step: string` — appends a log line+- `action: 'done'` — stops spinner, shows Close button, auto-reloads VS Code+- `action: 'stopped'` — stops spinner (for stop-only operations)+- `action: 'error', message: string` — shows error state++### Title+Dynamic based on `actionType`:+- Restarting: "Workspace Restarting..." → "Restart Complete"+- Stopping: "Stopping Workspace..." → "Workspace Stopped"+- Starting: "Starting Workspace..." → "Workspace Started"+- On error: "Restart/Stop/Start Failed"++### VS Code Auto-Reload+After the `done` event, the dialog polls code-server health (`/proxy/8080/`) every 5s+for up to 2 minutes. When healthy, it reloads all iframes whose src points at+`localhost:7380` (the host-side code-server port), then shows "VS Code iframe reloaded"+and stops.++## Tauri Commands++| Command | What it does (WSL mode) |+|---|---|+| `get_container_status` | Returns workspace status — WSL available, distro present/registered, Running + code-server reachable |+| `setup_and_start` | `WslDistroRuntime::setup_and_start` — `fresh_import` (import distro) + start code-server, up to 10 min timeout |+| `stop_container` | Stops the workspace (`wsl --terminate Adom-Workspace`) |+| `toggle_console` | Show/hide the debug console window |+| `is_console_visible` | Returns true if console window exists |++There is no `launch_docker_desktop` equivalent under WSL — there's no daemon to start.++## Menu Items (Adom Menu → Workspace Section)+- **Restart Workspace** — `wsl --terminate Adom-Workspace` + re-ensure code-server; emits lifecycle events, shows dialog+- **Stop Workspace** — terminates the distro; emits lifecycle events, shows dialog, triggers stopped floaty+- **Start Workspace** — available when stopped (from floaty button or menu)++## Settings (Desktop section in Settings dialog)+- `desktop.show_console_on_startup` — boolean, default false+- `desktop.launch_on_boot` — boolean, default true (auto-start registry key)++## Related skills++- [hd-workspace-lifecycle](../hd-workspace-lifecycle/SKILL.md) — import/export/unregister/terminate, the never-touch-global-WSL rule, control endpoints+- [hd-container-stats](../hd-container-stats/SKILL.md) — the title-bar CPU/RAM bars and `workspace_stats()` probe+- [hd-networking](../hd-networking/SKILL.md) — port 7380 code-server, control port 47084