Adom Hydrogen (platform base)

@@ -1,138 +1,86 @@ --- name: hydrogen-golden-image description: >-  Your Hydrogen workspace is a PRE-BAKED golden WSL2 image, not a-  machine that installed itself step-by-step. The adom/core wiki package-  (gallia's replacement; gallia is deprecated), the 8 Adom CLIs, the-  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-  I update gallia", "re-run install-hydrogen-skills / install-gallia / install-claude",-  or "where did these skills/CLIs come from": the answer is the image, and-  updates come from a tarball-version bump, NOT a setup step. Trigger words —-  golden image, pre-baked, baked image, adom-golden, adom-golden.tar.gz, hydrogen-wsl2--  image, wsl --import, tarball version, adom-tarball-version, migrate tarball,-  update gallia, reinstall gallia, install-hydrogen-skills, install-gallia, install--  claude-cli, install-claude-ext, verify-adom-bridge-cli, why is gallia here, where-  did the CLIs come from, how do I update the workspace, re-run setup, lightweight-  image, install on demand, command not found, ffmpeg not installed, install a tool,-  apt-get install, missing tool, is ffmpeg installed, install imagemagick/pandoc.+  Your Hydrogen workspace starts from a THIN golden WSL2 image (v24-thin and+  later): the image carries ONLY the OS baseline — Ubuntu, systemd, code-server,+  the folder contract, and the adom-wiki CLI. EVERYTHING Adom (the adom/core+  toolchain, the 8 CLIs, all hydrogen-* skills, the editor extensions including+  Claude Code) is installed LIVE by the setup cascade's first+  `adom-wiki pkg install adom/hydrogen-windows-bootstrap`, and kept current by+  the registry updater. READ THIS when a user asks "where did these skills/CLIs+  come from", "why did first-run setup take a few minutes", "how do I update+  the workspace", or "what's actually in the image". Trigger words — golden+  image, thin image, pre-baked, baked image, adom-golden, adom-golden.tar.gz,+  wsl --import, tarball version, adom-tarball-version, migrate tarball,+  install-hydrogen-skills, where did the CLIs come from, how do I update the+  workspace, re-run setup, lightweight image, install on demand, command not+  found, missing tool, apt-get install, is ffmpeg installed. --- -> NOTE (2026-07-21): gallia is deprecated. The base workspace install is now the-> adom/core wiki package (`adom-wiki pkg install adom/core`); the workspace-> self-updates via `adom-workspace-updater` (which re-pulls newer skills/CLIs-> periodically). References to gallia below are historical.--# Hydrogen Workspace = a pre-baked golden WSL2 image--Your workspace did **not** build itself by installing things one step at a time.-It was imported, fully-formed, from a **golden WSL2 image** that already contains-everything. Understanding this answers a whole class of "why is X here / how do I-update X" questions correctly.--## What's baked in (NOT installed at first-run)--The golden rootfs ships, pre-installed and smoke-gated, with:--- **the adom/core wiki package** (gallia's replacement; skills/CLIs come from-  signed adom-wiki packages, kept current by `adom-workspace-updater`)-- the **8 Adom CLIs** (`adom-cli`, `adom-bridge-cli`, etc. — at `/usr/local/bin`)-- 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 Hydrogen restarts-- VS Code **settings.json** (dark theme, Claude permissions), the-  **trusted-domains** list, and the **activity-bar trim** (all patched into-  `workbench.html` at bake time)-- all **hd-\* self-awareness skills** (the `shared/` + `wsl2/` buckets, flattened-  into `~/.claude/skills/<name>/`)--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-ext`, and `verify-adom-bridge-cli` 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-hydrogen-skills REMOVED — the hd-\* skills are baked"*. The-`install-adom-vscode` step still exists but **installs nothing** — it only proves-the baked extension *activated* (the `:8821` editor-control API answers).--## Lightweight by design — install other tools on demand--The golden image is deliberately **minimal**: it bakes the **Adom essentials** above-and little else. General-purpose tools are **not** pre-installed — **ffmpeg/ffprobe,-imagemagick, pandoc, jq, and friends are absent on purpose**, to keep the image small-and fast to download and migrate.--That is **not a limitation.** When a task needs a tool that isn't here, **install it on-demand and keep going.** The workspace has **passwordless sudo** + apt:--```bash-sudo apt-get update -qq && sudo apt-get install -y ffmpeg   # or imagemagick, pandoc, jq, …-```--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 `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.--## Where the image comes from--The image is built and released from the **public** `adom-inc/hd-wsl2-image`-repo. Hydrogen downloads the release asset `adom-golden.tar.gz` **anonymously** (Hydrogen-users have no GitHub identity), verifies its SHA-256, then `wsl --import`s it as-the `Adom-Workspace` distro. Evidence in `runtime/wsl.rs`:--- `TARBALL_URL_PLACEHOLDER` / `TARBALL_SHA256_PLACEHOLDER` (~lines 142-145) — the-  GitHub-release download URL + expected hash-- `download_tarball()` (~line 1893) — streams the ~550 MB asset to a cached-  `adom-golden.tar.gz` (under `%LocalAppData%\Adom\HydrogenDesktop\cache`),-  reusing the cache if present so a re-setup doesn't re-download-- `fresh_import()` (~line 307) — `wsl --import Adom-Workspace … --version 2`--So when a user asks **"why is gallia/the CLIs/these skills already here?"** the-answer is: they came pre-installed in the golden image — nothing installed them-on your machine.--## How updates actually happen — a tarball-version bump, NOT a setup step--The installed image carries a version label at **`/etc/adom-tarball-version`**-(const `TARBALL_VERSION_FILE`), written on import. Hydrogen's expected version is the-`TARBALL_VERSION` const in `runtime/wsl.rs` (~line 152). On each launch Hydrogen-compares them:--- `read_installed_version()` reads `/etc/adom-tarball-version` from inside the-  distro-- if it differs from `TARBALL_VERSION`, Hydrogen runs **`migrate_to_new_tarball()`**-  (~line 2076): terminate → full `wsl --export` rollback backup → back up-  `/home/adom` → `wsl --unregister` → `fresh_import()` the new image → restore-  `/home/adom` → `write_installed_version()`. Your files in `/home/adom` survive;-  the system layer is swapped wholesale. On any failure it rolls back from the-  export so you're never left with no distro.--The practical upshot for answering users:--| User asks | Correct answer |-|---|---|-| "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, Hydrogen's `TARBALL_VERSION` is bumped, and on next launch Hydrogen 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 **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 Hydrogen'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 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-[hydrogen-setup-steps](../../wsl2/hydrogen-setup-steps/SKILL.md) for the per-step detail.--## Related skills-- [hydrogen-workspace-lifecycle](../../wsl2/hydrogen-workspace-lifecycle/SKILL.md) — start/stop/reset/migrate the imported distro-- [hydrogen-setup-steps](../../wsl2/hydrogen-setup-steps/SKILL.md) — the 27 cascade steps (config/auth + AI-thread bootstrap) that run on top of the baked image+# Hydrogen Workspace = a thin golden image + a live first install++Since image **v24-thin** (2026-08-13, John's call: "simple golden image, setup+steps configure everything") the golden image is deliberately MINIMAL. What the+tarball actually contains:++- Ubuntu base + systemd (PID 1), the adom user, the folder contract+  (`~/project` is the workspace root)+- **code-server** (the VS Code backend) + its systemd unit+- systemd units for the relay and shotlog, guarded by `ConditionPathExists` so+  they wait quietly until setup installs their binaries+- the **adom-wiki CLI seed** at `~/.local/bin/adom-wiki` — the installer that+  brings everything else+- a first-boot oneshot that mints the per-import `/etc/adom-distro-id`++**Everything else arrives at setup time.** The setup cascade's update-packages+step runs `adom-wiki pkg install adom/hydrogen-windows-bootstrap`, the leaf+package whose dependency tree pulls hydrogen-bootstrap → adom/core and the+whole ecosystem: ~150 skills, ~22 packages, the 8 Adom CLIs, and ALL editor+extensions (adom-theme, adom-vscode, anthropic.claude-code). Measured cost:+about 7 minutes on a fresh install — that is the tradeoff for an image that is+125MB smaller and for day-one installs that are ALWAYS current (no stale baked+package can ever exist again; the slug-migration class of bug is structurally+impossible).++## Why this changed (history)++Images v15–v23 were FAT: the whole toolchain was baked at image-build time,+which made first runs fast but froze whatever package versions (and package+NAMES) existed on bake day into every container for months — the root cause of+the retired-slug pinning bug (adom/[email protected] sitting next to+adom/hydrogen-bootstrap on live machines). If you are inside an older fat-image+workspace, everything below still applies to you; the content is the same,+only WHO installed it differs.++## How updates work (same in both eras)++- The registry updater keeps packages current: `adom/hook` runs+  `adom-wiki pkg update` on agent activity, and ah's setup gates on+  hydrogen-bootstrap matching the registry's latest.+- The IMAGE only changes when ah ships a new pinned tarball+  (`/etc/adom-golden-version` says which rootfs you're on;+  `/etc/adom-tarball-version` says what ah imported). An image bump requires a+  workspace re-import (Virgin Reset) — package updates never do.+- Force a full converge by hand:+  `adom-wiki pkg install adom/hydrogen-windows-bootstrap` (idempotent).++## "Command not found" / missing tools++The image intentionally ships no long-tail tooling. Get tools on demand:+`apt-get install <tool>` (via sudo where available), `apt python3-<lib>` for+Python libraries (PEP-668: prefer apt; `pip --break-system-packages` or a venv+otherwise), and `adom-wiki discover search -q <capability>` for Adom packages.+The Claude Code CLI is installed by the `install-claude-cli` setup step and+self-updates thereafter.++## Answering common user questions++- "Where did all these skills come from?" → the setup cascade's first package+  install (fat-era workspaces: baked into the image). They live flat in+  `~/.claude/skills/` and update via the registry.+- "Why did first-run setup take a few minutes?" → the live toolchain install;+  it is downloading the current versions of everything rather than using+  months-old baked copies.+- "How do I update the workspace?" → you almost never need to; the registry+  updater converges packages continuously. A tarball-version bump (rare, OS+  level) comes through ah and needs a re-import.