Adom Hydrogen (Windows / WSL2)

@@ -4,7 +4,7 @@   "type": "bootstrap",   "title": "Hydrogen Desktop Bootstrap for Windows (apps + skills)",   "brief": "The Windows (WSL2) platform layer for Hydrogen Desktop.",-  "version": "0.2.5",+  "version": "0.2.6",   "description": "The Windows platform layer for Hydrogen Desktop, where the workspace runs in a WSL2 Ubuntu distro. Depends on adom/hd-bootstrap (the platform-generic HD layer, which bundles the generic hd-* skills) and adds everything specific to the WSL2 runtime: the WSL2/networking/lifecycle hd-* skills (BUNDLED here by design, John+Kyle 2026-07-16) and the WSL2 code-server workbench seed. Sibling adom/hd-mac-bootstrap carries the parallel mac skills. This is the package the golden WSL2 image installs.",   "org": "adom",   "platform": "linux",@@ -27,8 +27,5 @@     "postinstall.sh",     "README.md",     "skills/**"-  ],-  "hero": {-    "path": "docs/hero.png"-  }-}+  ]+}\ No newline at end of file

@@ -4,7 +4,7 @@   "slug": "hd-windows-bootstrap",   "title": "Hydrogen Desktop Bootstrap for Windows (apps + skills)",   "brief": "The Windows (WSL2) platform layer for Hydrogen Desktop.",-  "version": "0.2.5",+  "version": "0.2.6",   "author": {     "name": "John Lauer",     "email": "[email protected]"

@@ -34,7 +34,7 @@ If you ever need to confirm: `cat /etc/os-release`, `uname -m`, `/usr/lib/code-s  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`.+The WSL cascade is **27 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 Code extension, code-server, VS Code settings, and all `hd-*` skills). The one exception is the `claude` CLI, which is installed at RUNTIME by step 12 `install-claude-cli` (its self-setup needs a live session). 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.) 

@@ -1,33 +1,47 @@ --- name: hd-port-watcher description: >-  Dynamic port forwarding for Hydrogen Desktop. A daemon inside the WSL2-  workspace watches for new TCP listeners (OAuth callbacks from VS Code-  extensions like Codex, Copilot, GitLens) and notifies HD to create-  host-side TCP proxies. Covers the cases WSL2 auto-forward can't:-  `127.0.0.1`-only listeners and auto-forward gaps. Makes localhost:{port}-  on Windows reach the distro. Extensions just work — no manual setup.-  Trigger words: port forward, dynamic port, OAuth callback, Codex auth,-  extension auth, port mapping, localhost port, port watcher, port proxy.+  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. --- -# HD Port Watcher — Dynamic Port Forwarding+# HD Port Watcher — you don't port-watch anymore (mirrored networking does it) -> This is the WSL2-runtime version (default). For the legacy Docker container-> runtime (`HD_RUNTIME=docker`) see the docker/ bucket.+> **TL;DR for the AI: do NOT try to set up port forwarding in HD.** Under the+> default WSL2 `networkingMode=mirrored`, ports just work. If a `localhost:<port>`+> from the workspace isn't reachable on Windows, the fix is almost never "forward+> the port" — it's "confirm mirrored is on" (see below), or the service didn't+> actually bind. -## Why the daemon is still here under WSL2+## Why there's nothing to do (mirrored networking) -WSL2 auto-forwards any `0.0.0.0:<port>` listener in the distro to-`localhost:<sameport>` on Windows — so you might think a port watcher is-unnecessary. It isn't. The daemon is **RETAINED** because WSL2's auto-forward-has two gaps the watcher closes:+HD's setup cascade hard-targets `networkingMode=mirrored` in `.wslconfig`. Under+mirrored, the WSL2 distro shares the Windows loopback interface, so **any** listener+in the distro — `0.0.0.0:<port>` AND `127.0.0.1:<port>` — is reachable at the same+`localhost:<port>` on Windows with zero setup. This is why HD's own OAuth host-proxy+is explicitly **skipped** under mirrored (`lib.rs`: *"under WSL2 mirrored it's+redundant… host proxy not needed"*). -1. **`127.0.0.1`-only listeners.** WSL2 does NOT forward loopback-only+## The legacy daemon (Docker / non-mirrored only — historical)++The `port-watcher` daemon below existed for the pre-mirroring world: the Docker/NAT+runtime, where the distro could NOT reach Windows loopback, so a daemon watched+`/proc/net/tcp` for new listeners and HD spun up host-side TCP proxies. It closed+two gaps that DO NOT EXIST under mirrored:++1. **`127.0.0.1`-only listeners.** NAT-mode WSL2 did NOT forward loopback-only    listeners. VS Code extensions (Codex, Copilot, GitLens) start OAuth callback-   servers that frequently bind `127.0.0.1` — the browser redirects to-   `localhost:{port}/auth/callback?code=...` but WSL2 never mirrored that port,-   so on Windows it doesn't exist.+   servers that frequently bind `127.0.0.1`; without mirroring the browser redirect+   to `localhost:{port}/auth/callback?code=...` hit a port that didn't exist on Windows. 2. **Auto-forward lag / wedge.** WSL2 localhost-forwarding can lag or break    even for `0.0.0.0` listeners (a real HD-logged failure mode:    "code-server alive in distro but Windows can't reach 127.0.0.1:7380"). The

