Adom Hydrogen

@@ -41,26 +41,32 @@ From there, Hydrogen takes over and sets the container up for you.  ## First run: the automated setup -On first launch Hydrogen runs a fully automated **20‑step setup cascade**. It streams every step live, and the only things it needs from you are the two sign-ins (Adom, then Claude). It builds the Linux container, wires up the editor and toolchain, proves every connection actually works, and ends by opening your first AI conversations. The whole thing takes ~2 to 4 minutes on a typical machine (most of it the one‑time container download). Three moments are worth calling out, and the **[install walkthrough](install-walkthrough.md)** shows all of them screen by screen.+On first launch Hydrogen sets itself up. A calm card shows one plain sentence about what it is doing right now, and the only things it needs from you are a sign-in to Adom and, at the very end, a choice of which AI to use. On a PC that already has WSL2 it takes a few minutes, most of it the one-time workspace download. The **[install walkthrough](install-walkthrough.md)** shows it screen by screen, and **[setup steps pitfalls](setup-steps-pitfalls/README.md)** shows (with narrated videos) what happens on the PCs where things go wrong. -### 1 · It builds your Linux container+### 1 · It builds your workspace -Hydrogen's first and biggest job is creating the environment everything else runs in. It provisions a dedicated WSL2 Ubuntu distro called **`Adom‑Workspace`**: enabling the WSL2 feature first if your PC doesn't have it yet (the one point where Hydrogen may need a reboot, after which it picks right back up on its own), then downloading and SHA‑verifying a pre‑baked ~400 MB "golden" image, importing it, and starting code‑server (VS Code in the browser) inside it. The cascade refuses to advance until that environment is genuinely up and answering. From there it wires the editor to the platform in a handful of quick steps, reloading to activate the pre‑baked `adom‑vscode` extension, writing the Adom platform URLs, injecting and validating your Adom session token so every tool authenticates as you, and applying a clean dark VS Code layout.+Hydrogen's first and biggest job is the Linux computer your AIs work in: a WSL2 distro called **`Adom-Workspace`**, local to your PC. -![The setup cascade, reopened any time from the Adom menu: every step, its live output stream, and per-step run/rollback](screenshots/setup-steps.png)+- **No WSL2 yet?** Hydrogen turns it on for you. That needs one Windows restart, and only when you click Restart; setup carries on by itself afterwards.+- **The image:** it downloads a pre-built workspace image (about 800 MB), checks its SHA-256 and imports it. The download starts early and resumes after an interruption, and a damaged copy is thrown away and fetched fresh.+- **Connecting it to Windows:** it turns on WSL's mirrored networking, so the workspace and Windows share `localhost`. It records your original setting and puts it back if you uninstall. If you deliberately chose another networking mode, Hydrogen leaves it alone, and the Your AIs dialog tells you plainly what that costs.+- **The editor:** it starts VS Code (code-server) inside the workspace, listening on this PC only. -### 2 · It connects everything, then asks you to sign in to Claude: once+Before anything is built, it checks the things that would otherwise fail halfway: that the PC can run virtualization, and that the drive has room (about 8 GB). -Before bringing the AI online, Hydrogen proves the container can actually reach what it needs: it confirms **Bridge** (its companion app) is running, starts the in‑container relay, and tests both the fast direct path and the file‑transfer path, with a hard gate that `adom‑cli` reaches Adom on both the cloud and the proxy routes (if it can't, Hydrogen stops here rather than limp forward). Then it installs the Claude Code CLI and reaches the **one and only step that needs you**: signing in to Claude. Hydrogen restores your saved Claude credentials if they're still valid; otherwise it highlights and clicks the **Claude.ai Subscription** button and you approve in the browser. Hydrogen deliberately saves this single human moment for last, after all the hands‑off work is already done.+![The setup steps, reopened any time from the Adom menu: every step, its live output, and per-step run and rollback](screenshots/setup-steps.png) +### 2 · You sign in to Adom while it keeps going -### 3 · It opens your first AI conversations for you+Early on, Hydrogen opens the Adom sign-in in your browser: one Approve click if you are already signed in to adom.inc. It does not wait for you: the workspace keeps building in the background, and only the editor's final step waits for the sign-in. If a saved sign-in from an earlier install has expired, Hydrogen notices, clears it and asks you fresh. -With everything wired up, Hydrogen doesn't drop you at an empty editor, it **starts your first AI conversations automatically**. It opens the Welcome thread (your first prompt already sent), then quietly spins up two more: one that detects which electronics‑design tools you use (KiCad, Fusion 360, Altium, OrCAD/Cadence) and reports back what it found, and another that locates your quotes and offers to wire up a live loop that re‑prices your board as your KiCad design changes. By the time you glance over, an AI has already mapped your stack and lined up the next steps. Every one of these is **fully opt‑in**: nothing opens an app or writes code until you say so.+### 3 · It proves everything works, then hands you the keys -![Your first AI threads, already open as tabs](screenshots/conversation-tabs.png)+Hydrogen wires the editor to the platform, connects **Bridge** (the companion app that lets your AIs work with your desktop apps), and runs a final end-to-end check that refuses to call setup done until every piece really answers. Then it opens the Welcome page, **Your workspace is ready**, with **Choose your AI**: sign in to Claude Code or Codex, install Antigravity, Kimi Code or Grok Bot, or skip and come back later from the AI menu. -When the cascade finishes you're looking at a fully configured editor with Claude Code ready and your Welcome page open, and in minutes you are where the hero at the top of this page shows: a live AI thread working a real board.+### If setup stops++When something on your PC gets in the way, setup stops with a short, plain explanation and one button that fixes it, for example "Your C: drive is almost full", "Another app is using Hydrogen's editor port" (it names the app), "Hydrogen couldn't download your workspace", or "This PC can't run Hydrogen's workspace yet" with Microsoft's how-to. **Continue anyway** is always there, and **Report this problem** sends us the details; we try to fix reported problems within 2 hours.  --- 

