Adom Hydrogen (platform base)

@@ -68,7 +68,8 @@ package at all).** > (the in-distro updater daemon; removed from > [`adom/hd-windows-bootstrap`](/adom/hd-windows-bootstrap) in 0.2.3) and > [`adom/hd-skillpack`](/adom/hd-skillpack) (the short-lived separate skills-> package; its skills are bundled HERE as of 0.2.7). Updates are registry-native+> package; its skills are bundled HERE as of 0.2.7, hard-deleted 2026-07-16).+Updates are registry-native > via `adom-wiki pkg update` + [`adom/hook`](/adom/hook). The updater retirement > also removes the only `needs_sudo` package from the tree, so the old > `ADOMPKG_ALLOW_SUDO=1` requirement should die with it (verify on the v18 bake).@@ -119,10 +120,11 @@ The Carbon API key, `DefaultUid=1001`, the `host.docker.internal` alias.  ## Status (2026-07-16) -**PUBLISHED + PUBLIC**, latest `adom/[email protected]` (apps + skills model,-38 platform-generic skills bundled, incl. `hd-webview` + `hd-pup`). Deps resolve-anonymously. Golden image **v17** ships from+**PUBLISHED + PUBLIC**, latest `adom/[email protected]` (apps + skills model,+38 platform-generic skills bundled, incl. `hd-webview` + `hd-pup`; 0.2.9 = the+full stale-content audit sweep). Deps resolve anonymously. Golden image **v17**+ships from [hd-wsl2-image](https://github.com/adom-inc/hd-wsl2-image/releases) (baked with the deprecated adompkg; **v18 re-bake with `adom-wiki pkg` planned**, picking up-this version, hd-windows-bootstrap 0.2.4, and no retired packages). Build the+this version, hd-windows-bootstrap 0.2.6, and no retired packages). Build the image on the laptop via AD or in CI, never in the cloud container.

@@ -4,7 +4,7 @@   "type": "bootstrap",   "title": "Hydrogen Desktop Bootstrap (apps + skills)",   "brief": "Layer Hydrogen Desktop's workspace onto a standard Adom workstation.",-  "version": "0.2.8",+  "version": "0.2.9",   "description": "Hydrogen Desktop's PLATFORM-GENERIC workspace layer on top of adom/core. Installs adom/core for the full Adom ecosystem, then adds everything common to running inside Hydrogen Desktop on ANY platform: the platform-generic hd-* skills (BUNDLED in this package by design; wsl2 skills ride adom/hd-windows-bootstrap, mac skills ride adom/hd-mac-bootstrap) and the generic HD editor configuration (Claude Code CLI + extension, VS Code settings, trusted domains). Platform-specific layers depend on THIS: adom/hd-windows-bootstrap, adom/hd-mac-bootstrap.",   "org": "adom",   "tags": [@@ -30,4 +30,4 @@     "README.md",     "skills/**"   ]-}+}\ No newline at end of file