@@ -1,6 +1,6 @@ --- 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.+description: What HD's setup steps did to prepare your workspace — the 27-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. ---  # HD Setup Steps — what was done to prepare your workspace@@ -8,15 +8,15 @@ description: What HD's setup steps did to prepare your workspace — the 16-step 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.+When you first launched Hydrogen Desktop (or after a virgin reset), HD ran a 27-step cascade to turn a blank machine into a fully-tooled Adom workspace — the `Adom-Workspace` WSL2 distro. The heavy tooling (code-server, gallia, the Adom CLIs, the Claude Code VS Code extension, VS Code settings, and all `hd-*` skills) is already BAKED into the golden image; setup imports that image, injects your Adom session, wires up the relay, installs the `claude` CLI at runtime (the one thing NOT baked — its self-setup needs a live session), walks the Claude auth gate, then opens the first conversation + 9 named AI-thread conversations. 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)+## The 27 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. |+| 1 | ensure-workspace | Install WSL2 if needed (one auto-reboot), `wsl --import Adom-Workspace` from the golden image tarball (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` |@@ -24,22 +24,35 @@ The cascade is executed by `setup_steps_wsl.rs` (`step_defs_wsl()` / `run_all_ws | 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 |+| 9 | test-direct-connect | Prove the fast workspace→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 |+| 12 | install-claude-cli | Install the Claude Code CLI (`claude`) into the distro via the official installer. NOT baked (its self-setup needs a live session) — HD installs it here at runtime, before sign-in, so the editor's Claude Code + the Welcome/thread conversations have a working `claude`. Idempotent (skips if present). |+| 13 | 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 just before the payoff steps |+| 14 | ensure-sse | GATE: confirm the editor browser SSE session is connected so Welcome's webview-open doesn't 409 |+| 15 | verify-workspace | GATE: battery confirming the proxy holds a real layout |+| 16 | welcome | Open Claude Code, authenticate if needed, and human-type the first prompt ("who am i and what can i do here") |+| 17 | thread-parts-search | Fresh Claude conversation: Adom parts-search app in a webview, find a popular STM32 for a BLDC motor |+| 18 | thread-kicad | Fresh conversation: is KiCad installed? open the symbol library, else offer to install + show a sample board |+| 19 | thread-fusion360 | Fresh conversation: is Fusion 360 installed? open a sample project (sch/brd/3d), else offer to install |+| 20 | thread-altium | Fresh conversation: is Altium installed? open it, else report whether it can be installed |+| 21 | thread-pup | Fresh conversation: intro pup, show the Adom wiki (adom-lbr page) in a pup window |+| 22 | thread-native-browser | Fresh conversation: what the AI can do to drive the user's real Chrome/Edge (logged-in sites) + any extension needed |+| 23 | thread-google | Fresh conversation: install adom-google (its own guided auth), then latest email subject, next cal entry, a gchat DM, a sample PCB BOM sheet |+| 24 | thread-chip-fetcher | Fresh conversation: install chip-fetcher, show it in a webview, search VL53L8CH |+| 25 | thread-tsci | Fresh conversation: adom-tsci builds an RP2040 + USB-C dev board in one prompt, shown in pup |+| 26 | verify-setup | GATE (catch-all): independently re-verifies the whole workspace end-to-end; HALTS naming any artifact that isn't actually there |+| 27 | open-welcome | GATE (final): open welcome.html in HD's right pane; hard-fails if the Welcome tab doesn't appear |++Steps 17–25 (the AI threads) each open a FRESH Claude conversation and human-type a prompt, strictly one at a time. They replaced the old single `eda-discovery` + `instapcb-quote` steps.  ### 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`.+These are NOT setup steps anymore — they are baked at image-build time: `install-gallia`, `install-hd-skills`, `verify-adom-desktop`, `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 golden image at build time, not a setup step.** (Note: `install-claude-cli` is NOT in this list — the `claude` CLI IS a live setup step, since its self-setup needs a live session.) 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.+**"Why is X installed in my workspace?"** → If X is gallia, an Adom 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 `claude` CLI is the exception: it's installed at RUNTIME by step 12 `install-claude-cli`.) 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×). 

@@ -1,12 +1,12 @@ --- name: hd-setup description: >-  HD setup panel: 16 install steps, Run All, Rollback All, Virgin Reset with+  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, 16 steps, wipe, reset workspace, keep auth, test setup.+  rollback, step failed, 27 steps, wipe, reset workspace, keep auth, test setup. ---  # Hydrogen Desktop — Setup Panel & Virgin Reset@@ -25,7 +25,7 @@ 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 27 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@@ -48,20 +48,23 @@ Adom-Workspace`. | 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 | ✗ |+| 12 | install-claude-cli | Install the `claude` CLI into the distro at RUNTIME (NOT baked — its self-setup needs a live session). Idempotent | ✗ |+| 13 | claude-auth | The single human gate; restore creds or drive in-editor Claude.ai sign-in; runs just before payoff | ✓ |+| 14 | ensure-sse | GATE: editor browser SSE session connected so Welcome's webview-open doesn't 409 | ✗ |+| 15 | verify-workspace | GATE: battery confirming the proxy holds a real layout | ✗ |+| 16 | welcome | Opens Claude Code, authenticates if needed, human-types the first prompt | ✗ |+| 17-25 | thread-* (9) | Nine FRESH Claude conversations, one at a time: parts-search, kicad, fusion360, altium, pup, native-browser, google, chip-fetcher, adom-tsci. Replaced the old eda-discovery + instapcb-quote steps | ✗ |+| 26 | verify-setup | GATE (catch-all): independently re-verifies the whole workspace end-to-end; HALTS naming any missing artifact | ✗ |+| 27 | 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`,+`verify-adom-desktop`, `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+Adom CLIs, the Claude Code VS Code extension (the claude CLI is runtime step 12, NOT baked), code-server, settings, and all+`hd-*` skills are baked into the golden image. See `hd-golden-image`.  ## Panel Buttons@@ -89,7 +92,7 @@ live status badge showing the current state. The ONLY programmatic trigger is  | 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 |+| Install step state (`install_state`) | Resets all 27 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 |