Adom Hydrogen (macOS / Lima)

The macOS platform layer (adompkg bootstrap) for Adom Hydrogen — converges a Lima/nspawn Linux workspace to "ready to run inside Hydrogen on a Mac". Depends on adom/hydrogen-bootstrap; bundles the macOS-runtime hd-* skills. Installed by the golden Lima image (hd-lima-image). Not an interactive skill — this is a bootstrap package.

Diagnose and repair the workspace's Adom API key (`/var/run/adom/api-key`) on macOS Adom Hydrogen — the injected session token that adom-cli and every Adom tool authenticate with. Use when adom-cli returns 401/unauthorized, `/var/run/adom/api-key` is missing or empty, "adom-cli can't reach Adom", or the user asks to reauthorize Adom / re-pull the API key. Covers: pulling the current token from Hydrogen via `GET /auth-token`, re-writing the key (passwordless sudo), prompting the user to sign in to Hydrogen when the host has no valid session, and triggering Hydrogen's inject-api-key setup step. Trigger words — api key, api-key, /var/run/adom, 401 unauthorized, adom-cli auth, reauthorize adom, re-auth adom, pull api key, session token missing, fix adom auth, carbon 401.

macOS platform companion to hydrogen-api — the Apple/Lima-specific half of reaching Hydrogen's control API. The full endpoint catalog lives in hydrogen-api (adom/hd-bootstrap); THIS skill carries only what differs on macOS: the adom-host gateway (vz doesn't mirror loopback), the ~/.adom/hd-control-url discovery file, Hydrogen binding 0.0.0.0, and the nspawn machine-runtime endpoints (the /workspace/* routes, legacy /wsl/* route names kept for wire-compat). Trigger words — hydrogen control api macos, adom-host, hd-control-url, reach Hydrogen from the workspace, machine runtime endpoints, vz loopback, workspace health macos.

macOS platform companion to hydrogen-browser-picker — the Apple-specific half of how Adom Hydrogen intercepts EVERY URL and routes it through the Browser Picker. The picker dialog, the 3 branded variants, the 5-second auto-countdown, the fresh-window toggle, and the prefs API all live in hydrogen-browser-picker (adom/hd-bootstrap); THIS skill carries only what's wired differently on macOS: the top frame is a WKWebView served over http://localhost (not WebView2), and the native-browser targets are launched via LaunchServices (`open -a`). Trigger words — browser picker macos, WKWebView interception, open -a, native browser macos, Safari Chrome Arc Edge, localhost top frame, shell.open macos.

macOS platform companion to hydrogen-captions — the Apple-specific note on Hydrogen's on-screen captions. The two caption surfaces, the SECONDS-vs-MILLISECONDS unit trap, ids, positions, and the adom-cli / HTTP commands all live in hydrogen-captions (adom/hd-bootstrap) and are platform-neutral; THIS skill carries only the one macOS difference: the full-DESKTOP overlay (adom-desktop desktop_caption) is a Win32 click-through window and is NOT implemented on macOS yet (the non-Windows build is a stub). The workspace caption (adom-cli hydrogen caption) works the same on macOS. Trigger words — caption macos, desktop_caption macos, desktop overlay mac, screen overlay mac, caption not showing mac, click-through caption mac.

Hydrogen's workspace stats indicator in the top-right of the title bar — two thin progress bars (CPU + RAM) labelled "Container" plus an info tooltip on hover that shows the workspace name, CPU vs total cores, RAM usage vs limit, disk usage, image/machine, ID, and creation date. Polls once per second when running, every 5 seconds when stopped. Status badges show stopped / starting / restarting / restart-needed states. Use this skill when the user asks about CPU/RAM usage, the resource bars in Hydrogen's title bar, workspace disk usage, the "restart needed" badge, why bars are red/yellow, or what's in the tooltip. Trigger words — container stats, workspace stats, container cpu, container ram, container disk, resource bars, cpu bar, ram bar, container tooltip, container indicator, top bar stats, restart needed badge, container stopped badge, container starting, workspace_stats, machine stats, machine runtime stats.

Context for Claude Code running inside a Adom Hydrogen workspace machine. Documents the exact OS (Ubuntu 24.04, code-server 4.112.0, the Adom-Workspace machine), explains how setup differs from Adom cloud containers (setup-steps), what bridges are available, and how to use the relay. Trigger on startup, adom-cli errors, bridge commands, screenshot requests, container-platform questions, code-server / VS Code extension issues, or when the AI needs concrete facts about its environment instead of guessing.

What to do when KiCad or Fusion 360 is NOT installed on this machine and the user's request needs it. NEVER just report "not installed" and skip — offer to install and do it. KiCad installs unattended via one command; Fusion 360 needs the user to run Autodesk's installer but you can fetch and open it for them. READ THIS whenever a kicad/fusion bridge command fails with not-installed, a tour/demo step involves KiCad or Fusion, or the user asks for schematics/PCBs/CAD and the tool is missing. Trigger words — kicad not installed, fusion not installed, fusion 360 missing, install kicad, install fusion, no EDA tools, check my EDA tools, eda not found, kicad_not_installed, fusion_not_installed, bridge app missing.

Port architecture, hostnames, and networking rules for Adom Hydrogen. MUST READ before adding ports, exposing a service to your macOS host, referencing host URLs from inside the workspace, or wiring any service communication. Trigger words — Hydrogen port, Hydrogen network, port mapping, proxy, 127.0.0.1, loopback, adom-host gateway, hd-control-url, VSCODE_PROXY_URI, relay URL, code-server proxy, container networking, ADOM_CARBON_URL, ADOM_HYDROGEN_URL, direct connect, 8770, 7380.

macOS platform companion to hydrogen-notifications — the Apple-specific half of how Adom Hydrogen reaches the user outside the window. The generic notify handler, payload shape, levels, and /ui/toast live in hydrogen-notifications (adom/hd-bootstrap); THIS skill carries only the macOS delivery mechanics: Notification Center toasts, the emergency Dock-icon attention bounce, and the System Settings → Notifications grant. Trigger words — macos notification, notification center, dock bounce, request attention macos, allow notifications macos, toast on mac.

macOS platform companion to hydrogen-open-url — the Apple-specific half of "open a URL in a native browser". The six ways to open a URL (Hydrogen webview tab, Hydrogen window, Pup, native browser, the Browser Picker, headless curl), the decide-for-the-user rule, the /open-url + /open-in-profile + prefs API all live in hydrogen-open-url (adom/hd-bootstrap); THIS skill carries only the macOS native-browser mechanics: launching via LaunchServices (`open` / `open -a "<App Name>"` / `--new-window` fresh windows), macOS browser-profile dirs, and the control-URL discovery file (~/.adom/hd-control-url). Trigger words — open url macos, open -a, native browser mac, Safari Chrome Arc Edge, fresh window mac, browser profiles mac, hd-control-url.

macOS platform companion to hydrogen-permissions — the Apple-specific half of the permission story. The generic skill (adom/hd-bootstrap) covers Hydrogen's webview auto-grant: inside Hydrogen a webview app NEVER sees a "site wants to use your microphone/camera/clipboard/location" prompt. THIS skill carries only what's macOS-specific: the OS-level TCC privacy model (Screen Recording, Accessibility, Automation, Camera, Microphone) granted under System Settings → Privacy & Security, how Hydrogen preflights/requests them (CGPreflightScreenCaptureAccess, AXIsProcessTrustedWithOptions), and that some need a relaunch / a stable signing identity to stick. Trigger words — macos permissions, TCC, screen recording permission, accessibility permission, automation permission, privacy and security, AXIsProcessTrusted, CGPreflightScreenCaptureAccess, grant accessibility, relaunch to take effect.

Dynamic port forwarding for Adom Hydrogen. A daemon inside the Adom-Workspace machine watches for new TCP listeners (OAuth callbacks from VS Code extensions like Codex, Copilot, GitLens) and notifies Hydrogen to create host-side TCP proxies. Covers the cases macOS/Lima port exposure can't: `127.0.0.1`-only listeners and exposure gaps. Makes localhost:{port} on the Mac reach the machine. Extensions just work — no manual setup. Trigger words: port forward, dynamic port, OAuth callback, Codex auth, extension auth, port mapping, localhost port, port watcher, port proxy.

How Hydrogen does port forwarding between your workspace machine and your Mac — Lima's `0.0.0.0` port exposure (no Docker `-p` map), the code-server `/proxy/<port>/` URL pattern that exposes any internal port, the port-forward registry for `127.0.0.1`-only services that macOS won't expose, and the PortMappingsDialog UI. Use when the user asks "why isn't my server reachable", "how do I expose port X", "what's localhost:7380", "register a port", "expose a port", or "the dynamic port dialog". Trigger words — port forwarding, ports, hydrogen ports, container port, proxy port, code-server proxy, /proxy/, port mappings dialog, port hints, expose port, register port, host port, dynamic port, ports.json, PortConfig, port resolver, localhost port not working.

macOS platform companion to hydrogen-recording — the Apple-specific half of recording screen + window video from Adom Hydrogen. The recorder ladder, codec choice, the max-duration cap, audio-only narration, and the "● Recording" indicator live in hydrogen-recording (adom/hd-bootstrap); THIS skill carries only what's true on macOS: Hydrogen's native recorder is NOT available here (it's #![cfg(windows)]), so recording goes through the in-app getDisplayMedia recorder, pup per-tab, or the AD desktop relay — and the Screen Recording TCC grant gates the desktop paths. Trigger words — record macos, screen recording mac, record kicad mac, native recording windows-only, screencapturekit, avfoundation, getdisplaymedia mac, screen recording permission, tcc grant recording, desktop_record_start macos.

macOS platform companion to hydrogen-screen-lock — the Apple-specific half of the display wake-lock that a getDisplayMedia capture asserts. The cross-platform story (Hydrogen is native → CDP screenshots hold no lock; the recording cap + "● Recording" indicator; the contention guard) lives in hydrogen-screen-lock (adom/hd-bootstrap); THIS skill carries only the macOS power-assertion mechanics: the IOKit IOPMAssertion (PreventUserIdleDisplaySleep), diagnosing the holder with `pmset -g assertions`, and `caffeinate`. Trigger words — macos display wake-lock, iopmassertion, preventuseridledisplaysleep, pmset assertions, caffeinate, display won't sleep mac, screensaver blocked mac, screen capture assertion safari.

macOS platform companion to hydrogen-self-screenshot — the Apple-specific half of Hydrogen screenshotting its own window, PLUS the token-efficient capture flow (`shot` — one call, prints a PNG path, never floods context with base64). The tool ladder, the `POST /screenshot` CDP endpoint, selector region-clips, the sharing gate, and the during-a-recording contention matrix live in hydrogen-self-screenshot (adom/hd-bootstrap); THIS skill carries the `shot` helper doctrine and the macOS capture internals: the `screencapture` CLI / CoreGraphics window path, the CDP `Page.captureScreenshot` content grab, how the per-panel selector crop resolves the rect via `dom.measure` (WKWebView has no CDP) and crops with the image crate, and the Screen Recording TCC grant. Trigger words — screenshot hydrogen mac, shot helper, token efficient screenshot, screencapture cli, coregraphics screenshot, wkwebview no cdp, dom.measure crop, page.capturescreenshot mac, screen recording permission screenshot, tcc screenshot grant.

What Hydrogen's setup steps did to prepare your workspace — the 18-step install sequence that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, hydrogen setup, claude code extension install, hydrogen workspace ready.

Hydrogen setup panel: 16 install steps, Run All, Rollback All, Virgin Reset with toggles, and automated testing patterns. MUST READ before running setup, testing steps, or doing virgin resets. Covers the step list, the virgin reset toggle panel, how to keep auth during resets, and how Run All handles failures. Trigger words — setup panel, install steps, run all, virgin reset, rollback, step failed, 18 steps, wipe, reset workspace, keep auth, test setup.

MUST READ before ANY Hydrogen work. Explains the three-layer topology: cloud Docker (where Claude runs), the user's Mac (where Hydrogen + Adom Bridge run), and the Hydrogen local workspace (the Adom-Workspace machine). Every command you run goes through the relay to the Mac. You CANNOT directly access the workspace machine — you must shell through the Mac. Trigger words — Hydrogen topology, cloud vs local, machine exec, nsenter, where am I, which workspace, adom-desktop relay, test from container, three tiers, architecture, mac machine.

macOS platform companion to hydrogen-ui — the Apple-specific half of DRIVING Hydrogen's UI. Every menu/dialog/panel id, the GET /ui/actions → POST /ui/invoke contract, and registerUiAction live in hydrogen-ui (adom/hd-bootstrap); THIS skill carries only what's macOS-specific: Hydrogen's webview is WKWebView with NO Chrome DevTools Protocol, so the legacy CDP .click() path is dead — you drive the UI via the platform-agnostic command bus (hd-ui-command → /ui/_result) and the backend invoke_ui_action RPC (e.g. dom.measure resolves a selector's rect WITHOUT CDP). Trigger words — drive Hydrogen UI macos, WKWebView, no CDP, dom.measure, hd-ui-command, invoke_ui_action, ui/invoke macos, click Hydrogen menu mac, open dialog mac.

How Hydrogen's machine workspace storage is laid out — what's persistent, what's ephemeral, where your work lives, what survives a workspace restart vs a virgin reset, and how to access your workspace files from your Mac host. Use when the user asks "where are my files", "did I lose my work", "how do I copy a file out of the workspace", or "what happens to my code if I virgin reset". Trigger words — machine filesystem, hydrogen volume, where are my files, workspace files, persistent storage, lost my work, /home/adom/project, machine filesystem, machine export, copy file out of workspace, where is my code, workspace backup, machine remove.

Workspace machine (`Adom-Workspace`) lifecycle management for Adom Hydrogen on macOS. Import/export/remove/terminate, code-server-as-HD-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run a global teardown; touch ONLY Adom-Workspace so the user's other Lima VMs / machines stay safe. MUST READ before any workspace operation. Trigger words — machine, workspace, Adom-Workspace, restart workspace, terminate machine, remove, machinectl import-tar, machinectl remove, code-server, workspace broken, workspace unhealthy, machine hung, fix workspace, /workspace/status.

How Adom Hydrogen monitors and manages the local workspace machine (`Adom-Workspace`) and code-server. Covers the 15s workspace state poll, the two health levels (Lima VM up, machine running + code-server reachable), the floaty states (Lima VM not available, machine stopped), auto-start via setup_and_start, auto-reload of the VS Code iframe, and the lifecycle dialog system. Read BEFORE touching PanelVisualStudioCode.svelte, ContainerLifecycleDialog.svelte, or any workspace state handling code. Trigger words: workspace stopped, lima vm not available, workspace monitoring, machine poll, workspace floaty, start workspace, code-server reachable, lifecycle dialog, workspace state, Adom-Workspace running.