@@ -4,7 +4,7 @@   "type": "bootstrap",   "title": "Hydrogen Desktop Bootstrap (apps + skills)",   "brief": "Layer Hydrogen Desktop's workspace onto a standard Adom workstation.",-  "version": "0.2.8",+  "version": "0.2.9",   "description": "Hydrogen Desktop's PLATFORM-GENERIC workspace layer on top of adom/core. Installs adom/core for the full Adom ecosystem, then adds everything common to running inside Hydrogen Desktop on ANY platform: the platform-generic hd-* skills (BUNDLED in this package by design; wsl2 skills ride adom/hd-windows-bootstrap, mac skills ride adom/hd-mac-bootstrap) and the generic HD editor configuration (Claude Code CLI + extension, VS Code settings, trusted domains). Platform-specific layers depend on THIS: adom/hd-windows-bootstrap, adom/hd-mac-bootstrap.",   "org": "adom",   "tags": [

@@ -74,8 +74,8 @@ as a `Cookie: session_token=...` header on every request to `carbon.adom.inc`. ### Reading the token programmatically  ```bash-# From the control API-curl http://127.0.0.1:47084/auth-token+# From the control API (default 47084; the port is dynamic — read ~/.adom/hd-control-url)+curl "$(cat ~/.adom/hd-control-url)/auth-token"  # From inside the workspace (injected by setup step inject-api-key, mode 644) # run inside the workspace — WSL2: `wsl -d Adom-Workspace -u adom -- cat /var/run/adom/api-key`; Docker: `docker exec <container> cat /var/run/adom/api-key`@@ -322,5 +322,5 @@ full endpoint reference. - **hd-ui** -- menu layout, where profile menu lives - **hd-setup** -- bootstrap steps that depend on auth - **hd-settings** -- API Explorer (auth endpoints tab)-- **hd-networking** -- control API port (47084)+- **hd-networking** -- control API port (default 47084; dynamic — read ~/.adom/hd-control-url) - **carbon-preferences** -- user preferences that require auth

@@ -45,7 +45,7 @@ logo = go straight to the Dashboard.) Source: `EditorNav.svelte` → `.logo-butt | *— Container —* | (state shown: running/stopped/…) | | **Start / Restart / Stop Container** | Workspace lifecycle (see **hd-workspace-lifecycle**) | | *— Admin —* | |-| **Setup Steps** | Show the setup-steps panel — the setup cascade for the active runtime (16 steps under WSL2); see **hd-setup-steps** / **hd-setup** |+| **Setup Steps** | Show the setup-steps panel — the setup cascade for the active runtime (27 steps under WSL2); see **hd-setup-steps** / **hd-setup** | | **Virgin Reset** | Open the virgin-reset panel — wipe + re-run setup (see **hd-setup**) | | **Browser Picker Manager** | Manage saved browser choices per domain (see **hd-browser-picker**) | 

@@ -22,8 +22,8 @@ sources of truth you should hit first:  | Source | What it gives you | Where | |---|---|---|-| `GET /_manifest` | Curated, grouped, machine-readable list of the highest-value endpoints (path, method, args, description, `visibility`). `hd_api` forwards anything not listed. | `lib.rs:9144` |-| `GET /test/help` | Lists the `/test/*` diagnostics (window enumeration, UIA click, dialog classification, cascade reset). Gated behind `HD_TEST_API_ENABLED=1`. | `lib.rs:9723` |+| `GET /_manifest` | Curated, grouped, machine-readable list of the highest-value endpoints (path, method, args, description, `visibility`). `hd_api` forwards anything not listed. | `hd-control/src/lib.rs:11744` |+| `GET /test/help` | Lists the `/test/*` diagnostics (window enumeration, UIA click, dialog classification, cascade reset). Gated behind `HD_TEST_API_ENABLED=1`. | `hd-control/src/lib.rs:12423` |  **Base URL:** `http://127.0.0.1:<dynamic>` — the same loopback address from inside the workspace (WSL2 mirrored networking shares loopback with the Windows host) and on the@@ -347,8 +347,10 @@ not `~/`). Tilde doesn't expand through the exec chain. POST /container-exec {"command":"ls /home/adom/project"} ``` -### Trigger setup re-run after completion-The trigger file poller STOPS when all steps are done. Use the API instead:+### Re-run a setup step after completion+The trigger file poller STOPS when all steps are done. `POST /setup/run-all` is+**REFUSED as deprecated** — don't use it. Re-run one step by id (or relaunch HD to+auto-run the cascade): ```-POST /setup/run-all+POST /setup/step/<id> ```

@@ -14,7 +14,7 @@ description: >  # Hydrogen Desktop -- Bridge Ecosystem -HD is the bridge between your Docker container and the user's Windows desktop.+HD is the bridge between your WSL2 workspace (Docker only under `HD_RUNTIME=docker`) and the user's Windows desktop. All commands go through the relay at ws://localhost:8765/.  ---@@ -297,11 +297,11 @@ status` until installed). To use a catalog bridge: ## File Transfer  ```bash-# Send file from Docker to Windows desktop-adom-desktop send_files '{"files": [{"path": "/home/adom/project/output.pdf"}]}'+# Send file from the workspace to the Windows desktop+adom-desktop send_files '{"filePaths": ["/home/adom/project/output.pdf"], "saveTo": "C:\\Users\\john\\Downloads"}' -# Pull file from Windows to Docker-adom-desktop pull_file '{"remotePath": "C:\\Users\\john\\Downloads\\data.csv", "localPath": "/tmp/data.csv"}'+# Pull file from Windows into the workspace+adom-desktop pull_file '{"filePaths": ["C:\\Users\\john\\Downloads\\data.csv"], "saveTo": "/tmp"}' ```  ---@@ -310,7 +310,7 @@ adom-desktop pull_file '{"remotePath": "C:\\Users\\john\\Downloads\\data.csv", "  ```bash # Toast notification-adom-desktop notify_user '{"message": "Build complete!", "duration_ms": 5000}'+adom-desktop notify_user '{"title": "Build", "body": "Build complete!", "level": "info"}'  # Open URL in user's browser adom-desktop desktop_open_url '{"url": "https://..."}'

@@ -8,8 +8,8 @@ description: HD's Browser Picker — the canonical handler for EVERY URL that ge ## The Problem  HD wraps a WebView2 that contains:-- The Hydrogen SvelteKit frontend (localhost:1420)-- A code-server iframe (localhost:8080) with VS Code + Claude Code+- The Hydrogen SvelteKit frontend (localhost:1420 in DEV mode only; prod HD serves it via the tauri protocol)+- The code-server iframe (VS Code + Claude Code) — code-server is host port 7380 (8080 is the internal workspace port) - Webview panel iframes (any external URL like wiki, google, etc.)  When a link is clicked anywhere in this stack, HD needs to:@@ -431,15 +431,15 @@ Tauri compiles capabilities INTO the binary at build time. Capability changes re #    HD UI → Settings → Browser Picker Manager → add domain → choose Pup #    OR let the 5s auto-countdown pick Pup for unknown URLs. -# 2. Trigger a URL open-adom-desktop shell_execute '{"command":"curl -s -X POST -d {\"url\":\"https://example.com\"} http://127.0.0.1:47084/open-url"}'+# 2. Trigger a URL open (read the live control URL — the port is dynamic, default 47084)+adom-desktop shell_execute '{"command":"CTRL=\"$(cat ~/.adom/hd-control-url)\"; curl -s -X POST -d {\"url\":\"https://example.com\"} \"$CTRL/open-url\""}'  # 3. Within 5s, picker auto-routes to Pup (or saved pref) # 4. Drive Pup with adom-desktop browser_* verbs adom-desktop browser_eval '{"sessionId":"default","js":"document.title"}'  # Force a picker dialog (no auto-timer)-adom-desktop shell_execute '{"command":"curl -s -X POST -d {\"url\":\"https://example.com\",\"force\":true} http://127.0.0.1:47084/open-url"}'+adom-desktop shell_execute '{"command":"CTRL=\"$(cat ~/.adom/hd-control-url)\"; curl -s -X POST -d {\"url\":\"https://example.com\",\"force\":true} \"$CTRL/open-url\""}'  # Route through the picker with the fresh-window toggle PRE-CHECKED (force = skip the # 5s timer). The user/AI then picks a native browser → opens fresh + auto-foregrounds.@@ -471,4 +471,4 @@ routing-policy guidance lives in **[hd-open-url](../hd-open-url/SKILL.md)**.  ## How HD skills get deployed (workflow note) -HD public skills (this one, hd-open-url, hd-monitor, etc.) live in the HD repo under `skills/public-facing/{shared,wsl2,docker}/<name>/SKILL.md`. They're deployed into the user's workspace by the `install-hd-skills` setup step, which is runtime-aware: it installs `shared/` plus the active runtime's bucket (`wsl2/` by default via the `/mnt/c` auto-mount; `docker/` via `docker cp` under `HD_RUNTIME=docker`), flat into `~/.claude/skills/<name>/`. See `hd-skill-catalog` (public) and `hd-skills-structure` (dev-internal) for the full layout.+HD public skills (this one, hd-open-url, hd-monitor, etc.) live in the HD repo under `skills/public-facing/{shared,wsl2,docker}/<name>/SKILL.md`. They're BUNDLED into the HD bootstraps (adom/hd-bootstrap ships `shared/`, adom/hd-windows-bootstrap ships `wsl2/`) and deployed flat into `~/.claude/skills/<name>/` at install/bake time. See `hd-skill-catalog` (public) and `hd-skills-structure` (dev-internal) for the full layout.

@@ -27,8 +27,10 @@ auto-approves in ~3s), a brief countdown plays, then you can capture frames. > This is **not** the same as host OS screenshots. `desktop_screenshot_*` > (see [hd-adom-desktop](../hd-adom-desktop/SKILL.md)) take true OS screenshots via > AD with zero dialogs. This skill is the **in-webview** share that captures what-> HD itself is rendering (the editor) via the browser's `getDisplayMedia`/Element-> Capture, gated by an in-app consent dialog. And it is distinct from+> HD itself is rendering (the editor). Inside HD, frames are grabbed **natively via+> CDP — there is no `getDisplayMedia`**; the browser `getDisplayMedia`/Element-Capture+> path applies only to **web-Hydrogen**. Either way the share is gated by an in-app+> consent dialog. And it is distinct from > [hd-permissions](../hd-permissions/SKILL.md) (WebView2 auto-granting mic/cam OS > permissions) — that's a different layer. @@ -62,6 +64,13 @@ browser window. Webview = "see HD itself"; Pup = "see the AI-driven browser."  ## Capture scopes & how a frame is taken +> **Inside HD, capture is native (CDP), not `getDisplayMedia`.** Tab/screen+> snapshots come from the native CDP path — no live `MediaStream`, no browser+> screen-picker. The store still flips `isSharing` and sets `displaySurface` so the+> same UI/consent flow applies. The `getDisplayMedia`/Element-Capture machinery+> described below is the **web-Hydrogen-only** path; HD reuses its *scopes* and+> consent surface, but grabs the actual pixels via CDP.+ `screenCaptureStore.ts` exposes the scope type and the capture functions:  ```ts@@ -81,17 +90,15 @@ Other store entry points you'll see: `startTabCapture()`, `startScreenCapture()` State shape: `{ isSharing, displaySurface, hasElementCapture, promptMessage }`, where `displaySurface` is `'browser'` (tab) / `'window'` / `'monitor'`. -### Element Capture (RestrictionTarget)--When `'RestrictionTarget' in window` and `getDisplayMedia` are available, HD can-**restrict a tab capture to a single DOM element** so only that panel is in frame:-`restrictCaptureTo(el)` builds a `RestrictionTarget.fromElement(el)` and calls-`track.restrictTo(target)` (a short ~3s settle window). This is how a panel-scoped-capture yields just the panel, not the whole webview.+### Element Capture (RestrictionTarget) — web-Hydrogen only -> Native (Tauri) note: inside HD, tab/screen snapshots come from the native CDP-> path rather than a live `MediaStream`; the store still flips `isSharing` and sets-> `displaySurface` to `'window'`/`'monitor'` so the same UI flow applies.+This path only runs in **web-Hydrogen** (not inside HD, which captures via CDP —+see the note above). When `'RestrictionTarget' in window` and `getDisplayMedia` are+available, it can **restrict a tab capture to a single DOM element** so only that+panel is in frame: `restrictCaptureTo(el)` builds a `RestrictionTarget.fromElement(el)`+and calls `track.restrictTo(target)` (a short ~3s settle window). That is how a+panel-scoped capture yields just the panel, not the whole webview. Inside HD, the+same panel scoping is achieved through the native CDP capture instead.  ## The AI sharing-approval flow 

@@ -63,7 +63,7 @@ NOT `{"owner": "jlauer12", "repository": "workspace"}` — adom-cli reads `conta  ## Workspace Env Vars -Set when the workspace is created (e.g. `create_container()` in `hd-docker/src/lib.rs` under the Docker runtime):+Set when the workspace is created. WSL2 is the default runtime, so the primary path is the WSL2 workspace-creation code; `create_container()` in `hd-docker/src/lib.rs` is the legacy Docker path (`HD_RUNTIME=docker`):  | Var | Value | Why | |---|---|---|@@ -124,7 +124,7 @@ adom-cli hydrogen workspace add-tab \   --panel-id desktop-pane-right \   --panel-type adom/a1b2c3d4-0031-4000-a000-000000000031 \   --display-name "Test Page" \-  --initial-state '{"url":"https://wiki-ufypy5dpx93o.adom.cloud/apps/shotlog"}'+  --initial-state '{"url":"https://wiki.adom.inc/apps/shotlog"}'  # 4. Move tab adom-cli hydrogen workspace move-tab \

@@ -15,12 +15,17 @@ description: >   publish to adom wiki, ai-first electronics, who am i and what can i do, post-setup explore. --- -# EDA tool discovery & onboarding (run in the background after setup)+# EDA tool discovery & onboarding (guidance for the per-tool setup threads) -You're (likely) a **second Claude conversation** launched after HD setup to quietly figure out-the user's electronics-design stack and show them what the AI-first Adom workflow unlocks. Be-**exploratory and opt-in** — detect first, then offer; never auto-install or auto-build. Do the-detection in the background, then come back with a short, friendly summary + one clear offer.+> **How this runs now (2026-07-16):** the setup cascade no longer runs a single combined+> "discovery" conversation. It opens **dedicated per-tool AI-thread steps** —+> `thread-kicad`, `thread-fusion360`, `thread-altium` (plus `thread-parts-search`,+> `thread-chip-fetcher`, etc.). This skill is the **detection + onboarding playbook those+> threads use**: how to detect each EDA tool, the opt-in philosophy, and what to offer.++When you're one of those EDA threads (or a user asks "what EDA software do I use / what can you+do with it"), be **exploratory and opt-in** — detect first, then offer; never auto-install or+auto-build. Detect quietly, then come back with a short, friendly summary + one clear offer.  ## 1. Detect (via `adom-desktop` — see `hd-adom-desktop`, `hd-bridges`, `pup`) 

@@ -18,7 +18,7 @@ How AD launches when nobody owns it: - Main window opens on launch (unless `--start-hidden`) - Autostart shortcut in `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\AdomDesktop.lnk` → launches on every boot - Registered in Add/Remove Programs (HKLM `Uninstall\AdomDesktop`)-- Auto-update polls `wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/version.json` every 4h+- Auto-update polls `wiki.adom.inc/static/apps/adom-desktop/version.json` every 4h - Footer shows the user's email + a "Sign in" / "Sign out" link  This is what AD looked like before HD existed and what it reverts to when HD vanishes.@@ -138,4 +138,4 @@ Port discovery if 47200 is taken: read `%USERPROFILE%\.adom\direct-api-port` (si - HD's AD spawn: `hydrogen-desktop/src-tauri/crates/hd-app/src/ad_supervisor.rs:spawn_ad_embedded()` - HD's tray menu: `hydrogen-desktop/src-tauri/crates/hd-app/src/tray.rs:install_tray()` - HD's NSIS hook (embed-AD on install / offer-uninstall): `hydrogen-desktop/src-tauri/crates/hd-app/installer/hd-install.nsh.template`-- AD's release manifest (used by HD's release pipeline to fetch bundled AD): `wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/version.json`+- AD's release manifest (used by HD's release pipeline to fetch bundled AD): `wiki.adom.inc/static/apps/adom-desktop/version.json`

@@ -3,7 +3,7 @@ name: hd-golden-image description: >   Your Hydrogen Desktop workspace is a PRE-BAKED golden WSL2 image, not a   machine that installed itself step-by-step. gallia, the 8 Adom CLIs, the-  `claude` CLI + Claude Code VS Code extension, code-server, the VS Code+  Claude Code VS Code extension, code-server, the VS Code   settings / trusted-domains / activity-bar config, AND all the hd-* self-   awareness skills are BAKED at image-build time — none of them were installed   by a setup step. READ THIS when a user asks "why is X already here", "how do@@ -32,8 +32,9 @@ The golden rootfs ships, pre-installed and smoke-gated, with:  - **gallia** (deployed via its `install.mjs` snapshot) - the **8 Adom CLIs** (`adom-cli`, `adom-desktop`, etc. — at `/usr/local/bin`)-- the **`claude` CLI** + the **Claude Code VS Code extension** (the extension-  auto-updates via VS Code's `extensions.autoUpdate`)+- the **Claude Code VS Code extension** (baked; auto-updates via VS Code's+  `extensions.autoUpdate`). The **`claude` CLI** is NOT baked — it's installed+  at runtime by the `install-claude-cli` setup step - **code-server** + node, plus a baked **systemd** unit that owns code-server   across distro boots and HD restarts - VS Code **settings.json** (dark theme, Claude permissions), the@@ -44,7 +45,8 @@ The golden rootfs ships, pre-installed and smoke-gated, with:  Because all of this is baked, the OLD setup steps that used to install it were **removed**: `install-gallia`, `install-adom-cli`, `install-hd-skills`,-`install-claude-cli`, `install-claude-ext`, and `verify-adom-desktop` are gone.+`install-claude-ext`, and `verify-adom-desktop` are gone. (`install-claude-cli`+is NOT in this list — it's a LIVE step that installs the `claude` CLI at runtime.) You can see the removal comments in `setup_steps_wsl.rs` (around lines 421-450), e.g. *"install-gallia + install-adom-cli REMOVED — both baked into the golden image"* and *"install-hd-skills REMOVED — the hd-\* skills are baked"*. The@@ -66,7 +68,7 @@ sudo apt-get update -qq && sudo apt-get install -y ffmpeg   # or imagemagick, pa ```  So the rule when you hit **"command not found"**: **install it and proceed** — never-tell the user the workspace "can't do that." (This mirrors how `adompkg` helps install+tell the user the workspace "can't do that." (This mirrors how `adom-wiki pkg` helps install an app's dependencies for Adom Wiki apps: lightweight base, add what the user needs, when they need it.) Don't push to bake every tool into the image — the image stays lean and the AI provisions per task.@@ -111,18 +113,20 @@ The practical upshot for answering users: |---|---| | "How do I update gallia / the CLIs / the skills?" | You don't run an installer. A new golden image (`adom-inc/hd-wsl2-image`) is released, HD's `TARBALL_VERSION` is bumped, and on next launch HD migrates the distro — gallia/CLIs/skills come along baked. | | "Can I re-run `install-hd-skills` / `install-gallia`?" | No — those setup steps were **removed**. They don't exist anymore because the artifacts are baked. To refresh them, take a new image (tarball-version bump), not a setup step. |-| "Why is `claude` / the extension already signed-in-ready?" | The CLI + extension are baked; the only thing the cascade does is the one human **sign-in** (the `claude-auth` step). |+| "Why is `claude` / the extension already signed-in-ready?" | The **extension** is baked; the `claude` **CLI** is installed at runtime by `install-claude-cli`. Beyond that, the only thing the cascade does is the one human **sign-in** (the `claude-auth` step). | | "How do I reset to a clean image?" | `wsl --unregister Adom-Workspace` (or HD's Virgin Reset) → next setup re-imports the golden tarball (the cache can be cleared so it re-downloads). |  ## The cascade now just CONFIGURES the baked image -Because installation moved into the image, the WSL setup cascade shrank to **16-steps** that *configure* the already-complete workspace (ensure/start code-server,-activate the baked extension, set env vars, inject the API key, configure VS-Code, the relay/connectivity gates, Claude sign-in, and Welcome). See+Because installation moved into the image, the WSL setup cascade is now **26+steps** that mostly *configure* the already-complete workspace: ~14 config/auth+steps (ensure/start code-server, activate the baked extension, set env vars,+inject the API key, configure VS Code, the relay/connectivity gates, install the+`claude` CLI, Claude sign-in), then Welcome, then 9 AI-thread bootstrap steps and+a final verify + open-welcome. See [hd-setup-steps](../../wsl2/hd-setup-steps/SKILL.md) for the per-step detail.  ## Related skills - [hd-runtime-mode](../hd-runtime-mode/SKILL.md) — WSL2 (this golden-image path) vs the legacy Docker runtime - [hd-workspace-lifecycle](../../wsl2/hd-workspace-lifecycle/SKILL.md) — start/stop/reset/migrate the imported distro-- [hd-setup-steps](../../wsl2/hd-setup-steps/SKILL.md) — the 16 configure-the-image steps (what's left after baking)+- [hd-setup-steps](../../wsl2/hd-setup-steps/SKILL.md) — the 27 cascade steps (config/auth + AI-thread bootstrap) that run on top of the baked image

@@ -55,6 +55,8 @@ runtime, so in a given workspace you'll usually have exactly the right set. | **hd-notifications** | Reach the user outside the window — native Windows toasts + emergency taskbar flash via `notify_user`. | | **hd-captions** | Paint labeled text on the user's screen — a Win32 always-on-top caption overlay for demos / step callouts. | | **hd-welcome** | The static welcome page shown after setup completes. |+| **hd-self-update** | How HD updates itself: the "Restart to update (vX→vY)" banner (UpdateBanner.svelte) plus the AI-first update path. |+| **hd-workspace-updater** | How workspace skills/packages stay current — registry-native updates (`adom-wiki pkg update` + `adom/hook`); the old workspace-updater daemon is retired. | | **hd-skill-catalog** | The catalog of skills your Claude has in this workspace. | | **hd-overview** | This index. | 

@@ -20,7 +20,7 @@ runtime-specific advice.**  | `HD_RUNTIME` | Runtime | What the workspace is | Setup cascade | State file | |---|---|---|---|---|-| unset / `wsl2` | **WslDistro — DEFAULT** | WSL2 Ubuntu distro `Adom-Workspace` (`wsl --import`) | 16 steps | `setup-steps-wsl.json` |+| unset / `wsl2` | **WslDistro — DEFAULT** | WSL2 Ubuntu distro `Adom-Workspace` (`wsl --import`) | 27 steps | `setup-steps-wsl.json` | | `docker` | DockerDesktop — legacy fallback | Docker container (Docker Desktop) | 24 steps | `setup-steps.json` |  WSL2 is the default — you only get Docker if `HD_RUNTIME=docker` was set before

@@ -3,12 +3,20 @@ name: hd-self-update description: "How the AI keeps the Hydrogen Desktop APP itself (the Windows/macOS frontend, not the workspace) up to date — AI-first, consent-based. Use when asked \"is there an HD update\", \"update Hydrogen Desktop\", \"is my HD current\", \"what version of HD am I on\", \"update the app\", \"new HD version\". Trigger words: HD update, update hydrogen desktop, app update, is HD current, HD version, new version of HD, relaunch to update, self-update." --- -# HD Self-Update — the AI updates the app for you (consent-based)+# HD Self-Update — the app updates itself (a banner + an AI path)  This is how the **Hydrogen Desktop app itself** (the Windows/macOS shell around your editor)-stays current. It is NOT the `workspace-updater` (that's the in-distro tooling). It's **AI-first**:-there is no nagging button — the AI notices a new HD version, tells you both version numbers, and-on your OK downloads + relaunches onto the new version.+stays current. It is NOT how the in-distro tooling/skills update (those converge registry-native+via `adom-wiki pkg update` + the `adom/hook` prompt hook). There are **two ways** a new HD version+gets applied, and they share one backend:++1. **The Restart-to-update banner (what the user sees).** When the updater supervisor+   (`updater.rs`) has silently downloaded + SHA-verified a newer version in the background, HD+   shows a top-of-app bar: **"Restart to update (vX → vY)"** (`UpdateBanner.svelte`). One click+   calls `updater_install` and relaunches onto the new version. If the user ignores it, the staged+   update auto-applies on the next launch anyway.+2. **The AI-first path (you).** You can also proactively notice a new version, tell the user both+   numbers, and on their OK apply it — same backend, no waiting for the banner.  ## When to check Check at the **start of a session** and whenever the user asks about updates. Don't poll@@ -42,8 +50,9 @@ few seconds — you can pick the conversation right back up. - **Consent-first.** Never relaunch HD without the user's OK (it restarts their app). Pick a   natural break — not mid-task. - **State both versions** (current → latest) so the user knows what's changing.-- This updates the **app shell only**. Editor extensions/code-server use the reload banner;-  in-workspace tooling/skills use the `workspace-updater`. Don't confuse the three.+- This updates the **app shell only**. Editor extensions/code-server use their own reload banner;+  in-workspace tooling/skills converge registry-native (`adom-wiki pkg update` via `adom/hook`).+  Don't confuse the three.  ## Resolving the control port Read it from `VSCODE_PROXY_URI` / the HD `[ports]` log line (default control API `47084`), or

@@ -9,7 +9,7 @@ You're running inside a Hydrogen Desktop workspace — a **WSL2 Ubuntu distro `Adom-Workspace`** by default, or a **Docker container** under the legacy `HD_RUNTIME=docker` runtime. HD ships a curated catalog of public skills (all named `hd-*`) so your Claude knows about HD's own interface, networking, setup-flow, and gotchas. The `install-hd-skills` setup step deploys them **flat into+flow, and gotchas. They are BUNDLED into the HD bootstraps (adom/hd-bootstrap ships the shared/ set, adom/hd-windows-bootstrap the wsl2/ set) and deployed **flat into `~/.claude/skills/<name>/SKILL.md`** automatically.  ## How the catalog is bucketed (and what you actually have)@@ -23,7 +23,7 @@ The public skills live in three buckets in the HD repo under - **`docker/`** — the legacy Docker implementations of the same topics, plus the   Docker-Desktop-only skills. Installed only when `HD_RUNTIME=docker`. -`install-hd-skills` deploys `shared/` **plus the active runtime's bucket** —+The bootstraps deploy `shared/` **plus the active runtime's bucket** (WSL2 skills ride adom/hd-windows-bootstrap) — mirroring `runtime/mod.rs::select_runtime()`. So you have exactly one runtime's flavor of each topic, never both. **Read `hd-runtime-mode` first** to confirm which runtime you're in.@@ -94,7 +94,7 @@ build pipeline, debugging the Tauri/WebView2 source, internal architecture, postmortems. They live in the HD repo but are **NEVER** deployed to user workspaces. -The split is enforced by the `install-hd-skills` step, which only reads+The split is enforced by the bootstrap bundling, which only ships `skills/public-facing/{shared,<runtime>}/hd-*/` — never `dev-internal-facing/`.  | Folder | Audience | Deployed to user workspaces? |@@ -115,5 +115,4 @@ The split is enforced by the `install-hd-skills` step, which only reads  ## When skills get refreshed -The `install-hd-skills` step deploys skills. Re-run it via-`POST /setup/run-step {"id":"install-hd-skills"}` to refresh after an HD update.+Skills are deployed by the bootstrap postinstall at install/bake time. To refresh after a skills change, the workspace picks up new bootstrap versions via `adom-wiki pkg update` (the `adom/hook` prompt hook) — or a fresh golden image. There is no `install-hd-skills` setup step (removed).

@@ -33,7 +33,7 @@ fact. (Most skill bugs are confident, untested assertions.) | Copy | Path | Role | |---|---|---| | **Live (ephemeral)** | `~/.claude/skills/<name>/SKILL.md` (flat) | What the running AI reads NOW. Editing here fixes THIS session and lets you test — but it's wiped on virgin reset / replaced by the next image. |-| **Canonical (baked)** | repo `skills/public-facing/{shared,wsl2,docker}/<name>/SKILL.md` | What the golden image is built from. On the laptop the repo is auto-mounted at `/mnt/c/Github/hydrogen-desktop/...` (the same tree the install step reads). The bake pulls from `origin`. |+| **Canonical (baked)** | repo `skills/public-facing/{shared,wsl2,docker}/<name>/SKILL.md` | What the golden image is built from. On the laptop the repo is auto-mounted at `/mnt/c/Github/hydrogen-desktop/...` (the same tree the bootstrap bundles / the golden image bakes). The bake pulls from `origin`. |  A fix isn't done until it's in the **canonical** copy and pushed. 

@@ -33,7 +33,7 @@ HD's window has these regions (top to bottom, left to right): - Panes are split and resizable  ### Setup Panel (bottom)-- Collapsible panel showing the setup-cascade steps (16 steps under the WSL2 runtime)+- Collapsible panel showing the setup-cascade steps (27 steps under the WSL2 runtime) - See `hd-setup` skill for details  ## Menus@@ -62,7 +62,7 @@ The main menu, opened by clicking the Adom logo at the top-left. Items are group - **Stop** — stops the workspace; under WSL2 this terminates the `Adom-Workspace` distro, under the Docker runtime it's `docker stop <container>`.  **ADMIN**-- **Setup Steps** — opens the setup panel (the setup cascade for the active runtime; 16 steps under WSL2); see hd-setup-steps+- **Setup Steps** — opens the setup panel (the setup cascade for the active runtime; 27 steps under WSL2); see hd-setup-steps - **Virgin Reset** — opens the virgin reset section of the setup panel; see hd-volume for what each toggle deletes - **Browser Picker Manager** — configure per-domain default browser/profile prefs; see hd-browser-picker 

@@ -25,15 +25,16 @@ It's served locally at `http://localhost:1420/welcome.html` by HD's dev file ser ## When it appears  - Automatically as the final setup step. On the WSL2 runtime (default) that is-  the `open-welcome` gate (step 16 of 16); on the legacy Docker runtime it's-  the last of the 24 steps.+  the `open-welcome` gate — the final step of the 27-step cascade; on the legacy+  Docker runtime it's the last of the 24 steps. - Can be opened manually via the API  ## How to open it -### From inside the Docker container (the standard way)+### From inside the WSL2 workspace (the standard way) -This is how the setup steps do it, and how any AI inside the container should:+This is how the setup steps do it, and how any AI inside the workspace distro+(the legacy Docker container works the same way) should:  ```bash adom-cli hydrogen webview open-or-refresh \@@ -43,7 +44,7 @@ adom-cli hydrogen webview open-or-refresh \ ```  The URL is rendered by HD's WebView2 on Windows, so `localhost:1420` resolves-to HD's dev file server on Windows, NOT to anything inside the container.+to HD's dev file server on Windows, NOT to anything inside the workspace distro.  ### From outside (via HD control API) @@ -67,7 +68,7 @@ curl -X POST http://127.0.0.1:47083/api/workspaces/editor/{owner}/{repo}/current ## IMPORTANT: This is NOT  - NOT the adom.inc homepage (https://adom.inc)-- NOT the wiki (https://git-wiki-*.adom.cloud)+- NOT the wiki (https://wiki.adom.inc) - NOT the VS Code welcome tab inside code-server  It is a LOCAL static page at `http://localhost:1420/welcome.html`, bundled

