Adom Hydrogen (macOS / Lima)

@@ -1,199 +0,0 @@-----name: hydrogen-setup-description: >-  Hydrogen 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, 18 steps, wipe, reset workspace, keep auth, test setup.------# Adom Hydrogen — Setup Panel & Virgin Reset--Machine-runtime version (default). The legacy 24-step Docker cascade-(`HD_RUNTIME=docker`) is in the docker/ bucket.--## Zero-Click Goal--The Hydrogen 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, 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, Hydrogen downloads it — never-tell the user to install something manually. See the `hydrogen-golden-image` skill-for the baked-image model.--## The 16 Install Steps--The machine cascade is executed by `setup_steps_macos.rs` (`step_defs_machine()` /-`run_all_machine()`). `run_all_machine` is halt-on-failure, resume-not-restart, with-per-step 3× auto-retry. State is tracked in `setup-steps-macos.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 image into the workspace machine via-`machinectl import-tar Adom-Workspace`.--| # | ID | Label | Rollback? |-|---|---|---|---|-| 1 | ensure-workspace | Ensure the Lima VM `hd-builder` is up (provision it if missing — no host reboot needed on macOS), import golden image, create `adom` user, start code-server, verify code-server reachable from the Mac on 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 Bridge companion app is running on the Mac | ✗ |-| 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 Bridge 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 Hydrogen'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-hd-skills`,-`verify-adom-desktop`, `install-claude-cli`, `install-claude-ext`,-`write-vscode-settings`, `set-trusted-domains`, `clean-layout`. 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-`hydrogen-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_machine()`, after-the per-step 3× auto-retry is exhausted). Remaining steps are NOT executed.-`run_all_machine` 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 18 steps to pending (`setup-steps-macos.json`) | CLEAN / EXISTS |-| Workspace machine (`container`) | PRISTINE `machinectl remove Adom-Workspace` + reimport (ONLY that machine) | GONE / RUNNING / EXISTS |-| Machine 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 Hydrogen launch (restart_required) | CLEAN / EXISTS |-| VS Code state (`vscode_state`) | Queued wipe, flushed at next Hydrogen 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 machine reset is a PRISTINE `machinectl remove` + 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 Hydrogen launch-(restart_required), NOT immediate; there is no reboot for the wipe.--CRITICAL — the machine virgin reset only ever touches `Adom-Workspace`. It runs-`machinectl remove Adom-Workspace` — NEVER a global teardown (stopping/deleting the-`hd-builder` Lima VM itself or running global `machinectl` teardown), which would-knock out the user's other Lima VMs / `machinectl` machines (e.g. Docker-for-Mac's-own VM). 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 machine 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 /workspace/unregister` (destructive `machinectl remove Adom-Workspace`),-`POST /setup/virgin-reset`, `POST /setup/run-all`, `POST /setup/run-step`.--## Key Steps Explained--### Step 1 — ensure-workspace-The big one. Ensures the Lima VM `hd-builder` is up (provisions it if missing —-no host reboot needed on macOS), then `machinectl import-tar Adom-Workspace`-from the full pre-baked golden image `adom-golden.tar.gz` (pulled from the-`adom-inc/hd-lima-image` GitHub release — NOT a thin ~30 MB tarball, NOT a 390 MB-Docker image), creates the `adom` user, starts code-server, and verifies-code-server reachable from the Mac on port 7380. This single step replaces the-old Docker pull-image / create-container / start-container trio. The machine's-DEFAULT user is `adom` (UID 1001; under systemd-nspawn the default user comes from-the machine config / nsenter `-S 1001 -G 1001`), NOT root;-in-machine exec = `limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc '<cmd>'`-(root variant drops `-S 1001 -G 1001`) — NEVER `docker exec`.--### Step 5 — inject-api-key-Writes the Adom session token into the machine 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 `adom-host` gateway by `/etc/init-host-internal.sh`) and-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 Bridge 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 machine-(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 Hydrogen's right pane and HARD-FAILS-if the Welcome tab doesn't appear.--> Note: 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 `hydrogen-golden-image`.--## Machine Recreation--When the machine is removed and re-imported (step 1), the new machine is a-fully pre-baked Ubuntu from `adom-golden.tar.gz`. code-server binds-`0.0.0.0:7380` inside the machine and Lima exposes it to the Mac at-`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.