@@ -24,6 +24,8 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Another WSL distro already running | Hydrogen never stops it on its own; when it needs one WSL restart it names the distro and lets you choose (1.0.559) | [video](other-distro-running.mp4) | `scripts/test-scenarios/other-distro-running.sh` | | Workspace download blocked | Setup stops in seconds and says your network is blocking Adom's download server (1.0.557) | [video](image-download-blocked.mp4) | `scripts/test-scenarios/image-download-blocked.sh` | | Another app holding the editor's port | A Windows app on 127.0.0.1:7380: from a generic error, to wrong advice, to naming the app in 20 seconds (1.0.560) | [video](port-7380-taken.mp4) | `scripts/test-scenarios/port-7380-taken.sh` |+| Damaged workspace image | Hydrogen notices the bad copy, fetches a fresh one and finishes (1.0.562) | [video](download-corrupt.mp4) | `scripts/test-scenarios/download-cache.sh corrupt` |+| Download cut short | Hydrogen resumes from where it stopped and finishes (1.0.562) | [video](download-resume.mp4) | `scripts/test-scenarios/download-cache.sh resume` |  <video controls preload="metadata" width="1080" src="setup-steps-pitfalls/wsl2-from-scratch.mp4" style="max-width:100%;height:auto"></video> @@ -65,6 +67,14 @@ Each video was recorded on a test PC with the build named in its caption, sped u  *Another app on the editor's port, 1.0.556, 1.0.559 and 1.0.560: Hydrogen now asks Windows who is listening and names the app.* +<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/download-corrupt.mp4" style="max-width:100%;height:auto"></video>++*A damaged workspace image, recorded on 1.0.562: the fingerprint check catches it and setup quietly downloads a fresh copy.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/download-resume.mp4" style="max-width:100%;height:auto"></video>++*A download cut short, recorded on 1.0.562: setup resumes from 250 MB instead of starting over.*+ ## The pitfalls, by setup phase  **Tested by** names the scenario script that reproduces it on a test PC. *Not yet* means it is documented here and handled in the code, but has no automated reproduction yet.@@ -107,8 +117,8 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Pitfall | What you see | What Hydrogen does | Tested by | |---|---|---|---| | Slow download of the workspace image | Progress with size, speed and time left | Starts the download early (it overlaps the WSL restart) and resumes after an interruption | Not yet |-| Download cut short (restart, crash, network drop) | "Stopped at X of Y, resumes" | Resumes from where it stopped | Not yet |-| Corrupt download | Setup stops on the image check | Deletes it; Run setup again downloads it fresh | Not yet |+| Download cut short (restart, crash, network drop) | Nothing alarming: setup keeps building | Resumes from where it stopped and checks the finished file (verified on 1.0.562: resumed from 250 MB) | `download-cache.sh resume`, [video](download-resume.mp4) |+| Corrupt download, or a damaged cached image | Nothing alarming: setup keeps building | The SHA-256 check catches it, deletes the copy and downloads a fresh one without stopping (verified on 1.0.562) | `download-cache.sh corrupt`, [video](download-corrupt.mp4) | | The workspace download is blocked (company network, VPN, proxy, security tool) | 1.0.557+: "Hydrogen couldn't download your workspace. Your PC could not reach Adom's download server..." (was, on 1.0.556: "open PowerShell and run wsl --unregister", the wrong fix) | Stops within seconds, no hang, no crash; Run setup again resumes once the network allows it | `image-download-blocked.sh`, [video](image-download-blocked.mp4) | | Not enough disk space | 1.0.556: "Your C: drive is almost full (N GB free). Hydrogen's workspace needs about 8 GB..." before anything is built | Checks before building; if a drive fills anyway, the four-minute no-progress watchdog says the drive is full instead of asking for a Windows restart (which it did before) | `disk-almost-full.sh`, [video](disk-almost-full.mp4) | | A workspace left half-registered by a crash | (was) every import failed | Removes only Hydrogen's own leftover and imports again | Not yet |

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