@@ -35,7 +35,7 @@ Mention this in the welcome answer so they don't get confused when their `whoami  Tell them they have access to a full electronics prototyping ecosystem. Specifically: -- **Build PCBs** — InstaPCB workflow with tscircuit, KiCad, our autorouter+- **Build PCBs** — design with tscircuit, KiCad, and our autorouter - **Build apps** — wiki webview apps via the app-creator skill - **Build CLIs** — automate workflows from the terminal - **3D viewers** — full 3D component / STEP / GLB viewing in HD (via adom-step / adom-tsci panels)@@ -58,7 +58,7 @@ A few quick orientation notes: Here's what we can do together in HD:  **Electronics & hardware**-- Build PCBs end-to-end (tscircuit → KiCad → Adom's autorouter → InstaPCB fab)+- Build PCBs end-to-end (tscircuit → KiCad → Adom's autorouter → order at a fab like JLCPCB/PCBWay) - Open KiCad or Fusion 360 on your Windows machine directly from here - Browse parts (DigiKey, Mouser, JLCPCB) with live pricing + Adom-internal inventory - Generate KiCad symbols, footprints, and 3D models from datasheets

@@ -13,9 +13,12 @@ both Claude Code and Codex) and re-resolves `adom/core` so newly added tools arr - Force a check now: `adom-wiki pkg update` - See what's installed / behind: `adom-wiki pkg list` / `adom-wiki pkg outdated` -Skills arrive via the **`adom/hd-skillpack`** package (all hd-* workspace skills, symlinked into-`~/.claude/skills/`). Org member apps (e.g. the employee build of adom-google) arrive via your-org's **`org-bootstrap`** meta-package. Both are just dependencies — kept current like everything.+Skills are **bundled into the HD bootstraps** — `adom/hd-bootstrap` ships the platform-generic+hd-* skills, `adom/hd-windows-bootstrap` ships the WSL2-specific ones (Kyle's `adom/hd-mac-bootstrap`+ships the mac ones), each deployed flat into `~/.claude/skills/`. (There is no separate skills+package; the short-lived `adom/hd-skillpack` was deleted 2026-07-16.) Org member apps (e.g. the+employee build of adom-google) arrive via your org's **`org-bootstrap`** meta-package. All are just+dependencies — kept current like everything.  ## The reload banner code-server self-updates on disk but only takes effect after a restart. Hydrogen Desktop detects@@ -27,7 +30,9 @@ editor. Extensions never banner — VS Code's own auto-update activates them. Publish it as an `adom-wiki` package, then add it as a **dependency** of the right bootstrap: - every container: `adom/core` · every HD workspace: `adom/hd-bootstrap` ·   org members only: your org's `org-bootstrap` · HD skills: add the skill to-  `skills/public-facing/` in the hydrogen-desktop repo and republish `adom/hd-skillpack`.+  `skills/public-facing/` in the hydrogen-desktop repo (`shared/` for platform-generic, `wsl2/` for+  Windows-only) and republish the matching bootstrap (`adom/hd-bootstrap` or+  `adom/hd-windows-bootstrap`). The hook's re-resolve delivers it fleet-wide within ~30 minutes of users prompting.  ## The retired daemon (history)