Adom Hydrogen (macOS / Lima)

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/hydrogen-bootstrap); THIS skill carries only what differs on macOS: the adom-host gateway (vz doesn't mirror loopback), the ~/.adom/hydrogen-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, hydrogen-control-url, reach Hydrogen from the workspace, machine runtime endpoints, vz loopback, workspace health macos.

macOS note on Hydrogen's on-screen captions: the WORKSPACE caption (adom-cli hydrogen caption) is the supported surface here and behaves exactly as the generic hydrogen-captions skill documents. The desktop_caption verb is not a macOS surface — never plan a mac demo around it. Trigger words — caption macos, caption not showing mac, workspace caption.

Context for the AI running inside an Adom Hydrogen macOS workspace machine. Exact facts about the environment (Ubuntu 24.04 arm64 Rosetta-hybrid, code-server, the nspawn machine + Lima VM), how tooling got here (slim image + wiki converge), the bridge CLI, and how this differs from Adom cloud containers. Trigger on startup, adom-cli errors, bridge commands, container-platform questions, or whenever you need concrete environment facts 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, hydrogen-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/hydrogen-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 mechanics for opening a URL in a native browser from Adom Hydrogen: LaunchServices (`open` / `open -a "<App Name>"`), forcing a truly fresh window for auth flows, and the control-URL discovery file (~/.adom/hydrogen-control-url). The decision framework (webview tab vs window vs pup vs native, decide-for-the-user) lives in hydrogen-open-url (adom/hydrogen-bootstrap). Trigger words — open url macos, open -a, native browser mac, fresh window mac, Safari Chrome Arc Edge.

macOS platform companion to hydrogen-permissions — the TCC (Privacy & Security) layer under Hydrogen's webview auto-grant, and the ONE doctrine that governs it here: Adom Hydrogen itself NEVER prompts for or appears in the TCC lists — Adom Bridge is the machine's TCC identity (Screen Recording, Accessibility, Automation). Hydrogen's status commands are read-only preflights. Trigger words — macos permissions, TCC, screen recording permission, accessibility permission, privacy and security, grant accessibility, permissions deck.

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.

How to record video from Adom Hydrogen on macOS: the in-app getDisplayMedia recorder (records the Hydrogen workspace to a .webm in recordings/), pup per-tab screencasts, and the Adom Bridge whole-desktop recorder — plus the Screen Recording TCC grant that gates desktop capture. The recorder ladder, codecs, caps, and the "● Recording" indicator live in hydrogen-recording (adom/hydrogen-bootstrap). Trigger words — record macos, screen recording mac, record kicad mac, getdisplaymedia mac, desktop_record_start macos, recording blank mac, screen recording permission.

Token-efficient screenshots of the Hydrogen workspace on macOS: the `shot` wrapper (one Bash call → PNG path → Read; never base64 in context), panel / workspace / screen targets, selector crops, and the Screen Recording grant gotcha for blank captures. Trigger words — screenshot hydrogen mac, shot helper, token efficient screenshot, screenshot blank mac, capture panel.

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/hydrogen-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.

Safety rules for anything that touches the Mac host or the workspace machine's lifecycle from inside an Adom Hydrogen container — above all, NEVER run a global teardown (limactl/machinectl) on the host, and what to tell the user when the workspace feels broken. Trigger words — restart workspace, machinectl, limactl, workspace broken, workspace unhealthy, fix workspace, teardown.