bootstrap
Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
← Commit history
Publish 0.1.0
69 files changed
+9280−3
README.md+71−1SKILL.md+25docs/hero.pnghooks/hydrogen-linux-platform-hygiene.sh+30host/hydrogen-host-setup.sh+255install.sh+11package.json+43page.json+32−2skills/hydrogen-adom-auth/SKILL.md+323skills/hydrogen-adom-bridge-triage/SKILL.md+164skills/hydrogen-adom-bridge/SKILL.md+136skills/hydrogen-adom-menu/SKILL.md+74skills/hydrogen-ai-agents-dev/SKILL.md+202skills/hydrogen-ai-agents/SKILL.md+200skills/hydrogen-ai-threads-api/SKILL.md+435skills/hydrogen-ai-threads/SKILL.md+58skills/hydrogen-annotate/SKILL.md+122skills/hydrogen-api/SKILL.md+827skills/hydrogen-bridges/SKILL.md+310skills/hydrogen-browser-picker/SKILL.md+175skills/hydrogen-captions/SKILL.md+103skills/hydrogen-capture-share/SKILL.md+133skills/hydrogen-claude-auth/SKILL.md+84skills/hydrogen-claude-management/SKILL.md+212skills/hydrogen-container-stats/SKILL.md+141skills/hydrogen-container/SKILL.md+143skills/hydrogen-demo-recording/SKILL.md+126skills/hydrogen-desktop-sse/SKILL.md+228skills/hydrogen-dock/SKILL.md+284skills/hydrogen-doctor/SKILL.md+78skills/hydrogen-eda-discovery/SKILL.md+129skills/hydrogen-editor-state/SKILL.md+62skills/hydrogen-embedded-bridge/SKILL.md+97skills/hydrogen-eval/SKILL.md+137skills/hydrogen-file-transfer/SKILL.md+103skills/hydrogen-golden-image/SKILL.md+60skills/hydrogen-key-values/SKILL.md+102skills/hydrogen-lightbulb/SKILL.md+71skills/hydrogen-monitor/SKILL.md+177skills/hydrogen-naming/SKILL.md+80skills/hydrogen-networking/SKILL.md+130skills/hydrogen-notifications/SKILL.md+100skills/hydrogen-open-url/SKILL.md+212skills/hydrogen-overview/SKILL.md+107skills/hydrogen-permissions/SKILL.md+71skills/hydrogen-port-watcher/SKILL.md+57skills/hydrogen-ports/SKILL.md+161skills/hydrogen-profile-menu/SKILL.md+104skills/hydrogen-project-workspaces/SKILL.md+61skills/hydrogen-recording/SKILL.md+88skills/hydrogen-runtime-mode/SKILL.md+38skills/hydrogen-screen-lock/SKILL.md+55skills/hydrogen-self-screenshot/SKILL.md+142skills/hydrogen-self-update/SKILL.md+91skills/hydrogen-settings/SKILL.md+125skills/hydrogen-setup-steps/SKILL.md+126skills/hydrogen-setup/SKILL.md+129skills/hydrogen-skill-loop/SKILL.md+120skills/hydrogen-staying-current/SKILL.md+44skills/hydrogen-topology/SKILL.md+111skills/hydrogen-ui/SKILL.md+222skills/hydrogen-volume/SKILL.md+82skills/hydrogen-wake-repair/SKILL.md+55skills/hydrogen-webview/SKILL.md+145skills/hydrogen-welcome/SKILL.md+64skills/hydrogen-who-am-i/SKILL.md+100skills/hydrogen-widget/SKILL.md+266skills/hydrogen-workspace-lifecycle/SKILL.md+79skills/hydrogen-workspace-monitoring/SKILL.md+152README.md+71−1@@ -1,3 +1,73 @@ # Adom Hydrogen (Linux) -The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.+The **Linux** platform layer for Hydrogen. On Linux, Hydrogen's workspace is a systemd-nspawn+machine on your own computer; this package makes both the computer and the workspace ready for+Hydrogen and its dock apps, on **Ubuntu, Debian and Fedora**.++```+adom/core+ └─ adom/hydrogen-bootstrap (platform-generic Hydrogen layer)+ ├─ adom/hydrogen-windows-bootstrap (Windows, WSL2)+ ├─ adom/hydrogen-mac-bootstrap (macOS, Lima)+ └─ adom/hydrogen-linux-bootstrap <- THIS: Ubuntu, Debian, Fedora+```++You never install this by hand: Hydrogen for Linux installs it in the workspace and runs its+host half on your computer during setup and after every update.++## Two halves++**In the workspace** (`install.sh`, then `hooks/hydrogen-linux-platform-hygiene.sh` after every+package update): ffmpeg with libx264 (AI runs that make video), the en_US.UTF-8 locale, and+earlyoom, as in the Windows workspace.++**On the computer** (`host/hydrogen-host-setup.sh`): Hydrogen runs it with **one password+prompt**. It installs only what is missing, says what it is about to change, and changes nothing+on a second run. `check` changes nothing at all; Hydrogen Doctor uses it.++## What it sets up++| Item | Why | Ubuntu / Debian | Fedora |+|---|---|---|---|+| H.264 playback | Hydrogen's webviews (WebKitGTK) play video through GStreamer; Adom's videos are H.264 High + AAC | `gstreamer1.0-libav`, `-plugins-bad`, `-plugins-good`, `-vaapi` | RPM Fusion free (announced on screen), `ffmpeg` in place of `ffmpeg-free`, `gstreamer1-plugin-libav` |+| AppImage runtime | Grok Bot and the Adom Bridge AppImage need FUSE 2 | `libfuse2t64` (24.04, Debian 13) or `libfuse2` | `fuse-libs` |+| Flatpak + Flathub | KiCad installs from Flathub | `flatpak` | (present) |+| Flatpak apps in menus now | KiCad's icon and entry without logging out | links in `~/.local/share` + `environment.d` | same |+| Tray icon | Hydrogen lives in the tray when closed | Ubuntu has it; Debian GNOME: `gnome-shell-extension-appindicator` | `gnome-shell-extension-appindicator` |+| Desktop portal | screenshots, screen capture, annotate | `xdg-desktop-portal` + `-gnome`, `-xapp` (Cinnamon) or `-kde` | `xdg-desktop-portal-gnome` |+| Dictate audio | Hydrogen records the mic itself | PipeWire's `pw-record` (or `pulseaudio-utils` on PulseAudio) | `pipewire-utils` |+| Clipboard tools | an annotate picture stays on the clipboard | `wl-clipboard`, `xclip` | same |+| Notifications, links | Adom Bridge notifications, opening links | `libnotify-bin`, `xdg-utils` | `libnotify`, `xdg-utils` |+| Out-of-memory guard | a full memory must not freeze the desktop | `earlyoom` where systemd-oomd is not running (Debian) | systemd-oomd |+| Adom fonts | dashboards and tiles | Familjen Grotesk, Satoshi, JetBrains Mono in `~/.local/share/fonts` | same |+| Workspace time zone | the workspace follows the computer | set on every run | same |+| Google Chrome (optional) | only the native browser bridge needs it; your default browser is kept | Google's .deb | Google's .rpm |++In the workspace it also installs the libraries headless Chrome needs (`libnss3`, `libnspr4`,+`libasound2t64`, `libgbm1` and the rest), so tools that drive Chrome there (Hero Studio, page+renders) work.++**Known gaps, next:** the workspace's Node is 18 and some tools (`@puppeteer/browsers`) need 20 or+later; tools in the workspace cannot reach the computer's Adom Bridge relay the way `adom-bridge+ping` does (Hero Studio's pup fallback answers "Adom Desktop did not answer browser_status").++It also checks, and reports in Doctor: the Adom Bridge window list extension on GNOME Wayland+(Adom Bridge installs it; it is active after logging out and in once), Adom Bridge's mesh+(on, relay mode), firewalld for the mesh port, and the login keyring Chrome uses.++## Checking a computer++```bash+bash host/hydrogen-host-setup.sh check+```++```+Hydrogen host check 0.1.0 on Ubuntu 24.04.5 LTS (ubuntu:GNOME, wayland)+ h264 ok avdec_h264 decodes the High-profile sample+ fuse2 ok libfuse.so.2 present (AppImages run)+ flatpak ok flatpak with Flathub+ tray ok Ubuntu's own AppIndicator extension+ ...+```++`relogin` means installed, active after logging out and in once.
SKILL.mdadded+25@@ -0,0 +1,25 @@+---+name: hydrogen-linux-bootstrap+description: What Adom Hydrogen needs on a Linux computer and in its workspace, and how to check or fix it (H.264 playback, AppImages, Flatpak/KiCad, the GNOME tray, portals, Dictate audio, fonts, ffmpeg). Use when a video will not play in Hydrogen on Linux, an AppImage will not start, KiCad is missing, there is no tray icon, or the doctor reports a Linux host item.+---++# Hydrogen on Linux: host and workspace setup++Hydrogen runs `host/hydrogen-host-setup.sh` from this package on the computer:++```bash+S=~/.local/share/adom/hydrogen-linux-bootstrap/host/hydrogen-host-setup.sh # in the workspace+bash hydrogen-host-setup.sh check # on the computer: one line per item, changes nothing+bash hydrogen-host-setup.sh check --json # the same for scripts (Hydrogen Doctor reads this)+pkexec bash hydrogen-host-setup.sh apply-system --user "$USER" --desktop "$XDG_CURRENT_DESKTOP" --session "$XDG_SESSION_TYPE"+bash hydrogen-host-setup.sh apply-user # fonts, Flatpak exports, tray extension, default browser+```++Items: `h264` (GStreamer libav; RPM Fusion on Fedora), `fuse2` (AppImages), `flatpak` (+Flathub),+`tray` (AppIndicator on Debian/Fedora GNOME), `ab_windows` (Adom Bridge window list, GNOME Wayland),+`portal`, `audio` (pw-record or parec for Dictate), `clipboard` (wl-copy/xclip), `notify`, `xdg`,+`oom`, `fonts`, `mesh`, `firewall`, `keyring`, `chrome`, `workspace_tz`. `relogin` means the+item is installed and becomes active after logging out and in once.++In the workspace, `~/.adom/hooks/hydrogen-linux-platform-hygiene.sh` keeps ffmpeg with libx264,+the en_US.UTF-8 locale and earlyoom; Hydrogen runs it after every package update.
docs/hero.pngadded⋯ 1 unchanged line ⋯
hooks/hydrogen-linux-platform-hygiene.shadded+30@@ -0,0 +1,30 @@+#!/bin/bash+# The workspace half of adom/hydrogen-linux-bootstrap. Hydrogen on Linux runs this after every+# package convergence (hydrogen-setup linux_skills.rs) and the package runs it on install. It+# converges the Adom-Workspace machine (Ubuntu 24.04) for Linux Hydrogen, with the workspace's own+# passwordless sudo, and prints one summary line. Idempotent: a converged machine costs a few checks.+set -u+log=(); need_update=1+apt_i() { if [ $need_update = 1 ]; then sudo -n apt-get update -qq >/dev/null 2>&1; need_update=0; fi+ sudo -n env DEBIAN_FRONTEND=noninteractive apt-get install -y -q --no-install-recommends "$@" >/dev/null 2>&1; }+sudo -n true 2>/dev/null || { echo "linux-platform: no passwordless sudo in the workspace; nothing changed"; exit 0; }+# 1. ffmpeg with libx264 (AI runs that make video; the Windows image has it).+if ! ffmpeg -hide_banner -encoders 2>/dev/null | grep -q libx264; then+ apt_i ffmpeg && log+=("ffmpeg installed") || log+=("ffmpeg FAILED")+fi+if ffmpeg -hide_banner -loglevel error -f lavfi -i testsrc=size=64x64:rate=10 -t 0.5 -c:v libx264 -pix_fmt yuv420p -y /tmp/.hlb-x264.mp4 2>/dev/null; then x264=ok; else x264=FAIL; fi+rm -f /tmp/.hlb-x264.mp4+# 1b. Chrome's runtime libraries, so headless Chrome runs in the workspace (hero-studio, page+# renders, @puppeteer/browsers downloads); the golden image has none of them (m5-ubuntu 2026-11-15).+CHROME_LIBS="libnspr4 libnss3 libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 libcups2t64 libdrm2 libgbm1 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libpango-1.0-0 libcairo2 libgtk-3-0t64"+miss=""; for l in $CHROME_LIBS; do dpkg -s "$l" >/dev/null 2>&1 || miss="$miss $l"; done+if [ -n "$miss" ]; then apt_i $miss && log+=("Chrome runtime libraries") || log+=("Chrome libraries FAILED"); fi+# 2. en_US.UTF-8 (the hl VMs and many cloud images start with C.UTF-8 only).+if ! locale -a 2>/dev/null | grep -qi '^en_US\.utf8$'; then+ { apt_i locales && sudo -n locale-gen en_US.UTF-8 >/dev/null 2>&1 && sudo -n update-locale LANG=en_US.UTF-8 >/dev/null 2>&1; } && log+=("en_US.UTF-8 locale") || log+=("locale FAILED")+fi+# 3. earlyoom, as in the Windows workspace: a runaway build is stopped before the machine freezes.+if ! systemctl is-active -q earlyoom 2>/dev/null; then+ { command -v earlyoom >/dev/null 2>&1 || apt_i earlyoom; } && sudo -n systemctl enable --now earlyoom >/dev/null 2>&1 && log+=("earlyoom on") || log+=("earlyoom not started")+fi+echo "linux-platform: libx264 $x264; tz $(cat /etc/timezone 2>/dev/null || echo ?); ${log[*]:-already converged}"
host/hydrogen-host-setup.shadded+255@@ -0,0 +1,255 @@+#!/bin/bash+# hydrogen-host-setup.sh: everything a Linux computer needs for Adom Hydrogen and its dock apps+# (adom/hydrogen-linux-bootstrap; the inventory is in this package's README).+#+# hydrogen-host-setup.sh check [--json] what is missing (no root, changes nothing)+# hydrogen-host-setup.sh apply-system [opts] install what is missing (root: Hydrogen runs it+# with ONE pkexec prompt; idempotent)+# hydrogen-host-setup.sh apply-user the per-user part (fonts, Flatpak exports, tray+# extension, default browser), no root+#+# apply-system options: --user NAME (whose desktop), --desktop GNOME|X-Cinnamon|KDE,+# --session wayland|x11, --with-chrome (Google Chrome for the nb bridge), --dry-run.+# Ubuntu 22.04/24.04, Debian 12/13 and Fedora 40+ (and their derivatives). Prints what it does.+set -u+HHS_VERSION=0.1.3+MODE=${1:-check}; shift || true+JSON=0; DRY=0; WITH_CHROME=0; USERNAME=${SUDO_USER:-${PKEXEC_UID:+$(getent passwd "$PKEXEC_UID" | cut -d: -f1)}}+DESKTOP=${XDG_CURRENT_DESKTOP:-}; SESSION=${XDG_SESSION_TYPE:-}+while [ $# -gt 0 ]; do case "$1" in+ --json) JSON=1;; --dry-run) DRY=1;; --with-chrome) WITH_CHROME=1;;+ --user) USERNAME=$2; shift;; --desktop) DESKTOP=$2; shift;; --session) SESSION=$2; shift;;+esac; shift; done+HERE=$(cd "$(dirname "$0")" && pwd)+SAMPLE="$HERE/h264-high-sample.mp4"++. /etc/os-release 2>/dev/null || true+case " ${ID:-} ${ID_LIKE:-} " in+ *" fedora "*|*" rhel "*|*" centos "*) FAMILY=fedora ;;+ *" debian "*|*" ubuntu "*) FAMILY=debian ;;+ *) FAMILY=other ;;+esac+DE=$(echo "${DESKTOP}" | tr '[:upper:]' '[:lower:]')+is_gnome() { case "$DE" in *gnome*|*ubuntu*) return 0;; esac; return 1; }+is_cinnamon() { case "$DE" in *cinnamon*) return 0;; esac; return 1; }+is_kde() { case "$DE" in *kde*|*plasma*) return 0;; esac; return 1; }+have() { command -v "$1" >/dev/null 2>&1; }+say() { [ "$JSON" = 1 ] || echo "$*"; }++# ── checks: one function per inventory item; prints "id<TAB>ok|missing|n/a<TAB>detail" ──+R=()+rec() { R+=("$1 $2 $3"); }+c_h264() {+ if have gst-inspect-1.0 && gst-inspect-1.0 avdec_h264 >/dev/null 2>&1 && gst-inspect-1.0 avdec_aac >/dev/null 2>&1; then+ if [ -f "$SAMPLE" ] && have gst-launch-1.0; then+ if timeout 20 gst-launch-1.0 -q filesrc location="$SAMPLE" ! qtdemux ! h264parse ! avdec_h264 ! fakesink >/dev/null 2>&1; then rec h264 ok "avdec_h264 decodes the High-profile sample"; else rec h264 missing "avdec_h264 is there but the High-profile sample did not decode"; fi+ else rec h264 ok "avdec_h264 and avdec_aac present"; fi+ elif ! have gst-inspect-1.0; then rec h264 missing "no gst-inspect-1.0 (GStreamer tools) to confirm H.264 playback"+ else rec h264 missing "no avdec_h264 (GStreamer libav): H.264 videos do not play in Hydrogen"; fi+}+c_fuse() { if { ldconfig -p 2>/dev/null || /sbin/ldconfig -p 2>/dev/null || /usr/sbin/ldconfig -p 2>/dev/null; } | grep -q 'libfuse\.so\.2' || ls /usr/lib/*/libfuse.so.2* /lib/*/libfuse.so.2* /usr/lib64/libfuse.so.2* >/dev/null 2>&1; then rec fuse2 ok "libfuse.so.2 present (AppImages run)"; else rec fuse2 missing "no libfuse.so.2: AppImages (Grok Bot, Adom Bridge) cannot run directly"; fi; }+c_flatpak() {+ if ! have flatpak; then rec flatpak missing "no flatpak (KiCad installs from Flathub)"; return; fi+ if flatpak remotes --system 2>/dev/null | grep -qw flathub || flatpak remotes 2>/dev/null | grep -qw flathub; then rec flatpak ok "flatpak with Flathub"; else rec flatpak missing "flatpak without the Flathub remote"; fi+}+c_tray() {+ if ! is_gnome; then rec tray n/a "this desktop has its own tray"; return; fi+ if [ "${ID:-}" = ubuntu ]; then rec tray ok "Ubuntu's own AppIndicator extension"; return; fi+ if have gnome-extensions && gnome-extensions info [email protected] 2>/dev/null | grep -q "State: ACTIVE"; then rec tray ok "AppIndicator extension active"+ elif [ -d /usr/share/gnome-shell/extensions/[email protected] ]; then rec tray relogin "AppIndicator extension installed; enable it and log out and in once"+ else rec tray missing "no tray on this GNOME: a closed Hydrogen window would have no way back"; fi+}+c_abext() { user_item ab_windows && return;+ if ! is_gnome || [ "${SESSION:-}" != wayland ]; then rec ab_windows n/a "only GNOME on Wayland needs it"; return; fi+ if have gnome-extensions && gnome-extensions info [email protected] 2>/dev/null | grep -q "State: ACTIVE"; then rec ab_windows ok "Adom Bridge window list extension active"+ elif have gnome-extensions && gnome-extensions info [email protected] >/dev/null 2>&1; then rec ab_windows relogin "Adom Bridge window list extension installed; log out and in once"+ else rec ab_windows missing "Adom Bridge installs its window list extension on first use"; fi+}+c_portal() {+ local p=/usr/share/xdg-desktop-portal/portals want=""+ if is_gnome; then want=gnome; elif is_cinnamon; then want=xapp; elif is_kde; then want=kde; else want=gtk; fi+ if [ -f "$p/$want.portal" ]; then rec portal ok "xdg-desktop-portal ($want)"; else rec portal missing "no $want desktop portal (screenshots and screen capture)"; fi+}+c_audio() { if have pw-record || have parec; then rec audio ok "$(have pw-record && echo pw-record || echo parec) for Dictate"; else rec audio missing "no pw-record or parec: Dictate cannot record"; fi; }+c_clip() { if have wl-copy || have xclip; then rec clipboard ok "$(have wl-copy && echo wl-copy) $(have xclip && echo xclip)"; else rec clipboard missing "no wl-copy or xclip: an annotate picture leaves the clipboard when Hydrogen loses focus"; fi; }+c_notify() { if have notify-send; then rec notify ok "notify-send"; else rec notify missing "no notify-send (Adom Bridge notifications)"; fi; }+c_xdg() { if have xdg-open && have xdg-settings; then rec xdg ok "xdg-open, xdg-settings"; else rec xdg missing "no xdg-utils"; fi; }+c_oom() {+ if systemctl is-active -q systemd-oomd 2>/dev/null || systemctl is-active -q earlyoom 2>/dev/null; then rec oom ok "$(systemctl is-active -q systemd-oomd 2>/dev/null && echo systemd-oomd || echo earlyoom)"+ else rec oom missing "no out-of-memory guard (Debian): a full memory can freeze the desktop"; fi+}+c_fonts() { user_item fonts && return; if have fc-list && fc-list 2>/dev/null | grep -qi "familjen grotesk" && fc-list | grep -qi "satoshi" && fc-list | grep -qi "jetbrains mono"; then rec fonts ok "Familjen Grotesk, Satoshi, JetBrains Mono"; else rec fonts missing "Adom fonts not installed for this user"; fi; }+c_mesh() { user_item mesh && return;+ local f="${HOME}/.adom/config.json"+ [ -f "$f" ] || { rec mesh n/a "Adom Bridge not set up yet"; return; }+ if python3 -c "import json,sys;d=json.load(open('$f'));sys.exit(0 if d.get('mesh_enabled',True) and d.get('mesh_mode','relay')=='relay' else 1)" 2>/dev/null; then rec mesh ok "mesh on, relay mode"+ else rec mesh missing "Adom Bridge mesh off or not in relay mode: approvals do not mirror"; fi+}+c_firewall() {+ if have firewall-cmd && systemctl is-active -q firewalld 2>/dev/null; then+ local port; port=$(python3 -c "import json;d=json.load(open('${HOME}/.adom/config.json'));print(d.get('mesh_port') or '')" 2>/dev/null)+ [ -n "$port" ] || { rec firewall n/a "firewalld on; Adom Bridge uses the relay (no direct mesh port configured)"; return; }+ if firewall-cmd --query-port="$port/tcp" >/dev/null 2>&1; then rec firewall ok "firewalld allows $port/tcp"; else rec firewall missing "firewalld blocks the Adom Bridge mesh port $port/tcp"; fi+ else rec firewall n/a "no firewalld"; fi+}+c_keyring() { user_item keyring && return; if [ -f "${HOME}/.local/share/keyrings/login.keyring" ]; then rec keyring ok "login keyring exists"; else rec keyring warn "no login keyring: Chrome may ask for a new keyring password (nb/pup start Chrome with --password-store=basic)"; fi; }+c_chrome() { if have google-chrome || have google-chrome-stable; then rec chrome ok "$( (google-chrome --version || google-chrome-stable --version) 2>/dev/null | head -1)"; else rec chrome n/a "Google Chrome not installed (only the nb bridge needs it; Hydrogen offers it there)"; fi; }+c_workspace_tz() {+ local m=/var/lib/machines/Adom-Workspace host+ host=$(timedatectl show -p Timezone --value 2>/dev/null)+ if ! machinectl show Adom-Workspace >/dev/null 2>&1 && ! [ -d "$m" ]; then rec workspace_tz n/a "no workspace yet"; return; fi+ if [ "$(id -u)" != 0 ]; then rec workspace_tz ok "set to the computer's zone ($host) by the root step on every install"; return; fi+ if [ "$(cat "$m/etc/timezone" 2>/dev/null)" = "$host" ]; then rec workspace_tz ok "workspace follows $host"; else rec workspace_tz missing "workspace time zone is not the computer's ($host)"; fi+}+user_item() { [ "$(id -u)" = 0 ] && { rec "$1" user "checked by the user step"; return 0; }; return 1; }+run_checks() { R=(); c_h264; c_fuse; c_flatpak; c_tray; c_abext; c_portal; c_audio; c_clip; c_notify; c_xdg; c_oom; c_fonts; c_mesh; c_firewall; c_keyring; c_chrome; c_workspace_tz; }+print_checks() {+ if [ "$JSON" = 1 ]; then+ printf '{"version":"%s","distro":"%s","family":"%s","desktop":"%s","session":"%s","items":[' "$HHS_VERSION" "${PRETTY_NAME:-unknown}" "$FAMILY" "$DESKTOP" "$SESSION"+ local first=1 line id st de+ for line in "${R[@]}"; do IFS=$'\t' read -r id st de <<<"$line"; [ $first = 1 ] || printf ','; first=0+ printf '{"id":"%s","state":"%s","detail":"%s"}' "$id" "$st" "$(echo "$de" | sed 's/\\/\\\\/g; s/"/\\"/g')"; done+ printf ']}\n'+ else+ echo "Hydrogen host check $HHS_VERSION on ${PRETTY_NAME:-unknown} (${DESKTOP:-no desktop}, ${SESSION:-?})"+ local line; for line in "${R[@]}"; do IFS=$'\t' read -r id st de <<<"$line"; printf ' %-13s %-8s %s\n' "$id" "$st" "$de"; done+ fi+}+state_of() { local line; for line in "${R[@]}"; do case "$line" in "$1 "*) echo "$line" | cut -f2; return;; esac; done; }++# ── apply-system (root) ──+pkg_avail_deb() { apt-cache show "$1" >/dev/null 2>&1; }+run() { echo " + $*"; [ "$DRY" = 1 ] || "$@"; }+apply_system() {+ [ "$(id -u)" = 0 ] || { echo "apply-system needs root (Hydrogen runs it with pkexec)"; exit 2; }+ run_checks+ local pk=() changed=0+ echo "Adom Hydrogen: setting up this computer (${PRETTY_NAME:-unknown}, ${DESKTOP:-no desktop})"+ if [ "$FAMILY" = debian ]; then+ export DEBIAN_FRONTEND=noninteractive+ run apt-get update -qq+ # gstreamer1.0-tools: gst-inspect-1.0, which the check needs (Debian 13 does not install it).+ [ "$(state_of h264)" = ok ] || pk+=(gstreamer1.0-libav gstreamer1.0-plugins-bad gstreamer1.0-plugins-good gstreamer1.0-vaapi gstreamer1.0-tools)+ if [ "$(state_of fuse2)" != ok ]; then if pkg_avail_deb libfuse2t64; then pk+=(libfuse2t64); else pk+=(libfuse2); fi; fi+ have flatpak || pk+=(flatpak)+ if is_gnome && [ "${ID:-}" != ubuntu ] && [ "$(state_of tray)" = missing ]; then pk+=(gnome-shell-extension-appindicator); fi+ if [ "$(state_of portal)" != ok ]; then+ pk+=(xdg-desktop-portal)+ if is_gnome; then pk+=(xdg-desktop-portal-gnome); elif is_cinnamon; then pk+=(xdg-desktop-portal-xapp xdg-desktop-portal-gtk); elif is_kde; then pk+=(xdg-desktop-portal-kde); else pk+=(xdg-desktop-portal-gtk); fi+ fi+ [ "$(state_of audio)" = ok ] || pk+=(pulseaudio-utils)+ have wl-copy || pk+=(wl-clipboard); have xclip || pk+=(xclip)+ have notify-send || pk+=(libnotify-bin)+ { have xdg-open && have xdg-settings; } || pk+=(xdg-utils)+ [ "$(state_of oom)" = ok ] || pk+=(earlyoom)+ if [ ${#pk[@]} -gt 0 ]; then run apt-get install -y -q --no-install-recommends "${pk[@]}" && changed=1; fi+ [ "$(state_of oom)" = ok ] || run systemctl enable --now earlyoom+ elif [ "$FAMILY" = fedora ]; then+ have gst-inspect-1.0 || pk+=(gstreamer1)+ if [ "$(state_of h264)" != ok ]; then+ if ! rpm -q rpmfusion-free-release >/dev/null 2>&1; then+ echo " H.264 (the codec Adom's videos use) is not in Fedora itself. Adding the RPM Fusion free"+ echo " repository (rpmfusion.org), the standard source for it on Fedora."+ run dnf install -y -q "https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm"+ fi+ rpm -q ffmpeg-free >/dev/null 2>&1 && run dnf swap -y -q ffmpeg-free ffmpeg --allowerasing+ pk+=(gstreamer1-plugin-libav gstreamer1-plugins-bad-free gstreamer1-plugins-good gstreamer1-vaapi)+ fi+ [ "$(state_of fuse2)" = ok ] || pk+=(fuse-libs)+ have flatpak || pk+=(flatpak)+ if is_gnome && [ "$(state_of tray)" = missing ]; then pk+=(gnome-shell-extension-appindicator); fi+ if [ "$(state_of portal)" != ok ]; then pk+=(xdg-desktop-portal); if is_gnome; then pk+=(xdg-desktop-portal-gnome); elif is_kde; then pk+=(xdg-desktop-portal-kde); else pk+=(xdg-desktop-portal-gtk); fi; fi+ [ "$(state_of audio)" = ok ] || pk+=(pipewire-utils)+ have wl-copy || pk+=(wl-clipboard); have xclip || pk+=(xclip)+ have notify-send || pk+=(libnotify)+ { have xdg-open && have xdg-settings; } || pk+=(xdg-utils)+ if [ ${#pk[@]} -gt 0 ]; then run dnf install -y -q "${pk[@]}" && changed=1; fi+ else+ echo " ${PRETTY_NAME:-This distribution} is not one the bootstrap knows (Ubuntu, Debian, Fedora); nothing installed."+ fi+ # GStreamer caches what each plugin can do per user; swapping libavcodec underneath (Fedora:+ # ffmpeg-free -> ffmpeg) does not touch the plugin file, so the cache keeps saying "no H.264".+ if [ "$(state_of h264)" != ok ] && [ -n "$USERNAME" ]; then+ local uh; uh=$(getent passwd "$USERNAME" | cut -d: -f6)+ [ -n "$uh" ] && [ -d "$uh/.cache/gstreamer-1.0" ] && { echo " + GStreamer plugin cache of $USERNAME cleared (it still described the old codecs)"; [ "$DRY" = 1 ] || rm -rf "$uh/.cache/gstreamer-1.0"; }+ rm -rf /root/.cache/gstreamer-1.0 2>/dev/null+ fi+ if have flatpak && ! flatpak remotes --system 2>/dev/null | grep -qw flathub; then run flatpak remote-add --system --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo; fi+ if [ "$WITH_CHROME" = 1 ] && ! have google-chrome && ! have google-chrome-stable; then+ echo " Google Chrome for the native browser bridge (your default browser is kept)."+ if [ "$FAMILY" = debian ]; then run curl -fsSLo /tmp/google-chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && run apt-get install -y -q /tmp/google-chrome.deb+ elif [ "$FAMILY" = fedora ]; then run dnf install -y -q https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm; fi+ fi+ # The workspace keeps the computer's time zone (systemd-nspawn does not follow a change).+ local m=/var/lib/machines/Adom-Workspace tz; tz=$(timedatectl show -p Timezone --value 2>/dev/null)+ if [ -d "$m/etc" ] && [ -n "$tz" ] && [ -e "$m/usr/share/zoneinfo/$tz" ] && [ "$(cat "$m/etc/timezone" 2>/dev/null)" != "$tz" ]; then+ echo " + workspace time zone -> $tz"; [ "$DRY" = 1 ] || { echo "$tz" > "$m/etc/timezone"; ln -sfn "/usr/share/zoneinfo/$tz" "$m/etc/localtime"; }+ fi+ if have firewall-cmd && systemctl is-active -q firewalld 2>/dev/null && [ -n "$USERNAME" ]; then+ local home port; home=$(getent passwd "$USERNAME" | cut -d: -f6)+ port=$(python3 -c "import json;print(json.load(open('$home/.adom/config.json')).get('mesh_port') or '')" 2>/dev/null)+ if [ -n "$port" ] && ! firewall-cmd --query-port="$port/tcp" >/dev/null 2>&1; then run firewall-cmd --permanent --add-port="$port/tcp"; run firewall-cmd --reload; fi+ fi+ echo "Done."+ JSON=0; R=(); run_checks; print_checks+}++# ── apply-user (no root) ──+apply_user() {+ [ "$(id -u)" != 0 ] || { echo "apply-user runs as the desktop user, not root"; exit 2; }+ local st="$HOME/.local/share/adom-hydrogen"; mkdir -p "$st"+ # Default browser: remember it once, and put it back if a Chrome install took it.+ local cur; cur=$(xdg-settings get default-web-browser 2>/dev/null)+ if [ -n "$cur" ] && [ ! -f "$st/default-browser" ]; then echo "$cur" > "$st/default-browser"; fi+ local was; was=$(cat "$st/default-browser" 2>/dev/null)+ if [ -n "$was" ] && [ -n "$cur" ] && [ "$cur" != "$was" ] && case "$cur" in google-chrome*) true;; *) false;; esac && [ -f "$st/chrome-installed-by-hydrogen" ]; then+ echo " + default browser back to $was (a Chrome install had taken it)"; xdg-settings set default-web-browser "$was" 2>/dev/null+ fi+ # H.264 installed but still "missing": a stale GStreamer plugin cache; clear it and look again.+ if ! gst-inspect-1.0 avdec_h264 >/dev/null 2>&1 && [ -d "$HOME/.cache/gstreamer-1.0" ]; then+ rm -rf "$HOME/.cache/gstreamer-1.0"; gst-inspect-1.0 avdec_h264 >/dev/null 2>&1 && echo " + GStreamer plugin cache rebuilt: H.264 found"+ fi+ # Adom fonts.+ if ! (fc-list 2>/dev/null | grep -qi "familjen grotesk" && fc-list | grep -qi satoshi && fc-list | grep -qi "jetbrains mono"); then+ local fd="$HOME/.local/share/fonts/adom" tmp; mkdir -p "$fd"; tmp=$(mktemp -d)+ echo " + Adom fonts -> $fd"+ curl -fsSL -o "$fd/FamiljenGrotesk[wght].ttf" "https://github.com/google/fonts/raw/main/ofl/familjengrotesk/FamiljenGrotesk%5Bwght%5D.ttf"+ curl -fsSL -o "$fd/JetBrainsMono[wght].ttf" "https://github.com/google/fonts/raw/main/ofl/jetbrainsmono/JetBrainsMono%5Bwght%5D.ttf"+ if curl -fsSL -o "$tmp/satoshi.zip" "https://api.fontshare.com/v2/fonts/download/satoshi"; then+ python3 - "$tmp/satoshi.zip" "$fd" <<'PY'+import sys, zipfile, os+z = zipfile.ZipFile(sys.argv[1])+for n in z.namelist():+ b = os.path.basename(n)+ if b.lower().endswith(('.ttf', '.otf')) and 'variable' in n.lower() and b:+ open(os.path.join(sys.argv[2], b), 'wb').write(z.read(n))+PY+ fi+ rm -rf "$tmp"; fc-cache -f "$fd" >/dev/null 2>&1+ fi+ # Flatpak apps (KiCad) visible in menus and icons now, not only after the next login.+ local ex+ for ex in /var/lib/flatpak/exports/share "$HOME/.local/share/flatpak/exports/share"; do+ [ -d "$ex/applications" ] || continue+ mkdir -p "$HOME/.local/share/applications"+ for f in "$ex"/applications/*.desktop; do [ -e "$f" ] && ln -sf "$f" "$HOME/.local/share/applications/$(basename "$f")"; done+ if [ -d "$ex/icons" ]; then (cd "$ex/icons" && find . \( -type f -o -type l \) | while read -r i; do mkdir -p "$HOME/.local/share/icons/$(dirname "$i")"; ln -sf "$ex/icons/$i" "$HOME/.local/share/icons/$i"; done); fi+ done+ mkdir -p "$HOME/.config/environment.d"+ [ -f "$HOME/.config/environment.d/60-flatpak.conf" ] || printf 'XDG_DATA_DIRS=%s/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}\n' "$HOME" > "$HOME/.config/environment.d/60-flatpak.conf"+ have update-desktop-database && update-desktop-database "$HOME/.local/share/applications" >/dev/null 2>&1+ have gtk-update-icon-cache && [ -d "$HOME/.local/share/icons/hicolor" ] && gtk-update-icon-cache -q -t "$HOME/.local/share/icons/hicolor" 2>/dev/null+ # Tray on GNOME (Debian, Fedora): enable the AppIndicator extension; it loads at the next login.+ if is_gnome && [ "${ID:-}" != ubuntu ] && have gnome-extensions && [ -d /usr/share/gnome-shell/extensions/[email protected] ]; then+ gnome-extensions enable [email protected] 2>/dev/null && echo " + tray extension enabled (active after you log out and in once)"+ fi+ run_checks; print_checks+}++case "$MODE" in+ check) run_checks; print_checks ;;+ apply-system) apply_system ;;+ apply-user) apply_user ;;+ version) echo "$HHS_VERSION" ;;+ *) echo "usage: $0 check [--json] | apply-system [--user U --desktop D --session S --with-chrome --dry-run] | apply-user"; exit 2 ;;+esac
install.shadded+11@@ -0,0 +1,11 @@+#!/bin/bash+# adom/hydrogen-linux-bootstrap install (runs in the Adom-Workspace machine, as the workspace user).+# Installs the re-convergence hook Hydrogen runs after every package update, then runs it once.+# The host half (host/hydrogen-host-setup.sh) is run by Hydrogen itself on the computer, with one+# password prompt; see README.+set -u+HERE=$(cd "$(dirname "$0")" && pwd)+mkdir -p "$HOME/.adom/hooks"+install -m 755 "$HERE/hooks/hydrogen-linux-platform-hygiene.sh" "$HOME/.adom/hooks/hydrogen-linux-platform-hygiene.sh"+chmod +x "$HERE/host/hydrogen-host-setup.sh" 2>/dev/null || true+bash "$HOME/.adom/hooks/hydrogen-linux-platform-hygiene.sh" || true
package.jsonadded+43@@ -0,0 +1,43 @@+{+ "schema_version": 1,+ "slug": "hydrogen-linux-bootstrap",+ "type": "bootstrap",+ "org": "adom",+ "title": "Adom Hydrogen (Linux)",+ "brief": "The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.",+ "version": "0.1.0",+ "description": "The Linux platform layer for Adom Hydrogen, where the workspace is a systemd-nspawn machine on the user's own Linux computer. Depends on adom/hydrogen-bootstrap and adds what is specific to Linux: the Linux render of the hydrogen-* skills, the workspace convergence hook (ffmpeg with libx264, en_US.UTF-8, earlyoom) and host/hydrogen-host-setup.sh, which Hydrogen runs on the computer with one password prompt (H.264 playback, the AppImage runtime, Flatpak and Flathub, the GNOME tray, the desktop portal, clipboard tools, fonts, the workspace time zone). One package for Ubuntu, Debian and Fedora. Sibling layers: adom/hydrogen-windows-bootstrap (WSL2) and adom/hydrogen-mac-bootstrap (Lima).",+ "tags": [+ "bootstrap",+ "adom-hydrogen",+ "hydrogen",+ "linux",+ "ubuntu",+ "debian",+ "fedora",+ "nspawn"+ ],+ "needs_sudo": false,+ "scripts": {+ "install": "./install.sh"+ },+ "dependencies": {+ "adom/hydrogen-bootstrap": "^0.5.0",+ "adom/adom-shotlog": "^0.29.0",+ "adom/adom-bridge": "^2.0.0"+ },+ "files": [+ "package.json",+ "install.sh",+ "README.md",+ "SKILL.md",+ "hooks/**",+ "host/**",+ "skills/**",+ "screenshots/**"+ ],+ "changelog": "0.1.0: first release (DIR-150923-13629, DIR-150930-27112): host setup 0.1.3 (proved on clean Fedora 44 and Debian 13 and on Ubuntu 24.04) and the workspace hook (ffmpeg with libx264, en_US.UTF-8, earlyoom, Chrome's runtime libraries). Replaces the never-published hydrogen-ubuntu-bootstrap.",+ "hero": {+ "path": "docs/hero.png"+ }+}
page.json+32−2@@ -13,7 +13,16 @@ "author": { "name": "John Lauer" },- "tags": [],+ "tags": [+ "bootstrap",+ "adom-hydrogen",+ "hydrogen",+ "linux",+ "ubuntu",+ "debian",+ "fedora",+ "nspawn"+ ], "license": "proprietary", "visibility": { "public": true@@ -24,5 +33,26 @@ "metadata": {}, "created_at": "2026-11-15T16:02:46.484Z", "updated_at": "2026-11-15T16:02:46.484Z",- "org": "adom"+ "org": "adom",+ "description": "The Linux platform layer for Adom Hydrogen, where the workspace is a systemd-nspawn machine on the user's own Linux computer. Depends on adom/hydrogen-bootstrap and adds what is specific to Linux: the Linux render of the hydrogen-* skills, the workspace convergence hook (ffmpeg with libx264, en_US.UTF-8, earlyoom) and host/hydrogen-host-setup.sh, which Hydrogen runs on the computer with one password prompt (H.264 playback, the AppImage runtime, Flatpak and Flathub, the GNOME tray, the desktop portal, clipboard tools, fonts, the workspace time zone). One package for Ubuntu, Debian and Fedora. Sibling layers: adom/hydrogen-windows-bootstrap (WSL2) and adom/hydrogen-mac-bootstrap (Lima).",+ "needs_sudo": false,+ "scripts": {+ "install": "./install.sh"+ },+ "dependencies": {+ "adom/hydrogen-bootstrap": "^0.5.0",+ "adom/adom-shotlog": "^0.29.0",+ "adom/adom-bridge": "^2.0.0"+ },+ "files": [+ "package.json",+ "install.sh",+ "README.md",+ "SKILL.md",+ "hooks/**",+ "host/**",+ "skills/**",+ "screenshots/**"+ ],+ "changelog": "0.1.0: first release (DIR-150923-13629, DIR-150930-27112): host setup 0.1.3 (proved on clean Fedora 44 and Debian 13 and on Ubuntu 24.04) and the workspace hook (ffmpeg with libx264, en_US.UTF-8, earlyoom, Chrome's runtime libraries). Replaces the never-published hydrogen-ubuntu-bootstrap." }
skills/hydrogen-adom-auth/SKILL.mdadded+323@@ -0,0 +1,323 @@+---+name: hydrogen-adom-auth+description: >-+ Adom sign-in inside Hydrogen on Linux: the login/logout auth intent flow, where the+ session token lives (~/.config/hydrogen-desktop/hydrogen-session.txt), and how the+ session feeds setup. Use when Adom login fails, the session token expired, the user+ wants to sign in or out of Adom, or clear the Adom session.+---++# Hydrogen -- Authentication Reference++## Auth Flow Overview++Hydrogen uses an **auth intent** flow (no email/password entry in the app).+The backend creates a short-lived intent token on the Carbon API,+opens the user's default browser to the Adom login page, and polls until+the user completes sign-in in the browser.++### Sequence++1. Hydrogen calls `invoke('auth_intent_start')` -> backend POSTs to+ `https://carbon.adom.inc/auth/intents` with `{"max_age": 7776000}`+ (90-day session).+2. Carbon returns `{token, confirmation_code, expires_at, auth_url}`.+3. Hydrogen opens the browser to the **`auth_url` Carbon returned**, falling back to+ `https://hydrogen.adom.inc/auth/intent?token={token}` (singular `intent`,+ token as a query param — NOT `/auth/intents/{token}`).+ On Linux the browser opens through Hydrogen's browser launcher, which honours the+ Browser Picker's choice of browser and profile.+4. Hydrogen displays the confirmation code on screen and shows a spinner.+5. Frontend polls `invoke('auth_intent_poll', {token})` every 2 seconds.+ Backend GETs `https://carbon.adom.inc/auth/intents/{token}/status`.+6. When the user confirms in the browser, the response includes+ `{state: "authenticated", session_token: "..."}`.+7. The backend saves the session token to Hydrogen's app-data directory on the host+ (the `hydrogen-session.txt` file) and a replay copy alongside it.+8. Frontend redirects to the dashboard.++### Source files++- **Login page**: `src/routes/auth/login/+page.svelte`+- **Auth backend**: `src-tauri/crates/hydrogen-setup/src/app_glue.rs`+ (`auth_intent_start`, `auth_intent_poll`) and+ `src-tauri/crates/hydrogen-app/src/lib.rs` (`auth_proxy`,+ `check_replay_credentials`, `replay_adom_login`).+- **Auth components**: `src/lib/components/auth/` (Header, Form, Footer,+ SubmitButton, Error, Success)+- **User API**: `src/lib/api/authenticated_user.ts`++---++## Session Token++**Location**: Hydrogen's app-data directory on the host (the `hydrogen-session.txt`+file).++On Linux every auth file is in Hydrogen's state folder `~/.config/hydrogen-desktop/` on+the host (not in the workspace):++| File | Purpose |+|---|---|+| `hydrogen-session.txt` | The Adom session token. Read by the auth proxy; deleted on logout or a 401. |+| `replay-session.txt` | Replay copy; lets the login page sign you back in without a browser ("Signing you in... Ns"). |+| `replay-claude-credentials.json` | Claude Code credentials kept across a virgin reset (see **hydrogen-claude-auth**). |++From the workspace, the host's home is visible at `/mnt/host/home/<user>/`, but the+supported way to get the token is the control API below.++A plain-text file containing the Adom session cookie value. Created by either:+- The auth intent flow (on successful poll)+- The auth proxy (when Carbon returns a `set-cookie: session_token=...` header)++The auth proxy (`invoke('auth_proxy', ...)`) reads this file and attaches it+as a `Cookie: session_token=...` header on every request to `carbon.adom.inc`.++### Token lifecycle++- **Created**: on login (auth intent or browser set-cookie capture)+- **Refreshed**: automatically when the auth proxy receives a new set-cookie+- **Cleared**: on logout (`auth_proxy({path: "/auth/clear-local"})`) or on+ 401 response (backend auto-deletes the file)+- **Max age**: 90 days (set at intent creation)++### Reading the token programmatically++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # normally http://127.0.0.1:47084+curl -s "$BASE/auth-token" # the saved Adom session token+cat /var/run/adom/api-key # the same account's key, written into the workspace+```++Hydrogen writes `/var/run/adom/api-key` (mode 644) at every launch and once during setup's+activate-editor step, after sign-in. `adom-cli`, `adom-wiki` and the editor use it.++---++## Auth Proxy++The backend command `auth_proxy` is the gateway for all authenticated requests+to the Adom Carbon API. It:++1. Reads the session token from disk+2. Attaches it as a cookie to the outgoing request+3. Captures any `set-cookie` response and updates the saved token+4. On 401, deletes the token and returns `{expired: true}`+5. Supports a special `path: "/auth/clear-local"` to delete the token file++**Base URL**: `https://carbon.adom.inc`++```javascript+// Example: get the current user+const result = await invoke('auth_proxy', {+ path: '/api/me',+ method: 'GET'+});+// result = { status: 200, data: { id: "...", name: "jlauer12", ... }, ok: true }+```++---++## Credential Replay++On login page mount, Hydrogen checks for saved credentials before starting the+full auth intent flow:++1. `invoke('check_replay_credentials')` checks if replay files exist on disk.+2. If the replay-session file exists (has_adom = true), the login page shows+ "Signing you in... Ns" and counts down.+3. `invoke('replay_adom_login')` attempts to authenticate using the saved+ session token.+4. If replay succeeds, the user is logged in without opening a browser.+5. If replay fails, Hydrogen falls back to the normal auth intent flow.++This makes re-login after a virgin reset instant when the user chose to+preserve the Adom session token.++---++## Claude Credentials++**Location**: Hydrogen's app-data directory on the host (the+`replay-claude-credentials.json` file).++Stores Claude Code credentials so they survive a virgin reset (see+**hydrogen-claude-auth**).++### Virgin reset options for auth++The virgin reset panel (Setup Panel -> Virgin Reset) has per-item toggles:++| Toggle | File | What it clears |+|--------|------|----------------|+| Adom session token | `hydrogen-session.txt` | Adom login. Next launch requires re-auth. |+| Claude credentials | `replay-claude-credentials.json` | Claude Code OAuth. Next bootstrap re-authenticates Claude. |++These are independent -- you can wipe Claude creds without losing Adom login,+or vice versa.++### CSS selectors for virgin reset auth options++```+label.virgin-opt -- each checkbox row+input[type="checkbox"] -- the toggle (bind:checked to virginOpts.adom_token / virginOpts.claude_token)+.virgin-hint -- shows filename (hydrogen-session.txt / replay-claude-credentials.json)+.vp-badge -- status badge ("exists" / "clean")+.vp-exists -- green badge (file exists)+.vp-clean -- gray badge (file gone)+```++---++## Profile Menu++**Location**: Top-right corner of the editor nav bar.+**Source**: `src/lib/components/editor/EditorNav.svelte` (lines ~2403-2443)++Click the circular user avatar to open a dropdown with two sections.++### Menu items++| Item | Icon | Action |+|------|------|--------|+| Your profile | `mdi:account-circle-outline` | Navigates to `/users/{username}` |+| Your repositories | `mdi:folder-outline` | Navigates to `/users/{username}/repositories` |+| Your molecules | `mdi:atom` | Navigates to `/users/{username}/molecules` |+| Log out | `mdi:logout` | Confirms, then clears session + redirects to login |++**CRITICAL**: Logout is ONLY in the profile menu (top-right avatar), NOT in+the Adom menu (top-left logo). Do not look for logout in the wrong menu.++### CSS selectors++| Element | Selector |+|---------|----------|+| Profile dropdown container | `.profile-dropdown-container` |+| Avatar button | `.profile-dropdown-button` |+| Avatar image | `.profile-dropdown-button img` |+| Dropdown (open) | `.profile-dropdown-content.open` |+| Menu items | `.profile-dropdown-content .dropdown-link` |+| Menu item icons | `.dropdown-link span` |++### Eval examples (`/eval-in {target:"shell"}`)++```javascript+// Open the profile menu+document.querySelector('.profile-dropdown-button')?.click();++// Click "Your profile"+var links = document.querySelectorAll('.profile-dropdown-content .dropdown-link');+if (links[0]) links[0].click();++// Click "Your repositories"+if (links[1]) links[1].click();++// Click "Your molecules"+if (links[2]) links[2].click();++// Click "Log out"+var logoutBtn = Array.from(document.querySelectorAll('.profile-dropdown-content .dropdown-link'))+ .find(function(e) { return e.textContent.includes('Log out'); });+if (logoutBtn) logoutBtn.click();+// Note: this triggers a confirm dialog. To auto-confirm, you need to handle the dialog.++// Read the current user's avatar URL+var avatar = document.querySelector('.profile-dropdown-button img');+avatar ? avatar.src : 'no avatar';++// Read the current username from the avatar alt text+avatar ? avatar.alt : 'unknown';+```++---++## Logout Flow++1. User clicks "Log out" in profile menu.+2. `showConfirm('Are you sure you want to log out?', 'Log Out')` -- confirmation dialog.+3. If confirmed (app mode):+ - `invoke('auth_proxy', {path: '/auth/logout', method: 'DELETE'})` -- server-side logout+ - `invoke('auth_proxy', {path: '/auth/clear-local', method: 'POST'})` -- deletes `hydrogen-session.txt`+ - Clears auth-related domain preferences from `localStorage['hydrogen-url-routing-prefs']`+4. Redirects to `/auth/login`.++---++## Login Page UI++**Route**: `/auth/login`++### App mode (auth intent)+- Adom logo + "Log in to Hydrogen" header+- Confirmation code in a monospace box (`.confirmation-code`)+- Spinner + "Waiting for you to sign in..."+- "Open browser again" button (`.retry-button`)++### Browser mode (email/password)+- Standard form with email + password fields+- "Log In" submit button+- Footer with registration link++### Auth intent CSS selectors++| Element | Selector |+|---------|----------|+| Container | `.intent-container` |+| Confirmation code | `.confirmation-code` |+| Spinner | `.spinner` |+| Status message | `.intent-message` |+| Hint text | `.intent-hint` |+| Success message | `.intent-success` |+| Error message | `.intent-error` |+| Retry button | `.retry-button` |++### Eval on the login page (`/eval-in {target:"shell"}`)++```javascript+// Check auth intent state+document.querySelector('.intent-message')?.textContent;+// -> "Waiting for you to sign in..." or "Authenticated! Redirecting..."++// Read the confirmation code+document.querySelector('.confirmation-code')?.textContent;++// Click retry+document.querySelector('.retry-button')?.click();+```++---++## How Auth Affects Setup Steps++The setup/bootstrap process depends on a valid session token:++The activate-editor step waits for the Adom sign-in (the editor mounts only after login),+then binds the workspace to this launch: environment, the api-key write-through and the+relay. If the token is missing or expired, `adom-cli` in the workspace cannot authenticate:+sign in again, then run setup again from the Adom menu > Setup Steps.++---++## Control API Auth Endpoints++| Method | Path | Description |+|--------|------|-------------|+| GET | `/auth-token` | Read the saved Adom session token (same-origin callers only) |+| POST | `/claude-auth` | Start Claude Code OAuth (PKCE) |+| GET | `/oauth/callback` | Receives OAuth redirect (auto, do not call) |+| POST | `/start-oauth-proxy` | Spin up temp TCP listener for OAuth callback |+| POST/GET | `/auth/proxy` | Proxy request to Carbon API with session token |++See the **hydrogen-settings** skill (API Explorer section) for the+full endpoint reference.++---++## Cross-references++- **hydrogen-claude-auth** -- Claude Code sign-in, separate from Adom+- **hydrogen-profile-menu** -- where login/logout live in the UI+- **hydrogen-settings** -- API Explorer (auth endpoints tab)+- **hydrogen-networking** -- how to reach the control API port+- **hydrogen-api** -- the control API+- **hydrogen-key-values** -- the account's cloud key-value store
skills/hydrogen-adom-bridge-triage/SKILL.mdadded+164@@ -0,0 +1,164 @@+---+name: hydrogen-adom-bridge-triage+description: >-+ Triage Adom Bridge (ab) when a Hydrogen workspace on Linux cannot reach it:+ which half is broken, whether ab is even running on this Linux desktop, its+ app.log, the /ab/* probes, reaching the user's other machines through the+ mesh. Use when ab won't connect, no desktop client connected, ab never+ starts, or the bridge keeps dying.+---++Parent skill: **hydrogen-adom-bridge** (works with **hydrogen-doctor**, **adom-bridge-linux**, **adom-bridge**)++# Triage: Adom Bridge won't connect++**First fact: Hydrogen on Linux installs and supervises Adom Bridge only when ab's manifest has+a Linux build for the user's account.** The setup step `ensure-adom-bridge-cli` says which case+this is ("No Adom Bridge for Linux is published for your account yet" means none was installed).+When it is installed (`~/.local/share/adom-bridge-app/run.sh` exists), Hydrogen starts it hidden+and restarts it when it dies, so "No desktop client connected" then means it is crash-looping or+signed out: read `~/.local/share/adom-bridge-app/app.log` and the `[ab-linux]` / `[ad-supervisor]`+lines of Hydrogen's log.++`ping` returning **"No desktop client connected"** tells you only that the+desktop half is absent. It does **not** tell you whether ab is uninstalled,+signed out, misconfigured, or **installed and crash-looping**. Those need+opposite fixes, and the last one is invisible from the container unless you+go looking for it.++## The ladder, cheapest first++### 1. Which half is broken? (container-side, free)++```bash+curl -sf http://127.0.0.1:8766/health # connectedClients, usingDefaultToken+adom-bridge --ai-thread "<your thread>" ping+adom-bridge --ai-thread "<your thread>" targets+```++`connectedClients: 0` with a healthy relay ⇒ the container is fine; **every+remaining step is about the desktop**. Do not start reconfiguring the container.++`targets` may list the user's OTHER machines (for example their Windows PC or a laptop). Those+are reachable through the Adom mesh even when this Linux desktop has no ab: pass+`--target <name>`. Ask which machine the user means; never guess.++### 2. Ask Hydrogen (it sees the host without ab)++The workspace shares the host's network, so the control API is local:++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # normally http://127.0.0.1:47084+curl -s "$BASE/ab/health" | python3 -m json.tool # one roll-up of the probes below+curl -s "$BASE/ab/process" # ab processes on the HOST+curl -s "$BASE/ab/direct-api" # ab's API on 127.0.0.1:24680?+curl -s "$BASE/ab/discovery-file" # ~/.adom/direct-api-port live or stale+curl -s "$BASE/ab/embedded"+curl -s "$BASE/ab/relay"+```++`/ab/process` on Linux lists host processes named `adom-bridge` and ignores the workspace's own+relay process (same name, inside `machine.slice`). `count: 0` means ab is not running on this+desktop: go to step 4.++### 3. ab is running but not attached++Hydrogen hands a running ab the workspace relay and the Adom session (`POST /embedded/enter`,+relay name `hydrogen`) within about 10 to 20 seconds of seeing it, and again when ab restarts,+the relay moves, or the session changes. If ab answers on 24680 but `ping` still fails a minute+later:++- Check ab is signed in (its own window: tray menu > Open Adom Bridge).+- Read ab's log on the host. With the usual `run.sh` launcher it is+ `~/.local/share/adom-bridge-app/app.log`. From the workspace the host's home is+ `/mnt/host/home/<user>/` (file permissions permitting):++ ```bash+ ls -l /mnt/host/home/*/.local/share/adom-bridge-app/app.log+ tail -60 /mnt/host/home/*/.local/share/adom-bridge-app/app.log+ ```++ A log whose mtime keeps advancing with the same panic means ab is crash-looping. Compare its+ version (`adom-bridge-app.AppImage --version`, safe: it never starts a copy) with+ `adom-wiki release list adom/adom-bridge`.++### 4. ab is not on this desktop++That is the normal state. Either:++- work through another machine on the mesh (`--target <name>`), or+- tell the user that desktop features on this Linux machine (screenshots, files to the+ desktop, KiCad, pup) need the Linux Adom Bridge, and point them at the+ **adom-bridge-linux** skill for the one-copy install. Grok Bot shows "needs Adom Bridge" for+ the same reason.++## The out-of-band channels (why you are not blind)++When ab is dead you have not lost the host — you have lost one route to it.++1. **Hydrogen's control API** — `127.0.0.1:47084`, always up if Hydrogen is+ running. Diagnostics, ports, container state. See `hydrogen-api`.+2. **The host's files under `/mnt/host`.** The workspace never runs host programs+ directly; there is no interop channel. Reading the host's files under `/mnt/host`+ (home, /tmp, read-only /usr and /opt) is the out-of-band view.++## Do NOT do these while guessing++| Don't | Why |+|---|---|+| `register_container` for this workspace | Hydrogen already attaches ab as `hydrogen`; a second entry is a duplicate path the user sees in Connections and writes three cloud keys. |+| Rotate the relay auth token | Adds a mismatch to a system that is already broken. |+| `POST /setup/run-step` | Marked destructive; refuses without a visible UI. Not a debugging tool. |+| Conclude "broken" from `ping` alone on Linux | Most Linux desktops simply have no ab. |+| Start a second ab copy by hand | Two copies share one identity and knock each other off the relay. Use the locked `run.sh` or `systemctl --user start adom-bridge-app`. |+| Restart the relay, re-register, re-sign-in as a first move | All container-side; none of them touch a desktop process that is panicking. |++## Reverting a mistaken `register_container`++If you (or a previous agent) registered a container that should not exist,+removing it locally is **not enough** — ab re-reads the cloud profile at boot,+at sign-in, and hourly, so a local-only removal comes back. Remove both:++```bash+TOK=$(cat /var/run/adom/api-key)++# 1. cloud profile (the authoritative copy)+curl -s -X PATCH https://carbon.adom.inc/user/hydrogen/settings \+ -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \+ -d '{"key":"bridge.container.<id>","value":null}'++# 2. ab's local list+adom-bridge --ai-thread "<thread>" \+ server_remove '{"name":"<name>","reason":"<why>"}'+```++`register_container` writes **`bridge.container.<id>`, `bridge.last_slug`, and+`bridge.enabled`**. `bridge.last_slug` will be left pointing at the entry you+just deleted; null it too. Its previous value is **not recoverable** — which is+the real argument for not calling `register_container` speculatively.++Verify with `server_list` and by re-reading `hydrogen_preferences.settings`+(see `hydrogen-key-values`). Removing a relay entry you are *talking through*+severs your own transport (adom/adom-bridge#387) — check `ping`'s `transport`+field first; if it says `direct-http` you are on the loopback API and a relay+entry removal cannot cut you off.++## Gotchas that cost time++- ab's direct API is `127.0.0.1:24680`; `~/.adom/direct-api-port` on the host is authoritative+ (a stale file plus a silent port is a crash signal).+- **Caller identity is mandatory.** Verbs refuse with+ `errorCode: caller_identity_required` unless you pass+ `--ai-thread "<a name the user would recognize>"`. Gated verbs additionally+ need a per-call `reason`. See `adom-bridge-caller-identity`.+- Quitting Hydrogen asks ab to shut down when Settings > Adom Bridge > "Close Adom Bridge when+ you quit Hydrogen" is on (the default). Whether ab comes back then depends on how the user+ launches it (autostart, systemd unit), not on Hydrogen.++## When it is genuinely not a crash++If ab's log is old and quiet and no ab process exists on the host, ab is simply not on+this desktop: see step 4 and **adom-bridge-linux**. If ab runs and is signed in but the+workspace's connection is missing from its Connections list, follow `adom-bridge` /+`adom-bridge-auth`. The point of this skill is to make you *prove* that before you go+there.
skills/hydrogen-adom-bridge/SKILL.mdadded+136@@ -0,0 +1,136 @@+---+name: hydrogen-adom-bridge+description: >-+ What Hydrogen (ah) and Adom Bridge (ab) are on Linux and how they work together: ab is+ your hands on a real computer (files, shell, OS screenshots, apps, KiCad), Hydrogen installs and+ starts it here when a Linux build is published for the user's account, and the adom-bridge+ CLI also reaches the user's other machines. Use+ when asked what can you do on my computer, run a command on my PC, screenshot my screen,+ or send a file to my desktop.+---++# Hydrogen and Adom Bridge on Linux: your reach onto real machines++You (the AI) run inside the **Hydrogen workspace**, the `Adom-Workspace` systemd-nspawn machine on the user's Linux computer.+That's a sandbox. **Adom Bridge (ab) is how you reach OUT of it onto the user's+actual operating system** — their real files, shell, screen, and desktop apps.+Knowing ab exists is the difference between "I can only work in here" and "I can+create that file on your Desktop, screenshot your screen, and open it in KiCad."++## The Linux reality++- **Hydrogen for Linux installs and runs ab** when ab's manifest publishes a Linux build for the+ user's account (insiders first, everyone once it is promoted). Setup step+ `ensure-adom-bridge-cli` downloads the AppImage, checks its sha256, installs it+ (`--install --no-launch`, one per-user copy in `~/.local/share/adom-bridge-app`) and starts it+ hidden; Hydrogen restarts it if it dies and applies its staged updates. Before that, or with no+ Linux build for the account, there are no desktop verbs (desktop screenshots, files to the+ desktop, KiCad, pup, Grok Bot) on THIS computer.+- **Hydrogen adopts ab** (one it installed, or one the user runs): it hands ab the workspace relay+ and the Adom session (`POST /embedded/enter`) and ab works as on any other desktop. See+ **hydrogen-embedded-bridge**.+- **The user's OTHER machines still answer.** The `adom-bridge` CLI in the workspace reaches+ every machine on the user's Adom mesh that runs ab (for example their Windows PC or a Mac):+ `adom-bridge targets`, then `--target <name>`. Never guess which machine: ask.++To see which machines answer and whether ab runs on this computer:++```bash+adom-bridge targets # every machine on the mesh+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s "$BASE/ab/process" # ab processes on THIS Linux host (none = not running here)+curl -s "$BASE/ab/health" # ab's direct API, as Hydrogen sees it+```++## What ab lets you do (once a machine answers)++All via the `adom-bridge` CLI from inside the workspace. Rather than+re-document every verb here, this is a **capability map → the focused skill**:++| Capability | Verb(s) / surface | Where it's documented |+|---|---|---|+| Files to / from the machine | `send_files`, `pull_file`, `list_files`, `watch_files` | **hydrogen-file-transfer** |+| Shell command on the machine | `shell_execute`, `run_script` (base64 script, no quoting) | shell trust below |+| Screenshots and window control | `desktop_screenshot_*`, `desktop_list_windows`, `desktop_set_window_state` | **adom-bridge-window-capture** |+| Screen recording | `desktop_record_*`, `pup_record_*` | **hydrogen-recording** |+| Notifications | `notify_user` | **hydrogen-notifications** |+| Browsers (pup) | `pup_*` | **hydrogen-open-url**, `pup` |+| KiCad and other EDA bridges | `kicad_*`, `fusion_*`, ... | **hydrogen-bridges** |++For the complete verb list run `adom-bridge list_commands`.++A bridge without a Linux build answers `unsupported_on_this_os` on a Linux ab.++### Host shell-trust model++`shell_execute` really runs on the target machine. Approvals are the human's: see+**adom-bridge-permissions**. Revoke a standing auto-approval at any time:++```bash+adom-bridge shell_auto_approve '{"duration_secs":0}' # turn auto-approve off now+```++When you *don't* need a free-form shell, prefer the **no-escape structured+runners** over hand-quoted `shell_execute` (ab ≥ 1.8.50):+`adom-bridge run_script '{"interpreter":"bash","scriptB64":"<b64>"}'`. Base64 the script so+no quoting survives to be mangled.++## Talking to Hydrogen itself++You do not need ab for that. Hydrogen's control API is on the shared loopback:++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # normally http://127.0.0.1:47084+curl -s "$BASE/health"+curl -s "$BASE/setup/state"+```++See **hydrogen-api**.++## How the connection works (and how you check it)++```+You (AI in the workspace)+ -> adom-bridge <verb> '<json>' CLI in the workspace+ -> relay (adom-relay.service: WS :8765, HTTP :8766, inside the workspace)+ -> ab on this computer (when it runs)+ -> the Adom mesh -> ab on the user's other machines+```++- The workspace shares the host's network, so the relay's ports are this computer's+ `localhost:8765/8766`; Hydrogen's firewall table keeps them off the LAN. See+ **hydrogen-networking**.+- **Always verify the bridge before acting on the host:**+ ```bash+ adom-bridge ping # → {"status":"connected", ...} means a client is reachable+ adom-bridge status # who's connected + .capabilities + which local apps are installed/running+ ```+ If `ping` fails, no desktop client is connected: tell the user plainly that no Adom+ Bridge answers. Offer to use another machine of theirs, or point them at+ **adom-bridge-linux** to install it here. Don't claim you acted on a machine without a+ successful round-trip.++## What NOT to do++- Never kill ab on a machine you are driving: it is your control channel.+- Port `9001` is Hydrogen's liveness beacon for ab, not its control API (read+ `~/.adom/hydrogen-control-url`).+- **Don't broad-kill `node`** — VS Code Server runs as node; killing it kills the+ whole workspace.+- Resize screenshots to `<1500px` before reading them, and inject every screenshot+ into shotlog with a real description.++## Mental model for answering the user++When the user asks for something that lives on a real computer ("save this to my+Desktop", "what's on my screen", "open this in KiCad", "run this command on my+machine"), that's an **ab** job: find which machine answers (`adom-bridge targets`) and+ask which one when more than one could be meant. When it's about the workspace itself+(editor, files under `/home/adom/project`, the runtime), that's **Hydrogen**. Verify with+`adom-bridge ping`, then act.++## Related skills+- **hydrogen-embedded-bridge**: how a user-run Linux ab is adopted by Hydrogen+- **adom-bridge-linux**: installing and updating ab on Linux+- **adom-bridge-multi-machine**, **adom-bridge-mesh**: `--target` and the mesh+- **hydrogen-bridges**, **hydrogen-file-transfer**, **hydrogen-notifications**, **hydrogen-open-url**
skills/hydrogen-adom-menu/SKILL.mdadded+74@@ -0,0 +1,74 @@+---+name: hydrogen-adom-menu+description: >-+ The Adom logo menu in Hydrogen's upper-left corner on Linux (Manage AIs, Settings,+ Ports, API Explorer, Doctor, Developer Tools, workspace start/stop, Setup Steps,+ Virgin Reset) and the About dialog. Use when asked what's in the Adom menu, where+ settings or devtools are, or what version am I running.+---++# The Adom menu (upper-left logo dropdown)++Click the **teal Adom logo** in the top-left corner to open it. (Double-click the+logo = go straight to the Dashboard.) Source: `EditorNav.svelte` → `.logo-button`+→ `.logo-dropdown-container .dropdown-link` items.++> This is the **upper-LEFT** menu. The **upper-RIGHT** avatar dropdown (profile,+> repositories, logout) is a different menu — see **hydrogen-profile-menu**.++## Items (top to bottom)++| Item | What it does |+|---|---|+| **Manage AIs** | sign in to Claude Code, Codex or another AI, switch accounts, sign out |+| **Settings** | the Settings window (see **hydrogen-settings**) |+| **Ports...** | every port Hydrogen has bound on this computer and in the workspace, plus PortConfig |+| **API Explorer...** | browse and test every control-API endpoint (see **hydrogen-api**) |+| **Doctor...** | checks workspace, code-server, ports, relay, Adom Bridge and Claude, with fixes (see **hydrogen-doctor**) |+| **Back to project folder** | only when the editor is open outside your project folder |+| **Report a problem...** | files an issue on the Hydrogen wiki page as you, with the log tail and the Doctor's checks |+| **About Hydrogen** | version and build info |+| *Desktop* | |+| **Zoom** | minus / percent (reset) / plus for the whole UI (Ctrl -, Ctrl 0, Ctrl +) |+| **Fullscreen** | toggle (also F11) |+| **Console** | show or hide the console window, a live tail of `~/.config/hydrogen-desktop/hydrogen-desktop.log` |+| **Developer Tools** | opens the WebKit Web Inspector (also Ctrl+Shift+I) |+| *Container* (state shown) | **Start Container**, or **Restart Container** and **Stop Container** (see **hydrogen-workspace-lifecycle**) |+| *Admin* | **Setup Steps** (show or hide the setup panel), **Virgin Reset** (see **hydrogen-setup**), **Browser Picker Manager** (saved browser choices per domain) |++On Linux **Adom Bridge** shows ab's window, the same as Open Adom Bridge in the tray menu (it+does nothing until Hydrogen has installed ab). The menu has no Run Recovery Check (there is no wake watcher) and no Reclaim disk space (the workspace's+files sit directly on this computer's disk, so there is nothing to compact).++> **Removed items (do not list):** "Bridge Manager" (was a no-op with no backing+> panel) and "Port Mappings…" (no such action exists in the code).++Drive it programmatically with **hydrogen-eval** (`target:"shell"`): click+`.logo-button`, then click the `.dropdown-link` whose text matches the item.+You can also use the UI actions (`GET /ui/actions`, `POST /ui/invoke {"id":...}`): for example+`settings.open`, `ports.open`, `devtools.open`, `container.restart`, `report-problem.open`.++## Developer Tools++`open_devtools` (or `POST /devtools`) opens the WebKit Web Inspector for Hydrogen's main+window. It is compiled into release builds too. It is its own window, so a Hydrogen+screenshot does not show it. Pair with **hydrogen-eval** to inspect or inject into any panel.++## Version readout — title bar + About dialog++**Title bar** (always visible) shows, in order:+`Hydrogen v<version> · <dev|release> · <sha>-dirty · <build time>`, plus ` · AB <version>`+once Adom Bridge is reachable. A Linux build never says signed or unsigned.++**About dialog**: open it from this menu (**About Hydrogen**, `get_about_info`). It shows+Hydrogen's version, dev or release, commit (and dirty), build time, signed, and install+path, plus an Adom Bridge section (reachable, version, endpoint) that reports not reachable+until Adom Bridge runs on this computer (Hydrogen installs it when a Linux build is published+for the user's account).++## Related+- **hydrogen-profile-menu** — the upper-RIGHT avatar dropdown (don't confuse the two)+- **hydrogen-settings** — the settings tree behind the **Settings** item+- **hydrogen-api** — the control-API surface behind **API Explorer…**+- **hydrogen-setup** / **hydrogen-setup-steps** — what Setup Steps / Virgin Reset do+- **hydrogen-eval** — drive these menu items / inject UI from the workspace
skills/hydrogen-ai-agents-dev/SKILL.mdadded+202@@ -0,0 +1,202 @@+---+name: hydrogen-ai-agents-dev+description: >-+ Maintainer design notes for Hydrogen's AI agent support on Linux: golden-image vs user+ installs, auth oracles, how sign-in is driven, the VS Code toolbar and the Manage AIs dialog.+ Use before touching agent_harness.rs, PanelAiAccounts.svelte or ai-titlebar.js.+disable-model-invocation: true+---++# Hydrogen AI agents: how it is built++One record per AI, owned by Hydrogen, drives everything the user sees: the first-landing+"Choose your AI" dialog, the Manage AIs dialog, the VS Code toolbar buttons, and the Welcome+page line. This skill is the map. The user-facing how-to is+[hydrogen-ai-agents](../hydrogen-ai-agents/SKILL.md).++## The pieces++| piece | where | job |+|---|---|---|+| `Provider` table + `/agents/*` routes | `src-tauri/crates/hydrogen-control/src/agent_harness.rs` | the truth: detect, oracle, install, login, logout, facts, publish agent-bar.json |+| Choose your AI / Manage AIs dialog | `src/lib/components/editor/panels/PanelAiAccounts.svelte` (mounted as an overlay by PanelVisualStudioCode) | renders `/agents/catalog` + `/agents/facts`, drives sign-in |+| toolbar buttons + AI menu | adom-vscode `browser/ai-titlebar.js` (injected into workbench.html) and `extension/src/extension.ts` (`/ai/*` routes on :8821) | draws one button per installed AI, opens threads, "Manage AIs" row |+| golden image | the golden image repo, `image/bake-in-distro.sh` | bakes Claude Code + Codex extensions, the `claude`/`codex` wrappers, adom-vscode, bootstrap |+| converge on every workspace | hydrogen-bootstrap `install.sh` sections 4b to 4d | first-run flags, wrapper repair, duplicate removal |+| exec transport | adom-vscode `POST /exec` on :8821 (`container_exec`) | every probe runs through it, never one root-helper exec per probe (on Linux each helper exec is a `sudo -n` call) |++## Golden image versus user install++Baked (present on every fresh workspace): the Claude Code and Codex VS Code extensions, the+`~/.local/bin/claude` and `~/.local/bin/codex` wrappers, adom-vscode, adom-theme, the+hydrogen-* skills. Installed by the user from Manage AIs: Kimi Code and Antigravity, each as+extension + CLI in one click (`POST /agents/install {key}`; the CLI through the provider's+`install_cmd`). On Linux the extension half runs code-server's own CLI in a clean environment+(`hydrogen_log::host::CODE_SERVER_CLI`, `extension_cli_install`): from the exec route's VS Code+environment it hit the remote-CLI shim, printed garbage and installed nothing ("JSON Parse+error" toasts).++Why this split: the two baked AIs are what every Adom user gets signed in on day one, and+their extensions are large (235 MB and 620 MB) so baking saves the download. Kimi and+Antigravity stay optional; their installs are cheap and their sign-ins need a Google or Kimi+account the user may not have.++## The no-duplicates rule (John, 2026-09-20)++"I'm trying to achieve no redundancy of code across the vscode extension and the cli/tui."++- Where the extension ships the CLI (Claude Code: `resources/native-binary/claude`; Codex:+ `bin/linux-x86_64/codex`), the PATH command is a tiny wrapper that resolves the newest+ extension folder on every run and execs that binary. No second binary, ever.+- The Claude wrapper exports `DISABLE_AUTOUPDATER=1`. Without it, Claude Code's own updater+ (installMethod "native" in `~/.claude.json`) downloads a full second binary into+ `~/.local/share/claude/versions` on an interactive launch, even when already current.+ AdomLapper had four of them (825 MB); arav-rog got one during a sign-in pty.+- Antigravity's extension downloads its own `agy` to `~/.gemini/bin/agy`. `install_cmd` and+ `detect_cmd` link `~/.local/bin/agy` to it and only run the public installer when no copy+ exists. The first cut always ran the installer and left two identical 214 MB binaries.+- Kimi's extension ships no CLI, so `~/.kimi-code/bin/kimi` (2.x) is the only copy and is+ legitimate.+- hydrogen-bootstrap converges every workspace: 4c patches an old wrapper with+ `DISABLE_AUTOUPDATER` and deletes orphaned `~/.local/share/claude`; 4d removes an npm+ `@openai/codex` or `@anthropic-ai/claude-code` under `~/.local/lib` when the extension's+ binary exists and rewrites the wrapper if it was overwritten or emptied.+- `GET /agents/facts` measures all of it in the container (extension folder, CLI kind and+ bytes, data dirs, and a `dupes` list) and the dialog's "?" tooltip shows it, so a+ regression is visible to the user without anyone reading logs.++## Desktop apps: the host_app kind (Grok Bot)++`Provider.host_app` names an Adom Bridge verb prefix (`grok`). Such a provider has nothing in the+workspace: `host_app_state` asks ab (`<prefix>_readiness`, `<prefix>_status.webhookBound`). On+Linux ab may not be installed yet (Hydrogen installs it only when a Linux build is published for+the account), so a bridge that does not answer is reported as "needs Adom+Bridge, which is not running", never as unknown (unknown kept the first-run sign-in check+waiting forever). Send bridge verbs with `ad::send_verb_timeout` (no `app` field) and treat ab's+"Unknown verb" as "bridge not installed". adom-vscode draws nothing for a host app.++## Sign-in: detection (the oracles)++Each Provider has an `oracle_cmd`, a shell command run in the container whose stdout decides+"signed in". Rules learned the hard way:++- Read state, never make a network call. Antigravity's first oracle was `agy -p 'ok'`; when+ the account hit Google's 429 quota the dialog showed "Sign in" over a valid session. Now+ it checks `~/.gemini/antigravity-cli/antigravity-oauth-token` for a refresh token.+- Kimi 2.x keeps `[providers."managed:kimi-code".oauth]` in `config.toml` plus+ `credentials/kimi-code*.json`; the oracle globs the credentials dir (or an API key).+- Codex: `codex login status`, falling back to `~/.codex/auth.json`. Claude: the shared+ `~/.claude/.credentials.json` (the extension writes it, the CLI reads it).+- Oracles are cached (`FAST_ORACLE_TTL` 5 s, `ORACLE_IN_FLIGHT` guard) because the catalog+ is polled by several surfaces at once. Slow oracles are marked `oracle_slow` and cached+ longer.+- A failed probe is "unknown", never "not installed" (`detect()` returns Err on transport+ failure). Right after an update relaunch the exec route settles for a few seconds; the+ first cut read every AI as absent and raised the first-landing dialog on a signed-in box.++`shared_auth` on the Provider says whether one sign-in covers the extension and the CLI.+Claude, Codex and Kimi share a credential store. Antigravity does not, but Hydrogen makes it+shared: the extension's agy server keeps its Google login in+`~/.gemini/jetski-standalone-oauth-token` and the CLI in+`~/.gemini/antigravity-cli/antigravity-oauth-token`, both for the SAME OAuth client+(identical `aud` in the id_token, VERIFIED 2026-09-20) in the same JSON shape. The oracle+reads both and copies whichever exists to the missing side (mode 600), so a panel sign-in+signs the CLI in and a CLI sign-in signs the extension in. One limit, measured: the panel's+webview keeps its Welcome screen until the window reloads (restarting the agy server or+re-opening the side bar does not refresh it), so after a CLI-side sign-in the dialog offers+"Reload VS Code now". `shared_auth_note` carries that explanation into the tooltip.+`ext_separate_signin` still marks Antigravity so the dialog's primary Sign in opens the panel+(extension first). Sign-out removes both token files. Before this, Hydrogen ignored the+extension's file and showed "Sign in" over a signed-in panel (John, 2026-09-20).++## Sign-in: driving it for the user++`POST /agents/login {key}` runs the provider's `login_cmd` under a pty in the container with+`BROWSER=` pointed at a capture script, then `GET /agents/login-url` streams what the panel+needs: the consent URL (captured from `$BROWSER` or regexed out of the transcript with+`url_regex`), a device code (`code_regex`, Codex), and `needs_input` when the transcript+matches `input_prompt_regex` (the CLI wants a code pasted back). `auto_input` types menu+answers (Antigravity's "Select login method" wants Enter). The session ends when the oracle+flips or on `/agents/login-stop`.++Per AI:+- Claude: the CLI's OAuth in the browser. Hydrogen cannot raise the consent window for the+ user on Linux (`raise_window_for_user` is a no-op here).+- Codex: device code shown in the dialog, user types it on the page.+- Kimi: device flow against kimi.ai. `install_cmd` writes `global` into `~/.kimi-code/region`+ (the installer wrote mainland-cn, which sends the user to a WeChat page and the poll never+ completes). The 2.x login also moves aside a 0.8.x extension-written `config.toml` that+ lacks per-model `protocol` (it made every prompt refuse).+- Antigravity: the extension is primary (John: "stop giving preference to the tui"). The+ dialog's Sign in opens the extension's panel through `POST /agents/open-panel`, counts down+ "closing this dialog in 3, 2, 1" and closes so the panel is not hidden behind it. The CLI+ sign-in is the secondary link; its flow ends on antigravity.google/oauth-callback, a+ paste-only page, so the dialog shows a paste box (`paste_code`) feeding+ `POST /agents/login-input {key, value b64}`. No clipboard sniffing (John: "just give me a+ box to paste the code into").++On Linux, Manage AIs sign-ins (`signin: true`) and known sign-in hosts open straight in the+system browser (no picker countdown, no in-app tab: Codex's page refuses to be embedded).++Codex and Claude Code's shell sandbox is bubblewrap. On Ubuntu 23.10+ the host's+`kernel.apparmor_restrict_unprivileged_userns=1` breaks it; Hydrogen's helper loads+`/etc/apparmor.d/adom-hydrogen-bwrap` at machine start. A "needs access to create user+namespaces" error means that profile is not loaded.++First-run state for the Claude TUI lives in `~/.claude.json` (`hasCompletedOnboarding`,+`theme`, per-folder `hasTrustDialogAccepted`); the extension never writes it, so a signed-in+user still saw the wizard in a terminal. hydrogen-bootstrap 4b seeds those keys.++## The toolbar button decision++Hydrogen writes `~/.adom/agent-bar.json` whenever an oracle result changes:+`{"authed":[keys], "agents":[{key, cli, extension, extension_id, authed}]}`. adom-vscode+watches it (`fs.watchFile`) and its `/ai/providers` merges it with the extension list:++- `installed = extension || cli`. A main toolbar button appears only when installed, and it+ opens the extension surface (tab or side bar), never the TUI.+- TUI buttons exist for people who like them: off by default, added in the icon chooser, and+ only offered when the CLI exists.+- Antigravity's default surface is the side bar: its "editor tab" mode waits on a remote+ tunnel that never connects under code-server.+- The AI menu lists installed AIs plus an "Install the X extension" row when only the CLI is+ present, and a "Your AIs / Manage AIs" row that calls Hydrogen `POST /agents/present+ {manage:true}` through the control URL in `~/.adom/hydrogen-control-url`.++Signing in therefore lights the button by itself; nothing reloads.++## Keeping the Manage AIs dialog honest++- Every row is rendered from `/agents/catalog` (installed, authed, extension, has_login,+ has_apikey, has_install, shared_auth, extension_signin_separate). The pill says+ "Signed in · extension + CLI" when `shared_auth`, else "CLI signed in" plus "extension: own+ sign-in". The button says "Sign in" when one sign-in covers both, "Sign in extension" when+ it does not.+- The "?" opens a tooltip from `/agents/facts`: extension id, version, bytes; the CLI as a+ wrapper (0 MB extra), an extension-downloaded copy, a pip package, an npm package or a+ standalone binary with its bytes; the sign-in model; data dirs; duplicates; total. It is+ positioned from the button's measured rect as a sibling of the dialog inside the overlay.+ Rendering it in flow made the dialog grow and re-centre, slid the "?" out from under the+ cursor, and looped (John: "the worst human experience ever"). Nothing in that tooltip may+ change layout.+- One shared record per AI: the dialog, the toolbar and the Welcome line never compute their+ own state; they read Hydrogen's. Sign out goes through `/agents/logout` (provider+ `logout_cmd`, plus `ext_logout_cmd` for Kimi's extension) so all three surfaces flip+ together.+- The dialog is draggable by its header and has a close X; the first-landing variant has+ "I'll do this later" and "Continue".++## Ship checklist for a change here++1. Hydrogen for Linux: `scripts/linux-build.sh` (deb, rpm, AppImage), or+ `scripts/linux-build-jammy.sh` for the glibc 2.34 floor; install on the Linux test VMs and+ check `/buildinfo`. Releases go out through the manifest's `linux` section+ (`scripts/publish-version-json.sh --linux-*`).+2. adom-vscode: `bash build.sh`, `bash scripts/release-wiki.sh` (stamp guards, pushes main).+ Workspaces pull it with `adom-wiki pkg update adom/adom-vscode`.+3. hydrogen-bootstrap: bump `package.json`, `prepublish-check.sh`, `adom-wiki pkg publish --org+ adom --yes`. Test any new converge block on a test box first; it runs on every workspace.+4. Golden image: the golden image repo's `scripts/bake-weekly.sh` then `pin-golden.sh`; wrapper+ text in `image/bake-in-distro.sh` must match what bootstrap 4d writes.+5. Verify with `GET /agents/catalog` and `GET /agents/facts?fresh=1` on a box, then look at+ the dialog (screenshot), not just the JSON.
skills/hydrogen-ai-agents/SKILL.mdadded+200@@ -0,0 +1,200 @@+---+name: hydrogen-ai-agents+description: >-+ Install, sign in, sign out and check quota for the AIs in a Hydrogen workspace (Claude+ Code, Codex, Kimi Code, Antigravity) through the /agents API. Use when asked to install+ antigravity or kimi, sign in to codex, which AIs are signed in, how much usage is left,+ or why an AI button is missing.+---++# Hydrogen AI agents: install and sign in from a session++Hydrogen owns AI installs and sign-ins. Do not run `curl … | bash` installers, `npm install -g`,+`pip install kimi-cli` or `claude update` by hand: each of those puts a SECOND copy of a CLI the+VS Code extension already ships into the user's container (see the no-duplicates rule below).+Call Hydrogen's `/agents` API instead. It installs the extension and the CLI together, signs in+the right way for each AI, and keeps the VS Code toolbar and the Manage AIs dialog in step.++## Reach the API from inside the workspace++Hydrogen writes its control URL into the workspace:++```bash+HD=$(cat ~/.adom/hydrogen-control-url) # normally http://127.0.0.1:47084+curl -s "$HD/agents/catalog" | python3 -m json.tool+```++If the file is missing you are not inside a Hydrogen workspace (or Hydrogen is not running);+tell the user to open Hydrogen rather than improvising an install.++## The four AIs and their keys++| key | AI | extension | CLI / TUI | one sign-in covers both? |+|---|---|---|---|---|+| `claude` | Claude Code | anthropic.claude-code (baked into the golden image) | `claude`, a wrapper onto the extension's bundled binary | yes, `~/.claude/.credentials.json` |+| `codex` | Codex | openai.chatgpt (baked in) | `codex`, a wrapper onto the extension's bundled binary | yes, `~/.codex/auth.json` |+| `kimi` | Kimi Code | moonshot-ai.kimi-code (user installs) | `kimi` 2.x, standalone (the extension ships no CLI) | yes, `~/.kimi-code/credentials` |+| `antigravity` | Antigravity | google.google-antigravity (user installs) | `agy`, the copy the extension downloads to `~/.gemini/bin/agy` | yes, by Hydrogen: it copies the Google token between `~/.gemini/jetski-standalone-oauth-token` (extension) and `~/.gemini/antigravity-cli/antigravity-oauth-token` (CLI) |++`grok` is **Grok Bot**, a desktop app reached through Adom Bridge's `grok_*` verbs, not an+extension or a CLI. On this computer the catalog reports Grok as not installed with "Grok Bot+needs Adom Bridge, which is not running" until Adom Bridge runs here (Hydrogen installs it when a+Linux build is published for the user's account). A Grok Bot on another of the user's+machines is reached with `adom-bridge --target <machine> grok_*` (the `grok-account` skill in+adom/grok-bridge). No toolbar button.++## What each call does++```bash+HD=$(cat ~/.adom/hydrogen-control-url)++# Who is installed and signed in (installed = extension or CLI present; authed = the AI's own oracle)+curl -s "$HD/agents/catalog"++# Sizes, where each piece lives, and any DUPLICATE copies (what the ? in Manage AIs shows)+curl -s "$HD/agents/facts" # add ?fresh=1 to re-measure++# Install: extension + CLI together (Kimi, Antigravity). cli_only:true skips the extension.+curl -s -X POST "$HD/agents/install" -H 'content-type: application/json' -d '{"key":"antigravity"}'++# Sign in (CLI-driven for claude, codex, kimi; the shared credentials sign the extension in too)+curl -s -X POST "$HD/agents/login" -H 'content-type: application/json' -d '{"key":"kimi"}'+curl -s "$HD/agents/login-url?key=kimi" # poll: {authed, url, device_code?, needs_input?, detail}+# - url: hand it to the user as a tappable link (Hydrogen also opens it in their browser)+# - device_code: the user types it on the page (Codex)+# - needs_input: the page ends on a "copy this code" screen; paste it back:+curl -s -X POST "$HD/agents/login-input" -H 'content-type: application/json' -d "{\"key\":\"antigravity\",\"value\":\"$(printf %s "$CODE" | base64 -w0)\"}"+curl -s -X POST "$HD/agents/login-stop" -H 'content-type: application/json' -d '{"key":"kimi"}' # cancel++# Antigravity's EXTENSION sign-in happens inside its VS Code panel; open it for the user:+curl -s -X POST "$HD/agents/open-panel" -H 'content-type: application/json' -d '{"key":"antigravity"}'++# API key instead of OAuth where the AI supports it (base64 on the wire)+curl -s -X POST "$HD/agents/apikey" -H 'content-type: application/json' -d "{\"key\":\"kimi\",\"value\":\"$(printf %s "$KEY" | base64 -w0)\"}"++# Sign out (removes that AI's credentials; for Kimi also the extension's, they are shared)+curl -s -X POST "$HD/agents/logout" -H 'content-type: application/json' -d '{"key":"kimi"}'++# Raise the Manage AIs dialog in Hydrogen for the human to click through+curl -s -X POST "$HD/agents/present" -H 'content-type: application/json' -d '{"manage":true}'+```++A sign-in is done when `GET /agents/catalog` reports `authed: true` for that key. Poll every+few seconds; the human has minutes, not seconds, to click through Google or OpenAI.++## What to tell the user++- **"Install antigravity" / "install kimi"**: call `/agents/install`, wait for `installed: true`+ in the catalog, then start the sign-in. Say what got installed: the extension and the CLI.+- **Sign-in for claude, codex, kimi**: one sign-in covers the extension and the CLI. Give the URL+ as a link. For Codex give the device code too.+- **Sign-in for antigravity**: either side works and Hydrogen syncs the token to the other+ within seconds. Prefer the panel (`/agents/open-panel`): the user clicks Continue with Google+ there and the CLI is signed in right after. The CLI flow (`/agents/login`) ends on a page+ that shows a code; ask them to paste it and send it with `/agents/login-input`. After a+ CLI-side sign-in the VS Code panel keeps its Welcome screen until the window reloads; the+ dialog offers "Reload VS Code now", or call `POST $HD/reload-vscode?confirm=1` (it hard+ reloads the editor; ask first if the user may have unsaved editor state).+- **Kimi 403 "subscription does not have access to Kimi Code" from the CLI while the extension+ works**: that is the legacy pip Kimi 1.x (`kimi --version` says 1.x). Its upgrade also kills+ the TUI. Hydrogen's install (or hydrogen-bootstrap on its next run) replaces it with the 2.x+ binary in `~/.kimi-code/bin`, which uses the same credentials without error.+- **Kimi region**: Kimi's installer defaults to mainland China (kimi.com, WeChat). Hydrogen's+ install writes `global` into `~/.kimi-code/region` so sign-in goes to kimi.ai. If a user+ lands on a WeChat page, that file is wrong.+- **Quota is not "signed out"**: an AI that answers 429 (Antigravity: "Individual quota+ reached, resets in Nh") is still signed in. Hydrogen's sign-in check reads the token, not a+ live prompt, so it stays green; explain the quota instead of re-authenticating.++## Quota: how much of each plan is left++None of these calls runs a model, so reading quota costs nothing. Each one reads the sign-in the+AI already keeps in the workspace; never print the tokens, print only the numbers.++| AI | where the numbers come from | what comes back |+|---|---|---|+| Claude Code | `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`), `GET https://api.anthropic.com/api/oauth/usage` with `anthropic-beta: oauth-2025-04-20`; `GET .../api/oauth/profile` gives the account email | `five_hour.utilization`, `seven_day.utilization` (percent used) with `resets_at`; `limits` is the list `/usage` draws, including weekly limits scoped to one model |+| Codex | `~/.codex/auth.json` (`tokens.access_token`, `tokens.account_id`), `GET https://chatgpt.com/backend-api/wham/usage` with `ChatGPT-Account-Id` | `rate_limit.primary_window.used_percent` and `reset_at` (epoch), `limit_reached`; also `credits.balance` and `rate_limit_reset_credits.available_count` (what `/status` shows) |+| Antigravity | the running hub `agy --hub` (port and CSRF token on its command line), `POST http://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary` with `x-codeium-csrf-token`, body `{}` | `response.groups[].buckets[]`: `window` (`weekly` or `5h`), `remainingFraction`, `resetTime`, for the Gemini group and the Claude and GPT group; `GetLoadCodeAssist` gives the plan name and `GetUserStatus` the signed-in email |+| Grok Bot | a desktop app on a machine running Adom Bridge, no file in the workspace: `adom-bridge --target <machine> grok_settings {"page":"usage"}` then `grok_screenshot` (the `grok-account` skill ships in adom/grok-bridge) | the plan, weekly percent and reset, the on-demand cap |+| Kimi Code | not mapped yet | |++The Title Bar widgets `claude-usage`, `codex-usage` and `antigravity-usage` (wiki widget+packages, when installed) show the same numbers for this workspace.++```bash+python3 - <<'PY'+import json, os, re, subprocess, urllib.request+def get(url, h, data=None):+ return json.loads(urllib.request.urlopen(urllib.request.Request(url, data=data, headers=h), timeout=20).read())+try:+ c = json.load(open(os.path.expanduser('~/.claude/.credentials.json')))['claudeAiOauth']+ h = {'Authorization': 'Bearer ' + c['accessToken'], 'anthropic-beta': 'oauth-2025-04-20'}+ u = get('https://api.anthropic.com/api/oauth/usage', h); who = get('https://api.anthropic.com/api/oauth/profile', h)['account']['email']+ print('claude', who, '5h', u['five_hour']['utilization'], 'week', u['seven_day']['utilization'], 'resets', u['seven_day']['resets_at'])+except Exception as e: print('claude', e)+try:+ a = json.load(open(os.path.expanduser('~/.codex/auth.json')))['tokens']+ d = get('https://chatgpt.com/backend-api/wham/usage', {'Authorization': 'Bearer ' + a['access_token'], 'ChatGPT-Account-Id': a['account_id'], 'User-Agent': 'codex_cli_rs'})+ w = d['rate_limit']['primary_window']+ print('codex', d['email'], d['plan_type'], 'week', w['used_percent'], 'reset', w['reset_at'], 'credits', d['credits']['balance'])+except Exception as e: print('codex', e)+try:+ l = next(l for l in subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True).stdout.splitlines() if re.search(r'(^|/)agy\s.*--hub', l))+ port, csrf = re.search(r'--hub-port[= ](\d+)', l).group(1), re.search(r'--csrf_token[= ](\S+)', l).group(1)+ q = get(f'http://127.0.0.1:{port}/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary',+ {'Content-Type': 'application/json', 'x-codeium-csrf-token': csrf}, b'{}')['response']+ for g in q['groups']:+ for b in g['buckets']: print('antigravity', g['displayName'], b['window'], 'used', round((1 - b['remainingFraction']) * 100), 'reset', b['resetTime'])+except StopIteration: print('antigravity: hub not running (open the Antigravity panel once)')+except Exception as e: print('antigravity', e)+PY+```++**Across machines.** Each machine's workspace has its own sign-ins, and two machines can be on+different accounts. On another machine that runs Adom Bridge and Hydrogen, run the same script in+its workspace through the bridge (`adom-bridge --target <machine> --ai-thread "<thread>"+run_script ...`; see **adom-bridge-multi-machine**). Group the rows by account email, not by+machine: machines signed in to the same account share one pool.++**Reading the answers.**++- Codex at 100 percent (`limit_reached: true`) still has two ways on before the reset: the+ credits balance (pay-as-you-go, if the user turns it on) and `rate_limit_reset_credits`+ (one-shot window resets). Both spend money or a scarce reset: tell the user, never use one+ on your own.+- Antigravity reports separate pools for Gemini and for its Claude and GPT models. One pool+ can be empty while the other is full.+- Grok Bot sitting on its "Update ready, Restart to update" screen shows no Settings page and+ runs no bots. Restarting it stops whatever its bots are doing: leave that to the user.++## Codex and Claude Code's shell sandbox on Ubuntu++Both sandbox their shell commands with bubblewrap. Ubuntu 23.10 and later restrict unprivileged+user namespaces, which breaks bwrap ("Codex's Linux sandbox uses bubblewrap and needs access to+create user namespaces"). Hydrogen's workspace helper loads an AppArmor profile+(`/etc/apparmor.d/adom-hydrogen-bwrap`) at every machine start that lets bwrap set the namespace+up with no extra capabilities. If the error appears anyway, restart the workspace once; on Debian+and Fedora there is no such restriction.++## The VS Code toolbar and the Manage AIs dialog++Hydrogen publishes `~/.adom/agent-bar.json` (`{"authed":[…],"agents":[{key, cli, extension,+extension_id, authed}]}`) every time an oracle changes. adom-vscode watches that file and draws+one toolbar button per INSTALLED AI (extension first; a TUI button only if the user adds it in+the icon chooser and the CLI exists). So after an install or sign-in the button appears on its+own; nothing to reload. The Manage AIs dialog (Hydrogen: Adom menu, profile menu; VS Code: the+AI menu's "Manage AIs" row) reads `/agents/catalog` and `/agents/facts` live.++## The no-duplicates rule++The extension is the source of the CLI wherever it ships one. `claude` and `codex` on PATH are+719- and 830-byte wrappers that exec the extension's bundled binary; `agy` links to the copy the+Antigravity extension downloads; only `kimi` is a standalone binary because its extension ships+none. A second copy (an npm `@openai/codex`, a `claude update` native install under+`~/.local/share/claude/versions`, a second `agy` from the public installer) is a regression:+Manage AIs flags it under "Duplicate" with the bytes it would free, and hydrogen-bootstrap+removes it and restores the wrapper on its next run. If a user asks for the npm or native+channel on purpose, say that the extension then carries the same binary twice.++For the design behind all of this, Read `~/.claude/skills/hydrogen-ai-agents-dev/SKILL.md`.
skills/hydrogen-ai-threads-api/SKILL.mdadded+435@@ -0,0 +1,435 @@+---+name: hydrogen-ai-threads-api+description: >-+ Open and drive AI conversations in Hydrogen from code over the control API:+ open a thread, list open ones, put text in a chat box, send a prompt and+ confirm it landed, reopen or close. Use when asked to open a new claude/codex+ thread, send a prompt to an AI, or list open AI conversations.+---++# Driving Hydrogen's AI threads from your own app++Hydrogen keeps every open AI conversation (Claude, Codex, Kimi) in one live tree and exposes+it over its control API. **Anything that can reach that port can do everything the AI Threads+panel does**: the panel itself is a plain HTTP client with no privileged access, so there is+no capability you are missing.++## Find the API++The control port is dynamic (it drifts when 47084 is busy), so never hardcode it.++Inside the workspace:++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # e.g. http://127.0.0.1:55038+curl -s "$BASE/ai-threads" | jq .+```++From a Hydrogen panel or webview, ask your own origin: `fetch('/ports')` returns the resolved+`control` port. If neither is available, the discovery responder answers on the first+bindable of `47080, 48080, 49180, 50280` and returns the live `control_url`.++## From outside the workspace (host apps, Adom Bridge, a dock card)++The workspace shares the Linux host's network, so `127.0.0.1` is the same on both sides. On the+host, read `~/.config/hydrogen-desktop/ports.json` for the live `control` port, or probe the+discovery responder (`GET http://127.0.0.1:<c>/` for c in 47080, 48080, 49180, 50280; the first+answer carries `control_url`). Then call the same `/ai-threads/*` routes. Note: while the AI+Threads panel is off (its default), the first driving call wakes the machinery for that+session; read-only census calls while parked return `ok:false` by design.++**How it drives the editor on Linux.** WebKitGTK has no DevTools protocol, so Hydrogen reaches+the workbench and the AI panels through its frame bus: a script in every frame of its webview,+in an isolated script world (the DOM is shared with the page, page JS globals are not). Evals,+workbench clicks and reading webview DOM are proven on Linux; the end-to-end typing and+delivery flows below had not yet been exercised on Linux against a signed-in Claude as of the+2026-11-02 Linux notes. Trust `ok` and the on-disk delivery check,+and report a failure with its `_hints` rather than retrying blind.++## Open a new thread++```bash+curl -sX POST "$BASE/ai-threads/new" -H 'content-type: application/json' -d '{}'+```++**Omit `type` and the user's own preference decides.** That is the point: a caller like the+dock knows which APP the user clicked, not which AI they like, and hardcoding one imposes a+choice that is not yours to make. The default is **claude**, the workhorse every Adom user is+required to have, so the fallback is always something the user actually has installed.++```jsonc+{"ok": true, "type": "claude", "from_default": true, "result": { "via": "keybinding", ... }}+```++- `type` is the AI that was actually used.+- `from_default: true` means it came from the setting rather than your request.+- `via: "keybinding"` means it opened without flashing the command palette at the user.++**THE RESPONSE CARRIES NO THREAD ID, EVER** (`sid: null, tid: null`, explicit since+1.0.143): a new thread has no identity until its first submitted prompt, and the tab+itself settles in a background task after this call returns. Do NOT open-then-target:+`new` followed by `run-prompt {sid}` always fails because there is no sid to pass.+To open a thread AND deliver a first prompt, use the ONE-CALL composite:++```bash+curl -sX POST "$BASE/ai-threads/run-prompt" -H 'content-type: application/json' \+ -d '{"new": true, "prompt": "Search Mouser for STM32G474", "submit": true,+ "name": "Parts - say it", "tags": ["dock:my-app"]}'+```++`name` and `tags` stage exactly as they do on `/new` (1.0.143+) and attach when the+sid appears; the response verifies delivery against the on-disk transcript+(`delivered_to`). To find a thread you opened earlier, poll `GET /ai-threads` for your+staged name/tags to attach, never guess by position.++**Client timeouts: 45 seconds for targeted calls, 120 for the `new:true` composite.**+Opening drives the editor (extension command, dual detection, tab placement) and its+internal create cap alone is 60s on a busy workbench. A 5-10s client+timeout manufactures phantom failures. On a create-timeout error, follow the response's+`_hints`: poll GET /ai-threads for your staged name/tags (a late tab claims them), then+deliver by `tid`; a blind retry opens a duplicate.++**Adopt semantics (1.0.143+):** when an idle EMPTY Claude tab already exists, the+composite delivers into it (`adopted_empty_tab: true`) instead of asking the editor for+a new tab, which is deterministic where the editor's own "new conversation" may reuse an+arbitrary tab. Every /ai-threads response also now carries `_hints` telling the calling+AI what happened and how to recover; surface that text in your failure UI.++Name one explicitly only when your feature is genuinely AI-specific:++```bash+curl -sX POST "$BASE/ai-threads/new" -H 'content-type: application/json' \+ -d '{"type":"codex","prompt":"review the diff in this repo"}'+```++`prompt` is optional and seeds the conversation's first message.++`tags` is optional and marks the thread as YOURS before it even has an id:++```bash+curl -sX POST "$BASE/ai-threads/new" -H 'content-type: application/json' \+ -d '{"tags":["dock","app:kicad"],"prompt":"help me with this board"}'+```++A brand-new thread has no stable id until its first message creates the conversation, so+tags passed here STAGE and attach automatically the moment the id appears (the response+carries `tags_staged` confirming that). Staged tags expire after 10 minutes if no thread+materializes, so a failed open cannot mis-tag a stranger.++**Read or change the preference** (it is a normal setting, so let the user own it):++```bash+curl -s "$BASE/ai-threads/settings" | jq .default_ai # "claude"+curl -sX POST "$BASE/ai-threads/settings" -H 'content-type: application/json' \+ -d '{"default_ai":"kimi"}'+```++**Open the AI's CLI in a terminal tab instead** (the caret menu next to each toolbar+button does exactly this):++```bash+curl -sX POST "$BASE/ai-threads/new-tui" -H 'content-type: application/json' \+ -d '{"type":"claude"}'+```++A named terminal ("Claude TUI" / "Codex TUI" / "Kimi TUI") opens as an editor tab+running that AI's full CLI. TUI threads are FIRST-CLASS rows in the tree (marked+`tui: true`): they list alongside webview threads, and `/ai-threads/rename` and+`/ai-threads/close` work on them (close also answers VS Code's "terminate running+processes?" dialog). Delivery endpoints (`run-prompt`, `inject`) do not type into+TUIs; drive a TUI conversation in its terminal.++## The AI picker: what happens when you do not name the AI (1.0.213)++`POST /ai-threads/new` and `POST /ai-threads/run-prompt {new:true}` take an optional `type`+(`claude` | `codex` | `kimi`). Name it and that AI opens, no questions. Leave it out and the+USER decides: a picker dialog appears in the shell (the same idea as the Browser Picker) with+a 5 second countdown to their default AI, keys 1/2/3, Enter, Escape, and a "remember for this+app" checkbox keyed on the thread's `app:` tag. This is what a dashboard's "Send to AI" hits,+so the human chooses where their phrase goes and can switch from Claude to Codex before the+countdown fires.++What that means for you as a caller:+- No answer within 45 s, or the user's setting `ai_picker: "never"`: the default AI is used+ and the call proceeds as before. You are never stranded.+- The user cancels: the call returns `{ok:false, cancelled:true}` and nothing was opened or+ delivered. Do not retry in a loop; either pass `type` or tell the user.+- A Codex or Kimi pick with a prompt: the thread opens through that AI's own command, the+ fresh tab is found in the census (type matches, no sid yet) and the prompt is typed in; the+ answer carries `tid`, `inject`, and `delivered:false` with a reason when the tab never+ surfaced (then `POST /ai-threads/inject {tid, text}` once `GET /ai-threads` lists it).+- To open silently from a thread, pass `type`. The picker is for humans; an AI that wants a+ Codex thread says so.+- A dashboard that belongs to one AI (the Codex, Claude or Antigravity dock apps) passes+ `prefer:"codex"` (or claude, kimi): the picker still shows, with THAT AI as the countdown+ default, beating the user's default and any remembered per-app choice; Enter or the countdown+ picks it, the user can still choose another. `type` skips the picker; `prefer` keeps it.+- `GET /ai-threads/run-prompt/status?job=` (1.0.240+) also answers `progress` (0..1), `step`,+ `steps` (ordered, each done|current|pending|failed), `ai` (the AI's name), `human` (a ready+ toast line), `terminal`, `succeeded`, `failed`, `error`, `surface`, `picked_by`. A dashboard+ narrates ONE live toast from `human` + `progress` and stops on `terminal`.+- INJECT INTO AN EXISTING CONVERSATION (1.0.252+): `POST /ai-threads/inject {prompt, tid|label|sid, type?, mode?}`.+ `mode:front` types into the open tab (any of the four; Antigravity via `type:"antigravity"`),+ `mode:back` runs the AI's own CLI headlessly on that session (`claude -p --resume`,+ `codex exec resume`, `kimi --print -r`; not while that conversation is open in the editor,+ and never for Antigravity), `auto` picks front when a tab holds it, else back when `sid` is+ given; when back is refused because the conversation is open (Codex's agent panel shows no+ id, 1.0.254+), auto opens it as its own tab by id and types there. `background:true`+ returns a job; `done` carries `answer`.+- `antigravity` is a target too (Hydrogen 1.0.234+, when the Google Antigravity extension is+ installed): it opens as an editor tab with a new conversation and the prompt is typed into+ its chat box and sent. It has no `tid`: the tab is the thread, and its side bar keeps its+ own conversation.++`POST /ai-threads/settings {ai_picker: "ask"|"never", default_ai: "claude"|"codex"|"kimi", show_kimi: bool}`+controls it; the AI threads panel's settings expose the first two. The picker offers Claude and+Codex; Kimi is hidden unless `show_kimi` is true (or it is the default), though `type: "kimi"`+always works for a caller that names it.++## Know where your prompt went: jobs, status polling, toasts (1.0.218)++Every `POST /ai-threads/run-prompt` call is a **job** from its first millisecond, before the+picker, the open, or the typing. The answer always carries `job` and `state`; poll+`GET /ai-threads/run-prompt/status?job=<job>` about once a second and stop at `terminal:true`.++```bash+# a dashboard's "Send to AI": hand the id back right away, run the rest detached+curl -sX POST "$BASE/ai-threads/run-prompt" -H 'content-type: application/json' \+ -d '{"new":true,"prompt":"open the symbol in kicad","tags":["app:kicad-bridge"],"background":true}'+# -> {"ok":true,"job":"7f2c...","state":"accepted","background":true}++curl -s "$BASE/ai-threads/run-prompt/status?job=7f2c..."+# -> {"ok":true,"state":"picking","terminal":false,"elapsed_ms":1200,"human":"waiting for the AI picker", ...}+# -> {"ok":true,"state":"picked","job":{"type":"codex","picked_by":"user",...},"human":"Codex picked"}+# -> {"ok":true,"state":"delivered","terminal":true,"job":{"result":{...the full call response...}}}+```++**A question is waiting (1.0.607+).** When a Claude thread asks with its AskUserQuestion tool,+the job goes to `needs_you` and carries `job.question`: `{questions: [{header, text, options:+[{label, description}], multi_select}], at_ms}`. Show it to your human or decide yourself, then+answer it (1.0.659+) with `POST /ai-threads/answer {job|sid|tid, option}`: `option` is a label+or a 0-based index, `options: [...]` for a multi-select, `other: "text"` for a typed answer, or+`answers: [{question: <index|header>, option|options|other}, ...]` when it asks several+questions. It clicks the options and "Submit answers" in that tab, and answers `ok` once the+question is gone (`answered` lists what was picked; a wrong label returns the real `options`).+With no job/sid/tid it answers the one question showing, and refuses when several threads ask+at once. Older builds: answer in the tab. When it is answered the job returns to `working`+and `question` is gone. A watcher that does not own the job reads+`GET /claude/conversation-state` `pending_questions` (session id to the same object). Before+1.0.607 a question never left `working`; four minutes with no change in `msgs` was the only hint.++The states, in order: `accepted` -> `picking` (the picker is up, counting down) -> `picked`+(`job.type` and `job.picked_by`: `user` | `default` | `caller`) -> `opening` -> `prefilled`+(Claude: prompt in the composer) or `tab_found` (Codex/Kimi; 1.0.258+: seen through the+extension's tab push within seconds, `adopted_empty_panel:true` when the AI's own plain+panel was already open, active and empty) -> `submitted` -> `working` ->+`needs_you` (a permission or question waits) | `done`. All four AIs report through hooks+once the panel's "Install hook" ran (1.0.255+: Claude and Codex `SessionStart` /+`UserPromptSubmit` / `Stop` / `Notification`; Kimi the same from its config.toml `[[hooks]]`;+Antigravity `PreInvocation` / `Stop` with its conversationId, no `needs_you`, and its backend+reads the hooks file only after an editor reload). Without a hook event within 30s a job ends+at `delivered`; an existing `tid` goes `delivering` -> `delivered` | `failed`.+ HOW A NEW CODEX/KIMI TAB IS TYPED INTO (1.0.280): one extension command opens it (no+ editor polling), the extension reveals it by position, the tab's own front webview is+ located by the editor's DOM join (never a pooled webview of another conversation; if it+ never mounts the job ends `inject_failed` with nothing typed anywhere), the prompt is typed+ once, and the AI's hooks confirm it (a failed typing check with a fresh SessionStart since+ the attempt counts as landed, never a retype). Steady state measured 2026-09-07: Codex on+ a parked ConfRoomROG picked 5s, tab 6s, sent 11s, working 13s, done 15s. Failure+terminals: `cancelled` (Escape in the picker), `rejected`, `open_failed`, `open_unconfirmed`,+`tab_not_found`, `inject_failed`, `submit_failed`, `failed`, `timeout`. Every status answer+carries `human`, a ready-made toast line for that phase ("Codex is working", "Claude Code+needs you"), and `_hints.states` repeats this glossary.++- **`background: true`** returns `{job, state: "accepted"}` at once. Without it the call+ blocks through the picker (5 s countdown, up to 45 s) and the open, then returns the same+ fields; `wait: true` additionally holds for the Claude turn to finish. It does NOT keep the+ person's view: delivery still brings the chat's tab to the front.+- **`focus: false`** keeps the person's view (1.0.741+; also on `POST /ai-threads/resume`).+ Delivery still has to show the chat for a moment (its chat box only loads when shown, and+ it takes real keystrokes), so Hydrogen notes the tab in front of every editor group first,+ delivers, then puts those tabs back, the person's own group last. The answer carries+ `focus_restored: {ok, revealed:[{tid, ok}], unchanged}`. Use it for anything unattended: a+ routine posting into its own thread, a scheduled check-in, a dashboard that should not+ interrupt.+- **Pass your own `job`** (any string) to correlate a retry, or leave it out and use the one+ you are given. `GET /ai-threads/run-prompt/status` with no `?job=` lists the 20 most+ recent jobs, newest first, for a dashboard that lost an id.+- **The shell toasts the pick**: "Sending to Codex" or "Sending to Claude Code (your default)"+ appears in Hydrogen the moment the countdown resolves, so the person sees where the+ prompt went even when your dashboard is on another screen. `POST /ai-threads/new` says+ `picked_by` in its answer and toasts "Opening Codex" the same way.+- An AI calling this from a thread should pass `type` (no picker) and, for anything longer+ than a one-liner, `background:true` then poll; `human` is what to say back to the person.++## See what is open++```bash+curl -s "$BASE/ai-threads" | jq '.groups[].threads[] | {tid, type, label, sid, instantiated}'+```++- `tid` is the CURRENT position (`g0t3`). It changes when tabs move, so do not store it.+- `sid` is the STABLE conversation id. Store this one.+- `instantiated: false` means the tab exists but VS Code has not materialized its webview+ yet. Text cannot be typed into it until it has been focused once.+- `summary.identity` reports how each row was identified, so you can tell a solid row from a+ guessed one.+- `tags` is the thread's durable tag list (see "Tag a thread" below). Filter on it to find+ the threads that belong to your app: `jq '.groups[].threads[] | select(.tags | index("dock"))'`.+- `mention` (claude rows with a live session) is the thread's cross-session @mention+ address, e.g. `"@project-d5"`: any other Claude session on the machine can message it by+ typing that name in its composer.++`GET /ai-threads/wait` long-polls and returns when the tree changes. Use it instead of+polling on a timer.++## Put text in a chat box, or send it++```bash+# stage it for the human to review, nothing is sent+curl -sX POST "$BASE/ai-threads/inject" -H 'content-type: application/json' \+ -d '{"tid":"g0t1","prompt":"summarize this file","submit":false}'++# send it, and confirm it actually landed in THAT conversation+curl -sX POST "$BASE/ai-threads/run-prompt" -H 'content-type: application/json' \+ -d '{"sid":"<stable id>","prompt":"what model are you?"}'+```++Two guarantees worth relying on:++- **`submit: false` really does not send.** Prefer it when a human should see the text first.+- **`run-prompt` confirms delivery by reading the AI's own message list**, not by assuming+ the keystrokes went somewhere. If it says it delivered, it checked.+- **`run-prompt {sid}` types into the OPEN tab that carries that sid.** When no open tab+ carries it (the conversation is closed, or its tab is not matched yet) it is rejected with+ "no open editor tab carries sid ...: nothing was delivered" (1.0.659+; older builds said+ "pass 'tid' or new: true"). For a conversation that is not open, use+ `POST /ai-threads/inject {sid, type, mode:"back"}`: its own CLI resumes it headlessly.+- **VS Code's single-tab mode** (`workbench.editor.showTabs: "single"`) hides tabs from the+ tab strip; since 1.0.659 the census reads those groups from adom-vscode's tab list instead+ (`summary.tabs_from: "extension"`), so tid, sid, focus and run-prompt work the same.++Typical latency is single-digit to low-double-digit milliseconds against a loaded thread.+A thread whose webview has never been materialized costs a few seconds the first time while+VS Code creates it, so if you care about that, `POST /ai-threads/focus {tid}` first.++## Rename a thread++`POST /ai-threads/rename {tid, name}` names a thread; the name is keyed to its stable id, so it+survives restarts. For a **Claude** thread (1.0.614+) it is also Claude's own title: Hydrogen+writes the same two lines Claude Code's `/rename` writes to the session transcript+(`custom-title`, `agent-name`), so the name shows on the Claude tab and in `claude --resume`.+An open tab reads its title only when it opens, so an idle thread's tab is closed and reopened at+once (`claude_title.reopened: true`); a thread that is answering is left alone+(`claude_title.busy: true`) and shows the name the next time it opens. `{reopen: false}` skips+the reopen. Codex and Kimi keep no title of their own, so their names live in Hydrogen only.++## Tag a thread, and find it again forever++Tags are durable strings keyed to the conversation's STABLE id, so they survive restart,+drag, rename, close, and reopen. This is how an external app (the dock) re-finds ITS+threads without guessing from titles.++```bash+# tag an existing thread (ai + sid, or its current tid, or an explicit "<ai>:<sid>" key)+curl -sX POST "$BASE/ai-threads/tag" -H 'content-type: application/json' \+ -d '{"ai":"claude","sid":"<sid>","add":["dock","app:kicad"]}'++# remove one+curl -sX POST "$BASE/ai-threads/tag" -H 'content-type: application/json' \+ -d '{"ai":"claude","sid":"<sid>","remove":["app:kicad"]}'++# the whole store+curl -s "$BASE/ai-threads/tags"+```++Tags come back on BOTH surfaces, open and closed:++```bash+curl -s "$BASE/ai-threads" | jq '.groups[].threads[] | {label, sid, tags}'+curl -s "$BASE/ai-threads/history?tag=app:adom/fusion-bridge" # server-side filter+```++**Bring the user back to their thread, with a visual cue.** `highlight: true` on focus+foregrounds the tab AND pulses its header for about a second, so the user sees WHY this+tab just came forward ("this existing thread is why nothing new opened"):++```bash+curl -sX POST "$BASE/ai-threads/focus" -H 'content-type: application/json' \+ -d '{"sid":"<sid>","highlight":true}'+```++A thread with no conversation yet cannot be tagged here (there is no id to key on); pass+`tags` to `/ai-threads/new` instead and they attach when the id appears.++## Route wiki issues into a thread++Associate a thread with a wiki repo and Hydrogen's global notification watcher queues new+issues on that thread's row (amber count; the user injects with one click, or opts into+auto-inject in Settings):++```bash+curl -sX POST "$BASE/ai-threads/repo-link" -H 'content-type: application/json' \+ -d '{"ai":"claude","sid":"<sid>","repo":"adom/adom-shotlog"}' # repo:"" clears+curl -s "$BASE/ai-threads/repo-links"+curl -s "$BASE/ai-threads/issue-queue" # or ?key=<ai>:<sid>+curl -sX POST "$BASE/ai-threads/issue-inject" -H 'content-type: application/json' \+ -d '{"ai":"claude","sid":"<sid>"}' # injects the next queued issue+```++One thread per repo (a new association moves it and reports `replaced`). Injected issues+are framed as bug reports to evaluate, never as instructions, and only an injected+issue's notification is marked read.++## Reopen a past conversation++```bash+curl -s "$BASE/ai-threads/history" | jq '.items[] | {ai, id, title, updated_ms}'+curl -sX POST "$BASE/ai-threads/resume" -H 'content-type: application/json' \+ -d '{"ai":"codex","id":"01a01bfb-a89d-75e0-9f17-01a163ba399b"}'+```++Add `"focus":false` to reopen it without changing which tab the person sees (the same+restore as run-prompt's).++History lists conversations on disk for all three AIs and EXCLUDES anything currently open,+so "in History" means "not open right now". Every AI reopens into a real editor tab.++## Close a tab++```bash+curl -sX POST "$BASE/ai-threads/close" -H 'content-type: application/json' -d '{"tid":"g0t1"}'+```++The conversation is not deleted. It moves to History and can be reopened.++## Rules that will save you time++1. **Store `sid`, never `tid`.** `tid` is a position and moves.+2. **Do not pick an AI on the user's behalf.** Omit `type` unless your feature is genuinely+ specific to one.+3. **Trust `ok`, and read the rest.** These endpoints verify against real state (a tab+ appeared, the composer holds exactly your text, the message reached the conversation) and+ report `ok: false` with a reason rather than claiming success.+4. **Do not drive the editor UI yourself.** Clicking tabs or typing into webviews from+ outside races Hydrogen's own sweep and will deliver to the wrong conversation. Everything+ you need is here.+5. **Do not hardcode the port.**++## Complete example: a dock icon opens a thread about its app++```javascript+const base = await fetch('/ports').then(r => r.json()).then(p => `http://127.0.0.1:${p.control}`);++async function openThreadFor(app) {+ const r = await fetch(`${base}/ai-threads/new`, {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ // No `type`: the user's default_ai decides. No prompt if you would rather they type.+ body: JSON.stringify({ prompt: `I just opened ${app.name}. Help me use it.` }),+ }).then(r => r.json());++ if (!r.ok) throw new Error(r.error || 'could not open a thread');+ return r; // {ok, type, from_default, result:{via, ...}}+}+```
skills/hydrogen-ai-threads/SKILL.mdadded+58@@ -0,0 +1,58 @@+---+name: hydrogen-ai-threads+description: >-+ The AI Threads panel in Hydrogen: the live tree of open AI conversations+ (Claude, Codex, Kimi), reorder, rename, tag, TUI threads, and the beta+ on-startup setting. Use when asked about ai threads, my ai conversations,+ which ai is running, rename a thread, or a tui thread.+---++# hydrogen-ai-threads: the AI Threads panel++AI Threads is a panel that shows every AI conversation open in the editor as one+live tree, grouped the way the editor groups its tabs. Each row shows the+conversation's AI (Claude, Codex, Kimi), its name, whether it is the foreground+tab, and a busy indicator while that AI is generating. Click a row to bring its+conversation forward.++**It is BETA and off by default.** The setting is+`Settings > Hydrogen > Behavior > Ai Threads On Startup`. While it is off, nothing+related to AI Threads runs: no background scans, no editor probing, nothing. You+can still open the panel once from **Add Panel** (the `+` in any pane's tab bar)+without touching the setting; doing so wakes the machinery for that session only.++## What you can do in the panel++- **Reorder**: drag a row; the row ghosts while the move lands, then settles. The+ order IS the editor's real tab order, so reordering here reorders the tabs.+ Pressing Escape mid-drag abandons the drag and restores everything.+- **Rename**: right-click (or the row's menu) > Rename. The name is written into+ the conversation itself, so it survives restarts and shows on the editor tab.+ Renaming also works on TUI threads.+- **Tags**: threads can carry tags (the dock uses `dock:<app>` to mark threads it+ opened). Tags attach as soon as a brand-new thread earns its identity.+- **New thread buttons**: the toolbar has a button per AI. The small caret beside+ each opens that AI **in a terminal instead**: a named editor tab ("Claude TUI",+ "Codex TUI", "Kimi TUI") running the AI's full CLI. TUI threads appear in the+ tree like any other thread; drive the conversation in the terminal itself.+- **History / resume**: past conversations that are not open right now can be+ reopened into a real editor tab.++## Relationship to the API++The panel is a plain HTTP client of Hydrogen's control API and has no privileged+access: everything above is `POST /ai-threads/*` under the hood, and any app,+dock card, or AI can call the same routes. See **hydrogen-ai-threads-api** for+the full surface (open, list, deliver a prompt with verification, resume, rename,+close, tags) and how to find the control port from inside or outside the+workspace.++## Troubleshooting++- **Panel missing after restart**: the on-startup setting is off (its default);+ turn it on, or open the panel from Add Panel for this session.+- **API returns "AI Threads is not active"**: same cause; while parked, read-only+ census calls refuse by design. A driving call (`/ai-threads/new`, a delivery)+ wakes the machinery for the session.+- **A terminal row shows a shell name** (bash/zsh): that tab is a plain terminal,+ not an AI TUI; the tree deliberately excludes it from thread rows.
skills/hydrogen-annotate/SKILL.mdadded+122@@ -0,0 +1,122 @@+---+name: hydrogen-annotate+version: 1.3.0+description: >-+ Hydrogen's Annotate tool: the Title Bar pencil, the tray's Annotate screen, or+ Super+Alt+A lets the user draw on a frozen picture of the screen (pen, arrow,+ box, snip) and puts a PNG on the clipboard for the AI thread. Use when asked+ to annotate, circle it, mark up the screen, snip a region, or about POST+ /annotate.+---++# Annotate: draw on the screen, paste it into your AI thread++## Desktop annotate on Linux (freeze-frame)++Wayland lets no app hook the mouse globally or lay a click-through layer over other apps, so+annotate on Linux works on a still picture:++- The **pencil** in the Title Bar, the tray's **Annotate screen**, or **Super+Alt+A** first+ captures the screen, then shows that picture full screen.+- A **plain drag** draws. **Enter** copies, **Esc** cancels (it works even if the page failed+ to load), **Ctrl+Z** undoes. The toolbar (Pen, Arrow, Box, Snip, colours, Auto/Multi, Undo,+ Clear, Done) sits at the top of the picture.+- What you annotate is the screen as it was when you pressed the key: open the menu or dialog+ first, then start annotate.+- Hydrogen captures the screen itself, never through Adom Bridge: on X11 from the root window+ (no prompt), on Wayland through the desktop portal's Screenshot. If the desktop asks first+ (GNOME asks once whether Hydrogen may take screenshots), that is the desktop's own dialog; the+ overlay opens only after the answer. A refusal, or a desktop with no screenshot portal, falls+ back to annotating inside Hydrogen's window (below). An overlay whose page does not come up+ within 8 seconds closes itself.++### The shortcut is a desktop keybinding+GNOME 46 (Ubuntu 24.04) has no global-shortcuts portal, so Hydrogen adds a custom keyboard+shortcut "Adom Hydrogen: Annotate" in the desktop's own settings (GNOME/Ubuntu: Settings >+Keyboard > Custom Shortcuts; Cinnamon: Keyboard > Shortcuts > Custom). It runs+`~/.local/share/adom-hydrogen/annotate-hotkey`, which asks Hydrogen to start. If Super+Alt+A is+already bound, Hydrogen leaves it alone and `GET /annotate/hotkey` says `taken: true` with+`taken_by`. Settings > Hydrogen > Annotate turns it off (removing the keybinding);+uninstalling Hydrogen removes it too. `method` is `gsettings` (GNOME family),+`gsettings-cinnamon`, or `none` (other desktops: use the pencil or the tray).+`POST /annotate/hotkey {"enabled": false}` turns it off from the API.++### The result and the clipboard+The capture is the area around the drawing with the drawing on it, saved in+`~/.config/hydrogen-desktop/annotations` and put on the clipboard. The clipboard copy is held+by a small helper (`adom-hydrogen --clipboard-hold`, its own `systemd-run --user` unit+`adom-hydrogen-clipboard-<ms>`), so it survives Hydrogen restarting; it lets go when another+app copies, or after 12 hours. It offers `image/png` plus the saved file (`text/uri-list`,+`x-special/gnome-copied-files`), because a WebKitGTK chat box (the Claude panel in Hydrogen)+receives a pasted picture only as a file. The card says "on your clipboard" only after Hydrogen+read the clipboard back and saw `image/png`; otherwise it says "Not copied" and the file is+still saved. Check from a desktop terminal: `GDK_BACKEND=x11 adom-hydrogen --clipboard-check`+(exit 0 = an image is there).++## Inside Hydrogen's window++With `scope: "window"` (or when no desktop capture is possible) annotate puts a canvas over the+whole Hydrogen window (the editor, the wiki, every panel; they are all under the same canvas),+with the same toolbar pup uses. The human draws, and the area around the drawing is captured+and written to the clipboard as a PNG. The point is the next step: paste it into an AI thread+and say "this one".++| Tool | What it does |+|---|---|+| Pen | Draw freehand. With Auto on, the capture fires the moment the mouse is released. |+| Arrow | Drag from tail to tip; the arrowhead lands where the mouse is released. |+| Box | Frame a region with a rectangle, corner to corner. |+| Text | Click where the note starts, type, press Enter (window scope only). |+| Snip | Capture exactly a region: drag a marquee, it is copied on release, no strokes. |++Colours: red, blue, yellow on the bar, more one click deeper. Two capture modes:++- **Auto** (default): one shot. Draw one thing, lift the mouse, and it is captured, copied,+ and annotate mode closes. This is the "red circle" case.+- **Multi**: compose. Draw several shapes; nothing is captured until Done. The colour+ advances after each shape so every shape is distinct.++The capture is the composited window with the drawing on it, cropped tight around everything+drawn. A toast confirms it: "Captured 640×320, on your clipboard. Paste it into an AI thread."++Keys: **Enter** = Done (capture and close), **Esc** = leave without capturing, **Ctrl+Z** = undo+the last shape. Undo and Clear are on the bar too.++## What the AI does with it++**You do not need annotate to see the screen.** To look at Hydrogen yourself, take a+screenshot: `POST /screenshot` on the control API (the `hydrogen-self-screenshot` skill).+Annotate exists for the **human** to point at something.++When the user pastes an annotated PNG into your thread, treat the drawing as the pointer: the+circled, boxed or arrowed thing is what they mean, and a text note is their comment. Read the+image before answering.++You can open the overlay for the human when that is the fastest way to get an answer ("circle+the part you mean"):++```bash+CTRL="$(cat ~/.adom/hydrogen-control-url)"+curl -s -X POST "$CTRL/annotate" -H 'Content-Type: application/json' -d '{"tool":"pen","mode":"auto"}'+```++`tool` is pen | arrow | box | text | snip (desktop freeze-frame takes pen, arrow, box, snip),+`mode` is auto | multi, `scope` is desktop (default) or window, `close: true` dismisses it. The+result lands on **their** clipboard, not in your context, so ask them to paste it. Do not open+it while they are typing or during a recording without saying so first; it covers the screen+until Esc.++## Where it lives++- The pencil: `src/lib/components/editor/EditorNav.svelte` (button next to the meters).+- The overlay and toolbar: `src/lib/components/AnnotateOverlay.svelte`, driven by+ `src/lib/stores/annotate.ts` (`startAnnotate(tool, mode)`, `closeAnnotate()`).+- The route: `POST /annotate` in `src-tauri/crates/hydrogen-control/src/lib.rs`.+- The capture itself is `POST /screenshot` with `target=full`, cropped in the overlay.+- Desktop mode: `src-tauri/crates/hydrogen-app/src/desktop_annotate.rs` (module `linux`: the+ freeze-frame, clipboard holder, keybinding), `src/lib/components/annotate/DesktopOverlay.svelte`,+ shared tools in `src/lib/annotate/draw.ts`.++Related: `hydrogen-self-screenshot` (the AI's own screenshots), `hydrogen-captions` (text+overlays the AI puts on screen for narration; not for marking things up), `hydrogen-pup`+(pup's annotate, the same toolbar in the browser window).
skills/hydrogen-api/SKILL.mdadded+827@@ -0,0 +1,827 @@+---+name: hydrogen-api+description: >-+ Reference for Hydrogen's control API on Linux: drive the workspace, Claude Code, VS Code,+ workspace tabs and setup steps over HTTP; GET /_manifest is the live catalog. Use when+ calling a Hydrogen endpoint, finding the control port, using the API Explorer, or+ checking which endpoints are destructive.+---++# Hydrogen Control API Reference++The control API is large and grows. This file quoted "~159 endpoints" in its body and+"~200" in its own frontmatter while the router carried **274**: two stale numbers that did+not even agree with each other, in the one document whose job is to be accurate about the+API. So it no longer quotes a count at all. Don't trust a static count or list in+this file to stay exhaustive — the API is **self-documenting**, with two live+sources of truth you should hit first:++| Source | What it gives you | Where |+|---|---|---|+| `GET /_manifest` | **THE complete catalog** — every registered route (`path`, `method`, `args`, `category`, `description`, `visibility`). Curated entries carry richer descriptions; the rest are auto-generated from the router (`scripts/gen-manifest.py`), so it never drifts. **Discover here first — don't guess paths.** | `hydrogen-control/src/lib.rs` `/_manifest` arm |+| **API Explorer window** | The human face of `/_manifest`: every endpoint grouped by category tab, with a runnable **Try** + Copy URL. Open from the Adom menu, or `POST /api-explorer/open`. | Adom menu ▸ API Explorer |+| **Workspace control** (`:47083`) | A SEPARATE server (`hydrogen-proxy`), and its ~30 routes are **NOT in `/_manifest`**: `/tabs`, `/tabs/find`, `/active-tab`, `/splits`, `/swaps`, `/moves`, `/nav`, `/window-mode`, `/caption`, `/recording`, `/screenshot`, `/audio`, `/sharing`, `/notification`. This is the surface the in-container AI reaches through `adom-cli`. Enumerating `/_manifest` alone will NOT show you these. | `hydrogen-proxy/src/lib.rs` |+| `GET /test/help` | The `/test/*` diagnostics (setup-steps state, cascade reset). **Gated behind `HD_TEST_API_ENABLED=1`**: 404 by default (expected, not a bug). | `hydrogen-control/src/lib.rs` `/test/help` arm |++On Linux, routes that do nothing here say so in their `/_manifest` description ("Not available+on Linux.").++## ⛔ Safety — the API enforces this, and tells you in-band++The API itself now labels, warns about, and gates dangerous endpoints (single source of+truth: `safety.rs` in hydrogen-control). Three tiers:++- **`catastrophic`**: irreversibly destroys real user state:+ `/setup/panel/(run-virgin-reset|wipe-keep-auth)`, `/config-reset`, `/claude/wipe-creds`,+ `*-delete`.+ **Headless calls (no browser Origin header — i.e. YOU) get HTTP 409 `confirmation_required`+ and NOTHING happens** until you re-call with `?confirm=1`. Only add `?confirm=1` when the+ user explicitly asked for exactly that action — never to make an error go away.+- **`destructive`** — kills/restarts/re-runs real state (recoverable but real):+ `/app/(restart|relaunch-frontend)`, `/reload-vscode`,+ `/container(-stop|-restart)`, `/workspace/apply-updates`, `/setup/(run-all|run-step|state|+ force-close|trigger|countdown)`, `/claude/tabs/close-all`, `/updater/install`.+ Never call these speculatively or in a sweep.+- **`disruptive`**: the user SEES it (a window opens, focus moves, typing lands in their+ real chat): `/hbw/open` (and `/hbw/close` to close one by label), `/api-explorer/open`,+ `/open-url`, `/open-in-profile`, `/window/foreground`, `/ai-cursor/*`, `/ui/toast`,+ `/claude/(trigger-auth|open-with-message|inject*|send|submit|new-chat-and-send|type-and-submit)`+ (the send/submit ones SPEND a real user turn). Run only when the user actually wants that+ action, and clean up after yourself.++How the API tells you:+- **Before calling:** every `GET /_manifest` entry carries `safety` + `safety_note`. Check+ them before you POST anything unfamiliar. Unlabeled = safe.+- **When you call:** responses from these endpoints include a `_safety` block. READ IT —+ it says exactly what you just did to the user's machine.+- **The 409 gate** is your last chance to stop; it is not an error to route around.++A safe GET/POST returns within a couple seconds with a 2xx or a clean 4xx `{ok:false,...}`.+If you must probe an endpoint you're unsure about, POST an empty `{}` body and treat a+graceful validation error as "it works" — a 500 or a hang is the bug.++**Base URL:** `http://127.0.0.1:<dynamic>`, the same loopback address from inside the+workspace (the workspace machine shares the host's network) and on the host. The port is+dynamic per launch; read the live URL from `~/.adom/hydrogen-control-url`: see "Finding the+Control Port" below.++## Finding the Control Port++The control API port is dynamic (default 47084, auto-resolves conflicts).++```bash+# From the workspace: Hydrogen rewrites this file every launch. USE THIS.+CTRL="$(cat ~/.adom/hydrogen-control-url)"; curl -sf "$CTRL/health"++# On the host: the live port map+cat ~/.config/hydrogen-desktop/ports.json++# No file access (remote tool, browser)? Probe the DISCOVERY responder: fixed candidate+# ports tried in order. Take the FIRST that answers with+# service == "hydrogen-desktop-discovery"; its control_url is the live control API:+for p in 47080 48080 49180 50280; do+ R=$(curl -sf --max-time 2 "http://127.0.0.1:$p/") && echo "$R" | grep -q hydrogen-desktop-discovery && break+done+```++⭐ **From the workspace, read `~/.adom/hydrogen-control-url`** (e.g. `http://127.0.0.1:<control>`) — a+file, NOT an env var (your non-interactive Bash shells don't source `.bashrc`/`profile.d`). Hydrogen+rewrites it with the live dynamic port every launch. This is the channel for the UI command bus,+the live ports map, Claude control, etc. — distinct from `adom-cli` (`ADOM_HYDROGEN_URL` → SSE),+which is unchanged for web-hydrogen parity.++## Calling gotchas (learned the hard way)++- **Never hardcode the port.** It's dynamic (47084 is only the default and it auto-resolves+ conflicts). Read `~/.adom/hydrogen-control-url` from the workspace, or `GET /ports`. Hardcoding+ 47084 is what makes tools show Hydrogen as "down" when it's actually up on another port.+- **Calling from a REMOTE container (hc/cloud)? Use `adom-bridge hd_api`,** the relay's+ pass-through verb: `hd_api {"method":"POST","path":"/...","body":{...}}`. It auto-discovers+ the port; never shell curl through the relay (quoting gets mangled). Long-blocking calls+ (typed injection) can outlive the relay timeout: the work still completes on Hydrogen's side, so+ verify state instead of re-firing.+ This reaches this computer while Adom Bridge runs here (Hydrogen installs and starts it when+ a Linux build is published for the user's account).+- **Getting files OUT:** `POST /screenshot {"b64":true}` returns the PNG inline as `dataUrl` (the+ file itself is saved on the host under `~/.config/hydrogen-desktop/shots/`). To hand a+ workspace file to the host, copy it to `/mnt/host/tmp/` (the host's `/tmp`).+- **Confirm it's really the control API, not the SPA.** In dev, the frontend file server+ answers 200 with HTML for *any* path — so a bare 200 doesn't prove you hit Hydrogen's API. Check+ `GET /health` returns JSON with `service:"hydrogen-desktop-control"`.+- **Driving Hydrogen from a page Hydrogen serves? Use relative fetches, not Tauri IPC.** Tauri `invoke`+ is unavailable on remote http origins; a same-origin `fetch('/ports')` / `fetch('/_manifest')`+ works and sidesteps port discovery entirely.+- **No CDP on Linux.** WebKitGTK has no Chrome DevTools Protocol; nothing listens on the `cdp`+ port. `/eval`, `/eval-in`, `/cdp-eval` run over Hydrogen's frame bus (see **hydrogen-eval**);+ `/targets`, `/iframe-eval` and `/webview/frames` return nothing useful here.++## Health & Status++| Method | Path | Description |+|---|---|---|+| GET | `/health` | Hydrogen alive check — returns `{ok, port, service}` |+| GET | `/buildinfo` | Running build git SHA + build metadata (the only trustworthy "did my build ship?" check) |+| GET | `/ports` | The 4 editable PortConfig ports (proxy, control, cdp, code_server) |+| GET | `/ports/all` | LIVE full port map: host listeners + every listener inside the workspace machine |++## Driving Hydrogen's UI (command bus)++Open/close/toggle any Hydrogen menu, dialog, or panel. See the `hydrogen-ui` skill.++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/ui/actions` | — | List every drivable UI action `{id,label,description,group}` (+ `_hints`) |+| POST | `/ui/invoke` | `{"id":"ports.open"}` | Run a UI action; returns `{ok,value}` only after the frontend ran it |+| GET | `/auth-token` | Hydrogen session token |+| GET | `/setup-status` | Setup snapshot (legacy `container`/`image`/`volume` fields answered from the machine) |+| GET | `/diagnostics/all` | Run all diagnostic checks |+| GET | `/diagnostics/{name}` | Run a single diagnostic check |++## Workspace Management++These endpoints manage the workspace: the `Adom-Workspace` systemd-nspawn machine. The+paths keep their historical `container` spelling; there is no container.++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/container-status` | | Runtime present, machine present and running |+| GET | `/container-stats` | — | CPU, memory, disk usage |+| POST | `/container-restart`, `/container-stop` | | Restart / stop the machine (your own shell dies with it) |+| POST | `/workspace/exec` | `{"command":"..."}` | **The** way to run a command in the workspace as `adom` |+| POST | `/container-exec` | `{"command":"..."}` | Older alias path for the same job |+| POST | `/container/restart` | — | Alias for `/container-restart` |+| POST | `/direct/command` | `{...}` | Direct-connect command channel into the workspace |+| GET | `/workspace/health` | | Deep health: machine, code-server, host reachability |+| GET | `/wsl/status` | | Name kept for compatibility: machine present and running, code-server reachable |++`/container-delete`, `/image-delete`, `/volume-delete`, `/container-pull-image` answer that there+is nothing to do on Linux; a wipe is the Setup panel's Virgin Reset.++## WebView & VS Code++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/eval` | `{"js":"..."}` | JS eval in main Hydrogen webview |+| POST | `/eval-in` | `{"target":"workbench","js":"..."}` | JS in any surface (frame bus on Linux) |+| POST | `/click` | `{"selector":"..."}` | Click an element of the shell page by selector |+| POST | `/query` | `{"selector":"..."}` | Query DOM elements |+| POST | `/reload-vscode` | — | Reload the VS Code iframe |+| POST | `/vscode/hide-activity-items` | — | Hide activity-bar items (persisted, overflow-proof) |+| GET/POST | `/devtools` | | Opens the WebKit Web Inspector (also Ctrl+Shift+I) |++### AI cursor (visible cursor for demos / clicking)++Distinct from `/click` and `/mouse-click` — this renders a **visible** AI cursor,+glides it, and can click. Use for demos or when the user should see where the AI clicks.++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/ai-cursor/move` | `{"x":N,"y":N}` | Move (glide) the visible AI cursor to coordinates |+| POST | `/ai-cursor/click` | `{"x":N,"y":N}` | Move the visible AI cursor there + click |+| POST | `/ai-cursor/hide` | — | Hide the visible AI cursor |++On Linux `/mouse-click` does not move the pointer or click, and `/ai-cursor/click` shows the+cursor but its click is sent over CDP, so it does not land: click with `/click {selector}` or an+`/eval-in` that calls `el.click()`.++### Screenshot primitives++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/capture/viewport` | — | Capture the Hydrogen webview viewport (PNG) |+| POST | `/shot` | `{...}` | Screenshot primitive (see **hydrogen-self-screenshot** for the full workflow) |++### Port hints++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/adom-port-hints` | — | Read the workspace port-hints map |+| POST | `/adom-port-hints` | `{...}` | Write/merge the workspace port-hints map |++## Claude Code++### Status / auth state (GET)++| Method | Path | Description |+|---|---|---|+| GET | `/claude/status` | Install state, auth, active session, version |+| GET | `/claude/auth-check` | Deep auth check — file exists, token, expiry |+| GET | `/claude/auth-status` | Auth-status detail |+| GET | `/claude/auth-page-state` | Which auth screen the panel shows: `continue-in-browser` \| `subscription-button` \| `chat`; returns `oauth_url` + `at_browser_auth_gate` |+| GET | `/claude/detect-auth-failure` | Scan webview contexts for auth button/errors |+| GET | `/claude/sessions` | List active Claude sessions |++### Auth actions (POST)++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/claude/find-auth-button` | — | Find + highlight the sign-in button WITHOUT clicking (validation) |+| POST | `/claude/start-auth` | — | Find + highlight + CLICK the "Claude.ai Subscription" button to begin OAuth |+| POST | `/claude/trigger-auth` | — | Alias for start-auth |+| POST | `/claude/detect-state` | — | Detect current auth/panel state |+| POST | `/claude/authorize-in-browser` | | Not available on Linux: finish the claude.ai consent in the browser yourself. The `/claude/uia-*` routes are not available either. |+| POST | `/claude/authorize-tab-enter` | — | Approve the Adom OAuth tab via Enter (branded picker flow) |+| POST | `/claude/inject-creds` | — | Push host backup credentials into the workspace |+| POST | `/claude/wipe-creds` | `{"backup":B}` | Wipe Claude credentials (destructive); `backup:false` keeps the host backup so reinject can restore |++### Panel / conversation control (POST unless noted)++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/claude/open` | — | Open Claude Code panel (`claude-vscode.editor.open`) |+| POST | `/claude/ensure-open` | — | Ensure the panel is open (strict readiness; recovery if not rendered) |+| POST | `/claude/open-with-message` | `{"message":"..."}` | Open + pre-fill message |+| POST | `/claude/focus` | — | Focus Claude panel |+| POST | `/claude/new-conversation` | — | Start a fresh conversation (shows sign-in panel when unauthenticated) |+| POST | `/claude/new-chat-and-send` | `{"text":"...","typed":B,"submit":B,"delay_ms":N}` | Open fresh conversation, wait for compose box, type + (default) submit |+| POST | `/claude/submit` | — | Find + click send button |+| POST | `/claude/send` | `{"message":"..."}` | Send message to Claude |+| POST | `/claude/inject` | `{"message":"..."}` | Inject text into the compose box |+| POST | `/claude/inject-message` | `{"message":"..."}` | Inject into conversation |+| POST | `/claude/type-and-submit` | `{"message":"...","delay_ms":N}` | Type char-by-char (human-paced) + submit |+| POST | `/claude/remote-control` | `{"name":"..."}` | Turn on Claude Code Remote Control (submits `/remote-control` slash command) |+| POST | `/claude/highlight-open-button` | `{"duration":N}` | Glow animation on Claude button |+| POST | `/claude/clear-open-highlight` | — | Clear the open-button highlight |++## OAuth & Auth++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/claude-auth` | — | Full PKCE OAuth flow — opens browser, sets up callback |+| GET | `/oauth/callback` | — | OAuth callback handler (receives auth code) |+| POST | `/auth/proxy` | varies | Proxy auth requests to carbon.adom.inc |+| POST | `/open-url` | `{"url":"..."}` | Open URL (triggers browser picker) |+| POST | `/start-oauth-proxy` | `{"port":N}` | Start OAuth callback proxy on a port |+| GET | `/browser-profiles` | — | List browsers + profiles with avatars |+| POST | `/open-in-profile` | `{"url":"...","browser":"...","profileDir":"..."}` | Open URL in specific browser profile |+| POST | `/browser-picker/opened` | `{...}` | Frontend reports the browser picker was opened |+| GET | `/browser-picker/last-open` | — | Last browser-picker open event |++Because the network is shared, an OAuth callback on `localhost:<port>` in the workspace is+reachable from the host browser directly.++## Setup Steps & Setup Panel++### State / trigger / step control++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/setup/state` | — | Get current setup state (`never-run` \| `in-progress` \| `complete`) |+| POST | `/setup/state` | `{"state":"..."}` | Set setup state |+| POST | `/setup/step/<id>` | `{"continue_after":B}` | ⭐ Run one step by id (forces panel visible first); `continue_after:true` runs this step + every step after it |+| POST | `/setup/force-close` | — | Force-close setup panel |+| POST | `/setup/countdown` | `{"seconds":N,"message":"..."}` | Show countdown overlay |+| GET | `/setup/trigger` | — | Read trigger file |+| DELETE | `/setup/trigger` | — | Delete trigger file |+| POST | `/config-reset` | — | Reset Hydrogen config |++> To run steps: use `POST /setup/step/<id>` or relaunch Hydrogen to auto-run the cascade.++### Setup panel control++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/setup/panel/show` | — | Force the setup panel visible |+| POST | `/setup/panel/hide` | — | Hide the setup panel |+| POST | `/setup/panel/show-virgin-reset` | — | Show panel + expand the Virgin Reset section |+| POST | `/setup/panel/virgin/show` | — | Show the Virgin Reset section only |+| POST | `/setup/panel/virgin/hide` | — | Hide the Virgin Reset section |+| POST | `/setup/panel/set-virgin-options` | `{"options":{...}}` | Set the virgin-reset checkboxes |+| POST | `/setup/panel/run-virgin-reset` | — | ⭐ The **ONLY** allowed virgin-reset trigger — UI-visible by construction (shows panel + checkboxes + progress before deleting anything) |+| POST | `/setup/panel/wipe-keep-auth` | — | Synchronous wipe that KEEPS Adom + Claude tokens |+| POST | `/setup/screenshot-mode` | `{"enabled":B}` | Toggle per-step screenshot capture (default OFF) |+| GET | `/setup/screenshot-mode` | — | Whether per-step screenshot mode is on |++## Workspace Tabs++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/workspace/tabs` | — | List all workspace tabs |+| GET | `/workspace/tabs/find?name=X` | — | Find tab by name (404 if not found) |+| POST | `/workspace/tabs` | `{tab spec}` | Add a new tab |+| POST | `/workspace/tabs/activate` | `{tabId}` or `{name}` or `{panelId, tabIndex}` | Bring one tab to the front |+| POST | `/workspace/tabs/remove` | `{tabId}` or `{name}` or `{panelId, tabIndex}` | Close one tab (`/workspace/tabs/close` is the same) |+| POST | `/workspace/tabs/move` | `{tabId or name, targetPanelId}` | Move a tab to another pane |+| POST | `/workspace/swap` | `{panelA, panelB}` | Swap two panes |+| POST | `/workspace/split` | `{panelId, direction, position?, ratio?, panelType?, displayName?, initialState?}` | Split a pane; answers the new `panelId` |+| POST | `/workspace/resize` | `{splitId, ratio}` | Set a split's proportion (0.1 to 0.9) |+| POST | `/workspace/close-panel` | `{panelId}` | Close a pane and its tabs |+| GET | `/workspace/get` | (none) | The whole live layout tree: panes, splits (id and ratio), tabs |++The whole layout API is on the desktop control port (the same on Windows and Linux): drive it with+`curl` from the host or through Adom Bridge, no workspace needed. Each route is the twin of an+`adom-cli hydrogen workspace` verb (`get`, `active-tab`, `remove-tab`, `move-tab`, `swap`, `split`,+`resize`, `close-panel`) on the same live tree, and every answer's `_hints.adom_cli` names it.++**The VS Code pane holds the user's AI threads** (John 2026-11-15). A call that covers, hides,+replaces or removes it (closing its pane, removing or moving the VS Code tab, moving or activating+another tab in front of it, adding a tab to its pane by name) is allowed, but its answer carries+`_hints.vscode`: a strong warning and, in `undo`, the exact call that puts VS Code back. Read it,+and undo unless you had a very good reason. Hydrogen's own placement never does this: a new tab+with no pane named (the dock, `webview open-or-refresh`, `POST /workspace/tabs` without+`panelId`) opens in another pane, or, when VS Code's pane is the only one, in a new right-hand+split at half the width.++Example, from the host:++```bash+C=http://127.0.0.1:47084+curl -s $C/workspace/tabs # tabs with tabId, panelId, name+curl -s -X POST $C/workspace/split -d '{"panelId":"desktop-pane-left","direction":"horizontal","panelType":"adom/a1b2c3d4-0031-4000-a000-000000000031","displayName":"Notes","initialState":{"url":"about:blank"}}'+curl -s -X POST $C/workspace/tabs/move -d '{"name":"Wiki","targetPanelId":"<new pane id>"}'+curl -s -X POST $C/workspace/tabs/activate -d '{"name":"Wiki"}'+curl -s -X POST $C/workspace/tabs/remove -d '{"name":"Notes"}'+curl -s -X POST $C/workspace/close-panel -d '{"panelId":"<new pane id>"}'+```++## System++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/system/reboot-state` | | Always null on Linux: Hydrogen setup never needs a reboot here |+| POST | `/system/reboot` | | Not available on Linux: Hydrogen does not reboot this computer |++`/recording/native/*` answers that native recording is not available on Linux.++## App lifecycle & window++| Method | Path | Body | Description |+|---|---|---|---|+| POST | `/app/restart` | — | Restart the Hydrogen app (kills + respawns the binary) |+| POST | `/app/relaunch-frontend` | — | Relaunch the Hydrogen GUI (kill+respawn) while it is responsive |+| POST | `/window/foreground` | — | Bring the Hydrogen window to the foreground (unminimize + focus) |++The desktop's window manager may refuse to raise the window for `/window/foreground`.++## Diagnostics (`/test/*`)++Setup-cascade and state diagnostics. **Gated behind `HD_TEST_API_ENABLED=1`** (return 404 /+"test API disabled" otherwise). `GET /test/help` self-lists the whole cluster.++| Method | Path | Body | Description |+|---|---|---|---|+| GET | `/test/help` | — | Self-lists every `/test/*` endpoint |+| GET | `/test/window-tree` | | Not available on Linux |+| POST | `/test/click-uia` | | Not available on Linux |+| GET | `/test/setup-steps` | — | Raw setup-steps.json + derived summary (alias: `/test/install-steps`) |+| POST | `/test/reset-cascade` | — | Delete install-steps.json + emit setup-reset event |+| GET | `/test/probe-dialogs` | | Not available on Linux |++## Key Patterns++### container-exec+Runs as user `adom` inside the workspace. Use full paths (`/home/adom/`+not `~/`). Tilde doesn't expand through the exec chain.++```+POST /container-exec {"command":"ls /home/adom/project"}+```++### Re-run a setup step after completion+The trigger file poller STOPS when all steps are done. Re-run one step by id (or relaunch+Hydrogen to auto-run the cascade):+```+POST /setup/step/<id>+```++## Complete route index++> The index below lists the routes every platform's router carries. On Linux some of them answer+> that they are not available here; their `/_manifest` description says so.++<!-- BEGIN GENERATED ROUTE INDEX -->++Every route Hydrogen for Linux serves, 332 across 23 categories, grouped the way the+API Explorer groups them. Routes that do nothing on Linux are left out, as they are from+`/_manifest` and the API Explorer here. Generated from the same table `/_manifest` serves, so it+cannot drift from the code; `scripts/check-manifest-fresh.sh` fails the build if it does.++`/_manifest` remains the richer source at runtime: it carries each route's args, its+description, and a `safety` flag (`destructive` / `disruptive`) that this flat index does not.+**Read a route's safety from `/_manifest` before calling it, not from this list.**++**AI Accounts** (14)++- `POST /agents/apikey`+- `GET /agents/bar`+- `GET /agents/catalog`+- `POST /agents/install`+- `POST /agents/login`+- `POST /agents/login-input`+- `POST /agents/login-stop`+- `GET /agents/login-url`+- `POST /agents/logout`+- `POST /agents/present`+- `POST /agents/setup-done`+- `POST /agents/setup-reset`+- `GET /agents/setup-state`+- `GET /agents/status`++**AI Threads** (39)++- `GET /ai-threads`+- `POST /ai-threads/activate`+- `POST /ai-threads/answer`+- `POST /ai-threads/close`+- `GET /ai-threads/dom-debug`+- `POST /ai-threads/dom-event`+- `GET /ai-threads/dom-events`+- `POST /ai-threads/focus`+- `GET /ai-threads/history`+- `POST /ai-threads/hook-event`+- `POST /ai-threads/inject`+- `POST /ai-threads/inspect`+- `POST /ai-threads/install`+- `GET /ai-threads/install/log`+- `POST /ai-threads/issue-inject`+- `GET /ai-threads/issue-queue`+- `GET /ai-threads/names`+- `POST /ai-threads/new`+- `POST /ai-threads/new-tui`+- `POST /ai-threads/pick`+- `GET /ai-threads/prompts`+- `POST /ai-threads/rename`+- `POST /ai-threads/reorder`+- `POST /ai-threads/repo-link`+- `GET /ai-threads/repo-links`+- `POST /ai-threads/resume`+- `POST /ai-threads/run-prompt`+- `GET /ai-threads/run-prompt/status`+- `GET /ai-threads/settings`+- `POST /ai-threads/settings`+- `GET /ai-threads/tabs`+- `POST /ai-threads/tag`+- `GET /ai-threads/tags`+- `GET /ai-threads/tools`+- `POST /ai-threads/uninstall`+- `GET /ai-threads/wait`+- `POST /ai-threads/walk`+- `GET /ai-threads/walk-report`+- `GET /ai-threads/wiki-repos`++**Adom Bridge** (19)++- `GET /ab/direct-api`+- `GET /ab/discovery-file`+- `GET /ab/embedded`+- `GET /ab/health`+- `GET /ab/liveness-beacon`+- `GET /ab/permissions`+- `POST /ab/permissions/request`+- `POST /ab/permissions/revoke`+- `GET /ab/process`+- `GET /ab/relay`+- `GET /ab/settings`+- `POST /ab/settings`+- `POST /ab/show`+- `POST /ab/toast-ack`+- `POST /ab/verb`+- `GET /ab/workspace-direct`+- `POST /direct/command`+- `GET /direct/health`+- `GET /direct/status`++**Auth & User** (7)++- `GET /auth-token`+- `GET /auth/browser-status`+- `GET /auth/proxy`+- `POST /auth/proxy`+- `DELETE /user/avatar`+- `POST /user/avatar`+- `POST /user/refresh`++**Browser & Open** (11)++- `GET /browser-picker/last-open`+- `POST /browser-picker/opened`+- `DELETE /browser-picker/prefs`+- `GET /browser-picker/prefs`+- `PUT /browser-picker/prefs`+- `GET /browser-profiles`+- `POST /open-in-profile`+- `POST /open-url`+- `GET /webview-can-embed`+- `GET /webview-proxy`+- `GET /wiki-proxy`++**Claude** (46)++- `POST /claude-auth`+- `GET /claude/auth-check`+- `GET /claude/auth-page-state`+- `GET /claude/auth-status`+- `POST /claude/authorize-tab-enter`+- `POST /claude/clear-open-highlight`+- `POST /claude/cli-auth/code`+- `POST /claude/cli-auth/start`+- `GET /claude/contexts`+- `GET /claude/conversation-state`+- `GET /claude/conversations`+- `POST /claude/cross-eval`+- `GET /claude/detect-auth-failure`+- `POST /claude/detect-state`+- `POST /claude/ensure-open`+- `POST /claude/find-auth-button`+- `POST /claude/focus`+- `POST /claude/highlight-open-button`+- `POST /claude/inject`+- `POST /claude/inject-creds`+- `POST /claude/inject-message`+- `POST /claude/new-chat-and-send`+- `POST /claude/new-conversation`+- `POST /claude/open`+- `POST /claude/open-with-message`+- `POST /claude/remote-control`+- `POST /claude/sample-prompt`+- `GET /claude/sample-prompts`+- `POST /claude/sample-prompts/refresh`+- `POST /claude/send`+- `GET /claude/sessions`+- `POST /claude/start-auth`+- `GET /claude/status`+- `POST /claude/submit`+- `GET /claude/tabs`+- `POST /claude/tabs/activate`+- `POST /claude/tabs/close-all`+- `POST /claude/tabs/close-empty-groups`+- `POST /claude/tabs/close-untitled`+- `POST /claude/tabs/merge-groups`+- `POST /claude/trigger-auth`+- `POST /claude/type-and-submit`+- `POST /claude/wipe-creds`+- `POST /config-reset`+- `GET /oauth/callback`+- `POST /start-oauth-proxy`++**Container / Docker (legacy)** (15)++- `POST /container-delete`+- `POST /container-exec`+- `POST /container-pull-image`+- `POST /container-restart`+- `POST /container-start`+- `GET /container-stats`+- `GET /container-status`+- `POST /container-stop`+- `GET /container/disk`+- `GET /container/env`+- `GET /container/logs`+- `GET /container/ports`+- `POST /container/restart`+- `POST /image-delete`+- `POST /volume-delete`++**Dock** (6)++- `GET /dock/apps`+- `POST /dock/close`+- `POST /dock/launch`+- `POST /dock/refresh`+- `POST /dock/reset`+- `POST /dock/result`++**Editor State Machine (ESM)** (4)++- `POST /editor/audit-prompt`+- `POST /editor/bars`+- `POST /editor/normalize`+- `GET /editor/state`++**Eval & Automation** (17)++- `POST /ai-cursor/click`+- `POST /ai-cursor/hide`+- `POST /ai-cursor/move`+- `POST /cdp-eval`+- `POST /click`+- `GET /devtools`+- `POST /devtools`+- `POST /eval`+- `POST /eval-in`+- `POST /files/inject`+- `POST /iframe-eval`+- `POST /mouse-click`+- `POST /query`+- `POST /reload-vscode`+- `GET /targets`+- `POST /vscode/command`+- `POST /vscode/hide-activity-items`++**Health & Build** (17)++- `GET /_manifest`+- `POST /app/relaunch-frontend`+- `POST /app/restart`+- `GET /buildinfo`+- `GET /cdp-info`+- `GET /console`+- `GET /diagnostics`+- `GET /diagnostics/all`+- `GET /doctor`+- `POST /doctor`+- `GET /health`+- `GET /logs/tail`+- `GET /ports`+- `GET /ports/all`+- `POST /ports/check`+- `POST /ports/set`+- `POST /report/problem`++**Hydrogen Browser Window** (11)++- `GET /hbw/chrome`+- `POST /hbw/chrome-toggle`+- `POST /hbw/close`+- `POST /hbw/nav`+- `POST /hbw/open`+- `GET /hbw/speed`+- `POST /hbw/speed`+- `GET /hbw/state`+- `GET /hbw/tip`+- `GET /hbw/tip-state`+- `POST /hbw/tooltip`++**Other** (2)++- `POST /proxy/restart`+- `POST /telemetry/webview-gpu`++**Permissions** (3)++- `POST /permission/dismiss`+- `POST /permission/request`+- `POST /permission/resolve`++**Screenshots & Recording** (13)++- `POST /annotate`+- `GET /annotate/hotkey`+- `POST /annotate/hotkey`+- `GET /capture/availability`+- `GET /capture/viewport`+- `GET /recording/native/capabilities`+- `POST /recording/native/reset`+- `GET /recording/native/sources`+- `POST /recording/native/start`+- `GET /recording/native/status`+- `POST /recording/native/stop`+- `POST /screenshot`+- `POST /shot`++**Settings** (2)++- `GET /settings/external-changes`+- `POST /settings/rebroadcast`++**Setup Cascade** (25)++- `GET /setup-status`+- `POST /setup/countdown`+- `GET /setup/flags`+- `POST /setup/flags`+- `POST /setup/force-close`+- `POST /setup/panel/hide`+- `POST /setup/panel/run-virgin-reset`+- `POST /setup/panel/set-virgin-options`+- `POST /setup/panel/show`+- `POST /setup/panel/show-virgin-reset`+- `POST /setup/panel/virgin/hide`+- `POST /setup/panel/virgin/show`+- `POST /setup/panel/wipe-keep-auth`+- `POST /setup/run-all`+- `POST /setup/run-step`+- `GET /setup/screenshot-mode`+- `POST /setup/screenshot-mode`+- `GET /setup/state`+- `POST /setup/state`+- `POST /setup/step`+- `DELETE /setup/trigger`+- `GET /setup/trigger`+- `POST /setup/virgin-reset`+- `POST /virgin-reset`+- `GET /virgin-reset-progress`++**System** (6)++- `GET /adom-port-hints`+- `POST /adom-port-hints`+- `GET /gpu`+- `POST /gpu`+- `GET /system/nonce`+- `GET /system/reboot-state`++**Test & Dev** (10)++- `POST /debug/show-auth-caption`+- `POST /debug/zorder-probe`+- `POST /dev/emit-event`+- `POST /test/dump-state`+- `POST /test/focus`+- `GET /test/help`+- `GET /test/install-steps`+- `POST /test/reset-cascade`+- `POST /test/screenshot-hd-window`+- `GET /test/setup-steps`++**UI & Windows** (23)++- `POST /api-explorer/open`+- `POST /demo/run`+- `GET /dock-launch.html`+- `GET /favicon.ico`+- `GET /orbital-loader.html`+- `POST /panel-webview/fullscreen`+- `GET /panes/memory`+- `POST /panes/reload-errors`+- `POST /ui/_bus-pong`+- `POST /ui/_result`+- `POST /ui/_sync`+- `GET /ui/actions`+- `POST /ui/invoke`+- `POST /ui/toast`+- `POST /ui/toast-ack`+- `GET /webview/frames`+- `POST /webview/link-intercepted`+- `GET /webview/port-check`+- `GET /welcome.html`+- `GET /widget-launch.html`+- `POST /window/close`+- `POST /window/foreground`+- `POST /window/show`++**Wake & Repair** (5)++- `POST /wake/config`+- `POST /wake/preview`+- `POST /wake/preview/hide`+- `POST /wake/simulate`+- `GET /wake/status`++**Widgets** (8)++- `GET /widgets`+- `POST /widgets/card`+- `POST /widgets/close`+- `POST /widgets/menu`+- `POST /widgets/navigate`+- `POST /widgets/open`+- `POST /widgets/refresh`+- `GET /widgets/status`++**Workspace & Updates** (29)++- `POST /migration/approved`+- `POST /migration/dismissed`+- `POST /updater/check`+- `POST /updater/install`+- `POST /updater/show-banner`+- `GET /updater/status`+- `POST /workspace/apply-updates`+- `POST /workspace/check-updates`+- `POST /workspace/exec`+- `GET /workspace/health`+- `POST /workspace/migration/approve`+- `POST /workspace/migration/decline`+- `GET /workspace/stats`+- `GET /workspace/tabs`+- `POST /workspace/tabs`+- `GET /workspace/tabs/`+- `POST /workspace/tabs/`+- `GET /workspace/tabs/find`+- `POST /workspace/vscode-settings`+- `POST /workspaces/apply`+- `GET /workspaces/benches`+- `POST /workspaces/demo`+- `POST /workspaces/menu`+- `POST /workspaces/offer`+- `POST /workspaces/refresh`+- `POST /workspaces/reset`+- `POST /workspaces/save`+- `GET /workspaces/status`+- `POST /workspaces/unload`++**Workspace control** (~30 routes, a SEPARATE server on the proxy port, absent from `/_manifest`)++Reached at `/api/workspaces/editor/<owner>/<repo>/current/...`, which the handler strips+before matching. A bare `GET /tabs` on the proxy 404s; that is correct, not a fault.++- `/tabs`+- `/tabs/find`+- `/tabs/alert`+- `/active-tab`+- `/splits`+- `/swaps`+- `/moves`+- `/nav`+- `/reload`+- `/window-mode`+- `/caption`+- `/recording`+- `/screenshot`+- `/audio`+- `/sharing`+- `/notification`+- `/probe`++<!-- END GENERATED ROUTE INDEX -->
skills/hydrogen-bridges/SKILL.mdadded+310@@ -0,0 +1,310 @@+---+name: hydrogen-bridges+description: >-+ Bridges from a Linux Hydrogen workspace: the KiCad, Fusion 360 and Puppeteer+ bridges and the wiki bridge catalog, all served by Adom Bridge on a desktop,+ how to tell which machine has them, and bridge status. Use when asked about+ bridges, bridge status, install a bridge, or drive KiCad, Fusion or pup.+---++# Hydrogen bridges (Linux)++Bridges are small local servers that Adom Bridge (ab) runs on a desktop machine: `kicad_*`,+`fusion_*`, `pup_*` and the catalog bridges. The workspace reaches them with the+`adom-bridge <verb>` CLI through the relay at `ws://127.0.0.1:8765`.++**Hydrogen for Linux installs and runs ab when a Linux build is published for the user's account**+(see **hydrogen-embedded-bridge**). So on this desktop:++- With no ab running here (none published for the account yet), bridge verbs reach only the user's OTHER machines on the Adom mesh+ (`adom-bridge --ai-thread "<thread>" targets`, then `--target <name>`). For KiCad or Fusion+ on the user's Windows PC, that is the normal route. Never guess which machine: ask.+- With ab running here, bridges that have a Linux build+ run locally; bridges without a Linux build are listed but answer `unsupported_on_this_os`. Fusion 360+ has no Linux build.++The examples below leave out `--ai-thread` and `--target`; add them as above.++---++## Bridge Architecture++Adom Bridge launches bridge processes **on demand** on its machine. This is an **extensible**+ecosystem, not a fixed list: new bridges ship via the wiki catalog (see+"Extensible bridge catalog" below). The core/first-party bridges:++| Bridge | Display name | Port (default) | Target app | Description |+|--------|-------------|------|------------|-------------|+| `kicad-bridge` | KiCad Bridge | 8771 | KiCad | Control KiCad PCB editor from Adom containers |+| `fusion-bridge` | Fusion 360 Bridge | 8773 | Fusion 360 | Control Fusion 360 CAD/CAM and EAGLE PCB |+| `puppeteer-bridge` | Puppeteer Bridge | 8851 | Chrome for Testing | Chrome automation, screenshots, and recording |++**Bridge ports have conventional defaults** (KiCad **8771**, Fusion **8773**, Pup **8851**), but adom-bridge registers the **live** port at bridge launch and may pick a different one if a default is taken. To find the actual live port, run `adom-bridge status` and look at `desktop.apps.<bridge>.bridgePort` (or `adom-bridge bridge_list`). In practice you don't need the port directly — use the `adom-bridge <verb>` CLI which routes to the right bridge automatically.++Bridges are launched on demand. They are NOT always running. There is no Bridge Manager+dialog in Hydrogen for Linux; ask ab (`adom-bridge status` or `adom-bridge bridge_list`).++### What Adom Bridge can do (live capability list)++Bridges are only part of ab. Query the **authoritative, machine-specific** list:++```bash+adom-bridge status # → .capabilities and .desktop.apps+```++On a typical machine `.capabilities` =+`notify, files, kicad, fusion360, shell, usb, screenshot, browser, caption, record`.+Mapping to where each is documented:++| capability | what it is | skill |+|---|---|---|+| `kicad` / `fusion360` / `browser` | the three built-in app bridges | this skill |+| `screenshot` / `record` / `caption` | OS screenshots, screen/tab recording, recording captions | this skill (screenshots/recording); `caption` is recording-caption support |+| `files` | send_files / pull_file | **hydrogen-file-transfer**, **hydrogen-adom-bridge** |+| `notify` | desktop toast notifications | this skill |+| `shell` | run a command on the user's PC (approval-gated) | **hydrogen-adom-bridge** |++> `.desktop.apps` also reports, per app: `bridgeRunning`, `installed`, `running`,+> `version` — use it to check whether the target app (KiCad/Fusion/Chrome) is+> present before driving its bridge.++---++## Prerequisites++Check connection: `adom-bridge --ai-thread "<thread>" targets` lists the machines whose ab is+connected to the relay. On this desktop Hydrogen installs and starts ab when a Linux build is+published for the user's account (see **hydrogen-embedded-bridge**); if none is connected, the+setup step `ensure-adom-bridge-cli` and the `[ab-linux]` log lines say why.++---++## Screenshots (zero dialogs, instant)++```bash+# Full screen capture+adom-bridge desktop_screenshot_screen++# Resized for Claude vision (default to this)+adom-bridge desktop_screenshot_screen '{"maxWidth": 1500}'++# Specific window by HWND+adom-bridge desktop_screenshot_window '{"hwnd": 12345}'++# List all capturable windows+adom-bridge desktop_list_windows+```++**AI guidance:**+- Default to `maxWidth: 1500` -- Claude vision hard limit is 2000px+- Use `format: "png"` for UI/text (default, lossless)+- Use `format: "jpeg", quality: 80` for photos/3D renders+- Use `format: "webp"` for smaller file sizes++---++## Browser Automation (Puppeteer Bridge)++Port: default **8851** (adom-bridge registers the live port; see `adom-bridge status`). Auto-downloads Chrome for Testing if not present.++```bash+# Open browser window+adom-bridge pup_open_window '{"url": "https://example.com"}'++# Screenshot current tab+adom-bridge pup_screenshot '{"sessionId": "default"}'++# Evaluate JavaScript+adom-bridge pup_eval '{"js": "document.title", "sessionId": "default"}'++# Navigate+adom-bridge pup_navigate '{"url": "https://...", "sessionId": "default"}'++# List open windows/tabs+adom-bridge pup_list_windows++# Record tab (CDP screencast, zero dialogs)+adom-bridge pup_record_start '{"sessionId": "default"}'+adom-bridge pup_record_stop '{"sessionId": "default"}'+```++---++## KiCad Bridge++Port: default **8771** (adom-bridge registers the live port; see `adom-bridge status`). Requires KiCad to be installed on the user's machine.++```bash+adom-bridge kicad_open_board '{"path": "<host path to board.kicad_pcb>"}'+adom-bridge kicad_open_schematic '{"path": "<host path to schematic.kicad_sch>"}'+adom-bridge kicad_open_3d_viewer+adom-bridge kicad_run_drc '{"path": "..."}'+adom-bridge kicad_screenshot_all+adom-bridge kicad_window_info+adom-bridge kicad_send_key '{"key": "ctrl+s"}'+adom-bridge kicad_list_versions+adom-bridge kicad_install_symbol '{"path": "/tmp/symbol.kicad_sym", "library": "MyLib"}'+adom-bridge kicad_install_library '{"path": "/tmp/footprints", "name": "MyFootprints"}'+```++**Always run `kicad_window_info` BEFORE any KiCad operation** to check for modal dialogs —+and AFTER any save/DRC/open to catch errors KiCad raised.++### Finding + reading KiCad errors (modal dialogs)+`kicad_window_info` returns `hasModalDialogs` (bool) + a `modalDialogs` array — **this is how+you detect a KiCad error/blocking dialog** (a save-permission error, a file-format warning, a+DRC blocker). Each entry is `{hwnd, ownerHwnd, title}` (e.g. `title:"Error"`):++```bash+adom-bridge kicad_window_info '{}'+# → { editors:[...], hasModalDialogs:true,+# modalDialogs:[{ "hwnd":200934, "ownerHwnd":6163368, "title":"Error" }], projectManager:{...} }+```+- ⚠️ `modalDialogs` gives the **title + hwnd, NOT the body text**. To read *what the error says*,+ **screenshot the dialog by its hwnd**: `adom-bridge desktop_screenshot_window '{"hwnd":200934}'`+ → read the saved PNG. (Verified live 2026-06-15: a `ctrl+s` on a read-only board surfaced+ `hasModalDialogs:true` + a `title:"Error"` entry; screenshotting its hwnd read *"Insufficient+ permissions to save file …"*.)+- **Dismiss** it before proceeding: `kicad_send_key '{"hwnd":<dialog hwnd>,"key":"return"}'`+ (OK) or `"escape"` (Cancel). A lingering modal blocks every subsequent KiCad action.+- So the loop is: **operate → `kicad_window_info` → if `hasModalDialogs`, screenshot each+ `modalDialogs[].hwnd` to read it → handle/dismiss.** Don't assume an operation succeeded just+ because the verb returned `success:true` — KiCad can still pop a blocking error.++---++## Fusion 360 Bridge++Port: default **8773** (adom-bridge registers the live port; see `adom-bridge status`). Requires Fusion 360 to be installed on the user's machine.++```bash+adom-bridge fusion_start+adom-bridge fusion_import_step '{"path": "<host path to model.step>"}'+adom-bridge fusion_export_step '{"path": "<host path to output.step>"}'+adom-bridge fusion_board_info+adom-bridge fusion_electron_run '{"command": "..."}'+```++---++## Extensible bridge catalog (bridges are NOT a fixed set)++Bridges are a growing ecosystem. The three above (KiCad / Fusion 360 / Puppeteer)+are **built into Adom Bridge**. Additional bridges are published to the **wiki+bridge catalog** and installed on demand — for example the **Blender bridge**+(`adom-blender-bridge`), which is NOT built in (it won't appear in `adom-bridge+status` until installed). To use a catalog bridge:++- **Discover:** the wiki catalog at `/apps?tag=hydrogen-bridge`.+- **Reserved ports:** the `8900-8999` range is set aside for 3rd-party bridges.+- **Enumerate what's actually live:** `adom-bridge status` → `desktop.apps.*` lists+ every bridge ab currently knows about, with `bridgePort`, `status`, and whether+ the target app was detected. **Treat that as the source of truth** for "what+ bridges exist right now" — this skill's table lists the core ones, but new+ catalog bridges will appear in `status` without being in this table.+- **Invoke any bridge** through the `adom-bridge <verb>` CLI; it routes to the+ right bridge automatically (you rarely need the port directly).++> Maintainer note: keep this skill in sync by periodically running+> `adom-bridge status` against a fully-bridged machine and reconciling the table.++---++## File Transfer++```bash+# Send a file from the workspace to the desktop+adom-bridge send_files '{"filePaths":["/home/adom/project/out.pdf"],"saveTo":"<folder on that machine>"}'++# Pull a file from the desktop to the workspace (remotePath uses that machine's native path convention)+adom-bridge pull_file '{"remotePath": "<host path to data.csv>", "localPath": "/tmp/data.csv"}'+```++---++## Desktop Interaction++```bash+# Toast notification+adom-bridge notify_user '{"message": "Build complete!", "duration_ms": 5000}'++# Open URL in user's browser+adom-bridge desktop_open_url '{"url": "https://..."}'++# Open folder in the OS file manager+adom-bridge desktop_open_folder '{"path": "<host folder path>"}'++# Execute shell command in the host's native shell (requires user approval)+adom-bridge shell_execute '{"command": "<host shell command>"}'+```++---++## Screen Recording++> **Served by Adom Bridge.** The `desktop_record_*` / `desktop_recorder_*` verbs exist only+> when the target machine's ab offers them. Verify before using: `adom-bridge status`, then+> `.capabilities` must include `record`. See **hydrogen-recording** for full details.++> **Tab-vs-desktop footgun.** `desktop_record_start` records the **whole screen**+> and requires an explicit `confirmDesktopNotTabRecording:true` guard so you don't+> accidentally capture the entire desktop when you meant one tab. To record a+> single Chrome tab, use `pup_record_start` instead (CDP screencast, served by+> the Puppeteer bridge, no whole-screen capture).++```bash+# Record entire desktop (ab-served; needs the confirm guard, zero dialogs)+adom-bridge desktop_record_start '{"reason": "Demo recording", "confirmDesktopNotTabRecording": true}'+adom-bridge desktop_record_stop++# Record a single browser tab (CDP screencast, zero dialogs) — prefer this for one tab+adom-bridge pup_record_start '{"sessionId": "default"}'+adom-bridge pup_record_stop '{"sessionId": "default"}'+```++---++## Ralph Loop Pattern++```bash+# 1. Take screenshot+adom-bridge desktop_screenshot_screen '{"maxWidth": 1500}'+# 2. Read the screenshot (it's saved to /screenshots/)+# 3. Analyze with Claude vision+# 4. Make changes+# 5. Take another screenshot+# 6. Repeat until done+```++---++## Browser Profiles++Hydrogen can detect all browser profiles installed on the user's machine and open+URLs in specific browsers/profiles.++**Control API endpoints**:+- `GET /browser-profiles` -- detect Chrome, Edge, Brave, Firefox, Opera profiles+- `POST /open-in-profile` -- open URL in a specific browser and profile+- `POST /open-url` -- open URL in the default browser++On Linux the profiles are found from PATH, snap, Flatpak and Firefox `profiles.ini`+(Chromium and Vivaldi are detected too). None of this needs ab. See **hydrogen-browser-picker**.++**Source**: `src/lib/components/BrowserProfileDialog.svelte`++---++## Cross-references++- **hydrogen-adom-bridge-triage** -- ab will not connect+- **hydrogen-embedded-bridge** -- how a Linux ab and Hydrogen relate+- **adom-bridge-multi-machine** -- `--target`, `targets`, `primary_machine`+- **adom-bridge-linux** -- running ab on this Linux desktop+- **kicad-bridge** -- the KiCad bridge's own skill+- **hydrogen-networking** -- port architecture (conventional bridge ports + dynamic registration)+- **hydrogen-adom-menu** -- the API Explorer (has bridge-related endpoints)+- **hydrogen-settings** -- Hydrogen settings surface+- **hydrogen-self-screenshot** -- host screenshots, window control, and the ralph loop+- **kicad-interaction** -- foundational KiCad desktop interaction rules+- **pup** -- Puppeteer browser control via pup CLI
skills/hydrogen-browser-picker/SKILL.mdadded+175@@ -0,0 +1,175 @@+---+name: hydrogen-browser-picker+description: >-+ Hydrogen's Browser Picker on Linux: how URLs opened in Hydrogen are caught and+ routed (native browser profile, Hydrogen tab or window, Pup), the quiet+ remember-per-website mode, the countdown, and how Linux browsers and profiles+ are detected. Use when a link won't open, the picker lists no browsers, for+ oauth or sign-in links, or adding a URL-opening feature.+---++# Hydrogen Browser Picker (Linux)++## The Problem++Hydrogen wraps a WebKitGTK webview that contains:+- The Hydrogen SvelteKit frontend (localhost:1420 in DEV mode only; prod Hydrogen serves it via the tauri protocol)+- The code-server iframe (VS Code + Claude Code) on port 7380+- Webview panel iframes (any external URL like wiki, google, etc.)++When a link is clicked anywhere in this stack, Hydrogen needs to:+1. Catch it before it opens uncontrolled+2. Route it through the Browser Picker dialog+3. Let the user choose: native browser (Chrome/Edge), Hydrogen Tab (wv), Hydrogen Browser Window (short name: **hbw**), or Pup++## Links open without asking (remember per website)++With Settings > Hydrogen > Behavior > "When a link opens" on **Remember per website** (the+default, setting `hydrogen.link_open_mode`):++- A link opens where that website's links went last time, or at the picker's usual default (saved+ domain pref, then the bias file, then the work profile).+- A toast says where ("Opened example.org in Firefox ([email protected])") with a **Change** button that+ reopens the full picker for the same link; a pick there is remembered.+- Sign-in links and "move this page" (`-move` triggers) still show the picker every time.+- **Always ask** brings back the picker plus countdown on every link.+- Shift-click does not force the picker on Linux (Shift is not detected). Use **Change** on the+ toast, or `POST /open-url {"url":..., "force":true}`.++## How links are caught on Linux (WebKitGTK)++| Event | Caught by | Result |+|---|---|---|+| `window.open()` / `target="_blank"` from the app or the editor (VS Code `openExternal`, extension links) | Tauri `on_new_window` | Browser Picker |+| VS Code's `window.open('')` then `location = url` | frame-bus script turns `''` into `about:blank`; Hydrogen grants a managed popup (`hd-popup-*`) whose outside navigation goes to the picker, then the empty popup closes | Browser Picker |+| The main page itself starting to load an outside http(s) URL | GTK `load-changed` guard on the main frame: the load is stopped | Browser Picker |+| Link inside a webview tab iframe | not intercepted | navigates the iframe |+| `mailto:` / `tel:` / `sms:` in any frame | frame bus app-link handler | the desktop's default app, or the address copied to the clipboard if none |++Hydrogen turns on WebKitGTK's `javascript-can-open-windows-automatically` for the main webview so+scripted popups reach `on_new_window` at all (otherwise code-server shows "The browser blocked+opening a new window"). There is no "Open Link with Browser Picker" item in the right-click menu+on Linux.++## Browser Picker Dialog++`src/lib/components/BrowserProfileDialog.svelte`++### 3 Branded Variants+1. **Claude auth** — Claude logo, "Connect to Claude Code" (domains: `*.claude.ai`, `*.claude.com`)+2. **Adom auth** — Adom logo, "Sign in to Hydrogen" (domains: `*.adom.inc` + `/auth/intent`)+3. **General link** — "Browser Picker" title, no logo++On Linux, other AI sign-ins count as sign-ins too: auth.openai.com, accounts.google.com, Kimi /+Moonshot, x.ai, login.microsoftonline.com, GitHub device login, any `/oauth/authorize`,+`/oauth2/auth` or `/device` URL. For sign-ins the Hydrogen section starts collapsed, so native+browsers come first (those pages refuse to load inside Hydrogen), and the fresh-window toggle+starts on.++### Consistent Elements (all variants)+- "Browser Picker" title at top+- Native Browsers section with real Google profile avatars+- Hydrogen section (collapsible, collapsed for auth)+- Details section (collapsible, collapsed) — URL, remember checkbox, trigger info, build version+- Auto-timer with progress bar (cancelled by mouse movement): 5 s for links, 10 s for sign-ins+- Keyboard navigation (arrow keys + Enter)+- 800ms delayed tooltips++### Auto-Timer Behavior+- Picks best default: the saved domain pref, then the bias file, then the work browser profile+ (non-gmail email)+- 5-second countdown for links, 10 seconds for sign-ins, with a progress bar+- ANY mouse movement cancels the timer+- `force:true` on `/open-url` shows the dialog without the timer (Shift is not detected on Linux)+- Selected destination highlighted with teal border++### Fresh-window option+`fresh:true` opens a brand-new browser window rather than a tab. It does not force the+foreground: on Linux the window manager decides focus.++- Mechanism: Chromium-family browsers get `--new-window` and Firefox `-new-window` before the+ URL. With no concrete browser program, `xdg-open` is the fallback, which loses profile and fresh.+- UI: an **"Open in a fresh window"** checkbox above the Native Browsers list. **Defaulted+ ON for auth URLs** (Claude/Adom), OFF otherwise. Only native-browser destinations honor+ it; internal Hydrogen destinations ignore it. The dialog dispatches `select` with+ `fresh: dest.category==='native' ? freshWindow : false`; `onProfileSelect` threads it to+ `open_in_browser_profile` / `/open-in-profile`.+- `fresh` is honored by: Tauri `open_in_browser_profile` (direct), `POST /open-in-profile`+ (direct), and `POST /open-url` (where it **pre-seeds the picker's toggle**; add+ `direct:true` to open immediately instead). Direct paths echo+ `{"fresh":…, "method":"<exe … fresh-window>"}`.++### URL Event Deduplication+The frontend drops a repeat of the same URL within 1 second, so several handlers firing for+one click open it once.++### Prefs Sync+Preferences re-read from localStorage on every dialog open. If user deletes a domain in Browser Picker Manager, the next dialog open reflects it immediately.++## Browser detection (`hydrogen-control-ui/src/linux_browsers.rs`)++- **Programs:** each browser's commands on PATH plus `/snap/bin`, and Flatpak exports (system and+ per-user): Firefox (`firefox`, `firefox-esr`), Chrome (`google-chrome-stable`), Chromium,+ Edge, Brave, Vivaldi, Opera.+- **Profiles:** Chromium-family `Default` / `Profile N` dirs under `~/.config` (and the snap and+ Flatpak homes); Firefox profiles from `profiles.ini` (`~/.mozilla`, `~/.config/mozilla`, snap,+ Flatpak), only ones that have been used, with the Firefox Account email when signed in.+- **Default browser:** `xdg-settings get default-web-browser`, then `mimeapps.list`.+- **Launch:** Chromium-family with `--profile-directory=<dir>`; Firefox `Default` without `-P`+ (reuses the running Firefox), any other profile with `-P <name>`. `fresh` adds `--new-window`+ / `-new-window`. With no concrete program, `xdg-open` (via `open::that`) is the fallback, which+ loses profile and fresh.++"The picker lists no browsers": check the browser runs from a terminal by one of the names above,+and that a profile has been used at least once.++## Files++| File | What |+|---|---|+| `src-tauri/crates/hydrogen-app/src/lib.rs` | `on_new_window`, granted popups, the Linux main-frame guard, `dispatch_url_event`, `linux_open_app_link` |+| `src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs` | `window.open('')` fix and the app-link handler in every frame |+| `src-tauri/crates/hydrogen-control-ui/src/linux_browsers.rs` | browser, profile and default detection |+| `src/lib/components/BrowserProfileDialog.svelte` | Browser Picker dialog (3 variants, auto-timer, keyboard nav) |+| `src/lib/components/editor/EditorNav.svelte` | Browser Picker Manager modal |+| `src/routes/+layout.svelte` | CustomEvent listeners, URL event parsing, deduplication |+| `src/lib/assets/claude-logo.svg` | Real Claude logo from claude.ai/favicon.svg |+| `src/lib/assets/adom-logo-teal.svg` | Adom brand logo |+| `src/lib/buildVersion.ts` | Build version tracking for verification |++## The auto-countdown (why AI loves it)++The picker opens with a countdown on its best-default destination. If nothing interrupts, the URL auto-routes there. This is the key feature for AI automation: triggers like OAuth redirects, "open in browser" links, or wiki references work hands-free.++- **AI scripts can fire a URL open and the right thing happens within seconds**: no clicking, no blocking on a dialog.+- **Mouse movement cancels the timer** — if a human is at the keyboard, just wiggle the mouse and the picker waits.++## AI automation recipe++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}' "$BASE/open-url"+curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com","force":true}' "$BASE/open-url"+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://example.com","browser":"firefox","profileDir":"Default","fresh":true}' "$BASE/open-in-profile"+```++`/open-url` ROUTES THROUGH THE PICKER by default (emits `browser-open-request`):+`fresh` pre-seeds the "Open in a fresh window" toggle, `force:true` skips the 5s+auto-timer, `direct:true` (or naming a concrete `browser`) bypasses the picker and+opens immediately. The response `routed` field is `"browser-picker"` or `"direct"`.+`/open-in-profile` always opens directly (no picker). `signin:true` on Linux always opens+directly in the system browser. Read `method` in the reply before claiming success.++## Prefs are now an API — the picker is a FALLBACK, not a gate++The per-domain routing memory is CRUD over the control API, so the **AI governs routing** and+the picker only pops for a domain with no policy + no direct call:+`GET /browser-picker/prefs` (read `{domains:{<host>:{destination,label}}}`),+`PUT /browser-picker/prefs {domain,destination,label?}` (set/override),+`DELETE /browser-picker/prefs/<host>` (forget one), `DELETE /browser-picker/prefs` (clear all).+`destination` is an ID: `hydrogen-tab` (wv) | `webview-window` (**hbw** — Hydrogen's standalone Tauri browser window; also `POST /hbw/open`; close one with `POST /hbw/close {"label":"hbw-<ts>"}`, hbw labels only, from 1.0.142) | `pup-window` (pup), or a native id (**nb**): users address these as `nb <browser> [profile]` — "nb chrome work", "nb edge" — resolve via GET /browser-profiles; the id form is+`browser:<browser>:<dir>` (profile dir encoded in the ID). `fresh` is per-open, not stored.+Writes hit the Manager's live state (localStorage + `hydrogen-url-routing-prefs-changed`). Full+routing-policy guidance lives in **[hydrogen-open-url](../hydrogen-open-url/SKILL.md)**.+
skills/hydrogen-captions/SKILL.mdadded+103@@ -0,0 +1,103 @@+---+name: hydrogen-captions+description: >-+ Paint caption text on the Hydrogen workspace with `adom-cli hydrogen caption`+ (seconds, auto-expire, part of the window's pixels) for demos and+ walkthroughs. Use when asked to put text on screen, add a caption or+ callout, label a demo step, caption over other apps, or clear a stuck+ caption.+---++# Hydrogen: On-Screen Captions (Linux)++You can **paint labeled caption text inside the Hydrogen window** for demos and+walkthroughs ("Step 3: run DRC"). It is real pixels in Hydrogen's page, so a Hydrogen+screenshot includes it.++> Captions are **visual on-screen narration** — centered status / countdowns / "what+> I'm doing," great during demos and recordings. Distinct from:+> - **toasts** — corner pop-ups via `POST /ui/toast` (transient notifications, see+> `hydrogen-notifications`); a caption is centered narration, a toast is a corner alert.+> - **TTS** *audio* narration (`adom-tts`) — pair a caption with TTS for a narrated walkthrough.+> - the internal **auth-overlay caption** Hydrogen draws for login/auth flows — not something+> you trigger for demos. The workspace caption below is the one you drive.++**Only the workspace caption exists on Linux.** The desktop overlay caption over other apps+(`adom-bridge desktop_caption`) is not available on a Linux desktop: Adom Bridge for Linux+refuses to create the caption window. To label something in another app, put the caption in+Hydrogen or narrate with TTS.++## Workspace caption: `adom-cli hydrogen caption`++**Reach for this FIRST.** It's the *same* command on web Hydrogen and Hydrogen (adom-cli routes+through Hydrogen's workspace-events server → SSE → the frontend `captionStore`), so it stays+consistent across both — same principle as screenshots. Renders centered **inside the Hydrogen+workspace webview**. `show` takes the TEXT as a **positional arg** (NOT `--text`); the only+flags are `-d`/`--duration`, `-p`/`--position`, `-s`/`--size` (no `id`, `x`/`y`, or+`fontSize` — those are desktop-overlay-only). Subcommands: `show` / `hide`.++```bash+adom-cli hydrogen caption show "Step 1: open the board" -p center -s large # 30s auto-expire+adom-cli hydrogen caption show "Step 2: run DRC" -d 60 -p center -s large # hold 60 SECONDS+adom-cli hydrogen caption hide # clear now+```++### ⚠️⚠️ `-d` / `duration` is in **SECONDS — NOT milliseconds** ⚠️⚠️+THE gotcha. `-d 30` = 30 seconds. `-d 4000` = **66 MINUTES**, not 4 seconds. If you're+thinking in ms you're off by **1000×**. You almost never need a big number — the 30s+default already covers "leave it up while I do a thing."++> **Web-Hydrogen vs Hydrogen parity:** the **command + the SECONDS unit + `hide` are identical**+> on both (center/large rendering, `-d 20` held visibly). BUT the sane **lifecycle below+> (30s default / 300s cap / persist)** is verified on Hydrogen; web Hydrogen may still return the+> *older terse `_hint`* ("auto-hides after the specified duration") and may not enforce the+> 30s-default/300s-cap yet. **So on web Hydrogen, don't assume a fat `-d` self-heals — pass+> a sane duration.**++### Lifecycle (sane, never abandoned)+- **No `-d` (or `-d 0`) → auto-expires after 30s.** The right default — you do NOT need+ to `hide` it.+- **Positive `-d <seconds>` → holds that many seconds, HARD-CAPPED at 300s (5 min).** A+ larger value still clears at 5 min, so a fat-fingered `-d 4000` self-heals.+- **Newest wins:** showing another caption replaces the current one; `hide` clears immediately.+- **No "forever" via adom-cli** — its `-d` is an unsigned int (rejects negatives) by+ design. This is a **feature, not a gap**: adom-cli is the same binary on web-Hydrogen and+ Hydrogen, so "no persist via adom-cli" keeps both consistent and bounded (no abandoned+ captions). A persist-until-hidden escape exists ONLY on the raw HTTP endpoint+ (`{"duration":-1}`, below) — rarely needed.+- **No `caption status` verb (yet).** There's no way to query "is a caption up / how long+ left" from adom-cli — and with newest-wins + the 30s auto-expire you rarely need to.+- `-p` position: `top` / `center` / `bottom` (no corners). `-s` size: `small` / `medium` / `large`.+- Needs a live workspace/editor session (the server returns 409 if none).++### Direct HTTP fallback — only for scripts already hitting Hydrogen's API+adom-cli is the consistent default; use HTTP **only** when a script talks to Hydrogen's API+directly. It's the **same caption, same lifecycle** — adom-cli just wraps this path with+the workspace owner/repo. The caption lives on the **workspace-events server**+(`ADOM_HYDROGEN_URL`, the proxy) — **NOT the control port**:++```bash+# show — duration in SECONDS, identical body/lifecycle to adom-cli+curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \+ -H 'Content-Type: application/json' \+ -d '{"text":"Step 1: open the board","duration":60,"position":"center","size":"large"}'+# hide+curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \+ -d '{"hide":true}'+# persist until hidden (HTTP-ONLY escape — adom-cli can't send a negative):+# -d '{"text":"Recording…","duration":-1}'+```+Body: `{text, duration (SECONDS), position, size}`; clear with `{hide:true}`.++## Patterns++- **Walkthrough / demo callouts** — drop a `center` caption per step. Combine with a+ recording so the callouts end up in the finished video. Pair with TTS for narration.+- **Cleanup**: `hide` when a step is done.+- Hydrogen's native screen recorder does not run on Linux, so a caption ends up in a video+ only if whatever records the screen captures the Hydrogen window.++## Related skills+- `hydrogen-self-screenshot`: captions show up in Hydrogen screenshots+- `hydrogen-notifications`: toasts+- `adom-tts`: audio narration to pair with on-screen captions (captions are visual-only)
skills/hydrogen-capture-share/SKILL.mdadded+133@@ -0,0 +1,133 @@+---+name: hydrogen-capture-share+description: >-+ Hydrogen's screen-share and AI-consent flow for screenshotting the editor on Linux: the+ Screen Capture dropdown, the AI-wants-access approval and its countdown, and what a+ capture really grabs (a WebKit snapshot of Hydrogen's window). Use before screenshotting+ Hydrogen's own UI, or when asked to share this tab, share my screen or stop sharing.+---++# Hydrogen: Screen Capture and Sharing (the AI-consent surface)++This is the surface **you (the AI) trigger to see Hydrogen's own screen.** To screenshot the+editor (panels, the workspace) into the workspace, a share must be active first: you request+it, the user consents (Hydrogen auto-approves in about 3 s), a short countdown plays, then you+capture.++**What a capture is inside Hydrogen:** no `getDisplayMedia` and no browser screen picker.+Starting a share only flips the store's `isSharing`; each frame is taken by Hydrogen itself+through `POST /screenshot` on the control API. On Linux that is WebKit's snapshot of Hydrogen's+main window (iframes included); a panel capture crops it to the panel's selector. It never+shows other apps or the rest of the desktop. The `getDisplayMedia` / Element Capture path+(`restrictCaptureTo`) runs only in web Hydrogen in a browser.++This is distinct from **hydrogen-permissions** (the webview allowing every mic, camera and+notification request), a different layer.++## The Screen Capture dropdown (editor toolbar)++Source: `src/lib/components/editor/EditorNav.svelte` (~L2227–2332).+Store: `src/lib/stores/screenCaptureStore.ts`.++**When not yet sharing**, the dropdown offers two ways to start:++| Option | Description |+|---|---|+| **Share this tab** | "Panels and workspace screenshots" |+| **Share entire screen** | Sets the surface to `monitor`; inside Hydrogen it still captures only Hydrogen's window |++**While sharing**, it shows `Sharing <surface>` ("entire screen" / "window" / "this+tab") plus capture actions:++| Action | Description |+|---|---|+| **Workspace screenshot** | Save to container's `screenshots` folder |+| **Full screen screenshot** | Save to container's `screenshots` folder (only when the surface is a monitor/window) |+| **Stop sharing** | Ends the share |++### Window mode toggle (Webview vs Pup)++Below the share options is a **Window mode** toggle with two buttons —+**Webview** and **Pup** (`windowModeStore`). It selects which window surface+capture/recording targets: Hydrogen's own embedded Webview, or a Pup (Puppeteer)+browser window. Webview = "see Hydrogen itself"; Pup = "see the AI-driven browser."++Pup works where Adom Bridge runs: this computer once Hydrogen has installed it (when a Linux+build is published for the user's account), or another machine through `adom-bridge --target`.++## Capture scopes & how a frame is taken++`screenCaptureStore.ts` exposes the scope type and the capture functions:++```ts+type CaptureScope = 'screen' | 'workspace' | 'panel';+```++| Scope | Function | What you get on Linux |+|---|---|---|+| `panel` | `capturePanel(panelId)` | `POST /screenshot {target:'shell', selector:'[data-pane-id="<id>"] .panel-body'}`: that panel, cropped from the window snapshot |+| `workspace` | `captureWorkspace()` | the whole Hydrogen window |+| `screen` | `captureScreen()` | the whole Hydrogen window (not the desktop) |++Other store entry points you'll see: `startTabCapture()`, `startScreenCapture()`,+`stopScreenCapture()`, `captureFrame()`, `isCaptureActive()`,+`promptScreenCapture(message?)` (asks the user to enable sharing).++State shape: `{ isSharing, displaySurface, hasElementCapture, promptMessage }`,+where `displaySurface` is `'browser'` (tab) / `'window'` / `'monitor'`.++You can also call `POST /screenshot` on the control API directly (`b64:true` returns the PNG+inline as `dataUrl`); see **hydrogen-self-screenshot**.++## The AI sharing-approval flow++When you (or a bridge) need screen/mic access, Hydrogen shows a consent gate before any+capture. Source: `src/lib/components/editor/SharingApprovalDialog.svelte`,+store `src/lib/stores/sharingApprovalStore.ts`.++The request you send carries:++```ts+{ bridgeKey, reason, shareType: 'tab' | 'screen' | null, audio: boolean }+```++- The dialog header reads **"AI wants access"** and shows **your `reason`** in a+ highlighted box. **Send a clear, specific reason** — it's the only thing the user+ sees to decide. ("Screenshot the schematic panel to verify the layout," not+ "capture screen.")+- **Hydrogen auto-approves after ~3 s** (`AUTO_MS = 3000`), showing+ "Auto permission will be given in N…". This is the Hydrogen-only fast path so you're+ not blocked on hands-free flows.+- **The user can override before it auto-fires:** flip share-type between+ **Share this tab** and **Share entire screen**, toggle the **mic**, or pick a mic+ device. Any interaction cancels the auto-countdown so they stay in control.+- On approve, Hydrogen starts the screen share first (tab or screen), then mic if+ requested, and returns a result (`status: 'approved'`, with `sharing` + `mic`+ details) to the requesting bridge.++### CountdownToast — the cancelable lead-in++Source: `src/lib/components/editor/CountdownToast.svelte`. Before capture/recording+actually starts, a countdown toast ("Recording in N…", default 3) plays, optionally+showing the sources and reason. It has a **cancel (×)** — the user can abort right+up to the last second. Don't assume capture started the instant you requested it;+the toast is a real, abortable delay.++## What this means for you (the AI)++1. **To screenshot Hydrogen's editor you need an active share.** If you're not sharing,+ call `promptScreenCapture(...)` / send a sharing request with a reason; don't+ silently fail a `capturePanel`/`captureWorkspace`.+2. **Write the reason for a human.** It's your one chance to justify the access.+3. **Respect the override + countdown.** The user may switch share-type, deny mic,+ or cancel the countdown — read the returned result before claiming success.+4. **Pick the right scope:** `panel` for one panel, `workspace` for the window. `screen` adds+ nothing on Linux.+5. **For a picture of the user's whole desktop or another app,** Hydrogen has no way on Linux;+ Adom Bridge's `desktop_screenshot_*` verbs do it only where Adom Bridge runs.++## Related skills+- **hydrogen-self-screenshot**: per-panel screenshots and the shotlog verify loop+- **hydrogen-recording**: recording (no native recorder on Linux)+- **hydrogen-permissions**: the webview's permission layer+- **hydrogen-adom-bridge**: Adom Bridge's desktop screenshots, where it runs
skills/hydrogen-claude-auth/SKILL.mdadded+84@@ -0,0 +1,84 @@+---+name: hydrogen-claude-auth+description: >-+ How Claude Code signs in inside Hydrogen on Linux: the OAuth flow, where credentials+ live, the backup that survives a workspace rebuild, and how to recover. Use when Claude+ is not authenticated, the Claude token expired, or Claude needs to re-auth after a+ virgin reset.+---++# Hydrogen Claude Auth: how Claude Code signs in++Claude Code (the VS Code extension and the `claude` CLI in the workspace) signs in+separately from your Adom login.++For Adom auth (your hydrogen.adom.inc login), see [hydrogen-adom-auth](../hydrogen-adom-auth/SKILL.md). This skill is Claude-Code-specific.++## Where sign-in happens++Setup does not sign anyone in to Claude. After setup the user picks and signs in to an AI+from **Manage AIs** (Adom logo menu) or **Your AIs** (profile menu), the "Choose your AI"+dialog. On Linux those sign-in links always open in the system browser (never an in-app+tab), with no picker countdown.++1. The Claude Code panel shows "Claude.ai Subscription" when it is not signed in.+2. Clicking it opens the claude.ai OAuth page in the browser.+3. claude.ai redirects to a localhost callback port. The workspace shares this computer's+ network, so the callback reaches the workspace directly.+4. The credentials land at `/home/adom/.claude/.credentials.json` in the workspace.++## Where Claude credentials live++| Layer | Location | Purpose |+|-------|----------|---------|+| Inside workspace (live) | `/home/adom/.claude/.credentials.json` | Active credentials the extension and `claude` CLI both read |+| Host-side backup | `~/.config/hydrogen-desktop/replay-claude-credentials.json` | Lets a rebuilt workspace stay signed in |+| VS Code secret store (in code-server's user data) | webview-internal, can't be inspected directly | The extension also keeps a secret per panel; this is what dictates the chat UI showing vs the auth button |++The backup is written by a virgin reset that keeps Claude (it copies the live file out+before wiping) and by the old-image migration.++**Key insight**: each Claude Code panel instance keeps its own auth state. If one panel says "not authenticated", opening a NEW Claude Code conversation panel often shows the auth button fresh and lets you sign in cleanly.++## Recovery++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s "$BASE/claude/auth-status" # what Hydrogen sees+curl -s -X POST "$BASE/demo/run" -d '{"action":"reinject-claude-creds"}' # put the backup back+curl -s -X POST "$BASE/claude/wipe-creds" -d '{"backup":false}' # sign out, keep the backup+```++`/claude/wipe-creds` always removes the workspace credentials; `backup:true` (the default)+also deletes the host backup. `claude_authorize_in_browser` is not available on Linux.++## Virgin reset: what each option does++The setup panel's Virgin Reset section has a per-Claude-creds toggle:++| Toggle | What happens to Claude auth | When to use |+|--------|----------------------------|-------------|+| **Claude credentials** (default OFF) | Deletes the `replay-claude-credentials.json` backup from the host AND the credentials inside the workspace. **You will need to re-OAuth.** | When Claude is stuck in a broken auth state and you want a true fresh sign-in. |+| **Workspace** | The workspace machine is rebuilt. With the Claude credentials toggle OFF, the host backup is kept, so the user can be restored (`reinject-claude-creds`). | Normal virgin reset for testing. |++**Standard pattern for AI-driven testing**: keep the "Claude credentials" toggle OFF so testing doesn't bounce you out of Claude every cycle.++## Common failures++**"Claude.ai Subscription" button keeps appearing even though I just signed in**+- A SECOND panel still has stale auth state. Close all Claude Code panels and open one fresh — it'll read the new credentials.++**Credentials backup file exists but Claude says expired**+- Check `expiresAt` (epoch ms) in `~/.config/hydrogen-desktop/replay-claude-credentials.json`. If it is past, sign in again from Manage AIs.++**`claude auth status` says `loggedIn: true` but the extension says not authenticated**+- **Known quirk**: the CLI and the VS Code extension use SEPARATE credential stores. `claude auth status` checks the CLI store; the extension uses VS Code secrets. Trust the extension UI (the "Claude.ai Subscription" button) over the CLI's status output.++**OAuth callback fails / browser shows "connection refused"**+- The `claude` process that opened the callback port has exited, or the sign-in timed out: start the sign-in again from Manage AIs.++## Related skills++- **hydrogen-adom-auth** — Adom (hydrogen.adom.inc) login, separate from Claude+- `hydrogen-setup-steps`: what setup does and does not do for AIs+- `hydrogen-volume` — explains why the host-side backup survives workspace rebuild
skills/hydrogen-claude-management/SKILL.mdadded+212@@ -0,0 +1,212 @@+---+name: hydrogen-claude-management+description: >-+ API for the Claude Code conversations inside Hydrogen: list, open, close and switch+ tabs, read a conversation's state, type into a specific one, and Remote Control for a+ claude.ai URL. Use when asked to open a new Claude tab, type into a conversation, list+ conversations, or view this chat on mobile.+---++# Hydrogen Claude Conversation Management++Hydrogen runs Claude Code as webview tabs inside VS Code. This skill is the+**first-class API** for managing those conversations programmatically: from Hydrogen's control+API, from the user's AI inside the workspace machine, or from setup steps.++All endpoints are on the **Hydrogen control API** (a dynamic localhost port; the workspace+shares the host's network). Examples use `$Hydrogen`:++```bash+Hydrogen="$(cat ~/.adom/hydrogen-control-url)"+```++From a cloud container, call the same endpoints with+`adom-bridge --target <machine> hd_api '{"path":"/claude/...","method":"POST","body":{...}}'`,+which needs Adom Bridge on this computer (Hydrogen for Linux does not set it up). Everything here+works in the **background**: no window focus, no keystroke stealing.++**On Linux** these endpoints read and type into the chat through Hydrogen's frame bus (WebKitGTK+has no DevTools protocol). Context ids are the frame agent's ids: large numbers, stable for the+frame's life, never reused after a reload. Typing into a signed-in Claude over the frame bus is+new on Linux: do a dry run (`submit:false`, then read `compose_text`) before relying on it.++## The core idea: address conversations by CONTEXT ID, list from the TAB BAR++Each Claude conversation is its own webview **execution context** with a **stable integer id**.+That id — not the tab index, not the title, not visibility — is how you reliably *target* one+conversation (type into it, remote-control it). VS Code keeps multiple webviews "visible" at+once, so visibility/tab-index are NOT reliable addresses; the context id is.++But VS Code also **disposes the webview of a background tab**, so a context id only exists for+*loaded* tabs. That's why `GET /claude/conversations` **merges three sources** into one view:+the **tab bar** (every open conversation + which is active — what you see), the **live webview+contexts** (rich data for loaded tabs), and the **on-disk session logs** (the GUIDs). Each row+carries a `loaded` flag; `loaded:false` means activate the tab first to read its live details.++## GET /claude/conversations — everything in one call++```bash+curl -s $Hydrogen/claude/conversations+```+```jsonc+{+ "ok": true,+ "count": 4,+ "conversations": [+ {+ "ordinal": 3, // its position in the tab bar+ "active": true, // the currently-focused tab+ "loaded": true, // webview is live → rich fields are populated+ "context_id": 7, // STABLE address for inject/remote-control (null if not loaded)+ "title": "Calculate 10 times 10", // authoritative title (from the session log when matched)+ "tab_label": "Calculate 10 times 10", // raw tab label (may be ellipsis-truncated)+ "compose_text": "", // what's typed but not yet sent (null if not loaded)+ "msg_count": 16, // null if not loaded+ "session_id": "566cec21-…", // on-disk log GUID (read ~/.claude/projects/*/<id>.jsonl)+ "rc_active": false, // Remote Control on? (null if not loaded)+ "remote_control_url": null // claude.ai cloud URL when rc_active+ },+ { "ordinal": 1, "active": false, "loaded": false, "context_id": null,+ "title": "Find the capital of France", "tab_label": "Find the capital of Fran…",+ "compose_text": null, "msg_count": null, "session_id": "b352055b-…", "rc_active": null, "remote_control_url": null }+ ]+}+```+- **Merged view:** every tab is listed (from the tab bar). `loaded:true` rows have live fields+ (`context_id`, `compose_text`, `msg_count`, `rc_active`); `loaded:false` rows are background tabs+ VS Code disposed — **activate them** (`/claude/tabs/activate`) to read those. Even a disposed tab+ resolves its `session_id` when its title matches the on-disk log.+- A conversation is **`Untitled`** with **`session_id: null`** until its first message is submitted —+ then Claude names it and writes the session log.+- `?with_session=false` skips the disk read (faster; omits `session_id`).++`GET /claude/contexts` is the lighter version (just the *loaded* contexts: `context_id` + `compose_text`).++## Open / close / switch tabs++```bash+# Open a fresh conversation (new tab)+curl -s -X POST $Hydrogen/claude/new-conversation++# Open the Claude panel if it isn't open+curl -s -X POST $Hydrogen/claude/open++# List raw editor tabs (label/active/dirty)+curl -s $Hydrogen/claude/tabs++# Close ALL conversation tabs (also removes the leftover empty editor group)+curl -s -X POST $Hydrogen/claude/tabs/close-all++# Switch the visible tab by index or label substring (background)+curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"index":1}'+curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"label":"Eiffel"}'++# Remove a stale EMPTY editor group (the dead blank panel) WITHOUT collapsing a+# real 2-group left/right layout. (merge-groups is a back-compat alias.)+curl -s -X POST $Hydrogen/claude/tabs/close-empty-groups+```++## Type a message into a SPECIFIC conversation++`POST /claude/inject` types into the conversation you name with `context_index`. Two speeds:++```bash+# INSTANT paste (fast) — no typing animation. Best for slash commands and scripted input.+curl -s -X POST $Hydrogen/claude/inject -d '{"text":"summarize this repo","context_index":16,"typed":false,"submit":true}'++# SLOW human typing animation (the "watch the AI type" effect), then submit.+curl -s -X POST $Hydrogen/claude/inject -d '{"text":"hello there","context_index":16,"typed":true,"delay_ms":50,"submit":true}'++# Type but DON'T send (leave it sitting in the compose box):+curl -s -X POST $Hydrogen/claude/inject -d '{"text":"draft…","context_index":16,"typed":false,"submit":false}'+```+- `typed`: `true` = char-by-char with ±50% jitter (avg `delay_ms`); `false` = instant paste.+- `submit`: `true` = press Enter; `false` = leave in the box.+- Omit `context_index` ONLY when a single conversation is open. With **more than one** conversation+ open, omitting it can type your text into **several compose boxes at once** (it falls back to a+ visibility heuristic that isn't reliable when the window isn't foreground). When in doubt, pass it.+- Targeting by `context_index` is deterministic — it lands in exactly that tab even when it's+ not the foreground one and even with many tabs open (no fan-out into other tabs). **This is the+ safe default: list `/claude/conversations`, take the row with `active:true` (or the tab you want),+ use its `context_id`, then inject.**++Typical "open a new tab and ask a question":+```bash+curl -s -X POST $Hydrogen/claude/new-conversation+CTX=$(curl -s $Hydrogen/claude/contexts | jq '.contexts[-1].context_id')+curl -s -X POST $Hydrogen/claude/inject -d "{\"text\":\"what does this project do?\",\"context_index\":$CTX,\"typed\":true,\"submit\":true}"+```++## ⭐ Remote Control → view the conversation on claude.ai / mobile++This is the big one. Turn on Remote Control for a conversation and Hydrogen returns a **claude.ai+cloud URL**. Open it on claude.ai in any browser or in the Claude **mobile app** to see and+drive that exact conversation in the cloud — not tied to Hydrogen. The user can be on their phone+editing the same conversation.++```bash+curl -s -X POST $Hydrogen/claude/remote-control -d '{"context_index":7}'+```+```jsonc+{+ "ok": true,+ "rc_active": true,+ "toggled": true, // false + already_in_desired_state:true if it was already on+ "context_id": 7,+ "remote_control_url": "https://claude.ai/code/session_014koKPJxmjYpnX2SjRRqrD3"+}+```+- ⚠️ **`/remote-control` is a TOGGLE.** This endpoint **detects** the current state first and only+ toggles when needed — re-calling it on an already-on session is a **no-op** that returns the+ existing URL (it will NOT turn it off; doing that blindly archives the cloud session).+- `{enable:false}` turns Remote Control **off**.+- The `session_…` id in the URL is the **cloud** session id — distinct from the local on-disk+ `session_id` GUID. The cloud URL is the shareable one for claude.ai / mobile.+- `{name}` → `/remote-control <name>` to label the remote session.+- Each conversation's current state is also reported as `rc_active` in `/claude/conversations`.+- **Opening it for the user:** `POST $Hydrogen/open-url {"url":"<remote_control_url>"}` sends it+ through the Browser Picker to their browser. Never blind-type into the claude.ai page.++## How a live conversation maps to its on-disk log (JSONL)++Claude Code stores each conversation as `~/.claude/projects/<cwd>/<uuid>.jsonl` containing+`sessionId`, `aiTitle` (the generated title), and every message. **The session GUID is NOT+exposed in the conversation's webview DOM**, so Hydrogen correlates a live conversation to its log by+matching the **first user message** (exact + unique; present in both the DOM and the JSONL).+On a match, `/claude/conversations` fills in `session_id` and uses the log's `aiTitle` as the+authoritative `title`. (Matching on the title alone is unreliable — the rendered title and the+persisted `aiTitle` can differ.)++Read a conversation's full transcript from the workspace:+```bash+cat ~/.claude/projects/*/<session_id>.jsonl+```++## Why this is valuable++- **Multi-conversation orchestration:** open N conversations, drive each independently by+ context id, read each one's state — all from a script or an agent, in the background.+- **Cloud + mobile continuity:** Remote Control hands you a claude.ai URL so a conversation+ started in Hydrogen continues on the phone / web. Huge for working away from the desk.+- **Deterministic + safe:** context-id addressing never types into the wrong tab; the empty+ blank panel is cleaned up automatically; a real 2-group left/right layout is preserved.+- **Auditable:** every conversation maps to an on-disk JSONL you can read, diff, or archive.++## Endpoint quick reference++| Endpoint | Method | What it does |+|---|---|---|+| `/claude/conversations` | GET | Full per-conversation data incl. `session_id` (the canonical list) |+| `/claude/contexts` | GET | Light list: `context_id` + `compose_text` |+| `/claude/tabs` | GET | Raw editor tabs (label/active/dirty) |+| `/claude/new-conversation` | POST | Open a fresh conversation tab |+| `/claude/open` | POST | Open the Claude panel if closed |+| `/claude/tabs/close-all` | POST | Close all tabs + remove the leftover empty group |+| `/claude/tabs/activate` | POST | Switch visible tab by `{index}` or `{label}` |+| `/claude/tabs/close-empty-groups` | POST | Remove stale empty editor groups (preserves populated) |+| `/claude/inject` | POST | Type into `{context_index}` — `{typed,submit,delay_ms}` |+| `/claude/remote-control` | POST | Turn on RC for `{context_index}` → returns `remote_control_url` |+| `/claude/cross-eval` | POST | (Diagnostic) run JS across all workbench/webview contexts |++These are the same endpoints Hydrogen's own setup steps use to open Claude and inject the first+prompt — so behavior is identical whether a human, setup, or the workspace AI drives them.
skills/hydrogen-container-stats/SKILL.mdadded+141@@ -0,0 +1,141 @@+---+name: hydrogen-container-stats+description: >-+ Hydrogen's title-bar workspace stats indicator on Linux: the CPU and RAM bars+ (app half and workspace half), their tooltip (cores, RAM, disk, image),+ polling, the cgroup numbers, and the stopped/starting/restart-needed badges.+ Use when asked about container stats, the resource bars, workspace disk+ usage, OOM kills, or the restart needed badge.+---++# Hydrogen Workspace Stats Indicator++The top right of Hydrogen's title bar shows a small block titled **Adom** with a CPU bar and a RAM bar. Each bar has two segments: Hydrogen itself (the app and its panes) and the workspace (the `Adom-Workspace` systemd-nspawn machine). Hovering shows the details.++## How often it polls++There's an active polling loop in Hydrogen's title bar that asks the runtime for fresh stats on a timer:++- **Every 2 seconds** when the workspace is `running`+- **Every 5 seconds** when it's `stopped`, `starting`, `restarting`, or `restart needed` — saves cycles when nothing's changing++Each poll calls Tauri `invoke('get_container_stats')`, which dispatches through the runtime trait (`WorkspaceRuntime::get_stats`) to the active host's probe. The probe runs with short timeouts so a hung host subsystem can't freeze the UI.++On Linux that probe is `workspace_stats()` in the `hydrogen-runtime` crate, whose numbers come from its `linux_stats` module.++If you ever want to lighten the load (e.g. on a battery-constrained laptop), the relevant code is in `EditorNav.svelte`'s `pollStats()` closure — adjust the `pollInterval` ternary.++## Where the numbers come from on Linux++The machine shares the host kernel, so the workspace's own `/proc/meminfo`, `/proc/stat` and the kernel OOM counter describe the **whole PC**, not the workspace. Never quote those as workspace numbers. Hydrogen reads the workspace's cgroup instead:++- cgroup: `/sys/fs/cgroup/machine.slice/[email protected]` (or `machine-Adom-Workspace.scope`)+- RAM in use: `memory.current` minus `inactive_file`; limit: `memory.max`, else the PC's RAM+- CPU: `cpu.stat` `usage_usec` delta, as a percent of all cores+- OOM kills inside the workspace: `memory.events` `oom_kill`+- Disk: a background `du -sxm /` inside the machine, at most every 10 minutes (reads 0 until the first run lands)++## What the bars show++| Bar | What it measures |+|-----|------------------|+| CPU | % of all the PC's cores the workspace is using (from the cgroup). Capped at 100% display |+| RAM | % of the workspace's memory in use vs its limit |++Both bars share the same color-threshold rules:+- **Teal / green** — ≤ 50% usage (normal)+- **Yellow** (`warn` class) — 51-80% usage+- **Red** (`danger` class) — > 80% usage++## What the tooltip shows++When you hover over the bars, a tooltip appears with:++| Line | Example |+|------|---------|+| Container | the workspace name |+| CPU + RAM totals | `CPU: 1.7% of 16 cores | RAM: 0.7 GB / 16.0 GB` |+| Disk | `Disk: 1.3 GB` (workspace disk usage) |+| Image | `Image: systemd-nspawn: Adom-Workspace` |+| ID | the registered workspace identifier |+| Created | `5/24/2026, 3:18:09 PM` (locale-formatted) |++If the workspace is in a non-healthy state, the tooltip shows a single red line instead:+- `Workspace is stopped: start from the menu` (when stopped)+- `Container runtime is broken, restart from the menu` (when the machine or code-server is unreachable)++## Status badge in the header++The **Adom** header carries a status word: `workspace stopped` (red), `workspace starting` / `workspace restarting` (yellow), `workspace restart needed` (red: the machine or code-server is unreachable), or `disk almost full` (the filesystem holding `/var/lib/machines` is nearly full). No word means it is running normally.++Fix: Adom menu > **Restart Container** (stops the machine through `machinectl` and starts it again; see `hydrogen-workspace-lifecycle`).++## How it works under the hood++- **Polling frequency**: see "How often it polls" above: 2 s when running, 5 s when not.+- **Backend command**: Tauri `invoke('get_container_stats')` → `WorkspaceRuntime::get_stats`, routed to the active host runtime's probe.+- **Two health levels** the probe checks: (1) is the host runtime itself available; (2) is the workspace registered + running with code-server reachable on host port 7380. If either fails, the probe returns a needs-restart signal instead of stats and the UI shows the red "restart needed" badge.++The authoritative "which runtime am I on" log line is `[app] Active workspace runtime: ...` (on Linux it names the nspawn host runtime).++## API access++If you want the same stats data your AI can hit directly via the control API:++```bash+# From inside the workspace — query the control API on the host+curl -s "$(cat ~/.adom/hydrogen-control-url)/container-stats"+```++(Read the live URL from `~/.adom/hydrogen-control-url` rather than hardcoding it — the port is **dynamic per launch**.)++Key fields on Linux:++| Field | Meaning |+|---|---|+| `runtime` | `"nspawn_host"` |+| `container_name`, `container_id` | `Adom-Workspace` |+| `image` | `"systemd-nspawn: Adom-Workspace"` |+| `image_note`, `image_version` | the golden image version (for example `v31-full`) |+| `stats_source` | `"cgroup"` |+| `cpu_percent`, `cpu_cores`, `mem_usage_mb`, `mem_limit_mb`, `mem_percent`, `oom_kills` | the workspace's own numbers |+| `disk_usage_mb` | the cached `du` result |+| `machine_mem_total_mb`, `machine_mem_avail_mb`, `machine_cpu_percent` | the whole PC |+| `app` | Hydrogen's own process tree |+| `host_disk` | free/total MB of the filesystem holding `/var/lib/machines` (`df`), behind the "disk almost full" badge |+| `internet_reachable` | can the workspace reach the internet |++Or if the workspace is in a broken state:+```json+{ "ok": false, "needs_restart": true, ... }+```++## CSS selectors++| Element | Selector |+|---------|----------|+| The whole indicator block | `.resource-bars` |+| Header with title + status badge | `.resource-bars-header` |+| Title text ("Container") | `.resource-bars-title` |+| One bar row (CPU or RAM) | `.resource-bar-item` |+| Bar fill | `.resource-bar-fill` (modifier classes: `.warn`, `.danger`) |+| App segment of a bar | `.seg-app` |+| Bar percentage label | `.resource-bar-value` |+| Hover tooltip container | `.resource-bars-tooltip` |+| One tooltip line | `.resource-bars-tooltip-row` |++## Common questions+++**"Why does RAM stay constant at ~4% even when I'm doing nothing?"** Code-server, the relay, the adom-vscode HTTP API, etc. all run in the workspace all the time. ~700 MB baseline is normal.++**"The workspace shows OOM kills."** Those are kills inside the workspace's cgroup. Kills of host programs (KiCad and others) are not counted here.++**"Disk is 1.3 GB — does that include my project files?"** Yes — `/home/adom/project` lives inside the workspace, so the `Disk:` figure includes your project.++## Related skills++- `[[hydrogen-workspace-monitoring]]` — the 15s state poll + floaty states behind these badges+- `[[hydrogen-container]]` — workspace context: relay, bridges, env vars+- `[[hydrogen-workspace-lifecycle]]`: start, stop, restart, reset+- `[[hydrogen-networking]]`: code-server on 7380, the control port
skills/hydrogen-container/SKILL.mdadded+143@@ -0,0 +1,143 @@+---+name: hydrogen-container+description: >-+ Facts about the Hydrogen workspace Claude runs in on Linux: the Adom-Workspace+ systemd-nspawn machine, Ubuntu 24.04, code-server, the golden image, setup+ steps instead of bootstrap.sh, bridges and the relay. Use when asked what+ environment am I in, on adom-cli errors, code-server or extension issues, or+ bridge and relay questions.+---++# Hydrogen Workspace++You are running inside **`Adom-Workspace`, a systemd-nspawn machine** that Hydrogen (ah) runs on the user's Linux desktop. It is a container on the host's own kernel, not a VM. Hydrogen manages it, provides VS Code + Claude Code, and talks to it over the shared loopback.++## The workspace — exact facts (don't guess)++| Field | Value |+|-------|-------|+| Machine name | `Adom-Workspace` (fixed; `machinectl list` on the host shows it) |+| Made from | the golden rootfs `adom-golden.tar.gz` (currently `v31-full`), unpacked by Hydrogen's root helper into `/var/lib/machines/Adom-Workspace` on the host |+| Base | Ubuntu 24.04 |+| Init and kernel | systemd as PID 1, on the host's kernel (`uname -r` shows the host kernel; `systemd-detect-virt` says `systemd-nspawn`) |+| Hostname | the host's own name (the helper writes it into the machine at start) |+| code-server | systemd unit `code-server.service`, `--bind-addr 127.0.0.1:7380 --auth none`, binary `/usr/bin/code-server` |+| Extensions dir | `~/.local/share/code-server/extensions/` |+| Settings | `~/.local/share/code-server/User/settings.json` |+| Work user | `adom` (UID 1001, passwordless sudo, home `/home/adom`); uids are not remapped |+| Workspace | `/home/adom/project` |+| Host paths | `/mnt/host/home` (host `/home`, read-write), `/mnt/host/tmp` (host `/tmp`), `/mnt/host/usr` and `/mnt/host/opt` (read-only). The workspace itself is a plain directory in the machine's rootfs on the host disk. |+| `/tmp` | a tmpfs inside the machine (25% of RAM), empty after every machine restart |+| Pre-installed | Node + npm, Python 3.12 with `requests`, `yaml`, `bs4`, `lxml`, `pillow`, git, gh, curl, wget, jq, unzip, zip. **No C/C++ toolchain.** |+| Host side | `/usr/libexec/adom-hydrogen/hydrogen-workspace`, the root helper Hydrogen runs through `sudo -n` for start, stop, exec, import and remove |++Confirm with `cat /etc/os-release`, `systemd-detect-virt`, `code-server --version`.++## Installing packages (you have passwordless sudo)++**Python: Ubuntu 24.04 is PEP-668 "externally-managed"**, so `pip install <x>` fails. Prefer `sudo apt-get install -y python3-<lib>`; otherwise `pip install --break-system-packages <lib>`, a venv, or `pipx`. **Node:** `npm i -g <pkg>`. **System:** `sudo apt-get install -y <pkg>` (add `build-essential` first if something must compile).++## Setup is via Hydrogen's setup-steps, NOT a bootstrap script++Hydrogen provisions the machine through its setup cascade (the `hydrogen-setup` crate; Linux host prep in `hydrogen-runtime/src/runtime/linux.rs`). The first step, `ensure-workspace`, makes the host ready (systemd-container, the helper, its sudoers rule, at most one password prompt), then imports the golden image if the machine does not exist yet. Most tooling is baked into the image, not installed by a step. See `hydrogen-setup-steps`. Hydrogen never runs `bootstrap.sh`.++## VS Code extension caveats++- The Claude Code extension and `code-server` settings (including `extensions.autoUpdate: true` / `extensions.autoCheckUpdates: true`) are BAKED into the golden image — there is no `write-vscode-settings` or `install-claude-ext` setup step. Auto-update **must** stay on so every installed extension auto-updates from the marketplace; the image bakes it on. Do not regress this.+- Bare `code-server --install-extension <id>` (no version pin) historically resolves to the **universal** target-platform build. For some extensions (notably `anthropic.claude-code` after 2.1.89), Anthropic stopped shipping universal builds — so bare install permanently sticks at 2.1.89 even when newer per-arch builds exist. The golden-image bake installs the latest per-arch build pinned, so the workspace ships current. It also heals orphan `extensions.json` entries (entries pointing to deleted dirs cause a permanent "Invalid extensions detected" banner).+- The marketplace is Open VSX, through Hydrogen's `/gallery` endpoint (`EXTENSIONS_GALLERY` in code-server's unit environment).++## adom-cli is authenticated++Hydrogen auto-injects the user's session token on every launch. To verify:+```bash+adom-cli carbon user get+```+If this returns user data, all adom-cli commands work (containers, repos, orgs, wiki, etc.). If it fails, the user needs to log in via Hydrogen's login page.++## Relay server is running++The adom-bridge relay runs in the workspace (`adom-relay.service`, 8765 WebSocket / 8766 HTTP).++Check health: `curl -sf http://127.0.0.1:8766/health`+Check desktop connection: `adom-bridge ping`++The machine shares the host's network namespace, so `127.0.0.1` is the same on both sides.+The host control API is reachable from inside the workspace at `127.0.0.1`. The port is dynamic per launch, so read the live URL from `~/.adom/hydrogen-control-url` (`http://127.0.0.1:<dynamic>`): `BASE="$(cat ~/.adom/hydrogen-control-url)"; curl "$BASE/health"`.++## Bridges++Hydrogen installs and starts Adom Bridge (ab) on this Linux desktop when a Linux build is published for the user's account. The verbs below work while it runs here (`GET /ab/health` tells you), or when you address another of the user's machines (for example their Windows PC) through the Adom mesh with `adom-bridge --target <name>`. Fusion 360 and the window-handle verbs need a Windows machine. Check with `adom-bridge ping` and `adom-bridge targets`; see `hydrogen-bridges`. Host files for a local bridge are plain Linux paths (`/home/<user>/...`).++### Screenshots (zero dialogs, instant)+```bash+adom-bridge desktop_screenshot_screen # full screen capture+adom-bridge desktop_screenshot_screen '{"maxWidth":1500}' # resized for Claude vision+adom-bridge desktop_screenshot_window '{"hwnd": N}' # capture specific window+adom-bridge desktop_list_windows # list all windows with handles+```+Default to `maxWidth: 1500, format: "png"` for UI screenshots. Use `"jpeg"` for natural photos, `"webp"` for smaller files.++### Browser automation (Puppeteer)+```bash+adom-bridge pup_open_window '{"url": "https://..."}'+adom-bridge pup_screenshot '{"sessionId": "default"}'+adom-bridge pup_eval '{"js": "document.title"}'+adom-bridge pup_navigate '{"url": "..."}'+```++### KiCad bridge+```bash+adom-bridge kicad_open_board '{"path": "/path/to/board.kicad_pcb"}'+adom-bridge kicad_screenshot_all+adom-bridge kicad_run_drc '{"path": "..."}'+adom-bridge kicad_window_info+```+(Paths to host files use the host's native path convention.)++### Fusion 360 bridge+```bash+adom-bridge fusion_start+adom-bridge fusion_import_step '{"path": "..."}'+adom-bridge fusion_export_step '{"path": "..."}'+```++### File transfer+```bash+adom-bridge send_files '{"files": [{"path": "/home/adom/file.txt"}]}'+adom-bridge pull_file '{"remotePath": "<host path>", "localPath": "/tmp/file.txt"}'+```++### Desktop interaction+```bash+adom-bridge notify_user '{"message": "Build complete", "duration_ms": 3000}'+adom-bridge desktop_open_url '{"url": "https://..."}'+adom-bridge desktop_open_folder '{"path": "<host folder path>"}'+```++## What's different from Adom cloud containers++| Feature | Adom Cloud | Hydrogen local (Linux) |+|---------|-----------|-----------------|+| Workspace provisioning | Adom platform API | golden rootfs unpacked into a systemd-nspawn machine on the user's PC |+| Relay connection | wss:// through Cloudflare | ws://localhost:8765 (direct, no TLS) |+| Bridge latency | ~50-100ms (internet round-trip) | <1ms (localhost) |+| VSCODE_PROXY_URI | forwarded-port URL template | `http://{{port}}.localhost:<proxy port>/` (Hydrogen's reverse proxy); since the network is shared, `http://localhost:<port>/` also works directly |+| Socket.IO (collab) | Connected to iron.adom.inc | Disabled (single-user) |+| Service containers | Adjacent containers | Remote via Adom cloud |++## Environment variables++- `ADOM_DESKTOP_MODE=local` — indicates Hydrogen local mode+- `VSCODE_PROXY_URI=http://{{port}}.localhost:<proxy port>/` (Hydrogen 1.0.224+): the URL template for a forwarded port, served by Hydrogen's own reverse proxy with the app's paths untouched, so web apps that load assets by absolute path (Google Antigravity's side bar) work. The path form `http://localhost:7380/proxy/<port>/` still works when typed by hand. Before 1.0.224 the template was that path form. Code-server's proxy++- `ADOM_HD_CONTROL_URL`, `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `VSCODE_PROXY_URI`: written to `~/.bashrc` and code-server's unit, so AI shells inherit them.+- Commands Hydrogen runs through its helper also carry `HYDROGEN_HOST=linux` and `WSL_DISTRO_NAME=Adom-Workspace` (a compatibility name, not a sign of any other runtime).++## Related skills++- `[[hydrogen-container-stats]]` — the title-bar CPU/RAM indicator for this workspace+- `[[hydrogen-setup-steps]]` — what each setup step did to prepare your workspace+- `[[hydrogen-topology]]`: the layers and where commands run+- `[[hydrogen-volume]]`: where your files live and how to copy them out+- `[[hydrogen-workspace-lifecycle]]`: start, stop, restart, reset
skills/hydrogen-demo-recording/SKILL.mdadded+126@@ -0,0 +1,126 @@+---+name: hydrogen-demo-recording+description: >-+ Recipe for recording a Hydrogen demo video on Linux: human-typed prompt into+ a Claude tab, the user's desktop screen recorder (Hydrogen has no native+ recorder on Linux), getting the file into the workspace, then 10-30x speedup+ and an adom-tts voiceover. Use when asked to record a demo, make a demo video+ of an app, or show what the app feels like.+---++# hydrogen-demo-recording: a Hydrogen demo video on Linux++The canonical Adom demo: the viewer watches an AI prompt get TYPED into Hydrogen+Desktop, watches the AI do the work, and hears a narrator explain it, all in a tight+sped-up clip. This skill is the full pipeline. It exists because every piece is easy+to get slightly wrong and the pieces live in four different tools.++**On Linux Hydrogen cannot record the screen itself** (`/recording/native/*` answers `ok:false`,+native recording is not on this platform; see hydrogen-recording). The user records with their+desktop's own recorder while you drive Hydrogen. Everything else in the pipeline is the same.++The shape of every demo:++1. The user starts their screen recorder (GNOME: Ctrl+Shift+Alt+R, or the screenshot+ tool's video toggle; OBS anywhere).+2. Type the prompt into a Claude tab with VISIBLE typing (the sexy part) and submit.+3. Let the AI's output stream on camera.+4. The user stops the recorder; you fetch the file.+5. Post-production: speed up 10x to 30x (adom-video-post), overlay adom-tts narration.++## Step 0: pick your calling transport++Everything below is Hydrogen control-API calls. Inside the workspace the live base URL is+in a file, never an env var:++```bash+CTRL=$(cat ~/.adom/hydrogen-control-url)+curl -s -X POST "$CTRL/claude/inject" -H 'Content-Type: application/json' -d '{...}'+```++## Step 1: preflight (30 seconds, saves the take)++- `GET /health` answers with service `hydrogen-desktop-control` (not the SPA).+- `GET /claude/auth-check`: Claude is signed in (a demo of a sign-in wall is not a demo).+- Tell the user exactly when to start recording, and wait for their go.++## Step 2: type the prompt(s) on camera++One call per prompt opens a NEW Claude tab, waits for its compose box, types with+human jitter, and submits:++```json+POST /claude/new-chat-and-send+{"text":"<the demo prompt>","typed":true,"submit":true,"delay_ms":35}+```++- `typed:true` is the visible typing (about `delay_ms` per char with 50 percent+ jitter). `typed:false` pastes instantly: fine for seeding, boring on camera.+- The call BLOCKS until typing completes: perfect for sequencing. If your call times out+ on a long prompt, the typing still finishes on Hydrogen's side. Do NOT re-fire.+ Confirm with `GET /claude/conversation-state` (turns went up), then continue.+ Keep prompts short enough to type in under about 20 seconds.+- Single-prompt demo into the CURRENT tab instead: `POST /claude/inject` with the+ same body shape.++**Multi-prompt demos** (the 5-tabs pattern): repeat the call once per prompt (each+opens its own tab), then flip through the finished answers on camera with the+BACKGROUND tab switch:++```json+POST /claude/tabs/activate {"index":0} // 0-based; or {"label":"substring"}+```++Verify each switch took with `GET /claude/tabs` (`active:true` moved). Pause a few+seconds per tab so the sped-up video gives each answer screen time.+`GET /claude/conversations` gives per-tab context_ids if you want to seed specific+tabs deterministically (`/claude/inject` with `context_index`).++On Linux this automation runs over Hydrogen's frame bus (WebKitGTK has no DevTools+protocol). Do one dry run before the user records, and look at the result with+`POST /screenshot` (a snapshot of the whole Hydrogen window).++## Step 3: collect the video++GNOME saves to the host user's `~/Videos/Screencasts/`, which the workspace sees at+`/mnt/host/home/<host user>/Videos/Screencasts/`. If that is "Permission denied", ask the+user to copy the file to `/tmp` on their desktop and read it from `/mnt/host/tmp/`. Copy it+into `~/project/recordings/`. GNOME writes WebM; convert to h264 mp4 for the wiki:++```bash+sudo apt-get install -y ffmpeg # once; not preinstalled+ffmpeg -i in.webm -c:v libx264 -pix_fmt yuv420p -c:a aac out.mp4+```++## Step 4: post-production++- **Speedup**: the `adom-video-post` skill owns this. The house style is 10x for demos+ where the output matters, 30x for long AI work sessions. Keep the typing segment+ readable (video-post can ramp: normal speed on the typing, fast on the waiting).+- **Narration**: synthesize with `adom-tts say` (it pronounces Adom terms correctly+ and caches repeats), then video-post mixes it as the audio track. Write narration+ that explains what the viewer is SEEING at each sped-up moment.+- **Recording choreography** (captions, panel staging, what makes a take clean) lives+ in the `demo-recording` skill; read it for anything fancier than a single-window take.++## Known hazards++- **A Hydrogen restart mid-take resets the demo tabs.** Do not run a demo while anyone+ (another AI thread too) is relaunching Hydrogen on the same machine.+- Tab state reads (`GET /claude/tabs`) are DOM reads: labels can be briefly empty+ while the editor reloads. Prefer `GET /claude/conversations` for stable+ context_ids + titles.++## Safety and cleanup (non-negotiable)++- These endpoints are disruptive tier and their responses carry a `_safety` block:+ you are typing into the user's REAL Claude panel (each submitted prompt SPENDS a+ real turn; a 5-prompt demo spends 5). Only do it for a demo the user asked for.+- NEVER call `/claude/tabs/close-all` to clean up: it closes the user's own tabs+ too. There is no per-tab close; leave demo tabs open and tell the user they exist.+- Delete junk takes you pulled; do not litter recordings/ with failed attempts.++## Related++hydrogen-recording (what records on Linux), hydrogen-self-screenshot, demo-recording,+adom-video-post, adom-tts.
skills/hydrogen-desktop-sse/SKILL.mdadded+228@@ -0,0 +1,228 @@+---+name: hydrogen-desktop-sse+description: >-+ How Hydrogen's local workspace API and SSE stream work on Linux, so the+ workspace's adom-cli controls Hydrogen instead of the cloud: routing, env+ vars, port discovery, field formats. Use for Hydrogen SSE, the workspace API,+ add-tab or move-tab, EventSource, ADOM_HYDROGEN_URL, ports.json, or the+ discovery port.+---++# Hydrogen on Linux: Local Workspace API + SSE++## Architecture++```+Workspace adom-cli (the systemd-nspawn machine Adom-Workspace)+ → http://127.0.0.1:47083 (Hydrogen's proxy)+ → Hydrogen handles workspace commands locally + broadcasts SSE+ → Hydrogen frontend receives SSE, re-fetches workspace, renders++Cloud Docker's adom-cli (unchanged)+ → carbon.adom.inc → Hydrogen web+```++Hydrogen runs its own workspace API on port 47083 (the reverse proxy's default; see PortConfig) so the workspace's adom-cli controls Hydrogen's UI, not cloud Hydrogen. No cross-talk between environments.++The workspace machine shares the host's network namespace, so `127.0.0.1` is the same inside+the workspace and on the host: the workspace reaches Hydrogen's proxy and control API at+`127.0.0.1:<port>` with no host IP and no `/proxy/` hop, and Hydrogen reaches workspace+services the same way. Workspace ports are blocked from the LAN by Hydrogen's firewall table.++## Port 47083 routing (the hydrogen-proxy / reverse-proxy)++All requests hit port 47083 (reverse proxy, default — see PortConfig). The router in `handle_request()` decides:++| Path pattern | Handler | Where |+|---|---|---|+| `/api/workspaces/editor/{owner}/{repo}/current/*` | Local workspace API | In-memory |+| `/api/panels/webview/*`, `/api/panels/sandbox/*` | Local panel API | SSE broadcast |+| `/containers/*` | Local container discovery | Canned response |+| `/proxy/{port}/{path}` | Workspace proxy | Forward to that port in the workspace |+| `<port>.localhost:<proxy>` (Host header) | Subdomain form of the same forward | Forward to that port in the workspace |+| Everything else (`/api/*`, etc.) | Carbon proxy | HTTPS to carbon.adom.inc |++The dev file server on port 1420 forwards `/api/*` directly to `handle_request()` (same function, not TCP — supports SSE streaming via BoxBody).++## SSE Connection++**Endpoint:** `GET /api/workspaces/editor/{owner}/{repo}/current/events`++Uses `tokio::sync::broadcast` channel. On connect sends `{"type":"connected","connectionId":"hydrogen-local"}`. Workspace mutations broadcast `{"type":"workspace_updated"}`.++Other event types: `caption`, `nav`, `tab_alert`, `notification_request`,+`screenshot_request`, `audio_request`, `recording_request`.++**Frontend connects** in `PanelWorkspaceComponent.svelte` → `setupSSE()`. In Tauri mode, `$page.params` may be empty (adapter-static), so it falls back to `owner=local, repo=workspace`.++**Critical lesson:** The `onopen` handler PUTs the workspace state. This broadcasts `workspace_updated`, which the frontend re-fetches. Set `skipNextSSESync = true` before the PUT to prevent the feedback loop that kills the connection.++## Container Discovery++adom-cli calls `/containers/{slug}` to get owner/repo. Any slug gets the same answer.++**Response format** (must match Carbon's exactly):+```json+{+ "repository": {+ "owner": { "name": "jlauer12" },+ "name": "workspace"+ },+ "slug": "hdlocal",+ "status": "running"+}+```++NOT `{"owner": "jlauer12", "repository": "workspace"}` — adom-cli reads `container["repository"]["owner"]["name"]`.++## Workspace Env Vars++Hydrogen rewrites these on every launch (the ports are dynamic) into `~/.bashrc`,+`/etc/profile.d/hd-env.sh` and a code-server systemd drop-in, so every shell and every AI+tool call inherits them:++| Var | Value | Why |+|---|---|---|+| `ADOM_HYDROGEN_URL` | `http://127.0.0.1:<proxy>` | Workspace mutations (adom-cli sends these HERE, not to Carbon) |+| `ADOM_CARBON_URL` | `http://127.0.0.1:<proxy>` | Container discovery + non-workspace API |+| `ADOM_HD_CONTROL_URL` | `http://127.0.0.1:<control>` | Hydrogen's control API (`/ui/*`, `/ports/all`, `/claude/*`) |+| `VSCODE_PROXY_URI` | `http://{{port}}.localhost:<proxy>/` | What code-server hands extensions for a forwarded port |+| `ADOM_DESKTOP_MODE` | `local` | Tells adom-cli it's a local environment |++Discovery files in the workspace, rewritten each launch: `~/.adom/hydrogen-control-url`+(the control URL, normally `http://127.0.0.1:47084`), `~/.adom/hd-proxy-url`, and+`~/.adom/hydrogen-ports.json` (`hostname`, `control`, `proxy`, `cdp`, `code_server`).+Relay ports: `~/.adom/cli-relay-ports.json` (fallback 8765 WS / 8766 HTTP).++The API key at `/var/run/adom/api-key` comes from `GET "$(cat ~/.adom/hydrogen-control-url)/auth-token"`.++## Workspace Tree Format++The frontend serializes splits with `first`/`second`, NOT `children`:+```json+{+ "type": "split",+ "id": "desktop-root-split",+ "direction": "horizontal",+ "ratio": 0.5,+ "first": { "type": "leaf", "id": "pane-left", ... },+ "second": { "type": "leaf", "id": "pane-right", ... }+}+```++All tree traversal functions (`find_leaf_path`, `find_split_path`, `resolve_path`) must handle BOTH `children` array and `first`/`second` keys.++## REST Endpoint Field Names (adom-cli vs Hydrogen)++adom-cli sends different field names than you might expect:++| Endpoint | adom-cli sends | Hydrogen must read |+|---|---|---|+| POST /tabs | `{panelId, panelType, displayName, initialState}` | Construct tab with UUID, merge initialState into panelState |+| POST /moves | `{sourcePanelId, tabId, targetPanelId}` | NOT `sourcePanel`/`targetPanel` |+| DELETE /tabs | `{panelId, tabId}` or `{name}` | Support both |++## Smoke Test (from inside the workspace)++```bash+# 1. Probe — confirms SSE alive+adom-cli hydrogen probe+# → browser_connected: true, sse_connections: 1++# 2. Get workspace+adom-cli hydrogen workspace get++# 3. Add tab+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.adom.inc/adom/adom-shotlog"}'++# 4. Move tab+adom-cli hydrogen workspace move-tab \+ --from-panel-id desktop-pane-right \+ --tab-id <tab-id-from-step-3> \+ --to-panel-id desktop-pane-left++# 5. Screenshot to verify+curl -s -X POST "$(cat ~/.adom/hydrogen-control-url)/screenshot" -H 'Content-Type: application/json' -d '{}'+```++## What Broke and Why++### SSE never connected on fresh launch+`setupSSE()` checks `$page.params.owner` and `$page.params.repo`. In Tauri mode with adapter-static, these are empty. **Fix:** fall back to `owner=local, repo=workspace` when in Tauri mode.++### SSE connected then immediately disconnected+The `onopen` handler PUTs workspace state → broadcasts `workspace_updated` → frontend re-fetches → gets the state it just PUT → re-applies → triggers autosave → another PUT → loop. **Fix:** set `skipNextSSESync = true` before the `onopen` PUT.++### adom-cli "Could not get owner from container info"+Three stacked issues:+1. `VSCODE_PROXY_URI` was `http://localhost:8080/...` → slug parsed as `8080` → called `/containers/8080` → Carbon 404+2. Container info response had flat `{"owner": "..."}` but adom-cli reads `container["repository"]["owner"]["name"]`+3. `ADOM_HYDROGEN_URL` wasn't set → workspace commands went to `hydrogen.adom.inc` instead of Hydrogen++### add-tab returned "Missing 'tab' in body"+Hydrogen expected `{"panelId", "tab": {id, panelType, panelState}}` but adom-cli sends `{"panelId", "panelType", "displayName", "initialState"}` — flat format. **Fix:** accept both, construct tab with UUID for the flat format.++### move-tab returned "Source/target panel not found"+Two issues:+1. Handler read `sourcePanel`/`targetPanel` but adom-cli sends `sourcePanelId`/`targetPanelId`+2. `find_leaf_path` only traversed `children` array, not `first`/`second` keys++### Google showed "blocked" icon+Not a Hydrogen bug. Google sends `X-Frame-Options: SAMEORIGIN` which prevents iframe embedding. Sites that allow embedding (adom.inc, wiki) load fine.++## Port Discovery — How Any Client Finds Hydrogen++Host-side ports are dynamic. The config is `~/.config/hydrogen-desktop/ports.json` on the+host, rewritten every launch (control prefers 47084, proxy 47083, code-server 7380). Ways in,+best first:++1. Inside the workspace: `~/.adom/hydrogen-control-url` / `$ADOM_HD_CONTROL_URL`.+2. Discovery responder: `GET http://127.0.0.1:<c>/` for c in 47080, 48080, 49180, 50280+ (first that answers). Any path works; the JSON carries `control`, `control_url`, `proxy`,+ `code_server`, `hostname`.+3. From anywhere (another machine, the cloud): the Adom key-value store entry+ `hydrogen.runtime.<hostname>`, published every launch.++Then `GET <control_url>/ports/all` returns the whole port map.++### Implementation++Tiny `std::net::TcpListener` on port 47080 in `hydrogen-app/src/lib.rs`. Runs on a plain OS thread (no tokio). Reads `get_runtime_ports()` on each request. Returns raw HTTP response with JSON body.++```rust+std::thread::spawn(move || {+ let listener = std::net::TcpListener::bind("127.0.0.1:47080").unwrap();+ for stream in listener.incoming() {+ let ports = hd_control::get_runtime_ports();+ let body = serde_json::json!({ "ok": true, ...ports });+ // write HTTP/1.1 200 OK + JSON+ }+});+```++### Port defaults (PortConfig)++| Service | Default | Notes |+|---|---|---|+| Discovery | 47080 (walks 48080, 49180, 50280) | fixed candidate list |+| Proxy | 47083 | dynamic |+| Control API | 47084 | dynamic |+| code-server | 7380 | inside the workspace, 127.0.0.1 only |+| Relay WS / HTTP | 8765 / 8766 | inside the workspace, same port from the host |+| `cdp` field | 47085 | nothing listens on Linux: WebKitGTK has no DevTools protocol; Hydrogen's frame bus does that job (`POST /eval`, `/screenshot`) |++## Files++| File | What |+|---|---|+| `src-tauri/crates/hydrogen-proxy/src/lib.rs` | Workspace API, SSE, Carbon proxy, tree mutations (~1500 lines) |+| `src-tauri/crates/hydrogen-control/src/lib.rs` | `/auth-token` endpoint, `/ports` endpoint, `/setup/*` routes |+| `src-tauri/crates/hydrogen-control-core/src/ports.rs` | PortConfig load/save/resolve, the discovery candidates |+| `src-tauri/crates/hydrogen-app/src/lib.rs` | Discovery server on :47080, port resolution at startup |+| `src/lib/stores/portStore.ts` | Frontend Svelte store, `initPorts()`, `controlUrl()`, `codeServerUrl()` |+| `src/lib/components/editor/workspaces/PanelWorkspaceComponent.svelte` | Frontend SSE setup, autosave, workspace re-fetch |+| `src-tauri/crates/hydrogen-runtime/src/runtime/` | `refresh_distro_env()`: the env vars and discovery files above |
skills/hydrogen-dock/SKILL.mdadded+284@@ -0,0 +1,284 @@+---+name: hydrogen-dock+description: >-+ The Hydrogen dock bar (the app launcher rail on the right edge), how any wiki app+ becomes a card in it through a dockbar.json manifest, and how to drive it from an AI+ thread (/dock/* API). Use when asked to add my app to the dock, why my dock card does not+ work, set launch steps or an AI thread on launch, launch or relaunch a dock app, reset or+ customize my dock.+---++# hydrogen-dock: the Hydrogen app launcher++The dock is the launcher rail on the right edge of the Hydrogen workspace.+Since 1.0.140 it is **visible after startup by default** (so new users meet it), then+auto-collapses after an app launch; "Start with the dock collapsed" and the other+visibility behaviors live in Dock settings (the gear at the top of the rail). Every+card in it is a wiki app page. **Any public wiki app can be a dock card**, and+users can add one themselves without anybody's permission.++The dock resolves what to SHOW (name, brief, hero) from the page itself, and how+to LAUNCH from a `dockbar.json` manifest at the root of the app's wiki page repo.+Display is never duplicated into the manifest; the page is the single source of+truth.++**THE FULL PUBLISHER CONTRACT IS THE DOCK BAR GUIDE:**+https://wiki.adom.inc/adom/hydrogen/files/docs/dockbar.md++This skill is the working summary plus the traps. Send anyone writing a manifest+to the Dock Bar guide.++## Adding an app to a user's dock (the common request)++1. Confirm the page exists and is public (`adom-wiki discover search -q <term>`).+2. Dock settings (the gear at the top of the rail) → Add app → `owner/slug`.+3. If the page has no manifest, the card still works: it opens the wiki page.+ Tell the user that launch steps need a `dockbar.json` and point the publisher at+ the Dock Bar guide.++## The manifest, in one screen++```json+{+ "dock_manifest": "1.2.0",+ "webview": { "title": "My App", "favicon": "icons/app.svg" },+ "launch": {+ "mode": "container_command",+ "console": "show",+ "steps": [+ { "label": "Installing My App",+ "run": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; adom-wiki pkg install me/my-app'",+ "skip_if": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; command -v my-app'",+ "timeout_seconds": 180 },+ { "label": "Starting My App",+ "run": "sh -c 'PATH=\"$HOME/.local/bin:$PATH\"; exec my-app serve --print-url'",+ "await": "url",+ "timeout_seconds": 60 }+ ],+ "on_ready": "navigate_placeholder",+ "ai": {+ "prompt": "The user just opened My App from the dock.",+ "thread": "existing",+ "thread_fallback": "new",+ "submit": "staged"+ }+ }+}+```++Discovery order, first match wins: root `dockbar.json` only (dock.json support removed), then+`dockbar.json` in a sub-folder (depth 2 max, never `node_modules` or dot-folders).++`mode` is `container_command` (run steps, then show a URL), `webview` (load+`webview.url` directly, no steps), or `ai_thread` (no webview at all, the click+opens a thread).++## ⛔ The two rules that break every first attempt++**1. A serve verb MUST self-background.** Hydrogen runs the step synchronously+and waits for it to EXIT before reading stdout. A server that stays in the+foreground blocks the exec for the whole `timeout_seconds`, then the exec times+out and KILLS it, so the URL it printed is dead by the time Hydrogen polls it.+The launch fails with "started, but <url> never answered".++The tell: the server is healthy when run by hand and dead when the dock runs it.++**2. Steps must set PATH.** Wiki-installed CLIs land in `~/.local/bin`, which is+NOT on the PATH of the shell the workspace exec uses. A step calling the app's+own CLI by bare name fails with `command not found` (exit 127) on every machine+except the developer's, where it usually happens to be on PATH already. That+also makes `skip_if` report "installed" for the author and "missing" for users.++Both bundled bridges shipped both bugs. Check these two first when a card fails.++Two contracts that ride with the rules (full detail in the Dock Bar guide):++- **Print the DIRECT URL** `http://127.0.0.1:<port>/`. The workspace shares this computer's+ network, so a workspace port IS a host localhost port (see `hydrogen-networking`). Never the+ `:7380/proxy/<port>/` form.+- **The webview belongs to your CLI.** Every step runs with+ `ADOM_DOCK_WEBVIEW` (the tab the dock pre-opened) and `ADOM_DOCK_APP` in its+ environment; once serving, take the tab over with+ `adom-cli hydrogen webview open-or-refresh --name "$ADOM_DOCK_WEBVIEW" --url ...`+ and drive it yourself from then on. The printed URL is only the dock's+ readiness gate.++## What a click does++```+click ─▶ already open? ─▶ YES: close that tab first (re-click = relaunch, below)+ │+ placeholder webview opens instantly (theme bg + orbital animation, free)+ ├─ steps run in order, transcript streaming into the placeholder console+ ├─ await:"url" scrapes the app URL from stdout+ ├─ Hydrogen polls it until it answers (budget = that step's timeout_seconds)+ │ never answers ─▶ the launch FAILS loudly; it does not navigate to a+ │ dead URL and claim success+ ├─ on_ready: navigate_placeholder (show the URL) | hand_to_ai+ └─ ai block, if present: opens or reuses this app's own named thread+```++The `ai` block is its OWN branch, not an alternative to `on_ready`: an app can+show its dashboard AND open a thread about it.++**Re-click relaunches (since 1.0.211).** A click on an app whose tab is open+closes that webview, recreates it and runs the manifest steps again in the+container, so what appears is always the current code. This is deliberate: an+AI iterating on a dashboard could never tell whether a click showed its latest+work or the tab from before its change. The dock finds the tab by+`webview.title` against the live workspace layout, so it holds even after a+Hydrogen reload; publishers must keep `webview.title` stable or the old tab+survives next to the new one. A serve step is expected to be idempotent for+this (the bridge's version-aware serve retires its old instance).++## The ai block++| Field | Default | Meaning |+|---|---|---|+| `prompt` | app-naming default | The pre-canned prompt |+| `thread` | `"new"` | `"existing"` reuses THIS app's own thread, found by the name the dock gave it |+| `thread_fallback` | `"new"` | When `existing` finds none: `new`, or `current` (whatever is open) |+| `submit` | `"staged"` | `staged` waits in the input for the user; `auto` sends immediately |++Threads are opened, named and injected through the AI Threads API, so the thread+is named after the app (visible in the AI Threads panel, durable across+restarts), and injection is BACKGROUND: relaunching an app never steals focus+from whatever the user is typing. `ai.typed` is accepted and ignored.++## The loading screen is free++The instant a launch involves a webview, Hydrogen paints the panel with the theme+background and runs the Adom orbital animation until the app URL truly loads.+Apps bundle nothing and opt into nothing. `launch.console: "hide"` mutes the+command transcript (never the failures) when the output would be noise.++## Driving the dock from an AI thread++The control API presses the dock for you (`BASE="$(cat ~/.adom/hydrogen-control-url)"`):++| call | what it does |+|---|---|+| `GET /dock/apps` | every app: `id`, `wiki_repo`, `name`, `mode`, `running`, `launching`, `tab_open`, `url`, `health`, `last_launch` |+| `POST /dock/launch {id, relaunch?, timeoutSec?}` | presses the button (relaunch by default), waits (default 240 s) and returns `ok`, `url`, `reason`, `console` (the transcript, failing step verbatim) |+| `POST /dock/close {id}` | removes the app's tab; does not stop its container process |+| `POST /dock/refresh {full?}` | re-reads the curated apps.json now (`full:true` also every display, manifest and hero) |+| `POST /dock/reset` | back to defaults: drops locally added apps, pins, draft manifest URL, rail width and caches; Settings > Dock Bar toggles stay |++`id` is the dock id (`kicad`, `nb`, `codex`), the wiki repo or its slug. Look at the result with+`POST /screenshot {"target":"tab","title":"<name>","b64":true}`: the PNG comes back inline as+`dataUrl` (the whole Hydrogen window on Linux). Without `"b64":true` you only get a path on the+host (`~/.config/hydrogen-desktop/shots/`), which the workspace cannot open. To keep the picture,+decode it: `curl -s -X POST "$BASE/screenshot" -d '{"b64":true}' | python3 -c 'import sys,json,base64;+open("shot.png","wb").write(base64.b64decode(json.load(sys.stdin)["dataUrl"].split(",",1)[1]))'`.++What `ok:false` means, by `reason`: a step returned non-zero (its stderr is in `console`,+prefixed `stderr:`), the serve step printed no URL, the URL never answered within the+step's budget, or no webview tab could be opened. A `pending:true` answer means the+launch outran `timeoutSec`, not that it failed: `GET /dock/apps` shows it still+`launching`, and a first install of a bridge legitimately takes minutes.++The launch runs the same code path as a click, in the same shell webview, so a launch+that works through the API works for the user, and vice versa.++## Testing a draft++- **Per-app, instant:** Dock settings → Add app → `owner/slug` reads the live+ manifest immediately. Fastest loop.+- **Run the steps by hand in the container first**, exactly as written, and check+ the serve step RETURNS instead of blocking.+- **Whole-list draft:** Dock settings → Manifest URL (draft) points the dock at+ any `apps.json`. A DRAFT badge stays on the rail while active.++## Troubleshooting by symptom++| Symptom | Cause |+|---|---|+| `command not found`, exit 127 | PATH: `~/.local/bin` is not on the exec shell's PATH |+| "started, but <url> never answered" | The serve command did not self-background |+| "no URL within Ns" | Nothing matching `https?://\S+` on stdout (printed to stderr?) |+| Install step runs every launch | `skip_if` missing or probing the wrong name |+| LED red "not answering" while the server answers curl | Health endpoint lacks `Access-Control-Allow-Origin: *` (the dock probes cross-origin from the shell) |+| A duplicate tab appears | `webview.title` changed between versions |+| The `ai` prompt never fires | `mode: "webview"` has no steps and no ai branch |+| Works for the author, fails for users | Tested where the CLI was already installed |++## The right-click menu (and Hard Refresh Open)++Right-clicking a dock card opens a per-app menu; right-clicking empty rail space opens the+dock-wide one.++| Item | What it does |+|---|---|+| **Open** | Same as a left click: relaunch it (close the tab, run the steps again), or launch it. |+| **Hard Refresh Open** | The from-scratch relaunch for ONE app. Closes that app's webview if open, forgets its running state and health reading, drops its cached manifest AND display entry (name, brief, hero), re-resolves both from the wiki, then launches with a forced `adom-wiki pkg update <owner/slug> \|\| pkg install <owner/slug>` step ahead of the manifest's own steps, streaming into the launch console like any other step. The app's version-aware serve retires the old instance. Use it when an app just published a fix, when a card shows a stale hero, or when an install looks wedged. |+| **Pin to Dock / Unpin** | Pin the card to the top of the rail. |+| *(empty rail)* **Refresh list from wiki** | Dock-wide: blanks every card, wipes the display and manifest caches, and reloads the curated list, all manifests and all heroes from scratch. |+| *(empty rail)* **Reset to defaults** | Dock-wide: drops locally added apps, pins, the draft manifest URL, rail width and caches (`POST /dock/reset`); Settings > Dock Bar toggles stay. |++Hard Refresh Open is deliberately update-then-relaunch rather than uninstall-then-reinstall:+it gets the same freshness without discarding the app's installed skills and settings. A+genuinely corrupt install is a manual `pkg uninstall` followed by a normal click.++**Publishers:** this is how a user picks up your newest release without waiting for a cache+to expire, so the install-or-update step pattern matters (never pin a version with+`skip_if`, or the update step no-ops and your fix never lands).++## What you can change WITHOUT a new ah build++The dock is three layers and only one of them is compiled into the app. Knowing which is+which decides whether a change ships in minutes or waits for a release.++| Layer | Where it lives | To change it |+|---|---|---|+| **Which apps appear**, order, featured | `apps.json` in the `hydrogen-bootstrap` page repo | push to the wiki. Every dock re-polls on `poll_seconds` (default 6h) |+| **How YOUR app launches**, its phrases, hero | your app's own `dockbar.json` | push to your page repo. Picked up on the next resolve, or instantly via **Hard Refresh Open** |+| **The rail itself, the launch screen, the orbital** | compiled into ah | needs an ah build and release |++So an app can change everything about its own card, and adom can change the whole list, with+no release. Only the dock's own chrome needs a build.++**To make a change land NOW rather than on the next poll:** right-click the card and use+**Hard Refresh Open**, which drops the cached manifest and display entry and re-resolves from+the wiki, or use the dock-wide **Refresh list from wiki** on empty rail space.++## A dock only YOU see++**Dock settings > Manifest URL** points your dock at any `apps.json` you like, instead of the+adom-curated one. It is per-install and nobody else is affected. A **DRAFT** badge stays on+the rail while it is active, so a personal list is never mistaken for the fleet list.++It was built for testing curation changes before they reach everyone, and a personal dock is+the same mechanism: publish your own `apps.json` anywhere the workspace can fetch it, paste+the URL once, and your rail is yours. The AI can then edit that file for you freely without+you touching settings again.++## ⛔ What these things are CALLED, and why you should say the name++A user who does not know a part's name cannot ask for it in a chat window. **So use the+canonical name in conversation, every time, even when the user used a different word.** Say+"the dock bar" while doing what they asked, and they learn the term without being corrected.++| Say this | For | Users also say |+|---|---|---|+| **the dock bar** (or **the dock**) | the launcher rail on the right edge | app bar, launcher, sidebar, the icons |+| **a card** | one app's icon in the rail | tile, icon, button, app |+| **the launch screen** | the interstitial with the orbital | loading screen, splash, the spinner |+| **the orbital** | the animation on the launch screen | the ball, the sphere, the loader |+| **the launch console** | the command transcript under it | the log, the terminal, the output |+| **Dock settings** | the gear at the top of the rail | preferences, options, config |+| **Hard Refresh Open** | the right-click from-scratch relaunch | force refresh, reinstall, hard reload |+| **a webview tab** | the workspace tab an app opens into | window, panel, the app |++**Accept every synonym silently and answer in the canonical term.** Correcting someone's+vocabulary is worse than modelling it: they will pick the name up from your reply, and the+next time they will ask for it precisely.++## The curated list vs user-added++The global list (`https://wiki.adom.inc/blob/bootstrap/hydrogen-bootstrap/dock/apps.json`)+is adom-curated and is ONLY a list: which apps appear and in what order, plus+`featured` and `order`. It deliberately carries no launch blocks, because an+inline launch there overrides and freezes the manifest the app maintains. Being+on it is not required to be dock-ready. To request listing, open an issue on the+adom/hydrogen-desktop wiki page.+
skills/hydrogen-doctor/SKILL.mdadded+78@@ -0,0 +1,78 @@+---+name: hydrogen-doctor+description: >-+ The Hydrogen Doctor on Linux: a one-click health scan of the whole stack (workspace+ machine, code-server, Claude, Adom auth, ports, relay, Adom Bridge), also at GET/POST+ /doctor. Use when something is broken and nobody knows what, things are weird after the+ computer sleeps, or to run the doctor.+---++# Hydrogen Doctor: diagnose the whole stack in one place++The Doctor answers "is everything actually working?" with evidence: about 20 real checks+end to end (not "is the process alive" but "does it answer correctly"), each with a+plain-English explanation.++## Where it lives++- **UI**: Adom menu (top-left) → **Doctor...**. A dialog lists every check with+ a green/red state; hovering a row reveals a paragraph explaining what that+ check means and why it matters. Buttons: **Re-run checks**, **Fix problems**,+ and (only when recommended) **Restart workspace**.+- **API** (Hydrogen control API, see `hydrogen-api` for the port):+ - `GET /doctor` runs all checks: `{before: {checks: [...]}, still_failing, ...}`, each check+ with `ok` and `message`.+ - `POST /doctor` body `{"fix": true}` runs checks, tries the safe fix (none exists on Linux+ yet, see below), and returns+ `{before, after, actions, still_failing, recommend_workspace_restart}`.++## What it checks++Workspace side: the workspace helper responds (the helper `hydrogen-workspace` and+`machinectl` answer), the runtime is the `Adom-Workspace` systemd-nspawn machine+(`workspace`), the Adom API key exists (`api-key`), required env vars are exported+(`env-vars`), `adom-cli` is installed (`adom-cli`) and can actually reach Adom's cloud+(`adom-cli-api`), skills are deployed (`skills`), the in-container relay answers on+8765/8766 (`relay`).++Editor side: code-server is genuinely serving (`code-server`, the big one after+sleep), the required extensions are installed (`extensions`), Claude Code CLI is+installed (`claude-installed`) and signed in (`claude-auth`), the live SSE link+between editor and app is up (`sse`), the workspace-layout API responds+(`webview`).++Plumbing: workspace service ports reachable from this computer (`ports`), identity+(`identity`), the relay path for Adom Bridge (`adom-bridge`), ab's direct API+(`adom-bridge-direct`), and `port-integrity` (code-server serving; a control API that moved+off 47084 is a note, not a failure).++**`adom-bridge-direct` is red whenever no Adom Bridge runs on this computer.** Hydrogen installs and+starts it when a Linux build is published for the user's account, so red is expected only when+none is published yet (the setup step says so). If one is installed (`~/.local/share/adom-bridge-app/run.sh`)+and it stays red, read the `[ab-linux]` and `[ad-supervisor]` log lines.++## Repair on Linux++- **Fix problems** has no automatic heal on Linux: the heal cascade it triggers exists only on+ the other platforms, so `actions` says "Heal cascade unavailable" and the checks are not+ re-run. Read the failures and fix them directly.+- **Restart workspace** (disruptive, confirm-gated): `POST /container-restart` stops the+ machine and starts it again, reloading VS Code and Claude (`{"dry_run":true}` says what it+ would do). Never trigger it without the user's OK.+- A red "Workspace helper responds" means the helper or `machinectl` did not answer: restart the workspace from+ the Adom menu, then restart Hydrogen if that does not help.++## How you (the AI) should use it++- User says "nothing works" or "it froze after I opened my laptop": call+ `GET /doctor` first and READ the failures instead of guessing.+- Fix what the failures name (restart a service, sign in, start code-server).+- Offer a workspace restart only when the failures point at the machine itself, and ask first.+- After any repair, re-run `GET /doctor` and only claim health you can see+ (all `ok: true`).++## Related skills++- `hydrogen-wake-repair`: what happens after sleep on Linux (the Cannot reconnect watcher).+- `hydrogen-workspace-lifecycle`: what a workspace restart actually does.+- `hydrogen-api`: how to find the control port.
skills/hydrogen-eda-discovery/SKILL.mdadded+129@@ -0,0 +1,129 @@+---+name: hydrogen-eda-discovery+description: >-+ Post-setup playbook for discovering which EDA tools the user runs (KiCad, Fusion 360,+ Altium, OrCAD) on their Linux computer and other machines, and onboarding them into the+ AI-first electronics workflow. Use when asked to explore what EDA software I use, detect+ KiCad or Fusion, or on the post-setup discovery pass.+---++# EDA tool discovery & onboarding (run in the background after setup)++You're (likely) a **second Claude conversation** launched after Hydrogen 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.++## 1. Detect++### On this Linux computer, without any bridge++The workspace sees the host's `/usr` and `/opt` read-only at `/mnt/host/usr` and `/mnt/host/opt`,+and the host's `/home` at `/mnt/host/home`, so installs can be found from here:++```bash+ls /mnt/host/usr/bin 2>/dev/null | grep -iE '^(kicad|eeschema|pcbnew|eagle|librepcb|horizon-eda)' +ls /mnt/host/opt 2>/dev/null | grep -iE 'kicad|eagle|diptrace|cadence|orcad|librepcb'+ls -d /mnt/host/home/*/.local/share/flatpak/app/org.kicad.KiCad 2>/dev/null # per-user Flatpak+ls -d /mnt/host/home/*/.config/kicad/* 2>/dev/null # KiCad config = versions used+```++System-wide Flatpaks (`/var/lib/flatpak`) and snaps are not visible from the workspace; when+nothing turns up, ask instead of concluding "not installed".++**Fusion 360 and Altium Designer have no Linux build**, so they will not be on this computer.++### Driving the tools needs Adom Bridge++Opening a board, running DRC or taking a KiCad screenshot goes through Adom Bridge's bridges+(`kicad_*`, `fusion_*`, `altium_*`). Adom Bridge runs on this computer only once Hydrogen has+installed it (when a Linux build is published for the user's account), so:++```bash+adom-bridge ping # anything connected at all?+adom-bridge targets # the user's machines on the Adom mesh+adom-bridge --target <machine> kicad_list_versions '{}' # KiCad installed (+ versions)+adom-bridge --target <machine> fusion_status '{}' # Fusion 360 ("installed but not running" = yes)+adom-bridge --target <machine> altium_readiness '{}' # Altium (altium-bridge)+```++- On **this** computer these work while Adom Bridge runs here (Hydrogen installs it when a Linux+ build is published for the user's account) and the bridge has a Linux build; otherwise the verb answers `unsupported_on_this_os` or nothing connects. See+ **adom-bridge-linux**.+- On the user's **other** machines (for example their Windows PC or a Mac) they work through the+ mesh. Never guess which machine: ask.+- Tools with **no bridge** (OrCAD, Cadence/Allegro, EAGLE, DipTrace, ...) on another machine:+ detect them by install path or running process with+ `adom-bridge --target <machine> run_script '{"interpreter":"bash","scriptB64":"<b64>"}'`+ (pick the interpreter that machine has).++(Whatever the platform: treat **empty output as a timeout**, not a negative result.)++## 2. Branch on what you found++### A) KiCad and/or Fusion 360 found — we have bridges, go deep (opt-in)+1. **Remember it.** Write a small prefs file so future threads skip re-detection:+ ```bash+ mkdir -p ~/.adom+ cat > ~/.adom/eda-prefs.json <<'JSON'+ {"primary":"kicad","versions":["10.0"],"machine":"<where it runs>","detectedAt":"<date>",+ "notes":"KiCad 10 on this Linux computer; Fusion on the user's laptop"}+ JSON+ ```+ (Also worth a one-line memory note if you keep memories.)+2. **Show, don't tell** — offer to open an example so they *see* it work:+ *"Want me to open a sample board in KiCad and pop the 3D viewer so you can see what I can drive?"* → use the `pic_programmer` demo flow (`hydrogen-self-screenshot` and the kicad-bridge skills, `adom-wiki pkg install adom/kicad-bridge`): open `.kicad_sch` + `.kicad_pcb`, symbol/footprint editors, then the **board** 3D viewer (close the footprint+symbol editors first — `kicad_open_3d_viewer` attaches to the active editor otherwise).+ If KiCad is only on this computer and no Adom Bridge runs here, say so and offer what works+ without it (files, wiki parts, and `kicad-cli` exports if `command -v kicad-cli` finds it in+ the workspace).+3. **Pitch the loop** that AI makes effortless — *"From here I can export gerbers and help you+ order the board — JLCPCB, PCBWay, or OSHPark."* If they're keen, that's the on-ramp to (4).+4. **The real unlock — build the glue, publish it.** Most fab vendors have no clean API, so the+ value is AI-built automation: *pull from KiCad → stage in the workspace → drive the+ vendor's upload flow (pup) → order.* Offer to **vibe-code an uploader/automation app** for+ their fab of choice and **publish it to the Adom wiki** so the whole community gets it. This+ is exactly what the wiki is for (see §3).++### B) OrCAD / Allegro / EAGLE / other — no bridge yet (the community pitch)+We don't have a bridge for these — **but that's an opportunity, not a dead end.** Offer:++> *"You're on **OrCAD** — we don't have an Adom bridge for it yet, but we have a wiki for+> sharing apps with the whole community, and we could **build one together right now**. The+> KiCad and Fusion 360 bridges are great references for the AI to model the design on — it's+> probably ~30 minutes of vibe-coding. Then we publish it to the Adom wiki so every OrCAD+> user gets it. We could all use it. Want to?"*++- Reference bridges: `adom-inc/adom-bridge/plugins/kicad/` and `…/plugins/fusion360/` (a Python+ bridge that the desktop app dispatches to; see the adom/kicad-bridge and adom/fusion-bridge wiki pages for the verb+ shape). A new bridge = the same pattern (launch app, open files, screenshot, send keys, an+ optional in-process add-in for the richer API).+- Publish flow: the Adom wiki hosts shared apps (`apps/<name>`) — see the wiki publish skills.+- Building one: **adom-bridge-sdk**.++### C) Nothing detected / unsure+Ask what they design boards in, and whether they'd like a bridge or workflow built. Keep it+one friendly question, not an interrogation.++## 3. The frame (why this matters — say it briefly, don't lecture)+The electronics industry is moving **AI-first**, and the tools mostly aren't built for it yet.+**Adom is where that comes together:** you build an AI-first app (a bridge, an uploader, a+fab-automation glue), publish it to the **Adom wiki**, and the whole community can install and+improve it. KiCad/Fusion bridges, a JLCPCB/PCBWay/OSHPark uploader, an OrCAD bridge — each one+makes the next person's AI-first workflow turnkey. The user isn't just configuring their setup;+they can **contribute the missing piece** in half an hour.++## 4. Etiquette+- **Opt-in always.** Detect silently; *offer* the demo/build — don't open apps or write code+ unprompted. One clear offer beats five questions.+- **Don't overpromise vendor APIs.** JLCPCB/PCBWay/OSHPark uploads are mostly UI automation+ (pup), not clean APIs — frame the uploader as AI-driven glue, and verify pages exist before+ templating URLs (`hydrogen-pup`).+- **Respect read-only states** (e.g. an expired Fusion subscription is view/query-only).+- Report back to the user concisely: *what you found, one thing you can show them now, and one+ thing worth building.*++## Related skills+- **hydrogen-adom-bridge**: the bridge relay and the Linux reality+- **hydrogen-bridges**: the KiCad / Fusion / pup bridges+- **hydrogen-pup** — driving fab-vendor upload pages; **hydrogen-open-url** (platform bootstrap) — opening vendor sites+- the Adom wiki publish skills — sharing the bridge/app you build with the community
skills/hydrogen-editor-state/SKILL.mdadded+62@@ -0,0 +1,62 @@+---+name: hydrogen-editor-state+description: >-+ Hydrogen's Editor State Machine: how to know the true state of the VS Code+ editor and its Claude conversations, and the hard rules before typing into+ one. Use before typing into a Claude tab, or when a prompt landed in the wrong+ conversation, a split panel is empty, or the state is unknown.+---++# hydrogen-editor-state — the Editor State Machine++ONE authoritative read: `GET /editor/state` on Hydrogen's control API+(`$(cat ~/.adom/hydrogen-control-url)`). Everything below is what it returns and the rules for+acting on it. Full design: docs/EDITOR-STATE-MACHINE.md (hd repo).++## The layered truth (never blend layers)++| Layer | Question | Source | Trust |+|---|---|---|---|+| L0 `lifecycle` | starting / editor-up / ready | code-server `/healthz`, the extension's `:8821/health` | absolute |+| L1 `layout`+`conversations` | groups, widths, empty panels, tab census, focused tab | workbench DOM + tab bar | high (VS Code chrome is stable) |+| L2 `extension` | what commands can I invoke | the extension's contributed-command registry + fingerprint | absolute (it IS the API) |+| L3 `conversations_disk` | turns, first prompt, generating, delivered | the jsonl transcripts | absolute — works for DISPOSED background tabs |+| L4 `census` | compose boxes + submit buttons visible NOW | DOM probes across ALL contexts | only under the invariants below |++**On Linux** the DOM layers (L1, L4) are read through Hydrogen's frame bus, not a DevTools+protocol (WebKitGTK has none), and `lifecycle.cdp_attached` is always false: ignore it. `phase`+is decided by code-server and the extension alone.++## The HARD invariants (John 2026-07-17 — non-negotiable)++1. **Never type unless `census.safe_to_type == true`** (exactly 1 visible input across ALL+ webview contexts — not just the focused one).+2. **Freshness oracle is the TITLE**: `title == 'Untitled'` = never submitted. NEVER use+ `msg_count` for freshness — it counts welcome-screen DOM nodes (reads 5 on a pristine tab).+3. **After a submit, run the stray-text audit**: `POST /editor/audit-prompt {prefix}` must+ return `contexts_containing: 0`. 1+ = the prompt is ALSO sitting in another conversation's+ box (double-type) — clear it, fail loudly, never ignore.+4. **Delivery is proven on DISK, not in the DOM**: the prompt must be the first user turn of+ exactly ONE `~/.claude/projects/*/*.jsonl`. 0 = not delivered; 2+ = double-send.+5. **Background tabs are unreadable** (VS Code disposes their webviews): `loaded:false`,+ null ctx/compose. To read one, activate it first (`/claude/tabs/activate {index:<ordinal>}`+ — by ORDINAL, never by label: every Claude tab is labeled 'Claude Code').+6. **`normalize_needed: true` → `POST /editor/normalize`** before showing the user anything+ (an empty split group steals 50% of their editor; populated 2-group layouts are preserved).+7. **Prefer registered commands over DOM clicks**: `extension.commands` lists them+ (claude-vscode.newConversation, .focus, .editor.open, ...). Run via the workspace's+ `:8821/command` API. Commands survive extension updates; selectors don't.+8. **Extension drift**: `extension.fingerprint` changes when Claude Code updates — re-verify+ your assumptions (anchors, commands) before trusting flows after a fingerprint change.++## Quick recipes++- Am I safe to type? `GET /editor/state` → `census.safe_to_type`.+ `?fast=1` for tight loops.+- Did my prompt double-type? `POST /editor/audit-prompt {"prefix":"<first words>"}` → want 0 after submit.+- Which conversation is generating? `conversations_disk[*].generating` (disk truth, any tab).+- Fix a half-width Claude tab / dead empty panel? `POST /editor/normalize`.+- Bars: `layout.bars` reports activity / primary sidebar / secondary (auxiliary) bar / bottom+ panel visibility. A Claude conversation living in the SECONDARY bar is a second compose box+ (census=2). Close bars deterministically: `POST /editor/bars {"primary":"close","secondary":"close"}`+ (read -> toggle-on-mismatch -> verify; never a blind toggle).
skills/hydrogen-embedded-bridge/SKILL.mdadded+97@@ -0,0 +1,97 @@+---+name: hydrogen-embedded-bridge+description: >-+ How Hydrogen (ah) on Linux relates to Adom Bridge (ab): Hydrogen installs ab+ when a Linux build is published for the user's account, starts it hidden,+ restarts it and applies its updates, and ab enters embedded mode with the+ workspace relay and session from Hydrogen. Use when asked embedded vs+ standalone, why ab is not installed, why two apps, or where ab's tray went.+---++# Hydrogen and ab on Linux: installed, embedded and supervised++**Hydrogen for Linux installs and supervises Adom Bridge**, following ab's own Linux install:++- **Install:** when ab is missing, Hydrogen reads ab's manifest (insiders with the user's Adom+ session, else public) and uses its `linux` entry. No `linux` entry for this account means no+ ab yet: setup says so and Hydrogen checks again after sign-in and every 30 minutes. It downloads+ the AppImage (about 150 MB, never bundled with Hydrogen), checks the published sha256, and runs+ `<AppImage> --install --no-launch`: one per-user copy in `~/.local/share/adom-bridge-app`, its+ locked `run.sh`, a menu entry and login autostart (see **adom-bridge-linux**).+- **Start:** `~/.local/share/adom-bridge-app/run.sh --embedded --start-hidden --panel-collapsed` (the Windows spawn flags; without `--embedded` a first start shows ab's window). run.sh's lock keeps one copy.+- **Supervise:** when ab's direct API (`127.0.0.1:24680`, or the port in `~/.adom/direct-api-port`) stops+ answering and no ab process exists, Hydrogen starts it+ again through run.sh, with a growing wait if it keeps dying. A copy the user started by hand+ is never started twice or replaced.+- **Update:** ab updates itself. In embedded mode it stages the update and waits; Hydrogen sends+ `POST /update/apply` when ab is idle, ab swaps its AppImage and comes back through run.sh.+ Hydrogen never reinstalls an ab that is present.++This skill explains how the two interact so you can answer "why isn't ab in my tray?", "should I have two installs?", "why did the tray icon disappear?" and similar.++## How Hydrogen adopts ab++ab finds Hydrogen on its own: it reads the control port from+`~/.config/hydrogen-desktop/ports.json`, and Hydrogen answers ab's embedded probe on its+liveness beacon `127.0.0.1:9001`. Hydrogen then:++- hands ab the workspace relay and the Adom session with `POST /embedded/enter`+ (`relay_name: "hydrogen"`), checking every 10 to 20 s and re-sending when ab restarts, the+ relay changes port, or the session changes;+- starts it only through ab's own `run.sh` (above), so ab's autostart entry, a systemd user unit+ or a hand start never make a second copy.++In embedded mode ab hides its own tray icon; Hydrogen's tray menu (the desktop's tray, AppIndicator)+carries **Open Adom Bridge**, which shows ab's window. The rest of that menu: Open Hydrogen+(first, GNOME has no left-click action), New Claude/Codex/Antigravity chat (installed AIs only,+Kimi with show_kimi), Annotate screen, Open Adom Bridge, Settings, Quit Hydrogen.++## On quit++Quitting Hydrogen releases ab. With Settings > Adom Bridge > "Close Adom Bridge when you quit+Hydrogen" on (the default) Hydrogen asks ab to shut down; off, it sends+`POST /embedded/release` and ab decides whether to exit or go standalone.++## Checks++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s "$BASE/ab/embedded" # ab's own embedded_status+curl -s "$BASE/ab/process" # ab processes on the host (0 = not running here)+curl -s "$BASE/ab/liveness-beacon" # :9001+```++ab's direct API is `127.0.0.1:24680` (`POST /command` with+`{"app":"desktop","command":"embedded_status","args":{}}`). The workspace shares the host's+loopback, so it reaches that port directly.++## Runtime transitions++**ab ≥ v1.8.47** re-checks Hydrogen's liveness every 60s during runtime, not just at boot. This is the normal daily cycle for most users, not an edge case:++- User starts ab while Hydrogen runs: ab's next poll finds Hydrogen's beacon on :9001, ab+ embeds, its tray hides+- User quits Hydrogen with "Close Adom Bridge when you quit Hydrogen" off: ab's next poll fails+ the Hydrogen probe, ab reverts to standalone, its tray reappears+- User launches Hydrogen again: ab's next poll succeeds, ab re-embeds, its tray hides++The same ab process can flip mode back and forth indefinitely across a Hydrogen-quit / Hydrogen-relaunch cycle. Transitions:++| Current mode | Hydrogen probe says | What ab does |+|---|---|---|+| Standalone | dead | stay standalone (no-op) |+| Standalone | alive | → **embed**: hide tray, write marker, hide main window, show "Embedded · Hydrogen" pill |+| Embedded | dead | → **unembed**: show tray, delete marker, hide pill (main window left as-is) |+| Embedded | alive | stay embedded (refresh marker heartbeat in `last_seen`) |++Both transitions emit a `mode-changed` event so the frontend can update the footer pill in real time.++## Common questions++- **"Why isn't Adom Bridge installed?"** Hydrogen for Linux does not set it up yet. Without it,+ desktop features that go through ab (desktop screenshots, files to the desktop, KiCad, pup,+ Grok Bot) are unavailable on this machine. Other machines on the user's mesh still answer+ `adom-bridge --target <name>`.+- **"Is two apps normal?"** Yes: Hydrogen and ab are separate apps. Removing Hydrogen's package+ leaves ab in place.+- **"ab's tray icon appeared."** Hydrogen is not running (or quit), so ab went standalone.
skills/hydrogen-eval/SKILL.mdadded+137@@ -0,0 +1,137 @@+---+name: hydrogen-eval+description: >-+ Inject JavaScript into any surface of the Hydrogen window (app shell, VS Code workbench,+ wiki panel, Claude chat) through POST /eval-in, which runs over Hydrogen's frame bus on+ Linux. Use when asked to inject a UI add-on, add a demo arrow or overlay, highlight an+ element, or read the DOM of the Hydrogen window.+---++# hydrogen-eval: inject JS into any Hydrogen surface (`POST /eval-in`)++The Hydrogen window is a tree of frames, not one page:++| friendly target | what it is | typical use |+|---|---|---|+| `shell` | the Hydrogen app shell (Svelte): top nav, logo menu, dialogs, the floating layer | inject add-ons/overlays that float over everything |+| `workbench` | the VS Code editor (code-server) | activity bar, tabs, the "Claude Code: Open" button |+| `wiki` | the wiki panel iframe | wiki DOM |+| `claude` | the Claude Code chat **webview** (only exists while the panel is open) | the chat input + send button |++## How it runs on Linux: the frame bus++WebKitGTK has no Chrome DevTools Protocol. Hydrogen injects an agent script into every frame,+in an **isolated script world**, and `/eval-in` sends your JS to the frame you name over that+bus (`hydrogen-app/src/linux_frame_bus.rs`). What that means for you:++- **The DOM is shared, page JS globals are not.** `document.querySelector`, events, `click()`,+ `execCommand`, styles and IndexedDB all work. A page's own globals (Svelte stores, a+ `window.__something` the page defined) are invisible: drive the DOM, not the page's functions.+- **Context ids are the agent's random ids**, stable for the frame's life. Don't keep them+ across reloads.+- **No surface list:** `GET /targets` and a `/eval-in` call without `js` return nothing on+ Linux. A miss returns an error that names every candidate frame, which is the discovery.+- Same-origin child frames without their own agent (VS Code webview content) are reached+ through their parent's agent, so the Claude chat is still `target:"claude"`.++## Reaching the control API++The workspace shares the host's network, so the API is on `127.0.0.1`. Read the live URL from+the discovery file:++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # http://127.0.0.1:<dynamic>+```++(Never hardcode the port — read the live URL from `~/.adom/hydrogen-control-url`.)++## The call++```+POST /eval-in+{+ "target": "shell" | "workbench" | "wiki" | "claude" | "<url-substring>" | "<id>",+ "js": "<javascript; value of last expression is returned>",+ "find": "<OPTIONAL JS expression>", // disambiguate among same-origin contexts+ "frame": "<url-substring | index>", // OPTIONAL nested-context selector+}+→ { "ok": true, "value": <result>, "target": "<matched url>", "contextId": N, "frames": [...] }+```++A returned promise is always awaited on Linux.++### `find` — the important one++The workbench has several same-origin frames. Origin alone is ambiguous, so pass `find`:+a JS **expression** (e.g. `document.querySelector('...')`, NOT a bare CSS selector).+`/eval-in` evals it in each candidate context and runs your `js` in the **first+one where `find` is truthy**.++## Recipes++### Add-on: a widget in the top nav (e.g. a usage meter) — target `shell`+Inject once; it persists until reload. Append your element to `nav` in the shell.++### Demo overlay: a red arrow over everything that you reposition — target `shell`+Inject a `position:fixed; z-index:2147483647; pointer-events:none` element with a+CSS `transition` into the shell `body`, then move it with cheap follow-up evals+(it glides). The shell floats over all iframes, so window coords work everywhere.++### Highlight an element (even deep in the workbench / Claude webview)+Eval **inside the element's own surface** and set `outline` — no coordinate math.+Use `find` to land in the right context, e.g.+`find: document.querySelector("a[aria-label='Claude Code: Open']")`.++### Type into & submit the Claude chat (panel must be open)+Stable selectors (NOT the CSS-module hash classes like `.messageInput_xxxx`,+which change per build):+- input = `[aria-label='Message input']` (a `contenteditable` div) — focus it,+ then `document.execCommand('insertText', false, text)`.+- submit = `button[type='submit'][data-permission-mode]` (disabled until text) —+ `.click()` it; fallback = dispatch an `Enter` keydown on the input.+ Prefer the `/claude/inject` endpoints for this (see **hydrogen-claude-management**).++## Verify-then-fallback (recommended)++`/eval-in` returns the JS value, so always verify: after an action, eval a probe+and check it; if it fails, try a second technique.++## Don'ts+- Don't hardcode the control port — read `/ports`.+- Don't pass `find` as a bare CSS selector — it's a JS expression.+- Don't select by CSS-module hash classes — use stable attributes (`aria-label`, `data-*`, `role`).+- Don't expect the `claude` webview to exist unless the Claude panel is open.+- Don't use `/eval` for workbench/Claude — it only reaches the shell page.+- `/iframe-eval` is CDP-only and does nothing useful on Linux.+- Don't call page globals: the isolated world cannot see them.++## Cross-references+- **hydrogen-api** — the full control API surface+- **hydrogen-ui** / **hydrogen-adom-menu** — where UI elements live+- **hydrogen-self-screenshot** — capture the result of your injection++## Recipe: hide/show activity-bar icons (the RIGHT way — persisted, overflow-proof)++Do NOT hide activity-bar icons with `display:none` on `.action-item` — that misses+icons collapsed into the "…" (Additional Views) **overflow** and doesn't persist.+Instead write VS Code's own source-of-truth state, then reload the workbench:++- **DB:** `vscode-web-state-db-global` → store `ItemTable` → key `workbench.activity.pinnedViewlets2`+- It's an array of `{id, pinned, visible, order}`. Set **`pinned:false` to hide** an+ icon from the activity bar (works even if it's in the overflow), **`pinned:true` to restore**.+- **IDs:** Explorer `workbench.view.explorer` · Search `workbench.view.search` ·+ Source Control `workbench.view.scm` · Run&Debug `workbench.view.debug` ·+ Extensions `workbench.view.extensions` (extension views: `workbench.view.extension.<id>`).+- IndexedDB is **per-origin**, so read/write from **any** `localhost:7380` context+ (target `workbench`, `find: "(typeof indexedDB!=='undefined')"`) — don't require the+ workbench main doc (it's absent during a reload).+- After writing, **reload the workbench** (`iframe.src=iframe.src` on the `shell`, or+ `POST /reload-vscode`) so VS Code re-reads `pinnedViewlets2`.++```jsonc+// hide Search / Source Control / Run&Debug (then reload)+{ "target":"workbench", "find":"(typeof indexedDB!=='undefined')", "awaitPromise":true,+ "js":"(async function(){function g(d,k){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var q=b.transaction('ItemTable','readonly').objectStore('ItemTable').get(k);q.onsuccess=function(){b.close();r(q.result)}}})}function p(d,k,v){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var t=b.transaction('ItemTable','readwrite');t.objectStore('ItemTable').put(v,k);t.oncomplete=function(){b.close();r(true)}}})}var DB='vscode-web-state-db-global',K='workbench.activity.pinnedViewlets2';var a=JSON.parse(await g(DB,K));var ids=['workbench.view.search','workbench.view.scm','workbench.view.debug'];a.forEach(function(e){if(ids.indexOf(e.id)>-1)e.pinned=false});await p(DB,K,JSON.stringify(a));return 'hidden';})()" }+```++`POST /vscode/hide-activity-items` does the same job server-side.
skills/hydrogen-file-transfer/SKILL.mdadded+103@@ -0,0 +1,103 @@+---+name: hydrogen-file-transfer+description: >-+ Move files both ways between the Hydrogen workspace and the Linux computer it+ runs on: /mnt/host inside the workspace, /files/inject, machinectl copy-to and+ copy-from on the host, or adom-bridge send_files/pull_file to another machine.+ Use when asked to copy a file to my desktop, get a file from my computer, move+ a file in or out, or where my downloads go.+---++# Move files between the workspace and this computer++The workspace is the systemd-nspawn machine `Adom-Workspace` on this same computer. Your work is+at `/home/adom/project` inside it. The workspace user is `adom` (uid 1001); the host user is+usually a different uid.++## Method 1: `/mnt/host` (from inside the workspace), simplest++Hydrogen binds host folders into the machine:++| In the workspace | Host path | Access |+|---|---|---|+| `/mnt/host/home` | `/home` | read-write |+| `/mnt/host/tmp` | `/tmp` | read-write |+| `/mnt/host/usr` | `/usr` | read-only |+| `/mnt/host/opt` | `/opt` | read-only |++```bash+HOSTUSER=$(ls /mnt/host/home | head -1) # check with the user if there are several+cp /home/adom/project/report.pdf "/mnt/host/home/$HOSTUSER/Downloads/"+cp "/mnt/host/home/$HOSTUSER/Downloads/data.csv" /home/adom/project/+```++Host file permissions still apply, to uid 1001. Many distros make home folders private (mode+0750 or 0700), so `ls /mnt/host/home/<user>` may say "Permission denied". Then use the shared+`/tmp`: ask the user to drop the file in `/tmp` on the host and copy it from `/mnt/host/tmp`, or+write to `/mnt/host/tmp/<name>` and tell them where it is. A file you write lands owned by uid 1001:+the user can read it (with the default umask) but may need `sudo` to delete or edit it in place,+so tell them to copy it.++The workspace's own `/tmp` is a private tmpfs, cleared at every machine start. Never leave+anything there you want to keep.++## Method 2: `POST /files/inject` (any host program, through Hydrogen)++Writes files into the project as `adom`:++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s -X POST "$BASE/files/inject" -H 'Content-Type: application/json' \+ -d "{\"subdir\":\"downloads\",\"files\":[{\"name\":\"photo.png\",\"data\":\"$(base64 -w0 photo.png)\"}]}"+# -> /home/adom/project/downloads/photo.png+```++`subdir` (default `downloads`) and `name` must be single path components.++## Method 3: from a host terminal++The machine's files are at `/var/lib/machines/Adom-Workspace` on the host, readable by root only.+Use machinectl (the machine must be running):++```bash+sudo machinectl copy-from Adom-Workspace /home/adom/project/out.zip ~/Downloads/out.zip+sudo machinectl copy-to Adom-Workspace ~/Downloads/data.csv /home/adom/project/data.csv+```++A file copied out with sudo is owned by root; `sudo chown $USER` it afterwards.++## Method 4: the adom-bridge relay (to another machine)++`send_files` / `pull_file` talk to a computer running Adom Bridge: this computer once Hydrogen has+installed it (when a Linux build is published for the user's account), or the user's other+machines through the Adom mesh (for example a laptop). See `hydrogen-adom-bridge`.++```bash+adom-bridge send_files '{"filePaths":["/home/adom/project/out.zip"]}'+adom-bridge pull_file '{"filePaths":["<path on that machine>"],"saveTo":"/home/adom/project"}'+```++Notes:+- Confirm the bridge first: `adom-bridge ping` answers `pong` when a bridge is reachable.+- Files whose basename starts with `_` are silently dropped by the relay — use+ plain names.++## Which method to use++| Situation | Use |+|---|---|+| Scripting inside the workspace, file in the user's home or `/tmp` | Method 1 |+| A host program or page pushing files in | Method 2 |+| The user at a host terminal | Method 3 |+| A different computer | Method 4 |++## Where things persist++`/home/adom/project` survives workspace and computer restarts. A **virgin reset** deletes the+whole Adom-Workspace machine and every file in it. Copy anything important out first. See+`hydrogen-volume`.++## Related+- **hydrogen-volume** — what persists, where files live, backing up before virgin reset+- **hydrogen-adom-bridge** — the relay (send_files / pull_file) and OS reach+- **hydrogen-workspace-lifecycle**: start, stop and reset the machine
skills/hydrogen-golden-image/SKILL.mdadded+60@@ -0,0 +1,60 @@+---+name: hydrogen-golden-image+description: >-+ What the pre-baked golden workspace image contains on Linux (the rootfs+ Hydrogen unpacks into the Adom-Workspace systemd-nspawn machine), how package+ updates keep it current, the tarball pin, and where the Linux skill set comes+ from. Maintainer reference for where the CLIs and skills came from.+disable-model-invocation: true+---++# Hydrogen Workspace = a pre-baked golden image, kept current by packages++On Linux, Hydrogen unpacks the golden rootfs `adom-golden.tar.gz` (from Adom's public golden-image GitHub release, SHA256-verified, cached at `~/.local/share/Adom/HydrogenDesktop/cache/adom-golden.tar.gz`) into `/var/lib/machines/Adom-Workspace` and boots it as a systemd-nspawn machine. It is the same image the other Hydrogen platforms run (currently `v31-full`); only the runtime around it differs. It is PRE-BAKED: the Adom toolchain is already inside the tarball.++A new image ships every week or so, each the previous one with the current `adom-wiki pkg update` baked in. From v27 on there is no forced re-image (`NO_FORCED_MIGRATION_FROM = 27`), so an existing workspace stays on its image and packages keep it current. A fresh install simply gets the newer image.++> **The pin is the truth, this page is a snapshot.** The version actually+> shipped lives in three consts in `runtime/wsl.rs` (`TARBALL_VERSION`,+> `TARBALL_URL_PLACEHOLDER`, `TARBALL_SHA256_PLACEHOLDER`). If they disagree+> with this page, they win and this page is stale. An earlier era (v24-thin,+> 2026-08-13 to v26) shipped a MINIMAL image that installed everything live at+> setup; describing that as current tells a user their 695 MB image is empty.++What the tarball 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+- the **adom-wiki CLI** at `~/.local/bin/adom-wiki`+- **the Adom toolchain itself**: adom/core, the Adom CLIs, the hydrogen-*+ skills, and the editor extensions (adom-theme, adom-vscode,+ anthropic.claude-code)+- a first-boot oneshot that mints the per-import `/etc/adom-distro-id`++Version files inside the workspace: `/etc/adom-golden-version` (the rootfs you run), `/etc/adom-tarball-version` (what Hydrogen imported). The units are `code-server.service`, `adom-relay.service` and `adom-shotlog.service`; the `adom` user is UID 1001.++## How updates work++- `adom/hook` runs `adom-wiki pkg update` on agent activity; the Adom sidebar's Packages section runs it on demand. The image is not touched.+- `update-packages` is not part of the normal setup cascade any more; the `os-baseline` step only fills small OS gaps.+- The image itself changes only when Hydrogen ships a new pinned tarball, and an existing workspace gets it only through a Virgin Reset (re-import).++## Where the Linux skills come from++The image has the generic `adom/hydrogen-bootstrap` skill set plus a desktop package that was written for another platform. On Linux, Hydrogen applies its own **Linux skill set** (the Linux render of `skills/public-facing/shared/`, embedded in the app, `hydrogen-setup/src/linux_skills.rs`) after every package convergence and at every launch: each Linux skill is written over the package copy of the same name, and that package's skills with no Linux version are removed (unless another installed package also delivers them). A later `adom-wiki pkg update` that re-delivers them is undone at the next apply.++## "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.++## Answering common user questions++- "Where did all these skills come from?" Baked into the image, kept current by the package registry, with the Linux set applied by Hydrogen. They live flat in `~/.claude/skills/`.+- "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.
skills/hydrogen-key-values/SKILL.mdadded+102@@ -0,0 +1,102 @@+---+name: hydrogen-key-values+description: >-+ The user's cloud key-value store (Carbon KV): what the hydrogen.* and bridge.* keys+ mean, how to read and write them, and the ownership and no-secrets rules. Use before+ writing a key, or when asked about my cloud settings, kv pairs, hydrogen.runtime or the+ key-values viewer.+---++# Cloud key-values: the user's Adom-account KV store++Every Adom user has a small key-value store attached to their account (10MB).+It syncs to every machine and container they sign in on, which makes it the+shared memory between Hydrogen, Adom Bridge, and you: preferences live here,+and running apps publish their live addresses here so they can be discovered+from anywhere.++## Reading and writing++- Read: `GET https://carbon.adom.inc/user` then+ `body.hydrogen_preferences.settings` is the flat map. Auth is either the+ session token (`Cookie: session_token=<tok>`) or the workspace API key+ (`Authorization: Bearer $(cat /var/run/adom/api-key)`).+- Write: `PATCH https://carbon.adom.inc/user/hydrogen/settings` with body+ `{"key": "<dotted.key>", "value": <scalar>}`, same auth. A `null` value+ removes the key.+- From inside Hydrogen's UI surfaces, the control API relays for you:+ `POST /auth/proxy` with `{"path": "/user", "method": "GET"}` (see+ `hydrogen-api`).++## Conventions (follow these exactly)++1. **Dotted lowercase keys, brand-name prefix.** Each app owns its prefix:+ `hydrogen.*` (this app), `bridge.*` (Adom Bridge). Never write into+ another app's prefix. `desktop.*` keys are pre-rename legacy (the+ Adom-Desktop era); Hydrogen still READS them as a fallback but only ever+ WRITES `hydrogen.*`.+2. **Scalar values only.** Structured data goes in as a JSON *string*.+3. **User-visible.** The profile menu's "Your cloud key-values" dialog shows+ every entry, pretty-printed. Keep values compact and self-explanatory.+4. **NEVER a secret.** No tokens, no passwords, no credentials, ever.+5. **Modify with intent.** You MAY change a `hydrogen.*` preference when the+ user asks (e.g. set `hydrogen.editor_font_size`), but prefer the app's own+ settings surface when one exists; a raw PATCH bypasses the app's+ validation and mirrors.+ For example `hydrogen.launch_on_boot` only writes the autostart file through Settings.+6. **SCOPE BY MACHINE OR BY ACCOUNT — decide before you write (the+ multi-computer rule).** The store is account-wide: every machine the user+ runs Hydrogen on reads and writes the SAME map, so a key holding+ per-machine state under a plain name gets clobbered by whichever machine+ wrote last. Three classes, three homes:+ - **Account-level preferences** (font size, color scheme, nav collapsed):+ plain `hydrogen.<name>`. Shared across machines *on purpose* — that's+ settings sync, not clobbering.+ - **Per-machine state** (live ports, runtime identity, anything two+ machines would disagree about): the key MUST embed the sanitized+ machine name — `hydrogen.runtime.<machine>`, `bridge.container.<id>`.+ Each machine owns its own key; nothing fights.+ - **Machine-local settings** (launch-on-boot, the close button, workspace shutdown on+ quit, ab window behavior): never in the cloud at all. Hydrogen keeps these on this+ computer (per-machine localStorage and `~/.config/hydrogen-desktop/setup-flags.json`)+ so one machine's choice can't leak to another.+ Litmus test before writing any new key: "if the user ran two computers,+ should they see the same value?" Yes → plain key. No → machine-suffixed+ key, or local storage. Two machines with the same computer name would+ share a runtime key; the value's `instance_id`/`install_path`/`ts` fields+ let a reader detect that and trust the freshest writer.++## The keys you'll meet++| Key | Owner | What it is |+|---|---|---|+| `hydrogen.editor_font_size`, `hydrogen.color_scheme`, `hydrogen.wake_heal`, ... | Hydrogen | The Settings dialog's preference tree. |+| `hydrogen.runtime.<machine>` | Hydrogen | Live runtime identity, published at launch + every 4h: a JSON string `{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}`. `<machine>` is the lowercase sanitized computer name. |+| `bridge.container.<id>` | Adom Bridge | A container connection ab dials (may appear as legacy `desktop.container.<id>` until ab's rename ships). |+| `bridge.runtime.<machine>` | Adom Bridge | ab's live runtime identity, also the Adom Mesh directory record (node id, relay, version). |++On Linux the `cdp` port in `hydrogen.runtime.*` has nothing listening (WebKitGTK has no+DevTools protocol).++## Using a runtime entry (discovery)++`hydrogen.runtime.<machine>` lets you find a running Hydrogen from a cloud+container or another machine with no port scanning. Rules:++- `ts` is unix seconds; older than ~5h (one missed heartbeat plus slack)+ means that instance is probably gone.+- A live port is NOT identity: hit `GET /buildinfo` on the advertised control+ port and match `instance_id` before trusting it. Zombies from uninstalled+ copies answering `/health` are a real observed failure.++## The viewer++Profile menu (avatar, top-right) → **Your cloud key-values**: read-only list+with filter, per-row copy, and expand for long values; refreshes from Carbon+on open. AI-drivable via the `profile.keyvalues` UI action.++## Related skills++- `hydrogen-ports`: the full discovery ladder these runtime entries sit in.+- `hydrogen-settings`: the Settings dialog that owns the preference keys.+- `hydrogen-api`: the control API and auth proxy.
skills/hydrogen-lightbulb/SKILL.mdadded+71@@ -0,0 +1,71 @@+---+name: hydrogen-lightbulb+description: >-+ Hydrogen's lightbulb menu of sample prompts in the title bar: each item opens+ a fresh Claude thread and types a demo prompt; sample-prompts.json adds or+ rewords them without a release. Use when asked about the lightbulb, sample+ prompts, demo prompts, or adding a sample prompt.+---++# hydrogen-lightbulb: the sample-prompts menu++The **lightbulb button** just right of the Adom logo in Hydrogen's title bar (moved there+0.1.265 — the AI work happens on the left where VS Code lives) opens a menu of curated sample+prompts. Picking one opens a **new Claude conversation** in the editor and+human-types the prompt (open → ready → type → verify → submit, all verified) —+the user just watches it run. It exists to teach by DOING: each prompt+demonstrates a capability end to end.++**Hidden by default since 1.0.142** (`Settings > Hydrogen > Behavior > Show Lightbulb`,+default off): the menu earns its keep while learning Hydrogen and is header noise after+that. Turning the setting on shows the button immediately, no restart. The+`samples-menu.open` / `samples-menu.close` AI commands stay registered even while the+button is hidden.++## Current lineup (0.1.260+)++Full tour (everything at once) · Adom parts search · KiCad · Fusion 360 ·+Altium · pup (AI-driven browser) · Native Chrome/Edge · Google Workspace ·+chip-fetcher · adom-tsci (build a board) · shotlog · Webview panels ·+Hands-free (TTS) · **Speak Adom (wv, pup, nb...)** — teaches the popular Adom+shorthand with a cheat sheet in a wv and a quick quiz.++Some prompts (KiCad, Fusion 360, pup, desktop browsers) need Adom Bridge. On this desktop+they run once Hydrogen has installed ab (when a Linux build is published for the user's account),+or against another machine on the user's mesh (see **hydrogen-bridges**).++## Drive it as an AI++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -sX POST "$BASE/ui/invoke" -d '{"id":"samples-menu.open"}' # and "samples-menu.close"+curl -s "$BASE/claude/sample-prompts" # id, label, blurb of each item+```++## Where the list comes from (three layers, later wins)++1. **Compiled defaults** in the Hydrogen build (offline fallback).+2. **The wiki list** (0.1.263+): `lightbulb-prompts/prompts.json` on the Hydrogen wiki+ page — the fleet-wide lineup, updated INDEPENDENTLY of Hydrogen releases. Hydrogen checks+ it on every menu open (debounced 15 min) plus every 4 hours during business+ hours (Mon-Fri 7am-7pm local); a changed list pops into an open menu live.+ Cache on the host: `~/.config/hydrogen-desktop/sample-prompts-remote.json`. Docs + PR+ guide: the [Lightbulb Prompts sub-readme](https://wiki.adom.inc/adom/hydrogen-desktop/files/lightbulb-prompts/README.md).+3. **The user's local file** `~/.config/hydrogen-desktop/sample-prompts.json` on the host+ (from the workspace: `/mnt/host/home/<user>/.config/hydrogen-desktop/`), personal+ overrides, always wins:++```json+[{"id":"thread-my-demo","label":"My demo","blurb":"one line","prompt":"the full prompt text"}]+```++- A **new id** appends a menu item; a **matching id** overrides a lower layer+ (label/blurb, and the prompt body if non-empty).+- Any `thread-*` id routes to the runner automatically — no code change needed.+- Bad JSON (local or wiki) is logged and ignored — the menu never breaks.+- To contribute a prompt for EVERYONE: PR `lightbulb-prompts/prompts.json` in the+ hydrogen-desktop repo (see the sub-readme above for the rules).++Prompts are written in the user's casual first-person voice, as ONE flat+paragraph (a typed newline would submit early). Never edit John's compiled+prompt bodies without permission; add new ids instead.
skills/hydrogen-monitor/SKILL.mdadded+177@@ -0,0 +1,177 @@+---+name: hydrogen-monitor+description: >-+ Watch the Hydrogen workspace in real time through its SSE event stream and the Monitor+ tool: tab changes, sharing state, workspace mutations. Use when asked to wait until the+ user opens something, react to a tab change, or watch for a new panel.+---++# Hydrogen Real-Time Monitoring++Watch the Hydrogen workspace in real-time using Claude Code's Monitor tool + Hydrogen's SSE event stream. React to user actions as they happen — no polling, no "tell me when you're done."++## When to use++- You need to **wait for the user to do something** (enable sharing, open a panel, switch tabs)+- You want to **react to workspace changes** as they happen (auto-screenshot new panels, navigate web views)+- You're running a **multi-step demo** and need to know when the user is ready for the next step+- You want to **watch for errors** or state changes during a long-running task++## When NOT to use++- **One-shot waits** → use `--wait-for-sharing` on screenshot commands instead+- **Checking current state** → use `workspace tabs` or `screenshot status` directly+- **Short operations** → just run the command and check the result++## Lighter than SSE for point-in-time checks++The proxy SSE stream below is for *reacting continuously*. If you just need a+snapshot of current state, the **control port** (`$(cat ~/.adom/hydrogen-control-url)`,+i.e. `http://127.0.0.1:<dynamic>` — the workspace shares loopback with the host)+has cheaper reads:++- `GET /workspace/health` — deep workspace health (workspace + code-server + host reachability)+- `GET /workspace/tabs` — list all workspace tabs right now+- `GET /workspace/tabs/find?name=X` — does a named tab exist (404 if not)++Use these in a poll loop when SSE would be overkill. See **hydrogen-api** for the full+control-port surface.++## The SSE endpoint++```text+GET /api/workspaces/editor/{owner}/{repo}/current/events+Header: X-Api-Key: <token>+```++Emits:+- `{"type": "connected"}` — once on connect+- `{"type": "workspace_updated"}` — on every workspace mutation (tab add/remove, split, resize, active tab change, panel state change)++The events don't include details about *what* changed — query `workspace tabs` or other endpoints after receiving an event to see the current state.++## Basic monitor: watch for workspace changes++```bash+# Monitor tool script — reports tab changes in real-time.+# Inside an Hydrogen workspace, talk to the LOCAL Hydrogen workspace API, not cloud hostnames:+# derive the base from ADOM_CARBON_URL / ADOM_HYDROGEN_URL (they point at+# http://127.0.0.1:<proxy>). The Hydrogen-local slug is `hdlocal`.+API_KEY=$(cat /var/run/adom/api-key)+CARBON="${ADOM_CARBON_URL:-http://127.0.0.1:47083}"+HYDROGEN="${ADOM_HYDROGEN_URL:-$CARBON}"+SLUG="hdlocal"+INFO=$(curl -s -H "Authorization: Bearer $API_KEY" "$CARBON/containers/$SLUG")+OWNER=$(echo "$INFO" | python3 -c "import sys,json; print(json.load(sys.stdin)['repository']['owner']['name'])")+REPO=$(echo "$INFO" | python3 -c "import sys,json; print(json.load(sys.stdin)['repository']['name'])")+BASE="$HYDROGEN/api/workspaces/editor/$OWNER/$REPO/current"+LAST=""++curl -s -N -H "X-Api-Key: $API_KEY" "$BASE/events" 2>/dev/null | while IFS= read -r line; do+ cleaned=$(echo "$line" | sed 's/^data: //')+ [ -z "$cleaned" ] && continue+ type=$(echo "$cleaned" | python3 -c "import sys,json; print(json.load(sys.stdin).get('type',''))" 2>/dev/null)+ [ -z "$type" ] && continue++ if [ "$type" = "workspace_updated" ]; then+ NOW=$(curl -s -H "X-Api-Key: $API_KEY" "$BASE/tabs" 2>/dev/null | python3 -c "+import sys,json+tabs=json.load(sys.stdin).get('tabs',[])+names=[t['name'] for t in tabs]+active=[t['name'] for t in tabs if t.get('isActive')]+print(f'tabs: {len(names)} — {\", \".join(names)} | active: {\", \".join(active)}')+" 2>/dev/null)+ if [ "$NOW" != "$LAST" ] && [ -n "$NOW" ]; then+ echo "[workspace] $NOW"+ LAST="$NOW"+ fi+ elif [ "$type" = "connected" ]; then+ echo "[connected] Monitoring $OWNER/$REPO"+ fi+done+```++Use with the Monitor tool:+```text+Monitor(description: "Hydrogen workspace events", persistent: true, command: "<script above>")+```++## Simpler: use adom-cli in the monitor++For lighter-weight monitoring, use `adom-cli` commands inside a poll loop instead of the SSE stream:++```bash+# Poll sharing status every 5s until it activates+while true; do+ STATUS=$(adom-cli hydrogen screenshot status 2>/dev/null)+ ACTIVE=$(echo "$STATUS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('sharing',{}).get('active',False))" 2>/dev/null)+ if [ "$ACTIVE" = "True" ]; then+ echo "[sharing] Screen sharing activated"+ break+ fi+ sleep 5+done+```++```bash+# Watch for a specific tab to appear+while true; do+ adom-cli hydrogen workspace find-tab "Schematic Editor" >/dev/null 2>&1 && {+ echo "[found] Schematic Editor tab is open"+ break+ }+ sleep 2+done+```++## Reactive patterns++### Auto-screenshot new panels+When the monitor detects a new tab, automatically screenshot it:++```bash+# In your monitor's workspace_updated handler:+if [ "$NOW" != "$LAST" ]; then+ # A new tab appeared — find it and screenshot+ NEW_TAB=$(diff <(echo "$LAST") <(echo "$NOW") | grep "^>" | head -1)+ echo "[new] $NEW_TAB — taking screenshot"+ adom-cli hydrogen screenshot workspace >/dev/null 2>&1+fi+```++### Wait for sharing then capture+Instead of `--wait-for-sharing`, use a monitor for more control:++```bash+# Monitor until sharing activates, then take all the screenshots you need+while true; do+ ACTIVE=$(adom-cli hydrogen screenshot status 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin).get('sharing',{}).get('active',False))" 2>/dev/null)+ if [ "$ACTIVE" = "True" ]; then+ echo "[ready] Sharing active — capturing"+ adom-cli hydrogen screenshot workspace+ adom-cli hydrogen screenshot panel --name "Schematic Editor"+ break+ fi+ sleep 2+done+```++## Best practices++1. **Use `persistent: true`** for session-length watches (workspace monitoring, demo flows)+2. **Filter events** — don't echo every `workspace_updated`, only report when state actually changes (diff against last known state)+3. **Use `--line-buffered`** with grep in pipes so events arrive immediately+4. **Handle connection drops** — the SSE stream can timeout; wrap in a reconnect loop if needed+5. **Prefer `--wait-for-sharing`** for simple "wait then screenshot" — Monitor is for when you need to react to multiple events or do complex logic+6. **Don't spam** — if the monitor emits too many events, Claude Code auto-stops it. Keep output selective++## Monitor vs other approaches++| Need | Approach |+|------|----------|+| Wait for sharing, then screenshot | `screenshot workspace --wait-for-sharing 30` |+| Check current state once | `screenshot status`, `workspace tabs`, `audio status` |+| React to workspace changes in real-time | **Monitor + SSE stream** |+| Run a multi-step demo with user interaction | **Monitor** — watch for user actions between steps |+| Poll until a condition is met | **Monitor** with a poll loop + `break` |+| Long-running background task with status | `Bash` with `run_in_background` |
skills/hydrogen-naming/SKILL.mdadded+80@@ -0,0 +1,80 @@+---+name: hydrogen-naming+description: >-+ Adom product naming rules: OS-visible install surfaces say "Adom Hydrogen", never bare+ "Hydrogen"; plus the shorthand table (ah, ab, hc, nbe, hbw, pup), the names no longer+ used, and the Linux package and binary names. Use when naming an installer, launcher+ entry, window title or wiki page, or when unsure what to call a product.+---++# Adom Product Naming++Canonical source: the **adom/definitions** wiki page. This skill is the+operational summary so the rules survive in every workspace.++## The table++| Product | Everyday name | Formal Name | ai shorthand |+|---|---|---|---|+| The desktop app | **Hydrogen** | **Adom Hydrogen** | **ah** (ah win, ah mac, ah ubuntu) |+| The desktop bridge/relay | **Bridge** | **Adom Bridge** | **ab** (ab win, ab mac, ab ubuntu) |+| The hosted web app | **Hydrogen Cloud** | Adom Hydrogen Cloud | **hc** |+| The wiki | **the wiki** | Adom Wiki | **aw** |++Say the everyday name in speech and UI copy. Reach for the Formal Name when+the Adom association matters: executables, installers, app-store listings,+marketing, and the first mention in a public doc.++## THE INSTALLER RULE (John, 2026-08-09 - never forget this)++Every OS-visible install surface MUST carry the Formal Name **"Adom Hydrogen"** (and "Adom+Bridge" for ab). On Linux that is:++- the application launcher entry (the app grid, Activities search, the desktop's menu)+- the package's product name and the published artifact filename+- the autostart entry (`~/.config/autostart/adom-hydrogen.desktop`, `Name=Adom Hydrogen`)++**Why:** a new user opens their app search and types **"adom"**, not "hydrogen", because they+have not memorized the product name yet. They know they installed something from Adom. If the+launcher entry says bare "Hydrogen", that search finds NOTHING and the product looks broken or+gone.+Adom must be in the installed name. That is the entire reason the Formal Name+exists as a register.++## Linux names (frozen, do not "fix")++| What | Name |+|---|---|+| Binary | `adom-hydrogen` (`/usr/bin/adom-hydrogen`). Not `hydrogen`: Debian and Ubuntu's `hydrogen` drum machine package owns `/usr/bin/hydrogen`. |+| Package (.deb / .rpm) | `adom-hydrogen` (`dpkg -L adom-hydrogen`, `rpm -ql adom-hydrogen`) |+| Root helper | `/usr/libexec/adom-hydrogen/hydrogen-workspace` (historical name; it manages the systemd-nspawn machine) |+| Sudoers drop-in | `/etc/sudoers.d/adom-hydrogen` (package) or `/etc/sudoers.d/adom-hydrogen-user` (AppImage first run) |+| State dir | `~/.config/hydrogen-desktop/` (log, ports.json, session, setup state) |+| Image cache | `~/.local/share/Adom/HydrogenDesktop/` |++## Dead names - never write these++- **hd / "Hydrogen Desktop"** in any copy (chat, docs, UI, skills). Say+ Hydrogen or ah. (Code identifiers like `hd_*` verbs or `hd-` crate names+ are unrenamed call sites, not license to use the name in prose.)+- **ad / "Adom Desktop"** - the product is Bridge (ab). The CLI is+ `adom-bridge`; the native launcher is `adom-bridge`.+- **hw** (now hc), **hdbw** (now hbw), **abe** (now nbe), bare single-letter+ shorthands (say ah, ab, aw - never h, b, w).++## Shorthand rule++Every shorthand is at least two letters. A natural one-letter shorthand takes+the Adom "a" prefix: **ah**, **ab**, **aw**. Anything already 2+ letters+never does: **hc**, **nb**, **nbe**, **hbw**, **pup**.++## Frozen internal identifiers (do NOT "fix" these)++These deliberately keep old spellings because they are load-bearing state or+build identity, renaming them breaks installs:++- Bundle identifier `inc.adom.hydrogen-desktop`+- Cargo package `hydrogen-desktop`+- GitHub repo `adom-inc/hydrogen-desktop`+- Workspace name `Adom-Workspace`+- The Linux names in the table above, including the `hydrogen-desktop` state dir
skills/hydrogen-networking/SKILL.mdadded+130@@ -0,0 +1,130 @@+---+name: hydrogen-networking+description: >-+ Port architecture, hostnames and networking rules for the Hydrogen workspace+ on Linux: one shared localhost with the host, the control URL, the+ code-server proxy, relay ports, LAN protection. Read before adding a port or+ exposing a service. Use for Hydrogen ports, loopback, proxy, or 7380/8770.+---++> **THE ONE RULE: the workspace shares this computer's network, so a port bound inside the+> workspace is `http://localhost:<port>/` on the host, and the other way round.** Webviews,+> browsers and host tools use the direct form. `/proxy/<port>/` through code-server is only a+> fallback.++# Hydrogen — Networking & Port Architecture++The workspace is the systemd-nspawn machine `Adom-Workspace`, started with no virtual network+(`VirtualEthernet=no`, `Private=no` in `/etc/systemd/nspawn/Adom-Workspace.nspawn`). It lives in+the host's network namespace:++- `127.0.0.1` is the same interface on both sides. No forwarding, no port mapping, no gateway IP.+- A port can only be bound once on the whole computer. A dev server in the workspace and a host+ program cannot both listen on 5173.+- `ss -ltn` or `/proc/net/tcp` inside the workspace also lists the host's listeners. Hydrogen's+ Ports window tells them apart by cgroup: processes in `machine.slice` are the workspace's.++## Kept off the LAN++Because the network is shared, a workspace service that binds `0.0.0.0` would be reachable from+other computers. Hydrogen's root helper installs its own nft table `inet adom_hydrogen` (iptables+fallback) on every machine start: new inbound connections to 7380, 8765, 8766, 8820, 8821 and to+any listener owned by `machine.slice` are dropped (that last match needs nft cgroup v2 socket+support; without it only the listed ports are covered); loopback and replies pass. Bind+`127.0.0.1` by default anyway: it is reachable from this computer and never from the network.++## Workspace services++| Port | Service | From the host |+|------|---------|---------------|+| 7380 | code-server (VS Code), bound 127.0.0.1 | `localhost:7380` |+| 8765 | relay WebSocket | `localhost:8765` or `/proxy/8765/` |+| 8766 | relay HTTP | `localhost:8766` or `/proxy/8766/` |+| 8820 | shotlog | `localhost:8820` |+| 8821 | adom-vscode editor-control API | `localhost:8821` |+| 5173 | your dev server | `localhost:5173` |++## Hydrogen's own ports (in the adom-hydrogen process on the host)++| Port | Service | Notes |+|------|---------|-------|+| 47080 | Discovery | tries 47080, 48080, 49180, 50280; first free wins |+| 47083 | Reverse proxy (`proxy`) | dynamic: ephemeral if taken |+| 47084 | Control API (`control`) | dynamic: ephemeral if taken |+| 47085 | `cdp` slot | nothing listens: WebKitGTK has no DevTools Protocol, Hydrogen's frame bus does that job |+| 8770 | Hydrogen direct API | 127.0.0.1 only |+| 9001 | Adom Bridge liveness beacon | |++Live values: `~/.config/hydrogen-desktop/ports.json` on the host; `GET <control>/ports` or+`/ports/all`.++## Hostnames — reach the host at `127.0.0.1`++### From inside the workspace to the host++Use `127.0.0.1`: it is the same interface on both sides. Every shell and code-server child also has+`ADOM_CARBON_URL` / `ADOM_HYDROGEN_URL` (`http://127.0.0.1:<proxy>`), `ADOM_HD_CONTROL_URL`, and+`ADOM_SHARED_LOCALHOST=1`.++The control port is **dynamic per launch** — read it from `~/.adom/hydrogen-control-url`+(your non-interactive Bash shells don't source `.bashrc`/`profile.d`, so the env var+alone is unreliable): `BASE="$(cat ~/.adom/hydrogen-control-url)"`.++### From the host to workspace services++Directly at `http://localhost:<port>/`, since the network is shared. The code-server proxy is a+fallback:++```+http://127.0.0.1:7380/proxy/<port>/ ws://127.0.0.1:7380/proxy/<port>/+```++Works for any workspace listener. Hydrogen answers a `/proxy/<port>/` URL handed to it with a hint+to use `http://localhost:<port>/` instead: the direct form survives editor reloads and keeps+absolute asset paths working.++### From the host → host-side services+```+http://127.0.0.1:{port}/+```+Control API → `http://127.0.0.1:47084/health`++## Relay++`adom-bridge serve` runs inside the workspace on 8765 (WS) / 8766 (HTTP); its live ports are in+`~/.adom/cli-relay-ports.json`. Hydrogen installs and starts Adom Bridge on Linux when a Linux build is+published for the user's account, and hands it the relay URL and session.+++## VSCODE_PROXY_URI++Inside the workspace, `VSCODE_PROXY_URI` is set by code-server:+```+https://<slug>.adom.cloud/proxy/{{port}}/ (cloud)+http://{{port}}.localhost:<proxy port>/ (Hydrogen local, 1.0.224+; the path form http://localhost:7380/proxy/<port>/ still works)+```++Tools that build proxy URLs should use `VSCODE_PROXY_URI` when+available, falling back to `http://127.0.0.1:{code_server}/proxy/{port}/`.++## Running a command in the workspace from the host++You are normally already inside. From a host terminal:++```bash+sudo machinectl shell adom@Adom-Workspace+# or the helper Hydrogen itself uses (allowed without a password for the user):+sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- <cmd>+```+++## NEVER Do These++1. **NEVER hardcode Hydrogen's ports** in workspace code. Read `~/.adom/hydrogen-control-url` or the+ `ADOM_*` variables.+2. **NEVER use `host.docker.internal` or a gateway IP.** The host is `127.0.0.1`.+3. **NEVER open the LAN protection** (flush `inet adom_hydrogen`) without the user asking for a+ service to be reachable from other devices, and tell them what it exposes.+4. **NEVER assume a port is free because nothing in the workspace uses it:** the host shares the+ port space.+5. **NEVER assume 8770 is Adom Bridge.** It is Hydrogen's own direct API on Linux.
skills/hydrogen-notifications/SKILL.mdadded+100@@ -0,0 +1,100 @@+---+name: hydrogen-notifications+description: >-+ How Hydrogen on Linux reaches the user outside the window: desktop+ notifications through `adom-cli notify` (the Hydrogen window raises them on+ the desktop's notification server), the title-bar bell, and the in-app+ /ui/toast. Use when asked to notify me, send a desktop notification, tell me+ when it's done, or show a toast.+---++# Hydrogen on Linux: Notifications++## The bell in the Title Bar++The bell right of the pencil (Annotate) and left of the avatar is the one-time switch for+**browser notifications from the editor itself**: code-server and the extensions inside it+raise `Notification` events (a task finished, an extension wants attention) and the webview+only shows them once the user has granted permission. The bell with a dot means "not asked+yet": one click asks, and a confirmation notification proves it works. Once granted the bell+disappears; a crossed bell means permission was denied. This is separate from the desktop+notifications below, which the AI fires through `adom-cli notify` and which need no bell.++When the user is not looking at Hydrogen (a long build is running, you finished a job, or you+are **blocked and need them**), fire a notification instead of printing into a panel nobody+is watching.++## Desktop notification: `adom-cli notify`++```bash+adom-cli notify --title "Build complete" "hd build finished, exit 0"+adom-cli notify --title "Need your OK" --require-interaction "Approve the schematic change?"+adom-cli notify --title "Export" --tag export-progress "42 of 100 parts" # same tag replaces+```++The workspace's adom-cli sends it to Hydrogen (`POST .../current/notification` on Hydrogen's+proxy), Hydrogen's window raises it with the page Notifications API, and WebKitGTK hands it+to the desktop's notification server (GNOME's banner and message tray, Cinnamon's, any+freedesktop notification daemon). Flags: `--icon` (an image or data URL, not an iconify+name), `--tag`, `--require-interaction` (stays until dismissed), `--silent`,+`--no-focus-on-click` (by default a click brings Hydrogen forward).++Read the answer, it is the real outcome: `shown`, `permission_required`, `denied`,+`unsupported`, or `no_browser` (Hydrogen's window is not connected). Hydrogen grants every+permission request its pages make, so `permission_required` should be rare; if it appears,+ask the user to click the bell in the Title Bar once.++Do Not Disturb on the desktop hides banners; the notification still lands in the message+tray.++## In-app toast — `POST /ui/toast` (inside the Hydrogen window)++The desktop notification above reaches the user **outside** the window. For a+lightweight message **inside** the Hydrogen window — the same toast UI the app uses for its own+success/error messages — fire a control-API toast:++```bash+# via the control API (or adom-cli hydrogen api, or the API Explorer "Try it")+POST /ui/toast { "message": "Build finished ✅", "type": "success", "duration": 5000 }+```++| Field | Notes |+|---|---|+| `message` | Required. The toast text. |+| `type` | `info` (default) / `success` / `warning` / `error` — sets icon + color. |+| `duration` | ms before auto-dismiss (default 5000). **0 = persistent** until the user dismisses. |+| `groupId` + `detail` | Optional: coalesce related toasts into one expandable group. |++It emits the `hd-toast` Tauri event, which the main window renders via the global+`toastStore` (bottom-stacked toasts). Use a desktop notification when the user may be+**away from** Hydrogen; use `/ui/toast` for an in-window status cue while they work in it.++From the workspace shell:++```bash+curl -s -X POST "$(cat ~/.adom/hydrogen-control-url)/ui/toast" -H 'Content-Type: application/json' \+ -d '{"message":"Build finished","type":"success","duration":5000}'+```++## Adom Bridge's `notify_user`++`adom-bridge notify_user` reaches this machine while Adom Bridge runs here (Hydrogen installs+and starts it when a Linux build is published for the user's account; it shows notifications+through notify-send). It also reaches the user's OTHER machines through the+mesh: `adom-bridge --target <machine> notify_user '{"title":"...","body":"..."}'`, for+example to pop a toast on their Windows PC.++## When you (the AI) should notify proactively++- **Long-job completion**: a build, a batch, a render, a deploy finished. Fire a desktop+ notification so the user can wander off and get pulled back.+- **You need the user**: an approval, a decision, a credential. Add `--require-interaction`.+- **Hands-free / driving** — pair a notification with audio (TTS) so the user gets both a+ glance-able toast and the spoken answer.++One notification per meaningful event, no spam. Check the result field before telling the+user you notified them.++## Related skills+- hydrogen-captions: on-screen captions inside Hydrogen+- hydrogen-adom-bridge: what Adom Bridge is and how to reach other machines
skills/hydrogen-open-url/SKILL.mdadded+212@@ -0,0 +1,212 @@+---+name: hydrogen-open-url+description: >-+ Decision guide for opening a URL from Hydrogen on Linux: webview tab, Hydrogen+ browser window, a native browser profile (Firefox, Chrome, Chromium...), Pup,+ the Browser Picker, or a headless fetch, and when to use each. Use when asked+ to open a website, open a link, pull up a page, open in a tab, or which+ browser to use.+---++# Hydrogen: opening a URL (Linux)++When a user says **"open the ti.com website"** (or any URL), Hydrogen has several paths+and a Browser Picker — but **don't hand the user the picker to decide.** Pick the+best destination *for them* by use-case and **open it directly**, then offer the+alternatives in one line. The right path depends on what they're doing — look at+it, have you drive it, keep it as a tab, or just read it. See **"Decide for the+user — DON'T hand them the picker"** below for the rule.++## The governing rule: background by default++When YOU (the AI) open a browser window, ask for the background. To foreground, pass+`foregroundReason:"<why>"` (logged). Legit reasons: a sign-in or consent page the user must click+now, or the user said "show me now". Omit it and the open is a background open.++On Linux Hydrogen cannot push a newly opened native browser window behind its own window: the+desktop's window manager decides whether it takes focus. So prefer in-Hydrogen destinations (wv,+hbw) or a headless fetch when you only need to look, and tell the user when you open their browser.++## The six ways++| # | Option | Best when… | What the user sees | AI drives it? |+|---|--------|-----------|--------------------|---------------|+| 1 | **Hydrogen webview tab** (aka **wv**) | the user wants the site *inside* Hydrogen, next to their work, and to keep it around | a panel/tab in the Hydrogen workspace | partly (reload/route) |+| 2 | **Hydrogen Browser Window** | a quick popout window owned by Hydrogen, not a full browser | a standalone Hydrogen-owned window | no |+| 3 | **Pup (Puppeteer Chrome)** | **you** need to act on the page: screenshot, click, scrape, fill a form, verify | a pup window on a machine that runs Adom Bridge (Hydrogen does not set it up on Linux) | **yes, fully** |+| 4 | **Native desktop browser** | real logins/sessions, downloads, "just open it for me", auth flows | their own Firefox, Chrome, Chromium... profile | no |+| 5 | **Browser Picker** | you're not sure, or it's an auth/OAuth link — let the user choose (5s auto-default) | a chooser dialog | n/a (routes to one of the above) |+| 6 | **curl / fetch (headless)** | you only need the *content*, not to show anything (read a datasheet, scrape JSON) | nothing — runs in the workspace | **yes** |++## "wv" = webview — the shortcut (spread it like `pup`)++**`wv` is the short alias for "webview"** — recognize it **everywhere** a user might say+"webview" (`open it in wv`, `wv tab`, `shot the wv`, `wv mode`). Treat `wv` and `webview` as+identical.++**Help it catch on:** the *first* time in a session a user types the long form **"webview"**,+open it as normal **and** add a one-line nudge — *"(btw you can just say **wv** — fewer+keystrokes)."* Say it **once**, not every time (don't nag). This is exactly how+**puppeteer → `pup`** became universal among Adom folks; `webview → wv` is the same play.+(If the user already says `wv`, they got the memo — skip the nudge.)++**Never** use VS Code's Simple Browser for "show me X in webview". The only correct destination is+a Hydrogen webview tab (`hydrogen-webview` skill).++## How you invoke each++All of these run from inside the Hydrogen workspace. The control API base URL is the live+value in `~/.adom/hydrogen-control-url` — `http://127.0.0.1:<dynamic>` (the workspace+shares loopback with the host; the port is dynamic per launch).+Read it with `BASE="$(cat ~/.adom/hydrogen-control-url)"` then hit `"$BASE/<endpoint>"`. On+Linux the workspace machine shares the host's network, so 127.0.0.1 is the same on both sides.++**1. Webview tab (wv)** — add a web-view tab pointed at the URL (`adom-workspace-control`,+or `adom-cli hydrogen webview open-or-refresh --name <X> --url <url> --panel-id <id>`). Good+for "keep this open while we work." ⚠️ **`open-or-refresh` needs `--panel-id` to CREATE a new+tab** — without it you get *"Tab 'X' not found and --panel-id not provided"* (verified live+2026-06-14; get a panel id from `adom-cli hydrogen workspace get`). Re-running with the same+`--name` once it exists just navigates/refreshes (no panel-id needed). Same `adom-cli` on+web-Hydrogen and Hydrogen — the consistent surface.++**2 / 4 / 5. Through the Browser Picker** — the single unifying entry point. POST+the URL and Hydrogen routes it (auto-picking a sensible default after a 5-second+countdown, or showing the chooser):+```bash+BASE="$(cat ~/.adom/hydrogen-control-url)" # http://127.0.0.1:<dynamic>++# Auto-route (picker picks the best default in 5s — hands-free)+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://www.ti.com"}' \+ "$BASE/open-url"++# Force the chooser dialog (no auto-timer — make the user pick)+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://www.ti.com","force":true}' \+ "$BASE/open-url"++# Route through the picker with the FRESH-WINDOW toggle pre-checked (the picked+# native browser opens in a new window instead of a tab):+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://claude.ai/","fresh":true,"force":true}' \+ "$BASE/open-url"+# ...or bypass the picker and open directly+fresh in a specific browser:+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://claude.ai/","browser":"firefox","profileDir":"Default","fresh":true}' \+ "$BASE/open-in-profile"+```+If `/open-url` replies with a timeout, check `GET $BASE/browser-picker/last-open`+(`{destination, url, fresh, ts}`) before calling it a failure.++**Sign-ins open in the system browser.** On Linux, AI sign-ins (`/open-url` with `signin:true`,+sent by Manage AIs) skip the picker and open in the system browser in the foreground. The picker+also treats known sign-in hosts (auth.openai.com, accounts.google.com, Kimi, `/oauth/authorize`+pages, device-code pages) as sign-ins and lists native browsers first: those pages refuse to load+inside Hydrogen. For any sign-in the picker defaults to the OS default browser.++**Fresh window (`"fresh":true`)**: the native-browser path (#4) opens the URL in a new window+(`--new-window` / `-new-window`) instead of a tab in the running browser. Whether that window+takes focus is up to the desktop's window manager. The Browser Picker defaults the "Open in a+fresh window" toggle ON for auth URLs. On `/open-url`, `fresh` pre-seeds that toggle (add+`direct:true` to skip the picker); `/open-in-profile` opens fresh directly.++**4. Native browser in a profile (Hydrogen Native Open).**+```bash+curl -s "$BASE/browser-profiles" # [{browser, dir, name, email, isDefault}]+```+- Always pass a `profileDir` from `/browser-profiles` so the window carries the user's login.+- Browsers detected on Linux: Firefox, Chrome, Chromium, Edge, Brave, Vivaldi, Opera, installed+ natively, as a snap or as a Flatpak. A Firefox profile with dir `Default` is that install's+ default (opens in the running Firefox); any other is opened with `-P <name>`.+- The answer's `method` names the program and profile. Read it before claiming success.++**Pup.** Pup windows come from Adom Bridge's Puppeteer bridge. `adom-bridge pup_*`+reaches a machine that runs Adom Bridge: this computer once Hydrogen has installed it (when a Linux+build is published for the user's account), or the user's other machine through the Adom mesh.+If no bridge answers, use wv or hbw for looking and `curl` for reading. See `hydrogen-pup`.++**6. Headless content** — if you only need to *read* the page, skip the browser+entirely:+```bash+curl -sL https://www.ti.com/... # or fetch from your own code+```++## mailto:, tel: and other app links++They open with the desktop's default app for that scheme. When none is set, Hydrogen copies the+address to the clipboard and says so in a toast.++## Decide for the user — DON'T hand them the picker++**Default behavior: pick the destination by use-case and open it DIRECTLY (bypass+the picker), then give a one-line heads-up + easy undo.** Do NOT fire a plain+`POST /open-url {url}` and let the picker's generic 5-second auto-default decide —+that default is luck-of-the-draw and often wrong for the use-case (a vendor-login+site could land in Pup where the user has no login). Users don't want to make this+choice; make the smart one for them. (Mechanics: `/open-in-profile` opens a+specific native browser+profile directly; `/open-url {direct:true}` bypasses the+picker; Pup and webview-tab are direct calls. Reserve the picker only as below.)++| Use case | Open it in | How (bypass the picker) |+|---|---|---|+| **Login-likely site** — vendor/account/portal/cart: TI, Mouser, DigiKey, any "my…"/sign-in | the user's **native browser + WORK profile** (their saved login/cookies live there) | `GET /browser-profiles` → find the work profile (non-gmail) → `POST /open-in-profile {url, browser, profileDir, fresh:true}` |+| **Building/testing their own app**, or you need to drive/screenshot/scrape the page | **Pup** (AI-drivable, needs Adom Bridge, see above) | `adom-bridge pup_*` |+| **Glance at content alongside their work** | **Hydrogen webview tab** | `adom-workspace-control` add web-view tab |+| **A quick popout owned by Hydrogen** | **Hydrogen Browser Window (hbw)** | `POST /hbw/open` |+| **You only need the content** | **headless** | `curl -sL <url>` |+| **Genuinely ambiguous, OR an OAuth/sign-in the user must complete themselves** | let them choose | `POST /open-url {url, force:true}` — the one time the picker is right |++Then say it in one line, with the undo: *"Opened TI in your Chrome work profile+(where your TI login lives) — say the word for a tab here, Pup, or a different+profile."* Decide, act, offer alternatives — don't ask first.++Example — "open the texas instruments website" (login-likely → native work profile):+```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s "$BASE/browser-profiles" # pick the work profile (non-gmail email)+curl -s -X POST -H 'Content-Type: application/json' \+ -d '{"url":"https://www.ti.com","browser":"chrome","profileDir":"<work profileDir>"}' \+ "$BASE/open-in-profile"+```++## Govern routing policy — the picker is now a true FALLBACK (Hydrogen prefs API)++The picker's per-domain memory is a first-class API (Hydrogen app behavior), so **the AI OWNS URL+routing** — the picker only pops for a domain with **no stored policy AND no direct call**.+Use this to set policy the user would otherwise click through the Manager for ("always open+DigiKey in my work profile", "stop auto-opening X in Edge").++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+# READ the policy map+curl -s "$BASE/browser-picker/prefs"+# → {ok, prefs:{domains:{"<host>":{destination,label}, …}}}+# SET / override one domain+curl -s -X PUT "$BASE/browser-picker/prefs" -H 'Content-Type: application/json' \+ -d '{"domain":"digikey.com","destination":"browser:edge:Default","label":"Edge — Default"}'+# FORGET one domain (e.g. "stop auto-opening X in Edge")+curl -s -X DELETE "$BASE/browser-picker/prefs/digikey.com"+# CLEAR all+curl -s -X DELETE "$BASE/browser-picker/prefs"+```++- **Stored value = `{destination, label}`** — NOT `profileDir`/`fresh`.+- **`destination` is an ID:**+ - **internal:** `hydrogen-tab` (a webview/wv tab) · `webview-window` · `pup-window`+ - **native:** `browser:<browser>:<dir>` — e.g. `browser:edge:Default`, `browser:chrome:Profile 1`. **The profile dir is encoded in the ID** (no separate field).+- **Discover valid native IDs** via `GET $BASE/browser-profiles` (maps each detected profile → its `browser`+`dir`); the 3 internal IDs are fixed above.+- **`fresh` is NOT stored in prefs** — it's a per-OPEN flag (`/open-url {fresh:…}` / `/open-in-profile {fresh:…}`). Don't try to persist it here.+- **Writes hit the live Manager UI immediately** (the backend writes `hydrogen-url-routing-prefs`+ localStorage + dispatches `hydrogen-url-routing-prefs-changed`; an open Browser Picker Manager+ re-reads at once, and re-reads on open anyway).++**Net:** for a one-off open, *decide and call the direct endpoint* (`/open-in-profile`,+`/open-url {direct:true}`, or a wv/pup call). For a *standing* preference, `PUT` the domain's+policy so even user-initiated link clicks route there silently. The picker is now only a+fallback for the genuinely-undecided.++## Related skills+- [hydrogen-browser-picker](../hydrogen-browser-picker/SKILL.md) — the interception layers + picker dialog behind #2/#4/#5+- `hydrogen-pup` — driving Pup browser windows (#3): navigate, screenshot, eval, reload+- `adom-workspace-control` — adding/managing Hydrogen webview tabs (#1)+- [hydrogen-runtime-mode](../hydrogen-runtime-mode/SKILL.md) — none of this changes across workspace runtimes
skills/hydrogen-overview/SKILL.mdadded+107@@ -0,0 +1,107 @@+---+name: hydrogen-overview+description: >-+ Index of the Hydrogen skills on Linux, one line each. Use when asked what Hydrogen can do,+ which skill covers a Hydrogen feature, for Hydrogen help, or when a task is about the+ Hydrogen app itself.+---++# Hydrogen: Skill Index (Linux)++Hydrogen (ah) is Adom's Tauri v2 desktop app (WebKitGTK on Linux, binary `adom-hydrogen`,+packaged as .deb, .rpm and AppImage). It runs your workspace, VS Code, Claude Code and the+other AIs, and the Adom Wiki on this computer. Here the workspace is **`Adom-Workspace`, a+systemd-nspawn machine** on the host kernel (no VM) that shares the host's network.++## Where these skills come from on Linux++- **adom/hydrogen-bootstrap** (a wiki package) ships the platform-generic skills.+- **Hydrogen itself** ships the Linux layer: the Hydrogen build embeds the Linux set (repo+ `skills/public-facing/shared/`, Linux render) and writes it into `~/.claude/skills/` at every launch and+ after every package convergence. A Linux skill is written over the package's copy of the same+ name, and platform-only skills with no Linux meaning are removed. So the skills below are the+ Linux versions even where the name matches a package skill. There are no per-platform+ companion skills on Linux.++## The Hydrogen skills on Linux++| Skill | What it covers |+|---|---|+| **hydrogen-adom-auth** | Adom login/logout, session token, auth proxy, credential replay, how auth feeds setup. |+| **hydrogen-adom-bridge** | What Hydrogen and Adom Bridge (ab) are and how they work together; on Linux Hydrogen installs and runs ab when a Linux build is published for the account, and the mesh reaches the user's other machines. |+| **hydrogen-adom-bridge-triage** | Triage ab when the workspace cannot reach it: is ab running on this desktop, its log, the /ab/* probes, other machines with `--target`. |+| **hydrogen-adom-menu** | The upper-left Adom logo menu (Settings, Ports, API Explorer, Developer Tools (WebKit Web Inspector), Setup/Virgin Reset), About dialog, version readout. |+| **hydrogen-ai-agents** | Install, sign in/out and check quota for the AIs in the workspace (Claude Code, Codex, Kimi Code, Antigravity) via the `/agents` API. |+| **hydrogen-ai-threads** | The AI Threads panel: the live tree of open AI conversations, reorder, rename, tag, TUI threads. |+| **hydrogen-ai-threads-api** | Open and drive AI conversations from code over the control API: open, list, stage or send a prompt, reopen, close. |+| **hydrogen-annotate** | Draw on a frozen picture of the screen (Title Bar pencil, tray, Super+Alt+A) and put a PNG on the clipboard. |+| **hydrogen-api** | The control API reference: endpoints, the control port, `GET /_manifest`, the API Explorer, which calls are destructive. |+| **hydrogen-avatar** | Generate or change the user's Adom avatar and make Hydrogen show it immediately. |+| **hydrogen-bridges** | The KiCad, Fusion 360 and Puppeteer bridges, served by Adom Bridge on a desktop, and how to tell which machine has them. |+| **hydrogen-browser-picker** | How URLs opened in Hydrogen are caught and routed (native browser profile, Hydrogen tab or window, Pup), the countdown. |+| **hydrogen-capture-share** | The screen-share "AI wants access" approval and countdown the AI triggers to capture the editor; tab/screen scopes. |+| **hydrogen-captions** | Paint caption text on the Hydrogen workspace with `adom-cli hydrogen caption` for demos. |+| **hydrogen-claude-auth** | How Claude Code signs in: the OAuth flow, credential backup, the `claude-auth` step. |+| **hydrogen-claude-management** | List/open/close/switch Claude conversation tabs, read conversation state, type/submit into a specific conversation, Remote Control. |+| **hydrogen-claude-permission-modes** | Why "Bypass permissions" is visible in the Modes menu, and when to reach for it. |+| **hydrogen-container** | Facts about the workspace: the Adom-Workspace systemd-nspawn machine, Ubuntu 24.04, code-server, the golden image. |+| **hydrogen-container-stats** | The title-bar CPU and RAM indicator, its tooltip, the cgroup numbers. |+| **hydrogen-demo-recording** | Recipe for a demo video: a typed prompt into a Claude tab, the desktop's own screen recorder, the file into the workspace. |+| **hydrogen-desktop-sse** | Hydrogen's local workspace API and SSE stream, so the workspace's adom-cli controls Hydrogen, not the cloud. |+| **hydrogen-dock** | The dock bar (app launcher rail) and how any wiki app becomes a card in it — dockbar.json manifest, launch steps, AI threads. |+| **hydrogen-doctor** | The one-click full-stack health scan (Doctor) with safe one-click fix; GET/POST /doctor. |+| **hydrogen-eda-discovery** | EDA tool discovery / setup flow. |+| **hydrogen-editor-state** | The true state of the VS Code editor and its Claude conversations, and the rules before typing into one. |+| **hydrogen-embedded-bridge** | How Hydrogen installs, starts and supervises ab on Linux: embedded mode, relay and session handover, updates, quit behaviour. |+| **hydrogen-eval** | Inject JS into any Hydrogen surface (shell/workbench/wiki/Claude) via /eval-in — add-ons, overlays, highlights, drive UI. |+| **hydrogen-file-transfer** | Move files between the workspace and this computer: /mnt/host, /files/inject, machinectl copy-to/copy-from. |+| **hydrogen-golden-image** | What the pre-baked workspace image contains, how package updates keep it current, the tarball pin. |+| **hydrogen-key-values** | The user's cloud key-value store (Carbon KV): hydrogen.* / bridge.* keys, read/write, conventions. |+| **hydrogen-lightbulb** | The title-bar lightbulb menu of sample prompts and sample-prompts.json. |+| **hydrogen-monitor** | Real-time SSE event stream + Monitor-tool patterns for watching workspace mutations. |+| **hydrogen-naming** | The naming doctrine: Hydrogen/ah, Bridge/ab, and WHY installers/shortcuts MUST say "Adom Hydrogen". |+| **hydrogen-networking** | Port architecture on Linux: one shared localhost with the host, the control URL, the code-server proxy, LAN protection. |+| **hydrogen-notifications** | Desktop notifications through `adom-cli notify`, the title-bar bell, toasts. |+| **hydrogen-open-url** | Decision guide for opening a URL: webview tab, Hydrogen browser window, native browser profile, Pup, headless fetch. |+| **hydrogen-overview** | This index. |+| **hydrogen-permissions** | Hydrogen auto-grants every webview permission; the AI's screen-share consent and ab's approvals are separate layers. |+| **hydrogen-port-watcher** | Why no port forwarding is needed on Linux: every workspace port is already on the host's localhost. |+| **hydrogen-ports** | How ports reach the host: shared localhost, the /proxy/<port>/ fallback, the Ports window, ports.json. |+| **hydrogen-profile-menu** | The avatar dropdown: profile/repos/molecules links and logout. |+| **hydrogen-project-workspaces** | The Project workspaces menu and API: apply or unload a project's bench layout (hydrogen/workspace.json). |+| **hydrogen-pup** | What "pup" means and exactly how to open an AI-drivable Chrome window via the Puppeteer bridge. |+| **hydrogen-recording** | Recording on Linux: no native recorder; the desktop's own recorder, audio-only via adom-cli, pup on another machine. |+| **hydrogen-runtime-mode** | Which runtime hosts the workspace: always the systemd-nspawn machine on Linux, and how to tell. |+| **hydrogen-screen-lock** | Why Hydrogen's screenshots never keep the display awake, and what to check when something does. |+| **hydrogen-self-screenshot** | Screenshot Hydrogen from the workspace: a panel or the whole window, or one element by CSS selector. |+| **hydrogen-self-update** | How Hydrogen updates itself on Linux (.deb, .rpm, AppImage). |+| **hydrogen-settings** | Hydrogen's Settings dialog + the preferences tree. |+| **hydrogen-setup** | The setup panel: the step cascade, Run All, Rollback All, Virgin Reset and its toggles. |+| **hydrogen-setup-steps** | What each setup step did to build and prepare the Linux workspace. |+| **hydrogen-staying-current** | How workspace tooling stays current (`adom-wiki pkg update`, the adom/hook prompt hook, reload banner) and how to ship a skill/CLI/app. |+| **hydrogen-tab-icons** | Webview tab icon system — `displayIcon` placeholder vs. the page's own favicon, SVG data URLs. |+| **hydrogen-topology** | Where Claude runs relative to Hydrogen (local workspace or cloud container) and how to reach the host and workspace. |+| **hydrogen-ui** | Hydrogen's menus, dialogs, panels and tray menu, and driving them via the UI command bus. |+| **hydrogen-volume** | Where the workspace's files live, what survives a restart or virgin reset, reaching them from the desktop. |+| **hydrogen-wake-repair** | What Hydrogen does when the editor loses its connection: the Cannot reconnect watcher and the backend banner. |+| **hydrogen-webview** | What "webview" means and how to open one via `adom-cli hydrogen webview open-or-refresh`; the External Webview. |+| **hydrogen-welcome** | The welcome page shown after setup completes. |+| **hydrogen-who-am-i** | Answer "who am I / what can I do here" — identity, resources, environment intro. |+| **hydrogen-widget** | Build, list, open and drive Hydrogen Widgets in the Title Bar: the hydrogen-widget.json facet and /widgets API. |+| **hydrogen-wiki-review** | After editing any wiki page, load it in pup so the user can review the rendered result. |+| **hydrogen-workspace-lifecycle** | Import, start, stop, restart and remove the Adom-Workspace machine; the root helper; code-server as a unit. |+| **hydrogen-workspace-monitoring** | How Hydrogen watches the workspace machine and code-server: polls, the stopped floaty, auto-start, auto-reload. |++Maintainer-only (hidden from the skill listing; Read the file when you need it):++| Skill | What it covers |+|---|---|+| `~/.claude/skills/hydrogen-ai-agents-dev/SKILL.md` | Design of Hydrogen's AI agent support: auth oracles, the no-duplicate-CLI rule, the toolbar and Manage AIs dialog. |+| `~/.claude/skills/hydrogen-skill-loop/SKILL.md` | Fixing a wrong Hydrogen skill: verify against the live system, fix it at its text source, publish. |++To list what is installed, with each description:++```bash+ls ~/.claude/skills | grep '^hydrogen-'+grep -h -A3 '^description' ~/.claude/skills/hydrogen-*/SKILL.md+```
skills/hydrogen-permissions/SKILL.mdadded+71@@ -0,0 +1,71 @@+---+name: hydrogen-permissions+description: >-+ Hydrogen auto-grants every webview permission (mic, camera, clipboard,+ geolocation, notifications), so a webview app never shows an Allow prompt; the+ AI's screen-share consent and Adom Bridge's command approvals are separate.+ Use when building a webview app with getUserMedia or clipboard, or asked why+ there is no permission prompt.+---++# Hydrogen auto-grants every webview permission++Hydrogen on Linux runs on WebKitGTK. Every webview it creates connects WebKit's+`permission-request` signal and answers **allow** to every request: microphone, camera,+clipboard, geolocation, notifications, media keys. So **inside Hydrogen the user never sees a+"this site wants to use your microphone / camera / clipboard / location" dialog**+(`hydrogen-app/src/full_permissions.rs`, `linux_webkit`).++The same module auto-confirms WebKit's native "Leave page?" (beforeunload) dialog, so reloading+the editor never stalls on a modal. Other `alert` / `confirm` / `prompt` dialogs keep WebKit's+default handling.++## Why Hydrogen does this++Hydrogen is the user's **trusted desktop app** — they've already chosen to run it. Intermediate+per-site Web permission prompts (especially the clipboard-paste dialog) are pure friction+with no added safety here, since there's no untrusted third-party browsing context: the+surfaces are Hydrogen's own panels and the user's own webview apps. So Hydrogen grants them all up+front.++## What this means for you when building webview apps++- **Don't instruct the user to "click Allow."** There is no prompt — telling them to look+ for one is wrong and confusing. `getUserMedia({ audio: true })`, clipboard reads,+ geolocation, notifications all resolve without a dialog.+- If a webview app gets no mic or camera data, the cause is **not** a denied prompt. Look at:+ no device present (`arecord -l`, `v4l2-ctl --list-devices` on the host), the device held by+ another app, PipeWire/PulseAudio routing, the page served from a non-secure context, or a+ code bug.+- This is behavior baked into Hydrogen's webview host — it's not something the web page or the+ user configures.+- The per-iframe `allow` attribute rewrite Hydrogen injects on its other platform is not+ applied on Linux yet; a deeply nested iframe with its own narrow `allow` list may still be+ limited by that list.++## NOT the same as in-app screen-share / mic consent++This auto-grant is **only** the low-level webview browser-permission layer. It is separate+from the **screen-share / microphone consent the AI itself requests** when it wants to+capture the user's screen or mic for a session — that flow **is** explicitly user-approved+(the user sees and accepts an in-app consent UI). Don't conflate them: webview site+permissions are silently allowed; the AI's capture/share request is a real, user-facing+approval. See `hydrogen-capture-share`.++## Third layer: Adom Bridge command approvals++When an Adom Bridge (ab) is attached to Hydrogen, gated ab commands (shell_execute, run_script,+write_file, ...) are approved by ab, which mirrors the request into Hydrogen's in-app dialog;+a click there is relayed to ab, first click on any surface wins. Hydrogen for Linux does not set+ab up, so on a desktop without ab this layer does not appear.++- **Grants are HUMAN-ONLY by design.** No API self-approves; `/permission/resolve` is+ de-escalation only. Never attempt to grant yourself permissions.+- Requests **fail closed** if the human doesn't respond; the requester's stated reason is+ always shown attributed ("caller says: ..."), never as fact.++## Related skills+- `hydrogen-capture-share` — the SEPARATE, user-approved screen-share / mic consent the AI requests+- [hydrogen-open-url](../hydrogen-open-url/SKILL.md) — opening URLs/webview apps inside Hydrogen (where these permissions apply)+- `hydrogen-browser-picker`: routing URLs to webviews vs the user's browsers+- `adom-bridge-permissions`: ab's approval gate in full
skills/hydrogen-port-watcher/SKILL.mdadded+57@@ -0,0 +1,57 @@+---+name: hydrogen-port-watcher+description: >-+ Why you don't need port forwarding in Hydrogen on Linux: the workspace shares+ the host's network, so every port it binds, including 127.0.0.1 OAuth+ callbacks, is already on the host's localhost. Use when asked about port+ forwarding, OAuth callback ports, Codex or extension auth, or why can't I+ reach my port.+---++# Hydrogen port watcher on Linux: there is nothing to forward++> **TL;DR for the AI: do NOT set up port forwarding.** The `Adom-Workspace` machine runs in the+> host's network namespace, so a listener on `127.0.0.1:<port>` in the workspace is the host's+> `localhost:<port>` already. If a port is not reachable, the service did not bind (or failed with+> "address in use" because a host program holds the port). Check with `ss -ltnp` in the workspace.++## OAuth callbacks just work++VS Code extensions (Codex, Claude Code, Copilot, GitLens) start a callback server on+`127.0.0.1:<port>` in the workspace and open the provider's page in the user's browser. The+browser's redirect to `http://localhost:<port>/callback?...` lands on that server directly. No+watcher, no host proxy, no registration. On Linux, AI sign-ins from Manage AIs open straight in+the system browser (no in-app tab, no picker).++## The forwarding machinery still in the API (not needed here)++Hydrogen keeps its port-forward registry for parity, but on a shared network it has nothing to do:+a "host proxy" would have to bind the very port the workspace service already holds, so it fails+to bind (logged as `[port-fwd] Failed to bind host port`).++- `POST <control>/adom-port-hints` with `{"port":N,"action":"register","name":"...","reason":"..."}`+ (also `unregister`, `open`, `close`); `GET <control>/adom-port-hints` lists entries.+- `POST <control>/start-oauth-proxy` `{"port":N}` or `{"url":"<oauth url with redirect_uri>"}`.++Do not call these to "fix" reachability on Linux. If a page in the browser shows Hydrogen's+"OAuth callback proxy" 502, something called them anyway; the real callback server is reachable at+`localhost:<port>` without it.++## Debugging an unreachable port++```bash+ss -ltnp | grep ':<port>' # who listens (host listeners show here too)+curl -sI http://127.0.0.1:<port>/ # same answer inside the workspace and on the host+```++- Nothing listening: the service never started or already exited (a callback server closes+ after one request).+- Listening but owned by a host program: the workspace server could not bind the same port; pick+ another port.+- Reachable here but not from another device: expected, Hydrogen's nft table keeps the workspace+ off the LAN (see `hydrogen-networking`).++## Related skills++- `hydrogen-networking`: shared localhost, LAN protection+- `hydrogen-ports`: the Ports window, ports.json, discovering Hydrogen's live ports
skills/hydrogen-ports/SKILL.mdadded+161@@ -0,0 +1,161 @@+---+name: hydrogen-ports+description: >-+ How ports reach the Linux host from the Hydrogen workspace: one shared+ localhost, the code-server /proxy/<port>/ URL as a fallback, the Ports window,+ ports.json and how to discover Hydrogen's live ports. Use when asked why my+ server isn't reachable, how to expose a port, or what localhost:7380 is.+---++# Hydrogen ports on Linux++The workspace (`Adom-Workspace`, a systemd-nspawn machine) shares the host's network namespace.+A service listening on `127.0.0.1:<port>` inside the workspace IS `localhost:<port>` on the host.+There is nothing to forward, map or register. Every shell has `ADOM_SHARED_LOCALHOST=1`, and it is+always 1 on Linux.++## Bind 127.0.0.1++| Bind address in the workspace | Reachable on this computer? | From the network? |+|---|---|---|+| `127.0.0.1:N` | yes, `localhost:N` | no |+| `0.0.0.0:N` | yes, `localhost:N` | no for Hydrogen's ports and workspace-owned listeners (Hydrogen's nft table drops new inbound connections) |++Bind `127.0.0.1` (most dev servers' default). The port space is shared with the host: if a host+program already holds N, the workspace server fails with "address in use", and the reverse.++## The code-server proxy URL (fallback)++```+http://localhost:7380/proxy/N/ ws://localhost:7380/proxy/N/+```++Works for any workspace listener, but prefer `http://localhost:N/`: no code-server dependency,+absolute asset paths keep working. Hydrogen's own responses steer `/proxy/N/` URLs to the direct+form.++Examples:+- Your dev server on port 5173 → `http://localhost:7380/proxy/5173/`+- The relay HTTP server on port 8766 → `http://localhost:7380/proxy/8766/`+- adom-vscode's API on port 8821 → `http://localhost:7380/proxy/8821/`++## The Ports window++Adom menu > **Ports...** (or `GET <control>/ports/all`, which is what it renders):++- **This computer:** Hydrogen's own listeners (Control, Proxy, Discovery, direct API 8770,+ beacon 9001). The `cdp` row reads down on purpose: WebKitGTK has no DevTools Protocol.+- **Workspace:** every listener inside the machine, read live, each with a direct URL+ (`http://localhost:N`) and a proxy URL. A port held by a host program shows as "Program on this+ computer, outside the workspace".++Click a URL to open it through the Browser Picker.++## Hydrogen's host ports++Stored in `~/.config/hydrogen-desktop/ports.json` (`PortConfig`: `code_server`, `proxy`,+`control`, `cdp`, `hostname`).++Defaults (you can override via ports.json):++| Service | Default host port |+|---------|-------------------|+| code-server | 7380 |+| Discovery server | 47080 (then 48080, 49180, 50280) |+| Reverse proxy (`proxy`) | 47083 |+| Hydrogen control API (`control`) | 47084 |+| `cdp` (unused on Linux: WebKitGTK has no DevTools Protocol) | 47085 |++On startup a taken `proxy`, `control` or `cdp` port is replaced by an OS-assigned ephemeral port,+saved to ports.json. `code_server` is never moved. So never assume 47084: discover it.++## Discovering Hydrogen itself: the three-rung ladder++Because `control`/`proxy`/`cdp` can rebind to ephemeral ports, anything that+needs to FIND a running Hydrogen walks this ladder (static defaults are only+rung zero, never an assumption):++1. **Local files (authoritative when present).**+ - Host: `~/.config/hydrogen-desktop/ports.json` (written every launch).+ - Inside the workspace: `~/.adom/hydrogen-control-url` (full live control URL)+ and `~/.adom/hydrogen-ports.json` (all four ports), both stamped by+ Hydrogen into the workspace. The relay's ports are in+ `~/.adom/cli-relay-ports.json` (8765 WS / 8766 HTTP).+ - No file reachable: `GET http://127.0.0.1:<c>/` for c in 47080, 48080, 49180, 50280+ (the discovery probe); the reply carries `control_url`.+2. **Verify liveness AND identity.** A port answering `/health` is not proof+ it is THIS install: a zombie from an uninstalled copy can still be serving+ (a real observed failure). `GET /buildinfo` returns `instance_id`, `pid`,+ and `install_path`; check they match what you expect before trusting a+ discovered port.+3. **Cloud KV (works even when local files are unreachable).** On every+ launch, and every 4 hours after, Hydrogen publishes its live runtime+ identity to the Adom cloud KV (Carbon):++ - Key: `hydrogen.runtime.<machine>` (machine = the kernel hostname,+ lowercased, other characters as `_`).+ - Value: a JSON string:+ `{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}`.+ - Read it: `GET https://carbon.adom.inc/user` (session token or API key+ auth) then `body.hydrogen_preferences.settings["hydrogen.runtime.<machine>"]`.+ - Freshness: compare `ts` (unix seconds) to now; the heartbeat refreshes it+ every 4 hours, so a `ts` older than ~5 hours means that instance is+ probably gone. Always confirm by hitting `/buildinfo` on the advertised+ port and matching `instance_id`.++ Adom Bridge publishes its container connection the same way+ (`bridge.container.<id>`, legacy `desktop.container.<id>` until ab's rename ships). This is what lets a cloud container, another+ machine, or a fresh install find the user's running desktop apps without+ port scanning.++## Inside vs outside — which URL to use++| From | To a service on port N | Use |+|---|---|---|+| Workspace | another workspace service | `http://localhost:N` |+| Workspace | a host program | `http://127.0.0.1:N` |+| Host browser or tool | a workspace service | `http://localhost:N` |+| Workspace | Hydrogen's control API | `$(cat ~/.adom/hydrogen-control-url)` |++## Common problems++- **"My dev server doesn't load."** Check it listens: `curl -sI localhost:5173` inside the+ workspace. If it does, it loads on the host at the same URL. If it does not start, look for+ "address in use": something on the host may hold the port.+- **"Another device on my network can't reach it."** Expected: the workspace is kept off the LAN.+ Only change that if the user asks, and say what it exposes.+- **"`localhost:7380` shows nothing."** code-server is down or restarting; see+ `hydrogen-workspace-monitoring` and `GET <control>/workspace/health`.++## Related skills++- `hydrogen-networking`: shared localhost, LAN protection, NEVER-do rules+- `hydrogen-port-watcher`: why there is no port forwarding to set up+- `hydrogen-browser-picker`: what happens when you click a Ports URL++## Bridge ports are dynamic++KiCad, Fusion 360, Puppeteer, and any 3rd-party bridges no longer have known+fixed ports. When a bridge launches, **adom-bridge picks an available port at+runtime** and registers it. To find a running bridge's current port, query+adom-bridge:++```bash+adom-bridge status+# Look at desktop.apps.<bridge>.bridgePort+```++Or use the bridge directly via adom-bridge CLI — you don't need the port at all:++```bash+adom-bridge kicad_open_board '{"path":"..."}' # adom-bridge routes to the right port+adom-bridge pup_eval '{"js":"..."}'+```++This means **old code or skill examples that hardcoded fixed bridge ports+(8771 / 8773 / 8851) are stale.** Use the adom-bridge CLI or `status` lookup+instead.++These verbs reach a machine that runs Adom Bridge: this computer once Hydrogen has installed it+(when a Linux build is published for the user's account), or one of the user's other machines+through the Adom mesh.
skills/hydrogen-profile-menu/SKILL.mdadded+104@@ -0,0 +1,104 @@+---+name: hydrogen-profile-menu+description: >-+ Hydrogen's profile menu, the avatar dropdown in the top-right corner: your profile,+ organizations, AIs, cloud key-values, your wiki pages and packages, the forum, and+ logout behind a confirm dialog. Use when asked how to log out, where Your profile is,+ about the login page, or why am I locked out.+---++# Hydrogen Profile Menu++Click the **circular avatar in the top-right corner** of Hydrogen to open it. Source:+`EditorNav.svelte` (`.profile-dropdown-button`, `.profile-dropdown-content`).++This is **separate from the Adom menu** (top-left logo). Different audiences, different functions — see **hydrogen-adom-menu** for the Adom menu.++## Where your avatar image comes from++- **Logged in via Google** — Hydrogen displays the Google profile photo that Google gives us as part of the sign-in payload. You change it by changing your Google account photo.+- **Logged in another way**: Hydrogen shows the avatar uploaded to your Adom profile. Change it from **Your profile** in this menu.++## What's in the menu++| Group | Item | What it does |+|---|---|---|+| Account | **Your profile** | the Public profile dialog (name, bio, company, avatar) in its own window |+| | **Your organizations** | your orgs, pending invitations, members |+| | **Your AIs** | which AIs are signed in (Claude Code, Codex, more); install or sign in to another |+| | **Your cloud key-values** | read-only viewer of your account's key-value store (see **hydrogen-key-values**) |+| Wiki | **My pages**, **My packages**, **My issues**, **My stars**, **My cloud libraries**, **Review queue** | the matching wiki.adom.inc page in a Hydrogen Browser Window |+| Community | **Forum** | forum.adom.inc in a Hydrogen Browser Window, signed in as you |+| | **Log out** | confirm dialog, then sign out |++## Log out — the confirm dialog++Clicking **Log out** opens this dialog:++```+┌──────────────────────────────────┐+│ Log Out │+│ │+│ Are you sure you want to log out?│+│ │+│ [Cancel] [Confirm] │+└──────────────────────────────────┘+```++- **Cancel** — dismisses the dialog, you stay signed in+- **Confirm**: calls the auth proxy's `/auth/logout` and `/auth/clear-local` (which deletes `~/.config/hydrogen-desktop/hydrogen-session.txt` on this computer), forgets saved browser choices for hydrogen, adom and claude domains, and routes the webview to `/auth/login`++After Confirm: you land on the Hydrogen login page and **cannot use Hydrogen until you log in again.**++## Login is a gate to using Hydrogen++Hydrogen is **not usable without an Adom login**. There is no anonymous mode, no skip-login option once you're signed out. The (app)/+layout.svelte enforces this — if the session token is missing or expired, every protected route redirects to `/auth/login`.++The login itself uses the auth-intent flow (no email/password entry in Hydrogen — you complete sign-in in your default browser, then Hydrogen picks up the session). See [hydrogen-adom-auth](../hydrogen-adom-auth/SKILL.md) for the full flow.++After successful login, Hydrogen restores you to the route you were trying to reach (or the dashboard).++## Driving it from an AI++Prefer the UI actions on the control API (`GET /ui/actions` lists them):++```bash+BASE="$(cat ~/.adom/hydrogen-control-url)"+curl -s -X POST "$BASE/ui/invoke" -d '{"id":"profile-menu.open"}'+curl -s -X POST "$BASE/ui/invoke" -d '{"id":"profile.keyvalues"}'+curl -s -X POST "$BASE/ui/invoke" -d '{"id":"profile.logout"}' # still asks the user to confirm+```++Or click through the DOM with these selectors:++| Element | Selector |+|---------|----------|+| Avatar button (top-right) | `.profile-dropdown-button` |+| Open dropdown | `.profile-dropdown-content` |+| Your profile item | first `.profile-dropdown-content .dropdown-link` |+| Log out item | `.profile-dropdown-content .dropdown-link` whose text is "Log out" |+| Logout confirm dialog | `.confirm-dialog` containing text "Log Out" |+| Confirm button | `.confirm-dialog .confirm-btn.confirm` |+| Cancel button | `.confirm-dialog .confirm-btn.cancel` |++Run these snippets in the shell surface via `POST /eval-in {target:"shell", js:"..."}`+(see [hydrogen-eval](../hydrogen-eval/SKILL.md)):+On Linux this runs over Hydrogen's frame bus in an isolated script world: the page's DOM is+reachable, its JS globals are not.++```js+// Open profile menu+document.querySelector('.profile-dropdown-button')?.click()++// Trigger logout+Array.from(document.querySelectorAll('.dropdown-link')).find(e => e.textContent.includes('Log out'))?.click()++// Confirm logout (after dialog appears)+Array.from(document.querySelectorAll('button')).find(b => b.textContent.trim() === 'Confirm')?.click()+```++## Related skills++- [hydrogen-adom-auth](../hydrogen-adom-auth/SKILL.md) — the Adom session token, login flow, profile loading+- [hydrogen-claude-auth](../hydrogen-claude-auth/SKILL.md) — Claude Code auth (separate from Adom auth; logging out of Adom does NOT log you out of Claude)+- **hydrogen-adom-menu** — the Adom menu (top-left, different dropdown)
skills/hydrogen-project-workspaces/SKILL.mdadded+61@@ -0,0 +1,61 @@+---+name: hydrogen-project-workspaces+description: >-+ Hydrogen's Project workspaces menu (icon right of the Adom logo) and its API:+ apply or unload the bench layout a project ships in hydrogen/workspace.json.+ Use when asked about project workspaces, apply a bench, workspace.json, or the+ workspace offer card.+---++# hydrogen-project-workspaces: the desktop side of shared workspaces++A project can ship its Hydrogen layout as `hydrogen/workspace.json` (or `hydrogen/workspaces/<name>.json`) in its page repo. The platform pieces are shared with Hydrogen Cloud and documented in the **wiki-workspaces** skill (file, hints, `adom-cli hydrogen workspace export|apply|teardown`) and **adom-workspace-control** (the pane routes). Hydrogen (ah) adds a menu, a one-time offer, placeholder tabs that know the bridge state, and a control API for all of it. Use the API; never click for the user.++## The menu++Right of the Adom logo. Benches grouped by project, labelled "project / name", from the checkout (`~/project` root and one clone folder down) plus the cloud mirror (`mirror`, and `legacy` when keyed by repo instead of project). Rows have Apply, Unload and a copy-the-command button; below: "Replace existing tabs on Apply" and "Save as project workspace". Apply/Unload/Save run adom-cli in the workspace with the output in a launch console tab (closes itself on success, stays with the reason on failure).++## Control API (ah, port 47084 by default; GET /ports for the real one)+The live control URL is in `~/.adom/hydrogen-control-url`.++| Route | Body | Notes |+|---|---|---|+| `GET /workspaces/benches` | | `benches[]` with identity, project, name, path, dir, source, legacy, tabs, panels, requires, applied, apply_command, unload_sources. |+| `POST /workspaces/refresh` | | rescan checkout + mirror |+| `POST /workspaces/apply` | `{identity|project|path|name, merge?, dryRun?, timeoutSec?}` | replace by default (the bench is built from scratch, the VS Code pane kept, displaced tabs restored by unload; `merge: true` adds the bench next to what is open); returns `ok`, `summary`, `envelope` (the CLI JSON), `console` |+| `POST /workspaces/unload` | same selectors | tries identity, then the relative and absolute path adom-cli may have recorded |+| `POST /workspaces/save` | `{dir, out?, project?}` | `adom-cli hydrogen workspace export --out <out>` in `dir`; `project` when the folder has no page.json |+| `POST /workspaces/offer` | `{action: "apply"|"dismiss"}` | answers the one-time card |+| `POST /workspaces/menu` | `{open: bool}` | UI-bus: `project-workspaces.open` / `.close` |+| `POST /workspaces/demo` | | the "Show me how it works" walkthrough (ab demo panel `pw-tour`, captions, narration); returns at once |+| `GET /workspaces/status` | | running, walkthrough, last (with transcript), offer, applied this session |+| `POST /ab/verb` | `{command, args?, timeoutMs?}` | any Adom Bridge verb on this machine (ab's own gates still apply) |++A name given to apply/unload resolves to the applied bench first, then a checkout bench, then a mirror copy (a legacy mirror entry can share a name with a checkout bench).++On Linux, the walkthrough and `/ab/verb` work while Adom Bridge runs on this computer (Hydrogen installs it when a Linux build is published for the user's account; `GET /ab/health` tells you). Apply, unload, save and the menu do not need it.++## Rules the desktop follows++- A checkout bench is applied as the local file from its project folder (what the user is editing); a mirror-only entry with a project uses the wiki ref. Identity is `project#hydrogen/...` (path inside the project), the key adom-cli and the cloud use.+- The project for a files-only wiki clone comes from the wiki (page.json has the slug, not the owner).+- The offer card appears only for a project that shows up in the checkouts after Hydrogen's first scan on that machine (a new clone). One card per app start at most, preference key `workspace.offered.<owner>.<repo>`; Apply, Not now and the one-minute timeout are remembered. Never auto-apply.+- Placeholder tabs ("X (not available)" / "(not started)", or `panelState.placeholder`) carry a card saying what happened, with Re-apply; the Adom Bridge state and a Connect button appear only when the app is a desktop bridge. For about a minute after apply Hydrogen reads the app's newest `~/.adom/launch-logs/<owner>-<slug>-*.log` for its last `http://127.0.0.1:<port>/` line, probes it inside the workspace, and re-points the tab in place.+- The workspace API on the proxy (47083) serves the cloud's granular routes plus `GET /api/panels/catalog`, `POST .../current/apply` (replace mode, keeps the VS Code leaf), and forwards `.../shared[/...]` to Hydrogen Cloud with the desktop session. Every tree mutation bumps a revision; a `PUT /current` whose `_rev` is behind gets 409, so an external apply cannot be erased by the browser's echo.+- `POST /splits` seeds the new pane with the placeholder tab adom-cli sends (`panelType`, `displayName`, `position`, `ratio`); adom-cli deletes it as tabIndex 0 after adding the bench's tabs.+- No 3D panel on the desktop: a `3d-viewer` tab renders as "not available on Hydrogen Desktop" (the UI's own wording).+- `hydrogen://edit?workspace=<ref|identity|path>` is registered for this user at every start; a second launch focuses the running Hydrogen, which applies the bench once the list loads. Test with `xdg-open "hydrogen://edit?workspace=john/example-bench"` on the host.+- The VS Code pane is never created, removed or replaced by any of this.++## Testing a change (the ralph loop)++```bash+CTL=$(cat ~/.adom/hydrogen-control-url)+cd ~/project && adom-wiki repo clone john/example-bench+curl -s -X POST $CTL/workspaces/refresh | jq '.benches[].identity'+curl -s -X POST $CTL/workspaces/apply -H 'content-type: application/json' -d '{"identity":"john/example-bench#hydrogen/workspace.json"}' | jq '{ok,summary}'+curl -s $CTL/workspace/tabs | jq '[.tabs[].name]'+curl -s -X POST $CTL/workspaces/unload -H 'content-type: application/json' -d '{"identity":"john/example-bench#hydrogen/workspace.json"}' | jq '{ok,summary}'+```++Symptoms: "no recorded apply" from the CLI means the source spelling differs from what apply recorded (the unload route already tries identity, relative and absolute path); an empty mirror in the menu with entries visible to curl means the forward stripped gzip (fixed 1.0.371, the proxy asks for identity encoding); a tab created by apply vanishing within a second means a stale browser write got through (the revision check refuses it since 1.0.364).
skills/hydrogen-recording/SKILL.mdadded+88@@ -0,0 +1,88 @@+---+name: hydrogen-recording+description: >-+ Recording the screen, a window or audio from Hydrogen on Linux: the native+ recorder is not available here, what works instead (the desktop's own screen+ recorder, audio-only via adom-cli, pup on another machine). Use when asked to+ record my screen, record kicad, record a window, record narration, or why+ recording start fails.+---++# Hydrogen on Linux: Screen, Window and Audio Recording++**Hydrogen's native screen and window recorder does not exist on Linux yet.** Every+`/recording/native/*` endpoint answers `{"ok": false, "error": ...}` saying native recording is not on this+platform (status answers `{"ok": true, "recording": false}`), and+`adom-cli hydrogen recording start` relays that same error, because in the Hydrogen app it+drives those endpoints. Do not retry it and do not promise the user an mp4 from it.++## What to do instead++| The user wants | Do this |+|---|---|+| A video of the screen, Hydrogen, KiCad, any app | Ask the user to record with their desktop's own recorder (GNOME: Ctrl+Shift+Alt+R, or the screenshot tool's video toggle; other desktops ship their own, or OBS). Then fetch the file (below). |+| Just their voice, a narration track | `adom-cli hydrogen audio start/stop` (below). |+| One browser tab | `adom-bridge --target <machine> pup_record_start` on ANOTHER of the user's machines that runs Adom Bridge (pup lives there), or `adom-bridge pup_record_start` here once Hydrogen has installed Adom Bridge on this computer. |+| A still image, not a video | `POST /screenshot` on the control API (see hydrogen-self-screenshot). On Linux it is a snapshot of the whole Hydrogen window. |++### Getting a desktop recording into the workspace++The workspace machine sees the host's `/home` at `/mnt/host/home` and the host's `/tmp` at+`/mnt/host/tmp` (the workspace's own `/tmp` is separate). GNOME saves screencasts to+`~/Videos/Screencasts/` of the host user, so look at+`/mnt/host/home/<host user>/Videos/Screencasts/`. If that reads "Permission denied" (many+distributions make home folders private to their owner), ask the user to copy the file to+`/tmp` on their desktop and read it from `/mnt/host/tmp/`. Copy it into+`~/project/recordings/` before you work on it.++## Audio-only — record a narration / voice track (`adom-cli hydrogen audio`)++When the user wants **just their voice, no video** — "record a narration track for+the video", "record my voice", "let me record some audio to narrate this" — use the+dedicated **`audio`** verb, NOT the video recorder:++```bash+adom-cli hydrogen audio enable # activate mic (silent if cached)+adom-cli hydrogen audio start --countdown 0 --reason "narration for the demo video"+# ... user speaks ...+adom-cli hydrogen audio stop # → filePath: audio/<name>.webm (relative to ~/project)+```++- Output is a **WebM / Opus** audio file in **`~/project/audio/`**. It records the microphone in+ Hydrogen's page (the browser media API; Hydrogen grants the page's microphone permission by+ itself). Reason is required.+- Other subcommands: `audio status` (mic active? device label), `audio level`+ (rms/peak/clipping/gain — warn if clipping), `audio gain <0.0-4.0>` (persists),+ `audio disable`.++### Stitching / post-processing (ffmpeg) — install it on demand++A common follow-on is "stitch these clips together" or "lay this narration over the+video." **ffmpeg/ffprobe are NOT pre-installed** — the Hydrogen workspace image is+intentionally **lightweight**, and the AI adds tools as the user needs them. That's+not a blocker: when you need to concatenate clips, mux a narration `.webm` onto an+`.mp4`, transcode, or probe a file, **just install ffmpeg and proceed** (passwordless+sudo + apt are available; ffmpeg ~6.1 is in the repos):++```bash+sudo apt-get update -qq && sudo apt-get install -y ffmpeg # pulls ffprobe too+```++Don't tell the user "ffmpeg isn't available here" — install it (a few seconds) and do+the job. Same pattern for any other missing tool (imagemagick, pandoc, …): install on+demand rather than declaring it impossible.++## Quick reference++| Intent | On Linux |+|---|---|+| Record the screen or a window | The desktop's own recorder, then read the file via `/mnt/host/...` |+| Record narration | `adom-cli hydrogen audio start/stop` to `~/project/audio/` |+| Record a pup tab | `pup_record_start` on another machine with Adom Bridge (`--target`) |+| Is a recording running? | `GET /recording/native/status` always says `recording:false` here |++## Related skills+- hydrogen-self-screenshot: screenshots of Hydrogen's own window+- hydrogen-demo-recording: the demo recipe, adapted for Linux+- hydrogen-volume: which host paths the workspace can see+- hydrogen-screen-lock: why Hydrogen on Linux holds no display wake-lock
skills/hydrogen-runtime-mode/SKILL.mdadded+38@@ -0,0 +1,38 @@+---+name: hydrogen-runtime-mode+description: >-+ Which runtime hosts your Hydrogen workspace on Linux: always the+ Adom-Workspace systemd-nspawn machine (NspawnHost), how to tell, and what that+ means for files, ports and exec. Use when asked am I in docker, a VM or a+ container, which runtime, or when workspace networking, ports or setup advice+ conflicts.+---++# Hydrogen Runtime Mode on Linux: systemd-nspawn, always++On a Linux desktop Hydrogen has exactly one workspace runtime: **`NspawnHost`**, the `Adom-Workspace` systemd-nspawn machine on the host kernel (`select_runtime()` in `hydrogen-runtime/src/runtime/mod.rs` returns it unconditionally on Linux; the host prep is `runtime/linux.rs`). There is no Docker runtime, no VM, and no switch. If any advice assumes a different runtime, it is the wrong advice for this machine.++## Which runtime am I in? (authoritative checks)++1. **From inside the workspace:** `systemd-detect-virt` prints `systemd-nspawn`; `/mnt/host/home` exists.+2. **Hydrogen's API:** `curl -s "$(cat ~/.adom/hydrogen-control-url)/container-stats"` shows `"runtime": "nspawn_host"` and `"image": "systemd-nspawn: Adom-Workspace"`.+3. **Hydrogen's log** (`~/.config/hydrogen-desktop/` on the host): `[app] Active workspace runtime: NspawnHost`.+4. **On the host:** `machinectl list` shows `Adom-Workspace`.++## What this runtime means++| Concern | systemd-nspawn on Linux |+|---|---|+| Workspace | `Adom-Workspace`, the golden rootfs unpacked into `/var/lib/machines/Adom-Workspace` |+| Kernel | the host's own (no VM); `/proc/meminfo` inside is the whole PC's |+| Run a command in it (host side) | Hydrogen's root helper: `sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- <cmd>` (it enters the machine with `nsenter`) |+| Your files | `/home/adom/project` in the machine's rootfs on the host disk; host `/home` is mounted at `/mnt/host/home` |+| Ports | shared host network namespace: `127.0.0.1` is the same inside and outside; workspace ports are dropped for inbound LAN traffic by the helper's `adom_hydrogen` nft table |+| Reach Hydrogen | `127.0.0.1`; the live control URL is in `~/.adom/hydrogen-control-url` |+| Wipe/reset | Virgin Reset in the Setup panel (removes only `Adom-Workspace` through `machinectl`) |++Some API endpoints and env names keep their historical names (`/wsl/status`, the helper `hydrogen-workspace`, `WSL_DISTRO_NAME`): they serve the nspawn machine here.++## Which skills to trust++The workspace skills on this machine (`hydrogen-container`, `hydrogen-networking`, `hydrogen-ports`, `hydrogen-volume`, `hydrogen-topology`, `hydrogen-setup`, `hydrogen-setup-steps`, `hydrogen-workspace-lifecycle`, `hydrogen-workspace-monitoring`, ...) are the Linux versions. If something tells you to use `docker exec`, named volumes, or a VM's console, it does not apply here.
skills/hydrogen-screen-lock/SKILL.mdadded+55@@ -0,0 +1,55 @@+---+name: hydrogen-screen-lock+description: >-+ Hydrogen screen capture and the display wake-lock on Linux: why Hydrogen's+ screenshots never keep the display awake or block the screensaver, and what+ to check when something does. Use when the display won't sleep, the+ screensaver or screen lock is blocked, or before adding a screenshot or+ recording feature.+---++# Hydrogen screen capture & the display wake-lock++A browser screen share (`getDisplayMedia`) keeps the display awake for as long as the stream+lives: no screensaver, no blank, no auto-lock, and on some screens burn-in. Web Hydrogen keeps+such a stream alive all session, so it can hold the display on.++## Hydrogen on Linux holds no wake-lock++- **Screenshots** are a one-shot WebKit snapshot of Hydrogen's own window (`POST /screenshot`,+ `adom-cli hydrogen screenshot`). No media stream, nothing to release. See+ `hydrogen-self-screenshot`.+- **Native recording** does not run on Linux (`/recording/native/start` answers that it is not+ available here), so there is no recorder to forget.+- Hydrogen takes no idle or screensaver inhibitor of its own.++So if the display will not sleep, the holder is something else.++## Rules for any new capture feature+- **Screenshots:** grab the frame → done. Never hold a capture between shots.+- Anything long-running needs a hard maximum duration, a visible "recording" indicator, and a+ `reason` to extend the cap.++## If you DO find the display pinned on++In a terminal on the desktop (not in the workspace):++1. `systemd-inhibit --list` shows logind inhibitors (look for `idle`).+2. On GNOME, `gnome-session-inhibit --list` shows apps that asked the session to stay awake.+3. A **browser** holding it is usually a screen share: a web Hydrogen tab or a pup capture.+ Stop it at the source: `adom-cli hydrogen sharing stop`, close the tab, or+ `pup_record_stop`.+4. If it names **Hydrogen** (`adom-hydrogen`), that is unexpected: save the output and file it+ as a bug.++A screensaver cannot clear another process's inhibitor, so release at the source is the fix.++## Separate concern: capture contention+Another thread's screenshot must never silently fail. With no native recorder on Linux this+rarely matters; if the adom-cli path answers `capture_busy`, read its `alternatives` and use+`POST /screenshot`. `GET /capture/availability` lists the methods.++## Related skills+- `hydrogen-recording`: why native recording is not on Linux, and what to use instead+- `hydrogen-self-screenshot`: WebKit screenshots of Hydrogen's window (no wake-lock)+- [hydrogen-notifications](../hydrogen-notifications/SKILL.md) — OS toasts + the in-app `/ui/toast`
skills/hydrogen-self-screenshot/SKILL.mdadded+142@@ -0,0 +1,142 @@+---+name: hydrogen-self-screenshot+description: >-+ Screenshot Hydrogen from inside the workspace: a panel or the whole window+ with `adom-cli hydrogen screenshot`, or one element with POST /screenshot and+ a CSS selector. Use when asked to screenshot the welcome page, a webview, a+ menu, my screen, or to verify a UI change.+---++# Hydrogen: Screenshot a panel, webview or the window (Linux)++The built-in way to screenshot anything inside Hydrogen is the **`adom-cli hydrogen+screenshot`** command — the *same* `adom-cli` you already use. It captures the+real rendered surface, drops a PNG into the container's `screenshots/` folder,+and prints the path. Just `Read` that path. **No image resizer needed.**++On Linux every Hydrogen screenshot is **WebKit's own snapshot of the main window** (its+visible region, iframes included), taken once and released. A CSS selector crops that+snapshot to one element. There is no CDP capture on WebKitGTK.++## Which tool++1. **Hydrogen content (the default): `adom-cli hydrogen screenshot panel|workspace`.** Same+ command as web Hydrogen. It saves a PNG under `~/project/screenshots/` and prints the path;+ `Read` it.+2. **A precise element, inline base64, or no flash: `POST /screenshot`** on the control API+ (below).+3. **Another app or the whole desktop:** Hydrogen cannot capture outside its own window on+ Linux. `adom-cli hydrogen screenshot screen` returns the Hydrogen window, not the desktop.+ Its `desktop_screenshot_*` verbs work while Adom Bridge runs on this desktop (Hydrogen installs+ and starts it when a Linux build is published for the user's account; `GET /ab/health` tells you).+4. **Your app in a pup window:** `adom-bridge pup_screenshot` (the `pup` skill), which needs+ Adom Bridge on the machine running pup.++## Do this — it saves a PNG and prints the path; then Read it++```bash+# Whole workspace (simplest — no tab name needed):+adom-cli hydrogen screenshot workspace+# → prints screenshots/<ts>.png (relative to ~/project) → Read ~/project/screenshots/<ts>.png++# A specific panel / webview tab. Tab names are whatever the USER has open — DON'T+# guess (a guess like --name welcome 404s if the tab is actually named "Wiki").+# If you're not certain the tab exists by that name, LIST tabs first:+adom-cli hydrogen workspace get # shows every panel/tab: its id AND name+# then capture by --tab-id (most reliable) or the EXACT name you saw:+adom-cli hydrogen screenshot panel --tab-id <tabId>+adom-cli hydrogen screenshot panel --name "3D Viewer"+```++The welcome page is *usually* a tab named "Welcome", but on an active workspace it+may be replaced (e.g. by a "Wiki" tab) — so if `--name welcome` 404s with+`No tab matching 'welcome'`, run `adom-cli hydrogen workspace get` and screenshot+the webview tab you find by its `--tab-id`.++### What it returns — a saved path; just Read it+The command saves the PNG into the container's `screenshots/` folder and prints the+path. **Read it — done.** No decoding, no resizer, no second tool. The printed path+is **relative to `~/project`** (matches the cloud contract); the `_hint` gives the full+path:++```+screenshots/2026-06-13T20-04-43.png+_hint: Screenshot saved to ~/project/screenshots/<ts>.png. Read the file to view it.+```+→ `Read ~/project/screenshots/<ts>.png` (prepend `~/project/` to the line-1 path, or+just use the full path from the `_hint`).++### If a capture errors, retry once+A COLD capture can occasionally fail with a proxy URL containing a literal `{{port}}`+(e.g. `…/proxy/{{port}}/: error sending request`) — a known **adom-cli** cold-start+race (the proxy port isn't substituted yet). Just **run the same command again**; the+warm retry succeeds.++A panel shot activates the tab and crops to that panel.++`adom-cli hydrogen screenshot status` reports sharing; Hydrogen captures natively, so sharing+always reads active and nothing holds the display.++## What NOT to do (these are the traps)++- **You do NOT need an image resizer.** `adom-cli hydrogen screenshot` produces a+ normal PNG and the `Read` tool reads PNGs directly. (Don't reach for ImageMagick+ `convert` or Pillow — neither is guaranteed in the golden image, and you don't+ need them.)++## POST /screenshot: any element, inline, or silent++For a precise element, an inline PNG or no flash, use Hydrogen's capture endpoint+`POST /screenshot` (aliases: `/shot`, `/capture/viewport`). Read the control URL from the file:++```bash+CTRL="$(cat ~/.adom/hydrogen-control-url)" # http://127.0.0.1:<dynamic>+curl -s -X POST "$CTRL/screenshot" -H 'Content-Type: application/json' \+ -d '{"target":"full","b64":true}'+```++| Field | Meaning on Linux |+|---|---|+| `target` | Every target gets the whole main window (`full`, `window`, `shell`, `hd`, `vscode`, a tab name or a url piece). Per-surface crops are not implemented yet; use `selector`. |+| `selector` | CSS selector in Hydrogen's own page: crops the snapshot to that element (for example `.resource-bars`, `.setup-panel`, `.dialog`, `.dropdown-content.open`, `[data-pane-id="<id>"] .panel-body`). Not found means the whole window is kept. |+| `b64` | `true` → returns the PNG inline as a `dataUrl` (decode + Read); else saved to a file in `screenshots/` |+| `silent` | `true` → suppress the capture flash |+| `name` | optional label for the saved file |++Content inside an iframe is in the snapshot, but a selector only matches elements of+Hydrogen's own page (crop to the panel holding the iframe instead).++### Screenshot a menu / dialog / panel — open it, then clip to it+The killer combo with the UI command bus (see **`hydrogen-ui`**): **open a surface →+screenshot just that surface → close it** — no screen-clicking, no guessing where it is.+```bash+CTRL="$(cat ~/.adom/hydrogen-control-url)"+curl -s -X POST "$CTRL/ui/invoke" -H 'Content-Type: application/json' -d '{"id":"adom-menu.open"}'+curl -s -X POST "$CTRL/screenshot" -H 'Content-Type: application/json' -d '{"target":"shell","selector":".dropdown-content.open","b64":true}'+curl -s -X POST "$CTRL/ui/invoke" -H 'Content-Type: application/json' -d '{"id":"adom-menu.close"}'+```+Resolved selectors (verified live): **Adom menu & profile menu** → `.dropdown-content.open`+(only one open at a time); **Setup panel** → `.setup-panel`; **API Explorer** → `.dialog`.+`GET $CTRL/ui/actions` for the live set of menus/dialogs you can open (see `hydrogen-ui`).++## Ralph loop + shotlog (optional)++Verify a UI change: make the change → (rebuild if needed) →+`adom-cli hydrogen screenshot panel --name <panel>` → `Read` it → wrong? fix and+repeat. Log shots for the user with `shotlog inject -c hydrogen-ui -d "<desc>" <path>`+(shotlog resizes internally — another reason you don't need `convert`).++## Related skills+- [hydrogen-capture-share](../hydrogen-capture-share/SKILL.md) — the sharing/approval UX behind `screenshot`+- [hydrogen-recording](../hydrogen-recording/SKILL.md) · [hydrogen-captions](../hydrogen-captions/SKILL.md) — sibling `adom-cli hydrogen` AV verbs+- `shotlog` — the screenshot log viewer/injector+- `hydrogen-ui` (the command bus), `hydrogen-desktop-sse` (how adom-cli reaches Hydrogen), `hydrogen-annotate` (the human marks up the screen)++## Recording and capture_busy+Hydrogen's native screen recorder does not run on Linux, so a recording never blocks a+screenshot. If the adom-cli path ever answers `capture_busy`, read its `alternatives` and use+`POST /screenshot`; do not retry blindly. `GET /capture/availability` lists the methods.++## Do not+- Do not curl `host.docker.internal`; Hydrogen is at `127.0.0.1` (the workspace shares the host+ network) and the control URL is in `~/.adom/hydrogen-control-url`.
skills/hydrogen-self-update/SKILL.mdadded+91@@ -0,0 +1,91 @@+---+name: hydrogen-self-update+description: >-+ How the Hydrogen app itself (not the workspace tooling) updates on Linux: the+ restart-to-update banner, the .deb/.rpm/AppImage install with sudo or the password+ prompt, and the consent-based AI path through /updater. Use when asked is there a+ Hydrogen update, update Hydrogen, what version of Hydrogen am I on, or relaunch to update.+---++# Hydrogen Self-Update on Linux: the app updates itself (a banner + an AI path)++This is how the **Hydrogen app** on the user's Linux computer stays current. It is NOT how the+workspace tooling and skills update (those converge through `adom-wiki pkg update` and the+`adom/hook` prompt hook), and NOT the editor extensions (their own reload banner). Don't confuse+the three.++## How it works++1. **The manifest.** Hydrogen polls the wiki's `version.json` at startup, then every 4 hours on+ the public tier and every 8 hours on Insiders. The manifest has a `linux` section with up to+ three builds: `deb`, `rpm`, `appimage`.+2. **Which build applies: the kind this copy was installed with.** It is an AppImage when+ `$APPIMAGE` is set; otherwise whichever of dpkg or rpm owns `/usr/bin/adom-hydrogen`. A copy+ from none of the three (a dev binary) cannot update itself.+3. **Download and stage** in the background, verified by sha256 and size.+4. **The banner.** Hydrogen shows **"Restart to update (vX to vY)"** only when the manifest has+ a newer build for THIS package kind. A newer version with no Linux build of this kind (or none+ at all) shows no banner; `/updater/status` then says why in `not_installable`, for example+ "1.0.720 is out, but its Linux .rpm is not published yet."+5. **The install** (one click, or the AI path below):+ - **.deb**: `apt-get install -y <file>`.+ - **.rpm**: `dnf install -y <file>`, or `rpm -U` when dnf is not there.+ - Root comes from `sudo -n` first (never prompts; the package's sudoers rule covers admin+ users), then `pkexec`, which shows the desktop's password prompt (15 minutes to answer).+ - **AppImage**: the new file replaces the AppImage in place; no root needed.+ - VS Code's page is unloaded first so it saves its open tabs.+6. **Relaunch.** A relauncher started as its own `systemd-run --user` unit (setsid when that is+ missing) waits for the old process to exit and starts the new build. Sign-ins+ (`~/.config/hydrogen-desktop`) and the workspace machine are not touched, so this session+ reconnects in a few seconds.+7. **When it fails**, the banner shows the error with the command to run by hand (for example+ `sudo apt-get install -y /tmp/<file>.deb`). A cancelled password prompt changes nothing.++## When to check+Check at the **start of a session** and whenever the user asks about updates. Don't poll+constantly.++## How to check (know both version numbers)+```bash+C=$(cat ~/.adom/hydrogen-control-url)+curl -s -X POST "$C/updater/check" # same as Settings "Check now": re-poll and stage now+sleep 5; curl -s "$C/updater/status"+```++Returns `{ current_version, latest_version, update_available, staged, installable,+not_installable, tier, ... }`:+- `update_available: true` → a newer Hydrogen exists.+- `installable: false`: there is nothing this machine can install; tell the user the+ `not_installable` sentence, and do not offer to update.+- `staged: true`: already downloaded and verified, so applying is quick.++## What to do++If `update_available` and `installable`, **tell the user both versions and ASK**, and say that+the install may ask for their password:+> "Hydrogen **vX to vY** is available (already downloaded). Want me to install it and relaunch?+> Your computer may ask for your password. This workspace and our chat reconnect right after."++On **explicit consent**:+```+POST http://127.0.0.1:<control-port>/updater/install+```++It refuses (`deferred: true`, with `busy`) while an AI thread is mid-turn; pass+`{"force":true}` only when the person agreed to cut that work off.++## Rules+- **Consent-first.** Never relaunch Hydrogen 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 their own reload banner;+ in-workspace tooling/skills converge registry-native (`adom-wiki pkg update` via `adom/hook`).+ Don't confuse the three.+- The password prompt is the user's: never try to answer or bypass it.++## Resolving the control port+From inside the workspace, `cat ~/.adom/hydrogen-control-url` is the live URL+(the control port is 47084 by default but rebinds to an ephemeral port when+47084 is taken, so never hardcode it). See the discovery ladder in+`hydrogen-ports` (`~/.config/hydrogen-desktop/ports.json` on the host,+`~/.adom/hydrogen-ports.json` in the workspace, and the cloud KV fallback).
skills/hydrogen-settings/SKILL.mdadded+125@@ -0,0 +1,125 @@+---+name: hydrogen-settings+description: >-+ Hydrogen's Settings window and its preferences on Linux: color scheme, fonts, font+ size, launch on boot, close button and tray, link handling, the Dock Bar, the Adom+ Bridge options, vim mode, 3D control style. Use when asked how to turn on vim mode,+ change the theme, make Hydrogen launch on boot, or where the settings are.+---++# Hydrogen Settings: the preference tree++Open it from the **Adom logo menu** (upper-left) > **Settings**, or the tray menu's+**Settings**. The canonical tree of sections and keys lives in `src/lib/stores/settings.ts`+(`settingsTree`); on Linux `forHost()` hides the settings that do nothing here (listed below).++Preferences are saved per-user (`saveUserSetting` → `PATCH /user/hydrogen/settings`)+and persist across sessions. Setting a key back to its default removes the+override. Keys are dotted (`section.subsection.name`).+They live in the Adom account's cloud key-value store (see **hydrogen-key-values**), so they+follow the user to every machine.++## Sections, keys, and what each does++### general+| Key | Default | What it does |+|---|---|---|+| `general.developer_mode` | `false` | Enables extra developer/debugging features in the app |+| `general.pane_focus_mode` | `false` | Only the focused pane is active and highlighted; turn it on to get the highlight |+| `general.editor.workspace_folder` | `project` | Folder VS Code opens: `project` = /home/adom/project, `home` = /home/adom |++**general.appearance** (subsection)+| Key | Default | What it does |+|---|---|---|+| `general.appearance.theme` | `adom-dark` | App-wide theme. Options: `adom-dark`, `adom-light`, `adom-dark-high-contrast`, `adom-light-high-contrast` (→ "change the theme" / "light mode" / "high contrast") |+| `general.appearance.user_interface_style` | `standard` | UI compactness: `standard` or `compact` (→ "make the UI more compact") |++### hydrogen.behavior additions (1.0.141+)+| Key | Default | What it does |+|---|---|---|+| `hydrogen.ai_threads_on_startup` | `false` | Open the AI Threads panel at startup. BETA; while off, nothing AI-Threads-related runs. Add Panel can still open it for one session. Takes effect next start |+| `hydrogen.show_lightbulb` | `false` | Show the lightbulb (sample prompts) menu in the header. Applies immediately |++### More hydrogen.* keys+| Key | Default | What it does |+|---|---|---|+| `hydrogen.launch_on_boot` | `false` | Open Hydrogen when you sign in to your desktop: writes or removes `~/.config/autostart/adom-hydrogen.desktop` (XDG autostart, honoured by GNOME, KDE, Cinnamon and others) |+| `hydrogen.color_scheme` | `studio` | `studio`, `studio-bright`, `studio-dark`, `kickstand`, `slate` (whole app, editor included) |+| `hydrogen.editor_code_font` / `hydrogen.editor_prose_font` | `theme` | Code and prose fonts in the editor |+| `hydrogen.editor_font_size` | `15` | Editor and terminal text size, px |+| `hydrogen.annotate.hotkey` | `true` | Super+Alt+A starts annotate from anywhere (a desktop custom keybinding) |+| `hydrogen.notify.remote_prompts`, `.ab_toasts`, `.remote_toasts` | `true` | Prompts and toasts from your other machines and from Adom Bridge |+| `hydrogen.nav_minimized` | `false` | Compact Title Bar |+| `hydrogen.close_button` | `tray` (`quit` with no tray) | The window's X: `tray` hides Hydrogen to the desktop's tray (open the tray icon's menu > Quit Hydrogen to exit); `quit` exits. On a desktop with no tray icons (stock Fedora GNOME) the choices are `quit` (the default) and `minimize`; Quit Hydrogen is also in the Adom menu |+| `hydrogen.show_approval_prompts` | `true` | Show Adom Bridge approval prompts inside Hydrogen |+| `hydrogen.link_open_mode` | `remember` | Remember where each site's links open, or ask every time (see **hydrogen-browser-picker**) |+| `hydrogen.show_progress_animation` | `true` | The orbital animation on progress cards |+| `hydrogen.assisted_signin` | `false` | Narrate and click Authorize during sign-in; it relies on desktop automation Hydrogen does not have on Linux |+| `hydrogen.watch_internet` | `true` | Once a minute, check the workspace can reach the internet (header meter tooltip) |+| `hydrogen.codex_care` | `true` | Reopen dead Codex tabs and keep its backend in step |+| `hydrogen.updater.*` | actions | Check for updates now; apply a newer workspace image |++On Linux the GPU preference, workspace networking mode, the recovery and wake group, the+close notice and shutdown-on-close are hidden (`forHost()` in `settings.ts`): they do nothing here.++**Dock Bar** (`dock.*`): `dock.groups.enabled`, `dock.hover.arm_delay` (1800 ms),+`dock.hover.alt_pin`, `dock.visibility.reveal_at_launch`, `.start_collapsed`,+`.collapse_on_launch`, `dock.ai.open_thread_on_launch`.++### adom_desktop *(Adom Bridge)*+These apply while Adom Bridge runs on this computer (Hydrogen installs it when a Linux build is+published for the user's account).+| Key | Type / default | What it does |+|---|---|---|+| `adom_desktop.open` | action button | Show the Adom Bridge window |+| `adom_desktop.permissions` | action | ab's approval mode (ask every time, 1 h, 24 h, Auto); granting is always the user's click in ab |+| `adom_desktop.show_window_on_launch` | bool, `false` | Show ab's window when Hydrogen launches |+| `adom_desktop.exit_with_hd` | bool, `true` | Ask ab to shut down when you quit Hydrogen |++### schematic *(Schematic Workspace)*+| Key | Default | What it does |+|---|---|---|+| `schematic.nudge_amount.small` | `1` px | Arrow-key nudge distance for components |+| `schematic.nudge_amount.large` | `8` px | Shift+arrow nudge distance |+| `schematic.invert_zoom_direction` | `false` | Invert mouse-wheel zoom direction |+| `schematic.default_cursor` | `crosshair` | Default cursor: `crosshair` or `pointer` |++### 3d *(3D Settings)*+| Key | Default | What it does |+|---|---|---|+| `3d.control_style` | `fusion` | Orbit/pan/zoom control scheme: `fusion`, `solidworks`, or `blender` (→ "use blender/solidworks controls") |+| `3d.invert_zoom_direction` | `false` | Invert mouse-wheel zoom direction in 3D |++### code *(Code Workspace)*+| Key | Default | What it does |+|---|---|---|+| `code.appearance.font.family` | `DM Mono` | Code editor font family (→ "change the code font") |+| `code.line_numbers.enabled` | `true` | Show line numbers (→ "hide line numbers" = set false) |+| `code.line_numbers.style` | `absolute` | Line-number style: `absolute` or `relative` |+| `code.vim_emulation_mode` | `false` | Vim motions in the code editor (→ "turn on vim mode" = set true) |++### simulator *(Simulator Workspace)*+| Key | Default | What it does |+|---|---|---|+| `simulator.code_editor_position` | `right` | Code editor position relative to the 3D environment: `right` or `left` |++### extensions+Present in the tree but currently has **no properties** (reserved for future+extension-specific settings).++## Answering common asks++- **"Turn on vim mode"** → `code.vim_emulation_mode` = true+- **"Change the theme / dark mode / high contrast"** → `general.appearance.theme`+- **"Make Hydrogen start when I log in"** → `hydrogen.launch_on_boot` = true+- **"Closing the window should quit"** → `hydrogen.close_button` = quit+- **"Bigger editor text"** → `hydrogen.editor_font_size`+- **"Change the colors"** → `hydrogen.color_scheme`+- **"Blender / SolidWorks orbit controls"** → `3d.control_style`+- **"Hide line numbers / change code font"** → `code.line_numbers.enabled` / `code.appearance.font.family`+- **"Make the UI compact"** → `general.appearance.user_interface_style` = compact++## Related skills+- [hydrogen-adom-menu](../hydrogen-adom-menu/SKILL.md) — the logo menu that opens Settings (and Ports, API Explorer, etc.)+- [hydrogen-ui](../hydrogen-ui/SKILL.md) — the broader Hydrogen UI / panel layout this dialog sits in+- **hydrogen-key-values**: where the preferences are stored
skills/hydrogen-setup-steps/SKILL.mdadded+126@@ -0,0 +1,126 @@+---+name: hydrogen-setup-steps+description: >-+ What Hydrogen's setup steps did to prepare the Linux workspace: build the+ systemd-nspawn machine from the golden image, bind the Adom session, check the+ relay, open Welcome. Use when asked what did setup do, why is X installed,+ re-run a setup step, why did step N fail, why did it ask for my password, or+ what a virgin reset is.+---++# Hydrogen Setup Steps (Linux): what was done to prepare your workspace++On first launch (or after a virgin reset) Hydrogen turns this Linux computer into+an Adom workspace: the `Adom-Workspace` systemd-nspawn machine, running on the+host kernel (no VM). The tooling (code-server, the Adom CLIs, the claude CLI and+Code extension, VS Code settings, the `hydrogen-*` skills) is baked into the+golden image; setup builds the machine from it, binds your Adom session and+opens Welcome. See `hydrogen-golden-image`.++The cascade lives in `src-tauri/crates/hydrogen-setup/` (the same code as on+the other platforms; Linux differs only at the runtime seam). Halt-on-failure,+resume-not-restart, per-step 3x auto-retry. Work inside the machine runs as+`adom` (home `/home/adom`) through the root helper+`sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- <cmd>`.+From inside the workspace you are already there: run commands directly.++## The steps (in order)++| # | Step | What it does on Linux |+|---|------|-----------------------|+| 1 | ensure-workspace | Makes the host ready (`systemd-container`, the helper, its sudoers rule: one pkexec password prompt only if the package did not install them), downloads the pinned golden image (about 775 MB, cached), unpacks it into `/var/lib/machines/Adom-Workspace`, gives it its own `/etc/machine-id` (the image ships one; an install made earlier gets its own at its next start), boots it. The output is a short summary; the workspace's boot log is folded under **Show the boot log**. The machine shares the host network, so nothing to configure there. |+| 2 | wait-codeserver | Probes code-server on the host loopback (default 7380) with a signature check, up to 120 s |+| 3 | os-baseline | Fills xz-utils on a v27 image; a no-op on later images |+| 4 | ensure-adom-bridge-cli | Passes if Adom Bridge's direct API answers (`127.0.0.1:24680`; 8770 is Hydrogen's own). Otherwise installs it when ab's manifest has a `linux` entry for this account (download, sha256 check, `--install --no-launch`), starts it hidden through its `run.sh` and waits up to 2 minutes. No Linux build for the account (or not signed in yet) logs "Skipped" and continues; Hydrogen tries again after sign-in and every 30 minutes |+| 5 | test-relay | Makes sure the relay inside the workspace answers (restarts `adom-relay.service` once if not) and is reachable through the code-server proxy; a gate |+| 6 | activate-editor | Waits for your Adom sign-in (it opens in your browser as soon as the workspace is built), proves the `:8821` editor API answers, then binds env vars, api key and relay to this launch |+| 7 | verify-setup | GATE: re-checks every artifact independently: image floor, code-server, editor API, adom-cli against Adom, the Claude CLI, env vars, relay, the synced layout |+| 8 | open-welcome | GATE (final): opens welcome.html in the right pane; halts unless the Welcome tab appears |++Off by default: `test-direct-connect` and `test-adom-cli` run only with+`HD_SETUP_DIAGNOSTICS=1` or the `setup-diagnostics.flag` marker+(`test-direct-connect` also skips on Linux when no Adom Bridge is running).+`update-packages` and `claude-auth` stay in the code behind switches and are off:+adom/hook converges packages at boot and every 30 minutes, and Choose your AI+handles sign-in after setup.++Former step ids such as `set-env-vars`, `inject-api-key`, `start-relay`,+`configure-vscode`, `install-claude-cli`, `install-brand-fonts`, `ensure-sse`,+`verify-workspace`, `welcome`, `install-hd-skills` no longer exist; their work is+in the launch hook, the golden image, a package, or a later gate. Do not list or+run them.++## Common questions++**"Why is X installed?"** Baked into the golden image (or installed by an Adom+package), not a setup step.++**"Why did it ask for my password?"** Hydrogen never runs as root; starting the+nspawn machine needs it. The .deb/.rpm set up a sudoers rule for one helper file;+an AppImage, or a user outside the admin groups, gets the same through one pkexec+prompt on first run.++**"Setup failed at step N"** The card shows the error and, when it knows one, the+fix: reinstall the package or approve the prompt (helper or `systemd-container`+missing); `sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace`+then Retry (the import failed); `sudo machinectl terminate Adom-Workspace` then+Retry (the machine did not boot). Setup never asks for a restart on Linux. Each+step has a Retry button.++**"Re-run a step"** Setup panel, or `POST $(cat ~/.adom/hydrogen-control-url)/setup/step/<id>`+(body `{"continue_after":true}` to keep going).++**"Re-run all steps"** → Click "Run All" in the setup panel; it resumes from the+first not-done step. (The old headless `POST /setup/run-all` is now REFUSED.)++## Virgin reset++Virgin reset wipes parts of your workspace so setup can rebuild them cleanly.+The ONLY programmatic trigger is `POST /setup/panel/run-virgin-reset`. Toggle+which artifacts to delete (option keys in parentheses):++| Toggle (key) | What gets wiped | When to use |+|---|---|---|+| Install step state (`install_state`) | Marks all steps as pending so they re-run | Always (default on) |+| Workspace (`container`) | PRISTINE wipe + re-provision — deletes the workspace AND everything in it, including your project files | Always (default on); your work is GONE |+| Image tarball (`tarball`, legacy `image`) | Deletes the cached golden image (full re-download) | Rarely — only if the image is corrupted |+| Webview storage (`webview_storage`), VS Code state (`vscode_state`) | Nothing on Linux: the reset does not touch the WebKitGTK web data | Not useful here |+| Adom session token (`adom_token`) | Deletes `hydrogen-session.txt`; forces re-login | Rarely |+| Claude credentials (`claude_token`) | Deletes the host-side Claude creds backup; forces Claude re-auth | When Claude auth is stuck |++`confirmed_destructive` must be set (body `{"options":{...}}`; defaults keep auth). After+toggling, hit "Wipe Selected", then "Run All" to rebuild. The workspace reset backs up Claude+creds first unless `claude_token` is checked.++The `container` toggle stops and removes the `Adom-Workspace` machine+(`machinectl remove`) and everything in it, including `/home/adom/project`; the next setup+imports a fresh one. `tarball` deletes the cached image in+`~/.local/share/Adom/HydrogenDesktop/cache/`. The helper manages only `Adom-Workspace` and+refuses any other machine, and the reset performs no reboot. Toggles and the keep-auth+testing pattern are in `hydrogen-setup`.++## Setup panel APIs (useful for AI automation)++| Endpoint | What it does |+|---|---|+| `GET /setup/state` | Current state — `never-run`, `in-progress`, `complete`, or `error` |+| `POST /setup/step/<id>` | Re-run a single named step (optional `{"continue_after":true}`) |+| `POST /setup/panel/run-virgin-reset` | Trigger virgin reset with the supplied toggle options |+| `POST /setup/panel/show` | Open the setup panel from anywhere |++All on Hydrogen's control API at `$(cat ~/.adom/hydrogen-control-url)`.++Refused: `POST /setup/virgin-reset`, `/setup/run-all`, `/setup/run-step`.++## Setup state file++`~/.config/hydrogen-desktop/setup-steps-workspace.json` (an install made before 2026-11-06+called it `setup-steps-wsl.json`; Hydrogen renames it the first time it reads it): one entry per step with status, output and percent. Hydrogen+reads it at launch to decide whether the setup panel opens.++## Related skills++- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — the baked-image model: what's pre-installed vs. what setup does+- `hydrogen-setup` — the setup-panel UX and virgin-reset toggles+- `hydrogen-container`: the workspace machine setup builds+- `hydrogen-volume`: where files live and what a virgin reset removes
skills/hydrogen-setup/SKILL.mdadded+129@@ -0,0 +1,129 @@+---+name: hydrogen-setup+description: >-+ Hydrogen's setup panel on Linux: the install-step cascade, Run All, Rollback+ All, Virgin Reset with its toggles, keeping auth during resets, and test+ patterns. Read before running setup or a virgin reset. Use when asked about+ the setup panel, run all, a failed step, the password prompt during setup, or+ reset workspace.+---++# Hydrogen -- Setup Panel & Virgin Reset++## Zero-Click Goal++Setup targets zero manual clicks. The golden workspace image already carries+code-server, the Adom CLIs, the claude CLI and Code extension, VS Code settings+and the `hydrogen-*` skills. Setup builds the workspace machine from that image,+binds your Adom session, checks the relay and opens Welcome. Never tell the user+to install something by hand. See `hydrogen-golden-image`.++The one thing a Linux user may see: a single desktop password prompt (pkexec) on+the first run of an AppImage, or for a user outside the `sudo`/`wheel`/`admin`+groups. It installs `systemd-container` if missing, the root helper+`/usr/libexec/adom-hydrogen/hydrogen-workspace` and a sudoers rule for that one file.+The .deb and .rpm packages install these themselves, so no prompt appears. While+the prompt is up, the step log says it is waiting for the password every 20 s.++## The Install Steps++Halt-on-failure, resume-not-restart, per-step 3x auto-retry. State is per step+(pending / running / done / failed, output, percent) in+`~/.config/hydrogen-desktop/setup-steps-workspace.json`; Hydrogen reads it at launch to+decide whether the setup panel opens. The step list and what each step does are+in `hydrogen-setup-steps`.++## 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, after the per-step 3x+auto-retry is exhausted). Remaining steps are NOT executed. The cascade+resumes — it does NOT restart from the first step — 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 steps to pending | CLEAN / EXISTS |+| Workspace (`container`) | PRISTINE wipe + re-provision of the workspace (ONLY Hydrogen's own workspace) | GONE / RUNNING / EXISTS |+| Image tarball (`tarball`, legacy `image`) | Deletes the cached golden image (full 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 |++On Linux the `container` toggle removes the `Adom-Workspace` machine and every file in it,+including `/home/adom/project`; the next setup imports a fresh one. `tarball` deletes+`~/.local/share/Adom/HydrogenDesktop/cache/adom-golden.tar.gz` (forces the full image+download), and `adom_token` also deletes the session's replay copy and forces sign-in.++`confirmed_destructive` must be set for the reset to proceed. **"Wipe+Selected"** at the bottom executes the reset for all checked toggles.++The workspace reset is a PRISTINE wipe + re-provision — 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 virgin reset only ever touches `Adom-Workspace`: the helper refuses any other machine name and its+shutdown stops only that machine, never the user's other containers.++## 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+```++### Programmatic triggers (the ONLY supported headless paths)++```bash+CTL=$(cat ~/.adom/hydrogen-control-url)+# Virgin reset: the ONE allowed programmatic trigger. It shows the panel and the+# checkboxes, pauses, then runs. Defaults are the keep-auth set; override in "options".+curl -X POST $CTL/setup/panel/run-virgin-reset -H Content-Type:application/json \+ -d '{"options":{"tarball":false,"adom_token":false,"claude_token":false}}'++# Re-run one step (continue_after keeps going)+curl -X POST $CTL/setup/step/test-relay -H Content-Type:application/json -d '{"continue_after":true}'+```++Refused (deprecated headless triggers): `POST /setup/virgin-reset`,+`POST /virgin-reset`, `POST /setup/run-all`, `POST /setup/run-step`, and the+old workspace-unregister route. Use the two above.++## When a step fails++The card names a Linux fix when it knows one:+- helper, `systemd-container`, `pkexec` or `sudo -n` errors: reinstall the+ Hydrogen package (.deb or .rpm) or approve the permission prompt, then Retry.+- the workspace could not be built: in a terminal run+ `sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace`+ (clears a half-built copy), then Retry.+- the workspace did not finish starting: `sudo machinectl terminate Adom-Workspace`, then Retry.++Setup never asks for a computer restart on Linux. The full reason is in+`~/.config/hydrogen-desktop/hydrogen-desktop.log`.++## Related skills++- `hydrogen-setup-steps`: each step and what it did+- `hydrogen-golden-image`: what the image carries+- `hydrogen-workspace-lifecycle`: start, stop, import, remove mechanics
skills/hydrogen-skill-loop/SKILL.mdadded+120@@ -0,0 +1,120 @@+---+name: hydrogen-skill-loop+description: >-+ Maintainer loop for fixing a wrong Hydrogen skill on Linux: verify against the running+ system, fix the live copy, fix the text at its source (the Hydrogen repo's Linux set or a+ wiki package), ship it. Use when a skill is wrong or stale, or to publish a skill fix.+disable-model-invocation: true+---++# Hydrogen Skill Loop: verify, fix live, fix the source, ship++Hydrogen's skills are the **only** way the in-workspace AI knows anything about+Hydrogen. A wrong skill silently breaks every user's AI (it curls a dead+hostname, hunts a command that doesn't exist, claims it needs a tool that isn't+installed…). This skill is the loop to find those and make them perfect.++## Cardinal rule: TEST, don't assert++Never write a skill claim from memory, old skill text, or docs — **verify it+against the running system first.** Run the command. Read the live env. Read the+code. Observe the real return shape. If you can't test a claim, don't state it+as fact. (Most skill bugs are confident, untested assertions.)++## Where skills live — the live copy and the text source++| Copy | Where | Role |+|---|---|---|+| **Live (ephemeral)** | `~/.claude/skills/<name>/SKILL.md` (flat) | What the running AI reads NOW. Editing it fixes this session and lets you test, but the next Hydrogen launch or package update replaces it. |+| **Text source** | depends on who ships it (below) | Where the fix must land. |+| **Shipped** | a Hydrogen build (Linux set) or a wiki package | What every workspace gets. A fix isn't done until it ships. |++**Who ships which skill on Linux:**+- **The Linux set** (every skill Hydrogen writes on Linux): the Hydrogen repo,+ `skills/public-facing/shared/<name>/SKILL.md` (one source per skill: the Linux text is its+ shared text plus its Linux platform blocks). The build embeds its Linux render+ (`hydrogen-setup/build.rs`, `linux_skills.rs`) and Hydrogen writes it over+ `~/.claude/skills/` at every launch and package convergence. A fix ships with the **next+ Hydrogen build**, not a wiki publish. Rules the build's gate test enforces: the folder name+ equals `name:`, no folder carries a platform suffix, and the text names no other platform's+ host tools or paths.+- **Platform-generic `hydrogen-*` skills not in the Linux set:** the Hydrogen repo's+ `skills/public-facing/shared/`, published to `adom/hydrogen-bootstrap` with+ `scripts/publish-skills-to-bootstrap.sh <skill>...` (it clones the wiki repo, refuses to+ clobber lines that exist only in the wiki copy, bumps the patch version and publishes). If the+ Linux set has a skill of the same name, fix that one too, or Linux users keep the old text.+- **Every other package:** its wiki page repo is the source. Clone it, edit, publish.++Find which package owns a skill: `adom-wiki pkg list` shows installed packages;+the skill's frontmatter and content usually name their set, and the package's+wiki page (`https://wiki.adom.inc/<org>/<pkg>/skills`) lists what it ships.++If the folder exists in the Hydrogen repo's `skills/public-facing/shared/`, Hydrogen owns the+Linux text.++## The loop++### 1. Reproduce / notice+A skill made the AI do the wrong thing. Name the skill and the exact wrong claim.++### 2. Get ground truth from the LIVE system+- **Run the real command** and read its `--help` and actual output:+ `adom-cli hydrogen <verb> --help` → then run it → note the EXACT return shape.+- **Read the live env**, never hardcode: `env | grep ADOM_`,+ `adom-cli hydrogen probe`, the control-URL file if present.+- **Read the Hydrogen source** for the endpoint/behavior when you have a checkout.++### 3. Fix it live + re-test+Edit `~/.claude/skills/<name>/SKILL.md` to match what you verified. Re-read it,+then **re-run the failing action** to confirm the fix actually works.++### 4. Fix the source+For a skill in the Linux set, edit `skills/public-facing/shared/<name>/SKILL.md` in the Hydrogen+repo (the shared text, or its Linux block when only Linux differs). It ships with the next+Hydrogen build, not a wiki publish.++For any other package, a fix must land on both wiki surfaces, or the wiki page still shows+the stale skill:++1. **The page repo** (what renders at `/skills`): clone it, apply the same edit,+ push with `adom-wiki repo push <org>/<pkg> --files skills/<name>/SKILL.md -m "..."`.+2. **The package artifact** (what `pkg install/update` delivers): from the same+ edited tree, bump `version` in `package.json`, strip AppleDouble junk+ (`find . -name "._*" -delete`), then+ `COPYFILE_DISABLE=1 adom-wiki pkg publish --org <org>`. Fix lint errors rather than+ skipping the linter.++Staging both from one clone of the page repo keeps them identical.++If you added / renamed / removed a skill, also update the package's index skill+(e.g. **hydrogen-overview** for hydrogen-bootstrap) and check for cross-references+to the old name in the rest of the package.++### 5. Converge + verify+`adom-wiki pkg update` in a workspace, then re-read the installed skill and+confirm the wiki page shows the fix. Note: a package upgrade does not prune+skills an older version delivered — after a rename/delete, remove the stale+`~/.claude/skills/<old-name>` directory too.++For a Linux-set skill, install the Hydrogen build that carries the fix and re-read the skill+after its next launch.++## Validation checklist before you publish a skill+- [ ] Every command in the skill was actually RUN and produced the documented output.+- [ ] No invented CLI verbs — each confirmed with `--help`.+- [ ] No tool assumed present that isn't in the workspace — test before relying on it.+- [ ] Endpoint paths / ports / step names match CURRENT code (they drift fast).+- [ ] No content about deprecated or unimplemented features — it only pollutes context.+- [ ] Linux mechanics live in the Linux set; a Linux skill never describes another platform.+- [ ] Cross-links use sibling skill names that resolve flat at deploy.+- [ ] `name:` matches the directory.++## Why this matters+The skills ARE Hydrogen's self-knowledge for the AI. Ship them wrong and every+Adom user's AI is confidently wrong with them. Treat "the skill is inaccurate"+as a product bug and run this loop until the validation checklist is clean.++## Related skills+- **hydrogen-staying-current** — how workspaces receive published package updates+- **hydrogen-wiki-review** — load the edited wiki page in pup so the user can review it+- **hydrogen-self-update**: how a new Hydrogen build (and its Linux skills) arrives
skills/hydrogen-staying-current/SKILL.mdadded+44@@ -0,0 +1,44 @@+---+name: hydrogen-staying-current+description: >-+ How a Hydrogen workspace on Linux stays current: adom-wiki pkg update through the adom/hook+ prompt hook, the Linux skill set Hydrogen itself writes, the code-server reload banner, and+ how to ship a skill, CLI or app to every workspace. Use when asked how updates work, how to+ get the latest skills, or how to distribute a tool to all users.+---++# How this workspace stays up to date (Linux)++## TL;DR (anyone)+You don't do anything. Your workspace's Adom tooling is **registry-native**: everything is an+`adom-wiki` package (CLIs, skills, apps), and the **auto-update hook** (`adom/hook`, installed by+`adom/core`) runs `adom-wiki pkg update` in the background (throttled ~30 min, on your prompts, for+both Claude Code and Codex) and re-resolves `adom/core` so newly added tools arrive automatically.+- Force a check now: `adom-wiki pkg update`+- See what's installed / behind: `adom-wiki pkg list` / `adom-wiki pkg outdated`++## Where the Hydrogen skills come from+- **`adom/hydrogen-bootstrap`** (wiki package) ships the platform-generic Hydrogen skills, deployed+ flat into `~/.claude/skills/`.+- **Hydrogen itself** ships the Linux layer. The Hydrogen build carries the Linux skill set and+ writes it into `~/.claude/skills/` at every launch and after every package convergence,+ over any package copy of the same name. So a package update cannot leave a Linux workspace with+ another platform's text for long: the next launch or convergence puts the Linux version back.+ New Linux skill text arrives with a **Hydrogen update** (see **hydrogen-self-update**), not a+ package update.+- Org member apps arrive through your org's **`org-bootstrap`** meta-package.++## The reload banner+code-server self-updates on disk but only takes effect after a restart. Hydrogen detects+that natively and shows **"code-server has an update — click to reload"** at the top of the editor+(only after setup is complete, never mid-cascade). Clicking restarts code-server + reloads the+editor. Extensions never banner — VS Code's own auto-update activates them.++## "How do I ship a tool/skill/app to every Adom workspace?" (Adom employees)+Publish it as an `adom-wiki` package, then add it as a **dependency** of the right bootstrap:+every container: `adom/core`; every Hydrogen workspace: `adom/hydrogen-bootstrap`; org members+only: your org's `org-bootstrap`. Hydrogen skills: a platform-generic one goes in+`adom/hydrogen-bootstrap`; a Linux one is a Linux platform block in the Hydrogen repo's `skills/public-facing/shared/<name>/SKILL.md`+and ships with the next Hydrogen build (see `~/.claude/skills/hydrogen-skill-loop/SKILL.md`).+The hook's re-resolve delivers package changes fleet-wide within about 30 minutes of users+prompting.
skills/hydrogen-topology/SKILL.mdadded+111@@ -0,0 +1,111 @@+---+name: hydrogen-topology+description: >-+ Where Claude runs relative to Hydrogen on Linux: inside the local+ Adom-Workspace systemd-nspawn machine on the user's Linux computer, or in a+ cloud container, and how to reach the host and the workspace from each. Use+ when asked where am I, cloud vs local, reach the host, reach the workspace,+ machinectl, or adom-bridge relay.+---++# Hydrogen: Topology (Linux)++Up to three environments are involved: the user's **Linux computer** (where+Hydrogen (ah) runs), Hydrogen's **workspace** on it (the `Adom-Workspace`+systemd-nspawn machine, on the same kernel, no VM), and optionally an **Adom+cloud container** (hc). Where YOU run decides how you reach the others, so check+first: `adom-context` prints a "Where:" line.++## Case 1: you run inside the local workspace (the default on ah)++You (Claude) run inside the `Adom-Workspace` machine on the user's own Linux computer.++- Your shell, `/home/adom/project` and your repos are in the machine.+- The machine shares the host's network: 127.0.0.1 is the same on both sides.+ Hydrogen's control API is `$(cat ~/.adom/hydrogen-control-url)` (normally+ `http://127.0.0.1:47084`), and a port you listen on is reachable from the+ host's browser at `http://localhost:<port>/` directly.+- Host files: `/mnt/host/home` (read-write, the host's `/home`), `/mnt/host/tmp`+ (read-write), `/mnt/host/usr` and `/mnt/host/opt` (read-only). Your own `/tmp`+ is private to the machine. Nothing else of the host is visible.+- The machine's hostname is the host's name.+- There is no Hydrogen verb that runs a command on the host itself. Hydrogen+ for Linux installs and starts Adom Bridge when a Linux build is published for+ the user's account, and hands it the workspace relay, so `adom-bridge <verb>`+ reaches it. Check with `adom-bridge ping`. Without it, desktop verbs+ (screenshots, KiCad, pup) are unavailable on this computer.+- `adom-bridge --target <name>` still reaches the user's OTHER machines (for+ example their Windows PC) through the Adom mesh when they run Adom Bridge.+- Stopping or restarting the machine kills your own shell: do it only when the+ user asks.++## Case 2: you run in a cloud container, driving the user's PC++You (Claude) run inside an **Adom cloud Docker container**. The user's Linux+computer is a remote target you reach through the `adom-bridge` CLI relay, and+only if Adom Bridge runs there (`adom-bridge targets`). There are THREE separate+environments:++### 1. Cloud Docker (where you run)+- Your shell, your filesystem, your git repos+- `adom-bridge` CLI connects to Adom Bridge on the user's machines via relay+- This container has NOTHING to do with Hydrogen's local workspace+- Restarting the workspace machine does NOT affect you+- You can freely `git push`, edit code, run builds here++### 2. The user's Linux computer+- **Hydrogen**, the Tauri desktop app+- **Adom Bridge**, installed and started by Hydrogen when a Linux build is published for the user's account+- You reach it via `adom-bridge --target <linux-box> shell_execute '{"command":"..."}'`++### 3. Hydrogen's workspace (the `Adom-Workspace` systemd-nspawn machine)+- Machine name: `Adom-Workspace` (fixed)+- Runs code-server, adom-bridge CLI, relay server+- You reach it through Hydrogen's root helper, which the user may run without a password:+```bash+adom-bridge --target <linux-box> shell_execute \+ '{"command":"sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- ls /home/adom"}'+```+- This is TWO hops: cloud, relay, the Linux host, the helper, the machine.++## The relay chains++```+Cloud adom-bridge CLI -> cloud relay -> internet -> Adom Bridge on the user's machine -> runs it+```++Inside the workspace:+```+Workspace adom-bridge CLI -> local relay (:8765 WS / :8766 HTTP, adom-relay.service)+ -> code-server proxy (:7380/proxy/8765/) -> Adom Bridge, when one is connected+```++The workspace ports (7380, 8765, 8766, 8820, 8821, and any listener inside the+machine) are dropped for new connections from the LAN by the helper's nft table;+loopback works.++## Managing the machine (host side)++`machinectl status Adom-Workspace` and `machinectl list` work without root.+Hydrogen itself only acts through the helper, which manages `Adom-Workspace`+and refuses any other name. Never stop, remove or reconfigure other machines or+containers on the user's computer.++## NEVER Do These++1. **NEVER confuse your cloud container with the user's workspace.**+ `curl http://127.0.0.1:8766/health` in the cloud hits YOUR relay, not the workspace's.+2. **NEVER touch any machine or container other than `Adom-Workspace`.**+ Hydrogen's helper refuses any other name; do not work around it.+3. **NEVER assume the workspace's status affects your container.**+ They're completely independent.+4. **NEVER stop or restart the workspace machine from inside it unless the user asks.**+ It kills your own shell.+5. **NEVER skip the adom-bridge round-trip test.**+ The relay chain has many links — test end-to-end, not individual parts.++## Related skills++- `hydrogen-container`: facts about the workspace machine+- `hydrogen-volume`: where files live and how to copy them out+- `hydrogen-networking`: ports and the shared localhost
skills/hydrogen-ui/SKILL.mdadded+222@@ -0,0 +1,222 @@+---+name: hydrogen-ui+description: >-+ Hydrogen's interface (menus, dialogs, panels, profile menu, setup panel, tray+ menu) and how to drive it from the workspace via the UI command bus (GET+ /ui/actions, POST /ui/invoke) instead of clicking. Use when asked to open or+ close a Hydrogen dialog or menu, where a UI element is, or how to eval in+ Hydrogen's page on Linux.+---++# Hydrogen — UI Reference++Hydrogen on Linux is a Tauri app on WebKitGTK. The UI is the same as everywhere; what differs+is how you reach into the page (no Chrome DevTools Protocol, see "Eval" below).++## Window Layout++Hydrogen's window has these regions (top to bottom, left to right):++### Title Bar (frameless, 0.1.251+)+Hydrogen is a FRAMELESS window: the nav bar IS the title bar (no separate OS chrome).+- **Left**: Adom logo (the Adom menu button), then the lightbulb (sample-prompts menu, moved here 0.1.265) — drag anywhere else in the bar to move the window+- **Right**: CPU/RAM badges, the Annotate pencil, the profile avatar menu, then the window+ controls (minimize, maximize, close).+- The window has no system frame: it resizes from its edges.+- All title-bar controls share one interaction family: soft white hover wash, teal+ press, steady teal wash while their menu is open++### Tab Bar+- **VS Code** tab — the main code editor (iframe to code-server)+- **Webview** tab — wiki/app content panel+- Additional tabs for bridges, sensors, etc.++### Main Content Area+- **Left pane**: Usually VS Code iframe+- **Right pane**: Usually webview (wiki, shotlog, etc.)+- Panes are split and resizable++### Moving tabs between panes (drag-to-split, 1.0.140+)+Drag any tab and hover another pane: teal drop zones light up (Split Left / Right /+Top / Bottom, Swap, or the tab bar to add). This works over EVERY pane type,+webviews included (a glass layer covers iframes during the drag so they cannot+swallow the pointer), and exactly ONE zone pill shows at a time. Releasing on a+zone performs the move; **Escape abandons the drag** and everything returns to+exactly how it was. Right-clicking a tab offers the same splits as menu items+(a one-tab pane asks what to put in the new half via Add Panel).++### Setup Panel (bottom)+- Collapsible panel showing the setup steps+- See `hydrogen-setup` skill for details++## Menus++### Adom Menu (top-left logo dropdown)+The main menu, opened by clicking the Adom logo at the top-left. Items are grouped into labelled sections (in order, top to bottom):++**(top, unlabelled)** — "Go to Dashboard" was REMOVED (0.1.252, John 2026-07-24); don't offer it+- **Settings** — opens the Settings dialog+- **Ports...** — opens the port configuration dialog (see hydrogen-ports)+- **API Explorer...** — opens the control-API endpoint explorer dialog++**DESKTOP** (Tauri-only — won't appear in browser-served Hydrogen; in order)+- **Zoom** — webview zoom controls (− % +) with persistence across launches+- **Fullscreen** — toggle fullscreen+- **Console** — show/hide the Hydrogen debug console window+- **Developer Tools**: opens the WebKit Web Inspector (Ctrl+Shift+I opens and closes it from+ anywhere in the window). Zoom also answers Ctrl+plus / Ctrl+minus / Ctrl+0, Fullscreen F11.+ There is no "Adom Bridge" item on Linux, and the wake check and disk reclaim items are not shown.++> The Bridges section / "Bridge Manager" item was removed (it was a no-op with no backing panel). For the bridge panel itself, see `hydrogen-bridges`.++**Workspace / runtime section** (section label shows live status badge: `RUNNING`, `STOPPED`, etc.)+- **Restart**: stops the `Adom-Workspace` machine and re-ensures code-server.+- **Stop**: powers the `Adom-Workspace` machine off.++**ADMIN**+- **Setup Steps** — opens the setup panel (the setup cascade); see hydrogen-setup-steps+- **Virgin Reset** — opens the virgin reset section of the setup panel; see hydrogen-volume for what each toggle deletes+- **Browser Picker Manager** — configure per-domain default browser/profile prefs; see hydrogen-browser-picker++### Profile Menu (top-right avatar)+Click the user avatar (circular photo) in the top-right corner.+- **Your profile** — view Adom profile+- **Your repositories** — list repos+- **Your molecules** — list molecules+- **Log out** — signs out of Adom, removes session token++**CRITICAL**: Logout is ONLY in the profile menu (top-right avatar),+NOT in the Adom menu (top-left). Future AI threads: don't look for+logout in the wrong menu.++### Tray menu (the Adom icon in the desktop's tray: GNOME's top bar, Cinnamon's bottom panel)+Built in `src-tauri/crates/hydrogen-app/src/tray.rs`: Open Hydrogen; New Claude / Codex /+Antigravity chat (and Kimi when show_kimi is on), each only while that AI is installed;+Annotate screen; Open Adom Bridge; Settings; Quit Hydrogen. The AI items call+`POST /ai-threads/new {type}`. GNOME's AppIndicator has no left-click action (the menu always+opens), so Open Hydrogen stays first. Log lines: `[tray] <item id>`.++### Tray menu (system tray on Windows, top-bar Adom icon on Linux)++Built in `src-tauri/crates/hydrogen-app/src/tray.rs` from one list, `menu_entries()`, which+also builds the taskbar jump list, so the two always match: Annotate the screen (Win+Alt+A) and+Open Hydrogen; then New Claude chat, New Codex chat, New Antigravity chat (and New Kimi chat when+show_kimi is on), each listed only while that AI is installed; then Open Adom Bridge and Settings;+then Quit Hydrogen. The AI items call `POST /ai-threads/new {type}` and bring Hydrogen forward;+from the jump list they launch `hydrogen.exe --new-<ai>-chat` (and Settings `--settings`).+DevTools is not in the tray: use the Adom menu or Ctrl+Shift+I. Log lines: `[tray] new <ai>+chat ok=...` and `[tray] AI items: ...`.++## Dialogs++### Port Settings Dialog+Access: Adom menu → Ports...+Live host and workspace ports, with the PortConfig editor.+See `hydrogen-networking` and `hydrogen-ports`.++### Settings Dialog+Access: Adom menu → Settings+Application-level preferences.++### Browser Picker Dialog+Appears when clicking external links. Shows detected browser profiles+(Edge, Chrome, etc.) with per-domain "remember" option.++## Driving the UI — the command bus (PREFERRED, first-class)++⭐ **Every menu / dialog / panel Hydrogen has wired is a first-class action you drive over the control+API — no CDP, no `.click()`, no selector guessing.** This is how you operate Hydrogen's UI when the+user says "open the Ports dialog", "open About", "show settings", etc.++The control URL is in the discovery file `~/.adom/hydrogen-control-url` (Hydrogen rewrites it with the live, dynamic control port every launch; the workspace shares the host network, so `127.0.0.1` is the same on both sides). Read it from a file, not an env var: your Bash tool runs non-interactive shells that do not source `.bashrc`/`profile.d`:++```bash+CTRL="$(cat ~/.adom/hydrogen-control-url)"+```++**Always do this in order:**++1. **Discover** what's drivable (ids + descriptions):+ ```bash+ curl -s "$CTRL/ui/actions"+ # → {ok, count, actions:[{id,label,description,group}], _hints}+ ```+2. **Drive** one — returns ONLY after the frontend actually ran it:+ ```bash+ curl -s -X POST "$CTRL/ui/invoke" \+ -H 'Content-Type: application/json' -d '{"id":"ports.open"}'+ # → {ok:true, id:"ports.open", value:…}+ ```+3. **Not in the list?** That absence is the signal: the element isn't wired to the bus yet. It+ needs a 2-line `registerUiAction(...)` in its Svelte component (a dev change in the+ ah repo, hydrogen-desktop). Don't fall back to clicking;+ wire it. The response's `_hints.if_missing` says the same.++Common ids (always check `GET /ui/actions`): `adom-menu.open`/`.close`,+`profile-menu.open`/`.close`, `ports.open`/`.close`, `settings.open`/`.close`,+`api-explorer.open`/`.close`, `browser-picker.open`/`.close`, `about.open`/`.close`,+`samples-menu.open`/`.close`, `setup-panel.show`, `virgin-reset.open`, `fullscreen.toggle`,+`console.toggle`, `devtools.open`, `container.start`/`.stop`/`.restart`.++**Menu ITEMS, not just open/close:** the profile menu also exposes per-item actions —+**`profile.view`**, **`profile.repositories`**, **`profile.molecules`**, **`profile.logout`** —+so you can trigger a specific item directly (it navigates as if the human clicked it),+WITHOUT opening the menu + screen-clicking. (`profile.logout` is the canonical logout — see+the logout note above.) `GET /ui/actions` for the live set; the Adom menu will get the same+item-level treatment over time.++> Note: there is **no** `port-mappings.open`/`.close` id — that action was never+> registered. Don't try to invoke it.+> There is no `setup-panel.hide` either: to close the setup panel, open another surface (page globals like `window.__hdSetSetupPanel` are not reachable from `/eval-in` on Linux).++### Open a surface, then screenshot it (the killer combo)+Combine the bus with Hydrogen's canonical capture endpoint to grab any menu/dialog/panel with+**no screen-clicking**: `POST /ui/invoke {id:"<x>.open"}` → `POST /screenshot+{target:"shell", selector:"<open-state selector>"}` → `POST /ui/invoke {id:"<x>.close"}`.+The `/screenshot` region-flash lands on that selector. Resolved selectors (verified live):+**Adom & profile menus** → `.dropdown-content.open` (one open at a time); **Setup panel** →+`.setup-panel`; **API Explorer** → `.dialog`. Full `/screenshot` reference (target/selector/+b64/silent) is in **[hydrogen-self-screenshot](../hydrogen-self-screenshot/SKILL.md)**.+On Linux a selector in the main window crops the whole-window snapshot to that element.++> **This is Hydrogen-desktop-only and SEPARATE from `adom-cli`.** `adom-cli` drives *web-hydrogen's*+> UI via the SSE bridge (`ADOM_HYDROGEN_URL`) and is unchanged. For Hydrogen desktop's far richer UI+> control, use the command bus above — never `adom-cli` for this.++## Eval on Linux: the frame bus, not CDP++WebKitGTK has no Chrome DevTools Protocol. `POST /eval`, `POST /eval-in {target, js}` and+`POST /cdp-eval` all run over Hydrogen's **frame bus**+(`src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs`): an agent script in every frame+long-polls Hydrogen and runs your JS in an **isolated script world**. Answers carry+`"via":"frame-bus"`.++- The DOM is shared: `querySelector`, `textContent`, `getBoundingClientRect`, `.click()` work.+- Page JS globals are NOT visible (`window.__hd...` helpers, Svelte stores). Use the command+ bus for those.+- A returned promise is awaited.+- Same-origin child frames without their own agent (VS Code webview content) are covered too.++```bash+curl -s -X POST "$CTRL/eval-in" -H 'Content-Type: application/json' \+ -d '{"target":"shell","js":"document.querySelectorAll(\".step-row\").length"}'+```++There is no CDP port and no `hydrogen-cdp.js` on Linux. For hands-on inspection, the WebKit Web+Inspector (Ctrl+Shift+I) is the tool.++## CSS Selectors for Key Elements++| Element | Selector |+|---------|----------|+| VS Code iframe | `iframe.vis-studio-iframe` or `iframe[title="code"]` |+| Setup panel | `.setup-panel` |+| Run All button | `.run-all` |+| Virgin Reset button | `.virgin-reset-btn` |+| Wipe Selected button | `.virgin-go` |+| Step rows | `.step-row` |+| Step icon (✅/❌/○) | `.step-icon` |+| Step label | `.step-label` |+| Adom menu button | `.logo-button` |+| Profile menu button | `.profile-dropdown-button` |+| Tab bar | tab container at top |
skills/hydrogen-volume/SKILL.mdadded+82@@ -0,0 +1,82 @@+---+name: hydrogen-volume+description: >-+ Where files live in Hydrogen's Linux workspace (the Adom-Workspace+ systemd-nspawn machine), what survives a restart versus a virgin reset, and+ how to reach them from the Linux desktop. Use when asked where are my files,+ did I lose my work, how do I copy a file out, or what happens to my code if I+ virgin reset.+---++# Hydrogen Workspace Storage: what persists, what doesn't++Your work lives in the `Adom-Workspace` machine at `/home/adom/project`. There is no separate volume: the machine's whole rootfs is a plain directory tree on the host disk, and `/home/adom/project` is part of it.++## The filesystem++| Property | Value |+|----------|-------|+| Your work path | `/home/adom/project` |+| On the host | `/var/lib/machines/Adom-Workspace/home/adom/project` (root-owned pool, mode 0700: read it with `sudo` or through `/mnt/host`, below) |+| Backing store | a directory (a btrfs subvolume when `/var/lib/machines` is on btrfs); no disk image, so there is nothing to compact |+| Persistence | survives machine restart, Hydrogen restart, and host reboot, until the machine is removed |++## What lives where++| Path inside the workspace | Notes |+|---------------------------|-------|+| `/home/adom/project/` | Your code. Put everything important here. |+| `~/.local/share/code-server/` | Extensions and settings, baked into the image |+| `~/.claude/` | Skills (baked, kept current by packages) and Claude credentials |+| `/tmp/` | **A tmpfs: emptied on every machine stop or restart.** |+| `/mnt/host/home`, `/mnt/host/tmp` | The host's `/home` and `/tmp`, read-write (live host files, not workspace files) |+| `/mnt/host/usr`, `/mnt/host/opt` | The host's `/usr` and `/opt`, read-only |+| `/etc/`, `/usr/`, system | Part of the workspace image; replaced on a re-import |++**Rule of thumb:** if you want it to survive a workspace rebuild, put it under `/home/adom/project/`.++## What survives each virgin-reset choice++When you open Virgin Reset (Hydrogen setup panel), the checkbox toggles control which artifacts get deleted:++| Toggle ON means: | Result |+|------------------|--------|+| Install step state | `setup-steps-workspace.json` deleted; next setup re-runs everything. Your project files unaffected. |+| Workspace machine | **Removes the `Adom-Workspace` machine (`machinectl remove`), including `/home/adom/project/`. The one destructive option.** |+| Golden workspace image cache | Deletes the cached `adom-golden.tar.gz` (in `~/.local/share/Adom/HydrogenDesktop/cache/`) so setup downloads it again. Files unaffected. |+| Adom session token | Re-login required next time. Project files unaffected. |+| Claude credentials | Claude Code requires re-auth. Project files unaffected. |++The reset only ever touches `Adom-Workspace`; other containers on the machine are never stopped or removed.++## Getting files in and out++### 1. Through `/mnt/host` (simplest)+```bash+# Workspace file -> the user's Downloads on this desktop+cp /home/adom/project/myfile.txt /mnt/host/home/<user>/Downloads/++# Desktop file -> workspace+cp /mnt/host/home/<user>/Downloads/myfile.txt /home/adom/project/+```+`<user>` is the desktop login name (`ls /mnt/host/home`). Files you write there are owned by UID 1001 (`adom`); on the host that UID may belong to someone else or no one, so `chmod a+r` a file if the user cannot open it.++### 2. In the editor+The VS Code file tree shows `/home/adom/project`; drag files in, or right-click > Download.++### 3. Another of the user's machines+`adom-bridge send_files` / `pull_file` with `--target <name>` reach the user's other PCs through the Adom mesh (see `hydrogen-file-transfer`). The same verbs reach this computer while Adom Bridge runs here (Hydrogen installs it when a Linux build is published for the user's account).++## Backing up++Copy the project out before anything destructive:+```bash+tar czf /mnt/host/home/<user>/adom-project-backup.tar.gz -C /home/adom project+```+Or on the host, a full-machine snapshot: `sudo machinectl export-tar Adom-Workspace ~/adom-workspace.tar` (stop the workspace first for a consistent copy).++## Related skills++- `hydrogen-container`: the machine whose filesystem holds your work+- `hydrogen-workspace-lifecycle`: stop, restart, remove+- `~/.claude/skills/hydrogen-golden-image/SKILL.md` — what's baked into `adom-golden.tar.gz` (extensions, settings, skills) vs. what setup does
skills/hydrogen-wake-repair/SKILL.mdadded+55@@ -0,0 +1,55 @@+---+name: hydrogen-wake-repair+description: >-+ What Hydrogen on Linux does when the editor loses its connection (after sleep+ or otherwise): no wake heal cascade, but a watcher that clears VS Code's+ Cannot reconnect dialog and the backend banner. Use when Hydrogen didn't+ reconnect after sleep, a cannot reconnect dialog appears, or asked about+ /wake/status, the wake indicator or Run Wake Check.+---++# Hydrogen Wake Repair (Linux)++On Linux there is no wake detector and no wake heal cascade. The Wake settings,+the header wake indicator and the Adom menu's "Run Wake Check" are not shown.+The workspace machine runs on the host kernel, so sleep and resume do not leave+it in a separate state to repair; what can still go wrong is the editor's+connection.++## What does run++**Cannot reconnect watcher** (`hydrogen-app/src/linux_reconnect_watch.rs`).+Every 15 s it looks for VS Code's final "Cannot reconnect. Please reload the+window." dialog (never "Attempting to reconnect", which is VS Code still+trying). After two sightings, and only if code-server is serving+(`/workspace/health` says `editor_will_load`), it reloads the editor pane only,+at most once per 45 s. After three reloads in a row that did not clear it, it+backs off for 10 minutes and logs `restart Hydrogen`. It never acts while setup+runs or after the user stopped the workspace. Log lines start with+`[reconnect-watch]` in `~/.config/hydrogen-desktop/hydrogen-desktop.log`.++**Backend banner.** The VS Code panel reads `/workspace/health` every 8 s; two+misses of `editor_will_load` show a banner over the editor. Its Reconnect button+posts `/container-start` on Linux (there is no heal cascade): that makes sure the+machine runs, code-server is a systemd unit inside it that restarts itself, and+the banner clears once the editor serves again.+`editor_will_load` is honest: it is a real HTTP GET of code-server's+`/healthz` (success or redirect), not a bare TCP connect, because a wedged+code-server can still accept TCP while serving nothing.++## Control API endpoints++On the Hydrogen control API (port from `~/.adom/hydrogen-control-url`, see `hydrogen-api`):++- `GET /wake/status` answers `{"ok":true,"wake":null,"note":"no wake events this session"}`.+- `POST /wake/simulate` and `POST /wake/preview` answer `ok:false` (the wake+ watcher is not registered on Linux): there is nothing to run.++## If the editor stays disconnected++1. `curl -s $(cat ~/.adom/hydrogen-control-url)/workspace/health` and read+ `editor_will_load`.+2. Machine stopped: Adom menu > Start Container, or `POST /container-start`.+3. Machine running, code-server not serving: Adom menu > Restart Container.+4. Watcher gave up: restart Hydrogen.+5. Full diagnosis: the Doctor (`hydrogen-doctor`).
skills/hydrogen-webview/SKILL.mdadded+145@@ -0,0 +1,145 @@+---+name: hydrogen-webview+description: >-+ What "webview" means in Hydrogen: a native workspace tab opened with adom-cli hydrogen+ webview open-or-refresh, never VS Code's Simple Browser; plus the External Webview for+ sites that refuse embedding and the Hydrogen Browser Window (hbw). Use when the user says+ show me in webview, open in webview, wv, extwv or hbw.+---++# hydrogen-webview — "webview" means a native Hydrogen webview tab. Period.++When a user (or a setup prompt) says **"show me X in webview"**, they mean a+**native Hydrogen webview tab** — a first-class panel in the Hydrogen+workspace, next to their editor. Nothing else qualifies.++## ⛔ NEVER (the 2026-07-16 incident — do not repeat)++- **NEVER open VS Code's built-in "Simple Browser"** (or any editor-internal+ browser page) to satisfy a webview request. A setup-thread AI did this once —+ the user called it "an awful outcome that can never happen again." The Simple+ Browser is not the Hydrogen webview: it's cramped, it isn't a workspace tab, and it+ breaks every downstream flow (screenshots, captions, panel routing).+- Don't fall back silently to pup or a native browser either — those are+ *different, deliberate* destinations (see `hydrogen-open-url` for the decision+ guide). "webview" is not ambiguous; it names exactly one thing.++## ⭐ URLs for YOUR OWN servers: direct port, NOT /proxy/<port>/++The workspace machine shares this Linux computer's network, so every port you bind inside it+is the same port on the host: `http://localhost:<port>/`. For a server on port 8850:++```+http://localhost:8850/ ✅ the Hydrogen (ah) way+http://localhost:7380/proxy/8850/ ❌ Hydrogen Cloud (hc) habit — do not default to this here+```++The `/proxy/<port>/` route through code-server (what `VSCODE_PROXY_URI` points at) exists for+Hydrogen Cloud parity. Here it costs an extra hop, breaks absolute-path assets (`/style.css`),+and dies whenever the editor reloads. Opening a /proxy URL still works; the reply hints you back+to the direct form. If the direct port does not answer, check that your server listens (the+`hydrogen-networking` skill).++## ✅ The exact command (idempotent — safe to re-run)++```bash+# open (or refresh, if a tab with this name already exists) a webview tab:+adom-cli hydrogen webview open-or-refresh --name "<Tab Name>" --url "<url>" --panel-id <id>++# ⚠️ --panel-id is REQUIRED to CREATE a new tab (without it: "Tab 'X' not found+# and --panel-id not provided"). Get a panel id first:+adom-cli hydrogen workspace get # or: adom-cli hydrogen workspace tabs+# Re-running with the same --name once the tab exists just navigates/refreshes+# (no --panel-id needed). The --name is your stable handle.+```++Local Adom apps (parts search, chip-fetcher, adom-tsci previews, wiki pages)+are all shown this way: start/locate the app's local URL, then+`open-or-refresh` it into a named tab.++## Fullscreen: the 90% dialog++Every webview toolbar has a **fullscreen button**: it grows the page to a 90%+dialog over the Hydrogen window (never real OS fullscreen — the content stays+sandboxed inside Hydrogen). Exit via the close button, clicking outside, or Esc. Pages+that call the browser fullscreen API get the same 90% treatment.++## Verify you actually did it++The tab must appear in `adom-cli hydrogen workspace tabs` with your `--name`.+If it isn't there, you did NOT open a webview — go again.++For the broader "which surface should this URL open in?" decision (webview vs+pup vs native browser vs headless fetch), see **hydrogen-open-url**.++## extwv — External Webview: the real-browser panel for sites that refuse embedding++The default webview tab is an **iframe**, so sites that send `X-Frame-Options: deny/sameorigin`+or a restrictive CSP `frame-ancestors` (Google, Amazon, most login walls) will not load in it.+The **External Webview (extwv)** panel is the same tab ergonomics backed by a native WebKitGTK+webview that loads anything.++**How users hit it:** navigating a webview to a blocked site shows a handoff+card — "This site can't be embedded" — with two buttons: **Open in External+Webview** (a new extwv tab in the same pane) and **Open in Hydrogen Browser Window**+(hbw). Users can also add one directly from the **+ panel menu → "External+Webview"**.++On Linux Hydrogen's page has the origin `tauri://localhost`, which a CSP wildcard does not+match, so `frame-ancestors *` also refuses it; only a list naming `tauri:` lets it in. The check+below accounts for that.++**Check embeddability up front** (before choosing a surface for a known URL):++```bash+# Hydrogen control API — returns {"embeddable": bool, "reason": "...", "title": "<page title>"}+GET http://127.0.0.1:{control}/webview-can-embed?url=https://google.com+# → embeddable=false, reason "x-frame-options: sameorigin" → use extwv (or hbw)+```++**Open an extwv tab programmatically** (Hydrogen control API; the `adom-cli hydrogen+webview` verbs target the DEFAULT webview panel type, not extwv):++```bash+POST http://127.0.0.1:{control}/workspace/tabs+{"panelType": "adom/a1b2c3d4-0032-4000-a000-000000000032",+ "displayName": "Google", "initialState": {"url": "https://google.com"}}+```++**Know the trade-offs** (why extwv is opt-in, not the default):+- It is a native OS surface: **Hydrogen's own HTML can never draw on top of it**+ (menus and overlays are designed around it, but don't try to float custom UI+ over an extwv pane).+- Heavier than an iframe tab; prefer the default webview whenever the site+ embeds fine.+- Reload lives in the tab's right-click menu (0.1.258+), and the tab's hover+ tooltip identifies the panel as "External Webview (extwv)" (0.1.261+), so you+ can always tell the two apart.++**Vocabulary:** "open it in extwv" == this panel. See the shared Adom glossary+(`definitions` skill / wiki.adom.inc/adom/definitions) for the full surface+vocabulary.++## hbw: the Hydrogen Browser Window++**hbw** is Hydrogen's standalone browser window (picker label "Hydrogen Browser Window", window+label `hbw-*`): a separate desktop window Hydrogen manages, bigger than a pane tab, still not a+real browser. Open one with `POST $C/hbw/open {"url": "..."}` (the reply carries its label;+`POST $C/hbw/close {"label": "hbw-..."}` closes it), or pick it in the Browser Picker (`C=$(cat ~/.adom/hydrogen-control-url)`).++A browsing hbw window that is not in front is slowed to about 4 frames a second (its+`requestAnimationFrame` is capped), so a background 3D page cannot starve the editor. The window+in front runs at full speed. To keep a background one at full speed while you watch or film it:++```bash+curl -sX POST "$C/hbw/speed" -d '{"target":"Sprinkler Yard","minutes":20,"reason":"filming the 3D tour"}'+curl -s "$C/hbw/speed" # each window's mode and any lease left+```++`target` is the window's label or part of its title; `minutes` 1 to 120, renewable, `0` ends it.+On Linux "in front" means the window has keyboard focus, and Hydrogen has no native recorder or+GPU-process restart here, so a lease is the only way to keep a background window at full speed.++Surface shortlist: **wv** (this skill's pane tab), **extwv** (the native pane tab for+embed-blocked sites), **hbw**, **pup** (a real browser through Adom Bridge), **nb** (the user's+own browser). VS Code's Simple Browser is NEVER one of them.
skills/hydrogen-welcome/SKILL.mdadded+64@@ -0,0 +1,64 @@+---+name: hydrogen-welcome+description: >-+ The Hydrogen welcome page shown after setup completes ("Your workspace is ready"): a page+ built into the app and served by the control API, not the adom.inc homepage. Use when asked+ about the welcome page or tab, or to show the welcome page again.+---++# Hydrogen Welcome Page++The welcome page is `static/welcome.html`, compiled into the Hydrogen app. Hydrogen's control+API serves it at `<control URL>/welcome.html?control=<control port>`. The `control` parameter+tells the page's buttons which port to call, and the port is dynamic: read it from+`~/.adom/hd-control-url` (47084 by default). `localhost:1420` is the dev server and does not+answer on an installed build.++## What it shows++- The Adom logo and "Your workspace is ready"+- A checklist: VS Code, Your AIs (who is signed in), Adom skills, Adom Bridge+- **Manage AIs** when an AI is signed in, or **Choose your AI** when none is+- While the workspace is still starting (after an update, a reload or a wake) the AI and Adom+ Bridge rows say **checking** instead of "none signed in" or "starting up", and recheck every+ 5 s until they have a real answer (1.0.734+)++After someone signs in to an AI in the Choose-your-AI dialog (the first-run one or the one this+page's button opens), Hydrogen opens a new chat with that AI when the dialog closes, Claude first+if several were signed in, with an empty chat box (1.0.745+). Nothing is typed for them.++On Linux the Adom Bridge row reads "not running" until Hydrogen has installed and started Adom+Bridge, which it does when a Linux build is published for the user's account; desktop features+(screenshots, KiCad, pup) wait for it. Everything else on the page does not depend on it.++## When it appears++- Automatically as the final setup step, the `open-welcome` gate (the last step of the+ setup cascade for the active runtime).+- Any time on request (below).++## How to open it++```bash+C=$(cat ~/.adom/hd-control-url)+adom-cli hydrogen webview open-or-refresh \+ --name Welcome \+ --url "$C/welcome.html?control=${C##*:}" \+ --panel-id desktop-pane-right+```++Setup's own step runs this same command. Then look: if the tab is listed but the pane still+shows the previous tab, run `adom-cli hydrogen workspace active-tab --name Welcome`.++## IMPORTANT: This is NOT++- NOT the adom.inc homepage (https://adom.inc)+- NOT the Adom wiki (https://wiki.adom.inc)+- NOT the VS Code welcome tab inside code-server++It is `static/welcome.html` from the Hydrogen repo, served locally by the control API.++## Panel type++Webview tabs in Hydrogen use panel type `adom/a1b2c3d4-0031-4000-a000-000000000031`.+Do NOT use `panelType: "webview"`: that shows "Unknown panel type" error.
skills/hydrogen-who-am-i/SKILL.mdadded+100@@ -0,0 +1,100 @@+---+name: hydrogen-who-am-i+description: >-+ How to answer "who am I and what can I do here?", the first question Hydrogen's welcome+ step asks: which data to pull, Linux vs Adom username, and a template answer. Use when+ asked who am I, what can I do here, what is this environment, or what can Hydrogen do.+---++# Hydrogen Who Am I — answer the welcome-step prompt coherently++When the user starts their first chat, Hydrogen can send this prompt into it:++> **who am i and what can i do here**++Your job is to answer that prompt with a warm, accurate, **personalized** intro that confirms identity, surfaces resources, explains the environment, and points at what's possible. This skill tells you exactly where to get the data and how to phrase the answer.++## Data sources++Run these first (they're all fast — under 5s total):++| Field | Command | Notes |+|-------|---------|-------|+| Name + email + Adom username | `adom-cli carbon user get` | Returns `{name, formatted_name, email, ...}`. Adom username = the `name` field. |+| Repo count | `adom-cli carbon user repos --format json \| jq length` | Or count lines without jq |+| Cloud containers | `adom-cli carbon containers list --format json \| jq length` | Number of cloud-hosted Adom containers under this user |+| Computer name | `hostname` | The workspace carries the name of the user's Linux computer |+| OS | `cat /etc/os-release \| grep PRETTY_NAME` | Always Ubuntu 24.04 |+| Other machines | `adom-bridge targets` | The user's other computers on the Adom mesh, if any |++If `adom-cli carbon user get` fails with no session token, the user isn't authenticated. In that case answer: "I don't see an Adom session — please log in via the Hydrogen login page first."++## The Linux-username-vs-Adom-username quirk (always mention this)++Every user's Linux username inside the Hydrogen workspace is **`adom`** — not their Adom username. This is intentional (consistency across all Adom workspaces makes filesystem paths, scripts, and skill examples portable). The user's Adom identity is John, Jane, etc.; their shell prompt just always says `adom@<workspace-hostname>`.++Mention this in the welcome answer so they don't get confused when their `whoami` says `adom`.++## What Hydrogen + the Adom ecosystem can do (the capabilities pitch)++Tell them they have access to a full electronics prototyping ecosystem. Specifically:++- **Build PCBs** — 3rd party fab workflow with tscircuit, KiCad, 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 Hydrogen (via adom-step / adom-tsci panels)+- **Reach their other computers**: through Adom Bridge on those machines (KiCad, Fusion 360,+ files, a pup browser), with `adom-bridge --target <machine>`+- **Talk to their cloud containers** — adom-cli reaches Adom-cloud-hosted containers under their account+- **Main AI dev environment** — Hydrogen is designed as the primary AI-powered dev surface for hardware + software++Adom Bridge runs on this computer only once Hydrogen has installed it (when a Linux build is+published for the user's account), so do not promise KiCad,+Fusion 360, desktop screenshots or file transfer to THIS desktop unless `adom-bridge ping`+answers here. Offer them on another of their machines when `adom-bridge targets` lists one.++## Answer template++Adapt this to whatever the user's data is. Don't bullet-dump everything — write it as a warm welcome paragraph followed by capabilities. Use markdown.++```markdown+You're **{user.formatted_name}**, signed in to Adom as **{user.name}** ({user.email}). You're running in **Hydrogen**, Adom's local AI dev environment, on your machine. The workspace itself is Ubuntu 24.04 with code-server, the `claude` CLI, and the full Adom skill ecosystem already loaded.++A few quick orientation notes:+- Your **Linux username here is `adom`** (not `{user.name}`) — that's intentional, every Adom workspace uses `adom` for consistency. Your Adom identity (`{user.name}`) is what shows up across the Adom ecosystem.+- You have **{N} repos** and **{M} cloud containers** under your Adom account.++Here's what we can do together in Hydrogen:++**Electronics & hardware**+- Build PCBs end-to-end (tscircuit → KiCad → Adom's autorouter → 3rd party fab)+- Browse parts (DigiKey, Mouser, JLCPCB) with live pricing + Adom-internal inventory+- Generate KiCad symbols, footprints, and 3D models from datasheets++**Apps & automation**+- Build webview apps for viewing symbols, footprints, 3D chips, boards, layouts, schematics, oscilloscopes, etc.+- Write CLI tools to automate hardware workflows+- View 3D STEP/GLB files in a Fusion-360-feel viewer++**Talk to your stuff**+- Reach your cloud Adom containers from here+- {only if adom-bridge targets lists machines} Drive KiCad, Fusion 360 or a pup browser on {machine}, and move files to and from it++Ask me to do any of those, or just ask "what's the best way to start a new PCB project?" if you want a guided tour.+```++## How to deliver the answer++- **Don't just bullet-dump every capability** — group them, lead with the personalized intro, end with an invitation.+- **Pull real numbers** from `adom-cli` — generic "you have some repos" feels worse than "you have 4 repos."+- **Don't list internal jargon** — say "Adom's autorouter", not the internal skill name.+- **Mention the Linux username quirk early** — it WILL confuse users on first `whoami`.+- **If a data fetch fails** (e.g. adom-cli not yet configured), gracefully say "I can't read your Adom session right now, but here's what Hydrogen can do once you're signed in" and pivot to capabilities only.++## Related skills++- [hydrogen-adom-auth](../hydrogen-adom-auth/SKILL.md) — the session token that gives `adom-cli` its identity+- [hydrogen-claude-auth](../hydrogen-claude-auth/SKILL.md) — Claude Code's own auth (separate)+- **hydrogen-overview** — the index of Hydrogen skills your AI has access to+- `hydrogen-container` — the exact Ubuntu image / arch / pre-installed tools you'll mention+- **hydrogen-bridges**: what Adom Bridge adds and where it runs
skills/hydrogen-widget/SKILL.mdadded+266@@ -0,0 +1,266 @@+---+name: hydrogen-widget+description: >-+ Build, list, open and drive Hydrogen Widgets, small live panels in the Title+ Bar (Claude usage, Codex usage, your own): the hydrogen-widget.json facet,+ launch contract, and /widgets API. Use when asked to make a widget, add a+ title bar widget, or about the usage meter widget.+---++# hydrogen-widget: small live panels in Hydrogen's Title Bar++The bar across the top of the Hydrogen window is the **Title Bar**: the Adom menu, the+widgets, the CPU/RAM/GPU meter, the bell, your avatar and the window controls. Its short form+(the chevron at the top edge) is the **compact Title Bar**. A **Hydrogen Widget** is a page+that lives in a slot of that bar, left of the meter, served by a binary that runs **inside the+workspace** (the systemd-nspawn workspace machine on this computer), the way a dock app serves its dashboard. Hydrogen+mounts it in a sandboxed iframe. The user opens and closes widgets from the **Hydrogen+Widgets** pulldown (the puzzle-piece icon); an AI does the same through the control API. Open+widgets are remembered per user and come back on the next start.++The name has a prefix on purpose: wiki-widget is the component-page widget, and future+surfaces (kicad-widget, fusion-widget) get their own. This skill is only about the Title Bar.++## The three that ship++| id | what it shows | source of the numbers | repo |+|---|---|---|---|+| `claude-usage` | 5-hour session, weekly, and every weekly limit scoped to a model on your plan (Fable, Opus, ...), as percent used, in the provider's severity colour | the Claude Code sign-in in `~/.claude/.credentials.json`, asked at `api.anthropic.com/api/oauth/usage`; the `limits` list in that answer is what Claude Code's `/usage` panel draws | a facet of adom/adom-vscode |+| `codex-usage` | the plan's rate-limit window as percent used, plus a secondary window when the plan has one | the Codex sign-in in `~/.codex/auth.json`, asked at `chatgpt.com/backend-api/wham/usage` (what `/status` shows) | a facet of adom/adom-vscode |+| `clock` | the time and date, stacked when tall, inline when compact; the one to copy | the workspace clock | a facet of adom/hydrogen-bootstrap |++Neither usage call runs a model, so neither costs quota. They ask at most once every three+minutes per provider, pause while the window is hidden, back off on errors (doubling to 15+minutes), and re-read the sign-in file only when it changes.++## Drive it from an AI (no mouse)++All on Hydrogen's control API (`$ADOM_HD_CONTROL_URL` inside the workspace, `ports.json` on+the host). Nothing in the pulldown needs a click.++```+GET /widgets # the list: id, name, wiki_repo, source, open, status, url+POST /widgets/refresh # re-read the curated list and the checkout+POST /widgets/open {"id":"claude-usage"} # mount, install, stop any old instance, launch, hand the slot over+POST /widgets/close {"id":"claude-usage"} # unmount and stop it+POST /widgets/navigate {"id":"...","url":"..."} # point an open slot at a URL yourself+POST /widgets/menu {"open":true} # show or hide the pulldown+GET /widgets/status # open ids, each status (closed|installing|starting|live|failed), menu state+```++UI bus: `widgets.menu.open` and `widgets.menu.close` (POST /ui/invoke {id}).++`POST /widgets/open` returns when the widget's page answers (`ok:true, url`) or when the+install, launch or health wait failed (`ok:false, error`); the slot stays mounted with the+reason so the user can see it, and `/widgets/close` removes it. The launch log is+`~/.adom/widgets/<id>.log` in the workspace.++## What happens on open, exactly++1. The slot mounts with a compact placeholder (a ring and a status line, sized by the slot).+2. `adom-wiki pkg install <install>` runs in the workspace, every open, so publishing a new+ version of your package is enough to update the widget.+ When Hydrogen restores widgets at start it installs only what is missing (the launch+ command's binary is looked up first) and runs installs one at a time; an open from the+ pulldown or the API always installs, so a new package version lands then.+3. Any previous instance is stopped first (`launch.stop`, else a `pkill` on the command's first+ word), so a new version actually gets the port. The slot's frame is remounted on the+ placeholder for the same reason: a stale page never stays put.+4. `launch.command` runs in its own session (`setsid -f nohup ...`, so an editor reload or an+ extension host restart cannot take it down) as the workspace user, from the repo folder when the widget+ came from the checkout, with `HYDROGEN_WIDGET_ID`, `HYDROGEN_WIDGET_PORT`,+ `HYDROGEN_WIDGET_SLOT` and `HYDROGEN_PROXY_PORT` in its environment plus the workspace env+ every login shell has (`ADOM_HD_CONTROL_URL`, `ADOM_HYDROGEN_URL`).+5. Hydrogen asks for `http://127.0.0.1:<port>/<health.url>` from inside the workspace until it+ answers 2xx or 3xx, up to `health.timeout_seconds`, then navigates the slot to+ `http://<port>.localhost:<proxy>/` (its subdomain port proxy). The probe runs in the+ workspace on purpose: the proxy's own error page while the workspace boots is not an answer.+ Before any of this, if the workspace is not running yet (a full quit and relaunch boots the+ workspace machine, which can take a minute), the slot says "Waiting for the workspace" and waits, up to+ ten minutes; nothing is installed or launched until it is up.+6. Your page owns the slot from then on: poll your own JSON, redraw, push whatever you want.+ Explicit takeover, when you want the slot before health is up or want another page:+ `POST $ADOM_HD_CONTROL_URL/widgets/navigate {"id": $HYDROGEN_WIDGET_ID, "url": "..."}`.++## Make one: the facet++Put a `hydrogen-widget.json` at the root of a wiki repo. It can sit next to a dock manifest+and a `hydrogen/workspace.json`, or be the whole repo. One widget:++```json+{+ "hydrogen_widget": "1.0.0",+ "id": "clock",+ "name": "Clock",+ "icon": "mdi:clock-outline",+ "brief": "The time and date, the smallest widget there is.",+ "width": 110,+ "width_tall": 84,+ "install": "adom/hydrogen-bootstrap",+ "launch": { "command": "hydrogen-widget-clock", "port": 8933 },+ "health": { "url": "/", "timeout_seconds": 60 },+ "docs": "widgets/README.md"+}+```++Several in one repo: `{"widgets": [ {...}, {...} ]}`. Each entry has its own `id`, name, mark,+launch command and port; they share the repo's package (`install`) and page (`docs`). The curated+list names a Hydrogen Widget by repo plus id, so each is its own row in the pulldown and opens and+closes on its own. adom/adom-vscode ships Claude usage and Codex usage this way because both read+an AI sign-in that lives next to the editor extension; a repo with one thing to show ships one.++| field | meaning |+|---|---|+| `id` | unique, lowercase, stable; the curated list and the control API address it |+| `name`, `brief` | the pulldown row and its hover text; `brief` is also the body of the hover card when the widget shows no live view there, so write it for a person |+| `icon` | an iconify name for the row (`mdi:clock-outline`), or `vendor:claude` / `vendor:codex` for the vendor marks the AI launch bar paints, so a person can tell whose numbers a widget shows |+| `launch.port` | the port your page serves on inside the workspace. Pick one far from where apps land: not the 8000s (dashboards, dev servers, the KiCad dashboard's 8931), not the ephemeral range (32768 and up). The shipped widgets sit at 27011 to 27013; take 27020 and up for yours. A widget is a side panel and must never cost an app its port (John 2026-09-15). |+| `width` | slot width in px in the compact Title Bar (one horizontal row); clamped to 48..320 |+| `width_tall` | slot width in the full Title Bar, where your page stacks its rows; defaults to 60 percent of `width` |+| `install` | the adom-wiki package that provides the command; defaults to the repo itself |+| `launch.command` | run in the workspace as the workspace user, backgrounded; `launch.stop` optional |+| `launch.port` | the port the page listens on, 127.0.0.1 inside the workspace |+| `health.url` | path Hydrogen polls until it answers (default `/`); `timeout_seconds` default 60 |+| `about` | one or two sentences on how it works, shown under Details on the hover card ("Reads the Claude Code sign-in ... asks the usage endpoint ... no quota is spent") |+| `refresh` | how often it asks anything, shown under Details on the hover card ("the provider at most once every 3 minutes; pauses while hidden; backs off on errors") |+| `docs` | the widget's own page: a repo file path (`widgets/README.md`) or a full URL. The pulldown row links to it. Defaults to `<repo>/files/widgets/README.md` |++### The widget's own page (what the pulldown row opens)++Every widget should ship a page a person can read before opening it. The convention is+`widgets/README.md` in the repo (the default `docs`), with: a picture of the widget in the full+and the compact Title Bar, what it shows and where the numbers come from, how often it asks+anything, the list of files in the repo that make it a widget, and a link back to this skill. The+two shipped examples: adom/adom-vscode `widgets/README.md` and adom/hydrogen-bootstrap+`widgets/README.md`.++### The page in the slot: two layouts, chosen by height++The slot is 38 px tall in the full Title Bar (like the meter) and 20 px in the compact one.+Size your page by its height, never in fixed px: `@media (min-height: 34px)` stack rows+(label, bar, value) to use the room; `@media (max-height: 33px)` one horizontal row with+`clamp()` font sizes. Transparent background, no scrollbars. The shipped helper does this;+copy it.++### The hover card (a tooltip that lives outside the iframe)++A tooltip inside your page cannot reach past the slot's edge, so Hydrogen draws the card:+hover the slot and, after a moment, a card appears under it in the host, in the style of the+tab cards. It is for the person looking at the widget, so it leads with what the widget shows:+the name and mark, then the widget's own live view when it asks for one (see "A bigger view on+hover" below), otherwise its `brief`. A status line under the name appears only while the+widget is not live (Installing, Starting, Waiting for the workspace, Could not start: reason).++Everything about how it runs sits under **Details** at the foot of the card, folded by default:+`brief` (when a live view took its place), `about`, `refresh`, the port and the log path, the+page URL, the repo, and four links: the widget's page (`docs`), the wiki repo, this SDK, and+Close widget. Opening Details pins the card, so those links are live as soon as they show.+Moving onto the card keeps it; a click on the card (or its pin) pins it; Escape or a click+outside closes a pinned card. Your page needs nothing for this beyond the manifest fields, so+write `brief` for a person ("how much of your limits you have used; hover for when they+reset"), and put the mechanics in `about` and `refresh`. An AI shows the same card with+`POST /widgets/card {"id": "...", "pinned": true}` and hides it with `{"id": "...", "open": false}`.++### Resizing: who tells the page++Nobody has to. The slot is an iframe; when the Title Bar goes compact or tall, Hydrogen resizes+the slot and the iframe's own `window` gets a normal `resize` event, and any height media+queries re-evaluate by themselves. Hydrogen posts no message on resize. So a page must:++- size itself by its own `innerHeight`/`innerWidth` (or the height media queries above), never+ by fixed pixel widths;+- give every column a natural width and let one flexible column absorb the rest+ (`grid-template-columns: auto minmax(14px, 1fr) auto`), so a value is never clipped when the+ slot is narrow; trim long labels with an ellipsis instead;+- re-render on `resize` if its render depends on the size (the shipped helper keeps the last+ data and re-renders after 80 ms of quiet, no refetch).++The page decides its own width per layout: after every render and resize, measure your content+and post `window.parent.postMessage({hdWidget: {width: <px>}}, '*')`; Hydrogen sizes the slot to+it (clamped 48..320) and knows which slot from the frame that sent it. The manifest's `width`+(compact) and `width_tall` (full) are only the first guess before your page has measured. So a+tall layout can be narrow (rows stacked) and the compact one wide (one row), which is what the+shipped helper does. Measure on a hidden copy of your content laid out at `width: max-content`+(clone the root, remove ids, `position:absolute; left:-10000px; height:100vh; width:max-content;+visibility:hidden`, read its width, remove it): the live boxes stretch to the slot, so measuring+them only ever grows the slot (the clock once asked for 361 px that way). The helper's+`postWidth()` is that code; keep it when you copy the helper. For pictures of your widget the+helper serves `/preview?h=38` and `/preview?h=20`: its page in a frame of that height that follows+the width the page asks for, so a browser screenshot of `#w` at a high device scale is a crisp+docs image (`?w=` pins the frame instead). The shipped widgets are+the reference: adom/adom-vscode `widgets/bin/hydrogen-widget-lib.py` is the page and layout,+`hydrogen-widget-claude-usage` and `hydrogen-widget-codex-usage` the data feeds, and+adom/hydrogen-bootstrap `bin/hydrogen-widget-clock` the smallest one.++### Who draws what: your two canvases++Your widget has two canvases and draws everything inside them: the **slot** in the Title Bar and,+if you ask for one, the **card** view on hover. Hydrogen draws only what surrounds them: the slot's+edge, its height (38 or 20 px) and its close button, and the card's frame, header (your `name` and+`icon`), pin and Details (your `about`, `refresh`, `docs`, plus the port and log). Anything inside a+canvas changes when you publish your package, with no Hydrogen release. The table and the diagram:+the Hydrogen Widgets page, `widgets/README.md` on adom/hydrogen, section "Who draws what".++### A bigger view on hover (optional; Hydrogen 1.0.609+ gives the card its own frame)++Ask for a live view in the hover card by adding `expand` to the same message:+`window.parent.postMessage({hdWidget: {width: 265, expand: {width: 560, height: 400}}}, '*')`.+When the card opens, Hydrogen loads a **second copy of your page** in the card at that size (width+clamped 280..720, height 120..600, at most 45% of the window height), or the page at `expand.path`+(`{width, height, path: "/card"}`, a path on your own origin) if you want a separate one. Your slot+keeps showing your page the whole time. Rules:++- keep `width` the compact title-bar width; never send the expanded width as `width`;+- switch layouts on height (`@media (min-height: 100px)` shows the big view), not on a message:+ the card copy is simply a taller frame of the same page;+- the card copy is a fresh page each time the card opens: keep state you need on your server;+- send `expand: null` to withdraw, and omit it to keep the plain card (your `brief` as text);+- the request is dropped whenever the slot frame loads, so post it again on your `load` event;+- only the slot frame's `width` and `expand` count; the card frame may only send+ `{hdWidget: {collapse: true}}` (forward Escape with it, since keys do not leave an iframe).++Before 1.0.609 Hydrogen moved the slot's own frame into the card, leaving the slot empty with a+"Expanded below" stand-in; pages written for that work unchanged, because they already pick the big+layout by height. Adom AI Flow and the usage widgets are the references.+Details: `docs/hydrogen-widget-expansion.md` in the Hydrogen source.++### Listing it++- **Your checkout**: any repo under `~/project` (one clone folder down too) with a+ `hydrogen-widget.json` appears in the pulldown as "(checkout)", no publish needed.+- **Everyone**: publish the repo (with the binary in its package), then file an issue on the+ adom/hydrogen-bootstrap page titled `List widget: <owner>/<repo>` with a one-line description+ and a picture of the slot (its `/preview?h=38`). That page's maintainers add+ `{ "id", "wiki_repo", "order" }` to `widgets/widgets.json`, the curated list Hydrogen reads,+ and the widget appears in every user's pulldown at their next refresh. From a workspace:+ `adom-wiki issue create adom/hydrogen-bootstrap --title "List widget: <owner>/<repo>" --body "..."`.+ The list only orders and names repos; every other fact comes from the repo's own manifest.+- **Just you, or your team (private)**: keep the repo private on the wiki (`adom-wiki page+ create --private`, `adom-wiki page share` for teammates). Hydrogen reads the curated list and+ every manifest **with the signed-in user's session**, so a private repo's widget lists and+ installs for the people the page is shared with and nobody else. Private widgets are not in+ the curated list; they come from your checkout, or from your own `widgets.json` if you fork+ the bootstrap for your org.++### A binary in fifty lines++The shipped widgets are Python 3 scripts (already in every workspace), one file each plus a+shared helper: an `http.server` that answers `GET /` with the page, `GET /data.json` with fresh+numbers (cached per interval, refreshed only when asked after the interval, exponential backoff+on errors), and `GET /health`. Copy `hydrogen-widget-clock` and `hydrogen-widget-lib.py` from+adom/hydrogen-bootstrap `bin/`, change `data()` and the render expression, add a+`hydrogen-widget.json`, a `widgets/README.md` and an `install.sh` line that symlinks your script+into `~/.local/bin`. That is the whole SDK.++## Ralph test++```+curl -s -X POST $ADOM_HD_CONTROL_URL/widgets/open -H 'content-type: application/json' -d '{"id":"clock"}'+curl -s $ADOM_HD_CONTROL_URL/widgets/status+curl -s http://27013.localhost:$(python3 -c "import json;print(json.load(open('/home/adom/.adom/hydrogen-ports.json'))['proxy'])")/data.json+```++Then look: a screenshot of the Hydrogen window shows the slot left of the meter, the chevron+makes the Title Bar compact and the slot follows, and `/widgets/close` makes it go away.++
skills/hydrogen-workspace-lifecycle/SKILL.mdadded+79@@ -0,0 +1,79 @@+---+name: hydrogen-workspace-lifecycle+description: >-+ Lifecycle of Hydrogen's Adom-Workspace systemd-nspawn machine on Linux:+ import, start, stop, restart, remove, the root helper, code-server as a+ systemd unit, and the rule to touch only Adom-Workspace. Read before any+ workspace operation. Use when the workspace is broken, unhealthy, or needs a+ restart.+---++# Hydrogen: Linux Workspace Lifecycle++The workspace is **`Adom-Workspace`, a systemd-nspawn machine** on the host kernel, its rootfs at `/var/lib/machines/Adom-Workspace`, its settings in `/etc/systemd/nspawn/Adom-Workspace.nspawn` (written by Hydrogen; edits are overwritten). Hydrogen drives it through one root helper, `/usr/libexec/adom-hydrogen/hydrogen-workspace`, run as `sudo -n` (the .deb/.rpm installs a sudoers rule for it; an AppImage asks once through pkexec). The helper manages **only** `Adom-Workspace` and refuses any other name.++## ABSOLUTE RULE: touch only Adom-Workspace++The user may run other containers (`machinectl list`, Docker, Podman, LXC). Never stop, remove or restart anything else, never `systemctl restart systemd-machined`, and never kill `systemd-nspawn` processes by name. Allowed, scoped (on the host):++- `sudo machinectl poweroff Adom-Workspace` / `terminate Adom-Workspace`+- `sudo machinectl start Adom-Workspace`+- `sudo machinectl export-tar Adom-Workspace <file>.tar` (backup)+- `sudo machinectl remove Adom-Workspace` (destructive wipe)++Prefer Hydrogen's own controls and API below; they also keep Hydrogen's state right.++## Lifecycle++### Import (fresh setup)+Setup step `ensure-workspace`: make the host ready (`systemd-container` package, the helper, its sudoers rule), download `adom-golden.tar.gz` (SHA256-verified, cached in `~/.local/share/Adom/HydrogenDesktop/cache/`), and the helper unpacks it into `/var/lib/machines/Adom-Workspace` (numeric owners, xattrs; a btrfs subvolume on btrfs; `restorecon` on SELinux hosts).++### Start+The helper boots the machine on the first command into it (`machinectl start`, waits until systemd inside is up). At every start it also installs the `adom_hydrogen` nft table (workspace ports closed to the LAN), sets the hostname to the host's, and re-applies the editor fixes.++### code-server is a systemd unit in the machine+`code-server.service` (127.0.0.1:7380), `adom-relay.service` and `adom-shotlog.service` belong to the machine's systemd; Hydrogen attaches to them and does not hold its own copies, so a Hydrogen restart does not kill the editor. Readiness means code-server answers on 7380, not just "machine running".++### Restart+Adom menu > **Restart Container** (or `POST /container-restart`): stop the machine, then setup_and_start again. VS Code disconnects for about 10 s. `/tmp` inside is emptied.++### Stop+Adom menu > **Stop Container**, or `POST /container-stop`. Hydrogen latches "user stopped" so its own probes do not boot the machine again; Start clears it. Files persist.++### Remove (DESTRUCTIVE)+Only through the Setup panel's **Virgin Reset** with "Workspace machine" checked (type to confirm): `machinectl remove Adom-Workspace`, which deletes `/home/adom/project` too. `POST /wsl/unregister` is refused on purpose (a headless wipe is not allowed).++## Control API++Read the live URL: `BASE="$(cat ~/.adom/hydrogen-control-url)"` (same `127.0.0.1` inside and outside the workspace).++| Endpoint | What it does |+|---|---|+| `GET /wsl/status` | registered? running? code-server reachable? (name kept for compatibility; answers for the nspawn machine) |+| `GET /workspace/health` | the deep check: `editor_will_load` and which layer failed |+| `GET /container-status` | state for the menu and badges |+| `POST /container-restart`, `/container-stop`, `/container-start` | lifecycle; `{"dry_run":true}` says what would happen |+| `GET /container-stats` | Live CPU/RAM/disk from the `workspace_stats()` probe (see hydrogen-container-stats) |++## Diagnosing Workspace Problems++- **Editor stuck or "restart needed" badge:** `GET /workspace/health`. If code-server is dead, Restart Container.+- **VS Code "Cannot reconnect" dialog:** Hydrogen notices it over a serving backend and reloads the editor pane itself (at most three times in a row, 45 s apart). If it stays, Restart Container.+- **Setup says the helper or systemd-container is missing:** reinstall the Hydrogen package (.deb/.rpm) or approve the password prompt, then Retry.+- **Machine did not boot:** on the host `sudo machinectl terminate Adom-Workspace`, then Retry in Setup. Logs: `journalctl -u systemd-nspawn@Adom-Workspace`.+- **Half-built import:** `sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace`, then Retry (this deletes the machine: only for a workspace that never finished setup).++## Recovery Checklist++When the workspace is broken, follow this order:++1. `GET /wsl/status` and `/workspace/health` (or `machinectl status Adom-Workspace` on the host).+2. Running but editor dead: Restart Container, or relaunch Hydrogen.+3. Verify code-server answers on 127.0.0.1:7380.+4. Last resort (destructive, the user's decision): back up `/home/adom/project`, then Virgin Reset with "Workspace machine".++## Related skills++- [hydrogen-workspace-monitoring](../hydrogen-workspace-monitoring/SKILL.md) — the 15s poll, floaty states, lifecycle dialog, auto-start+- [hydrogen-container-stats](../hydrogen-container-stats/SKILL.md) — title-bar CPU/RAM bars + `workspace_stats()` probe+- `hydrogen-volume`: what a reset deletes and how to back up
skills/hydrogen-workspace-monitoring/SKILL.mdadded+152@@ -0,0 +1,152 @@+---+name: hydrogen-workspace-monitoring+description: >-+ How Hydrogen on Linux monitors the workspace machine and code-server: the 15 s+ state poll, the 8 s backend watch, the stopped floaty, auto-start, editor+ auto-reload, and the lifecycle dialog. Use when asked why the workspace+ stopped, about the workspace floaty, Start or Restart workspace, or before+ changing workspace state code.+---++# Hydrogen Workspace Monitoring (Linux)++## Architecture++The workspace is Hydrogen's local code-server-backed dev environment. Hydrogen monitors+workspace health at two levels:++1. **Runtime available** — is the workspace runtime itself installed and+ responding on this machine?+2. **Workspace healthy** — is the workspace present AND Running AND is+ code-server reachable on its host port?++The second level is a real reachability check, not just "is the workspace+present." A resume reality-check (after sleep, or after a Hydrogen rebuild/relaunch)+requires code-server to actually answer before Hydrogen trusts the workspace as+healthy — a workspace can be Running while code-server is dead.++On Linux the runtime is present when `machinectl` and `systemd-nspawn` exist and the+helper answers; the workspace is healthy when the `Adom-Workspace` machine exists, is+running, and code-server answers on host port **7380**.++Status reads (is the image there, is it running) use unprivileged `machinectl`;+only actions (start, stop, exec, import, remove) go through the root helper.+Health probes read `/proc` and the shared loopback directly, with no exec.++The VS Code panel (`PanelVisualStudioCode.svelte`) polls workspace state every+15s and shows appropriate UI for each state. These frontend components are+runtime-agnostic; they front the active runtime via the runtime trait.++## Workspace State Poll++`PanelVisualStudioCode.svelte` calls `get_container_status` (Tauri command)+every 15s. The command dispatches through the runtime trait to the active+runtime impl. Returns a status struct shaped like:+```rust+pub struct ContainerStatus {+ pub runtime_available: bool, // machinectl + helper usable+ pub workspace_installed: bool, // the machine image is present+ pub container_exists: bool, // the machine exists (running or stopped)+ pub container_running: bool, // running AND code-server reachable+ pub container_id: Option<String>,+ pub error: Option<String>,+}+```+The `container_*` names are historical.++Every 8 s, once the editor has loaded, the panel also reads `GET /workspace/health`. Two+misses of `editor_will_load` (a real HTTP check of code-server) raise a banner over the+editor. A deliberate Stop has its own screen instead.++## Floaty States++All floaties appear INSIDE the VS Code panel only — not as full-app modals.+They are draggable (grab header to move). The rest of the app (wiki tab, menu,+etc.) remains fully interactive.++- **Workspace stopped** (the machine is not running): "Your Linux workspace has+ stopped. Your files are safe; Start brings it back." Start calls+ `POST /container-start`.+- **Editor not answering** (machine running, code-server not serving): a+ Reconnect banner. Its button posts `/wake/simulate`, which does nothing on+ Linux (see `hydrogen-wake-repair`); use Restart workspace instead.+- **Disk almost full**: the message names the drive and asks to free space on+ that disk.++A missing runtime or a workspace not built yet shows no floaty: that is the+setup cascade's job (see `hydrogen-setup`). There is no runtime repair button on+Linux.++Separately, a watcher looks every 15 s for VS Code's "Cannot reconnect" dialog+and reloads only the editor pane when code-server is serving (see+`hydrogen-wake-repair`).++## Auto-Start via `setup_and_start`++The "Start Workspace" path calls Tauri `setup_and_start`, which delegates to+the active runtime's `setup_and_start`:+- If the workspace isn't present yet, `fresh_import` = download the golden+ image + provision the workspace + start code-server.+- If the workspace is present but code-server is down, it just (re-)starts+ code-server.++On Linux it first makes sure the host is ready (the helper and its sudoers rule, one+pkexec prompt only if missing).++code-server runs as `code-server.service` inside the machine, so it does not die with+Hydrogen, and Hydrogen re-ensures it on every launch. See `hydrogen-workspace-lifecycle`+for the full lifecycle detail.++## Lifecycle Dialog++`ContainerLifecycleDialog.svelte` — a draggable floating card (no background+blur) that shows live command output for start/stop/restart operations on the+workspace.++### Events+Listens for `hydrogen-container-lifecycle` CustomEvents on `window`:+- `action: 'restart' | 'stop' | 'start'` — opens dialog, starts spinner+- `action: 'step', step: string` — appends a log line+- `action: 'done'` — stops spinner, shows Close button, auto-reloads VS Code+- `action: 'stopped'` — stops spinner (for stop-only operations)+- `action: 'error', message: string` — shows error state++### Title+Dynamic based on `actionType`:+- Restarting: "Workspace Restarting..." → "Restart Complete"+- Stopping: "Stopping Workspace..." → "Workspace Stopped"+- Starting: "Starting Workspace..." → "Workspace Started"+- On error: "Restart/Stop/Start Failed"++### VS Code Auto-Reload+After the `done` event, the dialog polls `/workspace/health` every 5s for up to 2 minutes+and reloads the editor once `editor_will_load` is true. After an error it keeps checking+for 15 minutes and closes itself if the workspace answers again.++## Tauri Commands++| Command | What it does |+|---|---|+| `get_container_status` | Returns workspace status — runtime available, workspace present, Running + code-server reachable |+| `setup_and_start` | Host prep, `fresh_import` if no machine yet, boot, start code-server |+| `stop_container` | Stops the workspace |++On Linux `stop_container` powers off `Adom-Workspace` (helper, `machinectl poweroff`, then+terminate if it hangs).++## Menu Items (Adom Menu → Workspace Section)+- **Restart Container**: stop the machine, then re-ensure code-server; emits lifecycle+ events, shows the dialog+- **Stop Container**: powers off the machine; emits lifecycle events, shows the dialog,+ then the stopped floaty+- **Start**: from the stopped floaty++## Settings+- `hydrogen.launch_on_boot` (Launch on boot), default off. On Linux it writes+ `~/.config/autostart/adom-hydrogen.desktop` (honoured by GNOME, KDE, Cinnamon).++## Related skills++- `hydrogen-workspace-lifecycle` — provision/export/remove/stop, the never-touch-global rule, control endpoints+- `hydrogen-container-stats` — the title-bar CPU/RAM bars and `workspace_stats()` probe+- `hydrogen-networking` — code-server port, control port