Adom Hydrogen (Windows / WSL2)

@@ -3,15 +3,14 @@   "slug": "hydrogen-windows-bootstrap",   "type": "bootstrap",   "title": "Adom Hydrogen (Windows / WSL2)",-  "brief": "The Windows (WSL2) platform layer for Hydrogen Desktop.",-  "version": "0.3.0",-  "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.",+  "brief": "The Windows (WSL2) platform layer for Hydrogen.",+  "version": "0.3.1",+  "description": "The Windows platform layer for Hydrogen, where the workspace runs in a WSL2 Ubuntu distro. Depends on adom/hydrogen-bootstrap (the platform-generic layer, which bundles the generic hydrogen-* skills) and adds everything specific to the WSL2 runtime: the WSL2/networking/lifecycle hydrogen-* skills (BUNDLED here by design, John+Kyle 2026-07-16) and the WSL2 code-server workbench seed. Sibling adom/hydrogen-mac-bootstrap carries the parallel mac skills. This is the package the golden WSL2 image installs.",   "org": "adom",   "platform": "linux",   "tags": [     "bootstrap",-    "hydrogen-desktop",-    "hd",+    "hydrogen",     "windows",     "wsl2"   ],@@ -20,7 +19,7 @@     "install": "./install.sh"   },   "dependencies": {-    "adom/hydrogen-bootstrap": "^0.3.0",+    "adom/hydrogen-bootstrap": "^0.3.1",     "adom/adom-shotlog": "^0.24.0"   },   "files": [

@@ -3,8 +3,8 @@   "type": "bootstrap",   "slug": "hydrogen-windows-bootstrap",   "title": "Adom Hydrogen (Windows / WSL2)",-  "brief": "The Windows (WSL2) platform layer for Hydrogen Desktop.",-  "version": "0.3.0",+  "brief": "The Windows (WSL2) platform layer for Hydrogen.",+  "version": "0.3.1",   "author": {     "name": "John Lauer",     "email": "[email protected]"@@ -15,11 +15,10 @@     "path": "screenshots/hero.png"   },   "org": "adom",-  "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.",+  "description": "The Windows platform layer for Hydrogen, where the workspace runs in a WSL2 Ubuntu distro. Depends on adom/hydrogen-bootstrap (the platform-generic layer, which bundles the generic hydrogen-* skills) and adds everything specific to the WSL2 runtime: the WSL2/networking/lifecycle hydrogen-* skills (BUNDLED here by design, John+Kyle 2026-07-16) and the WSL2 code-server workbench seed. Sibling adom/hydrogen-mac-bootstrap carries the parallel mac skills. This is the package the golden WSL2 image installs.",   "tags": [     "bootstrap",-    "hydrogen-desktop",-    "hd",+    "hydrogen",     "windows",     "wsl2"   ],@@ -28,7 +27,7 @@     "install": "./install.sh"   },   "dependencies": {-    "adom/hydrogen-bootstrap": "^0.3.0",+    "adom/hydrogen-bootstrap": "^0.3.1",     "adom/adom-shotlog": "^0.24.0"   },   "files": [

@@ -1,7 +1,7 @@ --- name: hydrogen-networking description: >-  Port architecture, hostnames, and networking rules for Hydrogen Desktop.+  Port architecture, hostnames, and networking rules for Hydrogen.   MUST READ before adding ports, exposing a service to your Windows host,   referencing host URLs from inside the workspace, or wiring any service   communication.@@ -11,7 +11,7 @@ description: >   ADOM_CARBON_URL, ADOM_HYDROGEN_URL, direct connect, 8770, 7380. --- -# Hydrogen Desktop — Networking & Port Architecture+# Hydrogen — Networking & Port Architecture  > This is the WSL2-runtime version (default). For the legacy Docker container > runtime (`HD_RUNTIME=docker`) see the docker/ bucket.@@ -54,7 +54,7 @@ native TCP listeners on Windows — not inside the distro. | Port | Service | Notes | |------|---------|-------| | 1420 | Dev file server | Dev mode only, serves `build/` |-| 8770 | adom-desktop direct connect | Owned by Adom Desktop, NOT HD |+| 8770 | adom-bridge-cli direct connect | Owned by Adom Bridge, NOT HD | | 47080 | HD discovery server | | | 47083 | HD reverse proxy | Proxies to code-server | | 47084 | HD control API | Health, setup, eval, CDP, `/wsl/status`, `/port-forward` |@@ -111,12 +111,12 @@ Direct connect → `http://127.0.0.1:8770/health`  ## Relay Architecture -The relay (`adom-desktop serve`) runs inside the distro on ports 8765+The relay (`adom-bridge-cli serve`) runs inside the distro on ports 8765 (WebSocket) and 8766 (HTTP). It binds `0.0.0.0`, so it is reachable both via WSL2 auto-forward (`localhost:8765` / `localhost:8766` on Windows) and via the code-server proxy. The proxy path is preferred for connection stability: -1. **adom-desktop on Windows** connects as a WS client via the+1. **adom-bridge-cli on Windows** connects as a WS client via the    code-server proxy: `ws://127.0.0.1:7380/proxy/8765/` 2. **Registration** happens via `server_add` on the direct connect    API (port 8770):@@ -130,7 +130,7 @@ code-server proxy. The proxy path is preferred for connection stability: 3. **Health checks** use the proxy path:    `http://127.0.0.1:7380/proxy/8766/health` -This matches cloud containers where adom-desktop connects via+This matches cloud containers where adom-bridge-cli connects via `wss://<slug>.adom.cloud/proxy/8765/`.  ## VSCODE_PROXY_URI@@ -170,6 +170,6 @@ wsl -d Adom-Workspace -- su - adom -c '<cmd>' 5. **NEVER hardcode port numbers** in distro code. Read from env vars    (`ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`) or discover via the direct    connect API.-6. **NEVER assume adom-desktop direct connect (8770) is owned by HD.**-   It's owned by Adom Desktop. HD's direct-api thread binds to 8770-   as a fallback but Adom Desktop takes priority when both are running.+6. **NEVER assume adom-bridge-cli direct connect (8770) is owned by HD.**+   It's owned by Adom Bridge. HD's direct-api thread binds to 8770+   as a fallback but Adom Bridge takes priority when both are running.

@@ -1,7 +1,7 @@ --- name: hydrogen-port-watcher description: >-  Port reachability in Hydrogen Desktop — and why you do NOT need to set up+  Port reachability in Hydrogen — 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

@@ -134,9 +134,9 @@ Defaults (you can override via ports.json): | Reverse proxy (`proxy`) | 47083 | | HD control API (`control`) | 47084 | | WebView2 CDP (`cdp`) | 47085 |-| KiCad bridge | **dynamic** (adom-desktop picks at bridge launch) |-| Fusion bridge | **dynamic** (adom-desktop picks at bridge launch) |-| Puppeteer bridge | **dynamic** (adom-desktop picks at bridge launch) |+| KiCad bridge | **dynamic** (adom-bridge-cli picks at bridge launch) |+| Fusion bridge | **dynamic** (adom-bridge-cli picks at bridge launch) |+| Puppeteer bridge | **dynamic** (adom-bridge-cli picks at bridge launch) |  **Conflict resolution is NOT "next sequential port."** On startup `PortConfig::resolve_available()` checks `proxy`, `control`, and `cdp`; if a@@ -202,22 +202,22 @@ of truth every consumer reads. ## Bridge ports are dynamic  KiCad, Fusion 360, Puppeteer, and any 3rd-party bridges no longer have known-fixed ports. When a bridge launches, **adom-desktop picks an available port at+fixed ports. When a bridge launches, **adom-bridge-cli picks an available port at runtime** and registers it. To find a running bridge's current port, query-adom-desktop:+adom-bridge-cli:  ```bash-adom-desktop status+adom-bridge-cli status # Look at desktop.apps.<bridge>.bridgePort ``` -Or use the bridge directly via adom-desktop CLI — you don't need the port at all:+Or use the bridge directly via adom-bridge-cli CLI — you don't need the port at all:  ```bash-adom-desktop kicad_open_board '{"path":"..."}'  # adom-desktop routes to the right port-adom-desktop browser_eval '{"js":"..."}'+adom-bridge-cli kicad_open_board '{"path":"..."}'  # adom-bridge-cli routes to the right port+adom-bridge-cli browser_eval '{"js":"..."}' ```  This means **old code or skill examples that hardcoded fixed bridge ports-(8771 / 8773 / 8851) are stale.** Use the adom-desktop CLI or `status` lookup+(8771 / 8773 / 8851) are stale.** Use the adom-bridge-cli CLI or `status` lookup instead.

@@ -8,7 +8,7 @@ description: What HD's setup steps did to prepare your workspace — the 28-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 28-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.+When you first launched Hydrogen (or after a virgin reset), HD ran a 28-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. @@ -18,15 +18,15 @@ The cascade is executed by `setup_steps_wsl.rs` (`step_defs_wsl()` / `run_all_ws |---|------|---------| | 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 | update-packages | GATE: `adom-wiki pkg update` converges the container to the LATEST published packages (skills included) — the golden image is baked once but installed for months. Gates on the ARTIFACT (hd-bootstrap == registry latest + skills deployed), not the raw exit code; re-runs bootstrap postinstalls when an update lands. |+| 3 | update-packages | GATE: `adom-wiki pkg update` converges the container to the LATEST published packages (skills included) — the golden image is baked once but installed for months. Gates on the ARTIFACT (hydrogen-bootstrap == registry latest + skills deployed), not the raw exit code; re-runs bootstrap postinstalls when an update lands. | | 4 | 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 | | 5 | set-env-vars | Set `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `ADOM_HD_CONTROL_URL`, `VSCODE_PROXY_URI`, `ADOM_DESKTOP_MODE` | | 6 | inject-api-key | Write the Adom session token into the distro at `/var/run/adom/api-key` (mode 644) so adom-cli works | | 7 | configure-vscode | settings.json / trusted-domains / activity-bar are BAKED; re-asserts theme + workbench backstops idempotently, and applies the per-session layout via :8821 |-| 8 | ensure-adom-desktop | Verify the Adom Desktop companion app is running on Windows (the relay's desktop bridge) |-| 9 | start-relay | Start the adom-desktop relay inside the workspace (ports 8765 WS / 8766 HTTP) |+| 8 | ensure-adom-bridge-cli | Verify the Adom Bridge companion app is running on Windows (the relay's desktop bridge) |+| 9 | start-relay | Start the adom-bridge-cli relay inside the workspace (ports 8765 WS / 8766 HTTP) | | 10 | test-direct-connect | Prove the fast workspace→desktop command path |-| 11 | test-relay | Register the relay with Adom Desktop for file streaming (file transfer + shell exec) |+| 11 | test-relay | Register the relay with Adom Bridge for file streaming (file transfer + shell exec) | | 12 | test-adom-cli | GATE: carbon path + hydrogen-proxy reachability via adom-cli (6 retries) | | 13 | 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). | | 14 | 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 |@@ -49,7 +49,7 @@ Steps 18–26 (the AI threads) each open a FRESH Claude conversation and human-t  ### 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-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`.+These are NOT setup steps anymore — they are baked at image-build time: `install-gallia`, `install-hd-skills`, `verify-adom-bridge-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 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 

@@ -9,7 +9,7 @@ description: >   rollback, step failed, 28 steps, wipe, reset workspace, keep auth, test setup. --- -# Hydrogen Desktop — Setup Panel & Virgin Reset+# Hydrogen — Setup Panel & Virgin Reset  WSL2-runtime version (default). The legacy 24-step Docker cascade (`HD_RUNTIME=docker`) is in the docker/ bucket.@@ -43,10 +43,10 @@ Adom-Workspace`. | 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) | ✓ |+| 7 | ensure-adom-bridge-cli | Verify the Adom Bridge companion app is running on Windows | ✗ |+| 8 | start-relay | Start the adom-bridge-cli 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 | ✗ |+| 10 | test-relay | Register the relay with Adom Bridge for file streaming | ✗ | | 11 | test-adom-cli | GATE: carbon path + hydrogen-proxy reachability via adom-cli (6 retries) | ✗ | | 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 | ✓ |@@ -61,7 +61,7 @@ Adom-Workspace`.  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-ext`,+`verify-adom-bridge-cli`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`. gallia, the 8 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@@ -166,10 +166,10 @@ Writes the Adom session token into the distro at `/var/run/adom/api-key` ### 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.+routes through Adom Bridge's direct connect API.  ### Step 10 — test-relay (register relay)-Registers the relay (started by step 8, `start-relay`) with Adom Desktop for+Registers the relay (started by step 8, `start-relay`) with Adom Bridge for file streaming via the code-server proxy path. This enables `pull_file`, `send_files`, and `shell_execute`. 

@@ -71,13 +71,13 @@ cp /home/adom/project/myfile.txt /mnt/c/Users/john/Downloads/ cp /mnt/c/Users/john/Downloads/myfile.txt /home/adom/project/ ``` -### 3. `adom-desktop send_files` / `pull_file` (from inside the workspace, via the relay)+### 3. `adom-bridge-cli send_files` / `pull_file` (from inside the workspace, via the relay) ```bash # Send a workspace file to your Windows desktop's Downloads folder-adom-desktop send_files '{"filePaths":["/home/adom/project/myfile.txt"],"targetApp":"general","destinationFolder":"."}'+adom-bridge-cli send_files '{"filePaths":["/home/adom/project/myfile.txt"],"targetApp":"general","destinationFolder":"."}'  # Pull a Windows file into the workspace's /tmp-adom-desktop pull_file '{"filePaths":["C:\\Users\\john\\Downloads\\myfile.txt"],"saveTo":"/tmp"}'+adom-bridge-cli pull_file '{"filePaths":["C:\\Users\\john\\Downloads\\myfile.txt"],"saveTo":"/tmp"}' ```  ### 4. Open the workspace's `/home/adom/project/` in VS Code's File Explorer

@@ -1,9 +1,9 @@ --- name: hydrogen-workspace-lifecycle-description: WSL2 distro (`Adom-Workspace`) lifecycle management for Hydrogen Desktop on Windows. Import/export/unregister/terminate, code-server-as-HD-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run global WSL operations; touch ONLY Adom-Workspace so a co-installed Docker Desktop WSL integration stays safe. MUST READ before any workspace operation. Trigger words — wsl, workspace, distro, Adom-Workspace, restart workspace, terminate distro, unregister, wsl --import, wsl --unregister, code-server, workspace broken, workspace unhealthy, wsl hung, fix workspace, /wsl/status.+description: WSL2 distro (`Adom-Workspace`) lifecycle management for Hydrogen on Windows. Import/export/unregister/terminate, code-server-as-HD-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run global WSL operations; touch ONLY Adom-Workspace so a co-installed Docker Desktop WSL integration stays safe. MUST READ before any workspace operation. Trigger words — wsl, workspace, distro, Adom-Workspace, restart workspace, terminate distro, unregister, wsl --import, wsl --unregister, code-server, workspace broken, workspace unhealthy, wsl hung, fix workspace, /wsl/status. --- -# Hydrogen Desktop — WSL2 Workspace Lifecycle+# Hydrogen — WSL2 Workspace Lifecycle  > This is the WSL2-runtime version (default). The legacy Docker equivalent > (`HD_RUNTIME=docker`) is in the docker/ bucket.

@@ -1,7 +1,7 @@ --- name: hydrogen-workspace-monitoring description: >-  How Hydrogen Desktop monitors and manages the local WSL2 workspace distro+  How Hydrogen 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,