Adom Hydrogen (Windows / WSL2)

@@ -1,199 +0,0 @@-----name: hd-setup-description: >-  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, 28 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 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-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 | 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-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-`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 28 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.