Adom Hydrogen (macOS / Lima)

@@ -1,9 +1,9 @@ #!/usr/bin/env bash # install (scripts.install) for adom/hydrogen-mac-bootstrap — the macOS (Lima/nspawn) platform layer. #-# Runs as the workspace user after the dependency tree (adom/hd-bootstrap → adom/core,-# adom/adom-workspace-updater) has installed. The generic adom/hd-bootstrap layer already-# deployed the 31 platform-generic hd-* skills + the shared code-server config; THIS layer+# Runs as the workspace user after the dependency tree (adom/hydrogen-bootstrap → adom/core,+# adom/adom-workspace-updater) has installed. The generic adom/hydrogen-bootstrap layer already+# deployed the platform-generic hydrogen-* skills + the shared code-server config; THIS layer # only adds the macOS-runtime specifics on top: the Lima/nspawn-runtime skills and the # mac config seed for the machine. #@@ -33,7 +33,7 @@ log "deployed $n macOS-runtime hydrogen-* skills -> $SKILLS" # code-server's data dir is the standard Linux-workspace path inside the Lima/nspawn machine. WB_DIR="$HOME/.local/share/code-server" if [ -d "$WB_DIR" ]; then-  log "code-server workbench present at $WB_DIR (trusted-domains seed handled by adom/hd-bootstrap)"+  log "code-server workbench present at $WB_DIR (trusted-domains seed handled by adom/hydrogen-bootstrap)" else   log "code-server not found at $WB_DIR yet — skipping workbench seed (non-fatal)" fi@@ -176,4 +176,54 @@ for stale in "$HOME/.claude/skills/adom-desktop" "$HOME/.codex/skills/adom-deskt   fi done +# 0.1.22: platform hygiene (Kyle's 2026-08-25 container audit). A mac container+# must not teach windows facts:+#+# (a) The WINDOWS Bridge pkg (adom/adom-bridge — pulled onto mac boxes by+#     adom/nb-bridge's dependency) delivers ~15 windows-only skills+#     (SendInput verbs, -anywhere-windows, the windows sdk docs …). Purge every+#     skill delivered EXCLUSIVELY by it, data-driven from the pkg DB's+#     delivered_skills — never a hardcoded list, so pkg evolution stays covered.+#     (Skills BOTH pkgs deliver — the contested adom-bridge-* dirs — are NOT+#     touched here; Hydrogen re-asserts adom/adom-bridge-macos after any+#     nb-bridge install so the mac docs win those dirs deterministically.)+#+# (b) The base layer's windows-flavored twins: for every skill X-mac THIS+#     package ships, the base layer's X is the windows doc (hydrogen-api,+#     hydrogen-ui, hydrogen-recording, …). Purge X — the -mac fork is canonical+#     on this platform. Re-runs every converge, so base-layer updates that+#     re-deliver them are re-purged. Remove when hydrogen-bootstrap moves them+#     into hydrogen-windows-bootstrap (upstream request filed 2026-08-25).+INSTALLED_JSON="$HOME/project/adom_modules/.installed.json"+if [ -f "$INSTALLED_JSON" ] && command -v python3 >/dev/null 2>&1; then+  python3 - "$INSTALLED_JSON" <<'PY' || log "WARN: windows-bridge skill purge failed (non-fatal)"+import json, os, shutil, sys+pk = json.load(open(sys.argv[1]))+pk = pk.get('packages', pk)+owner = {}+for name, e in pk.items():+    for s in (e.get('delivered_skills') or []):+        owner.setdefault(s, []).append(name)+purged = []+for s, o in sorted(owner.items()):+    if o == ['adom/adom-bridge']:+        p = os.path.join(os.path.expanduser('~'), '.claude/skills', s)+        if os.path.isdir(p):+            shutil.rmtree(p)+            purged.append(s)+print("[hydrogen-mac-bootstrap] purged %d windows-only Bridge skills: %s"+      % (len(purged), ', '.join(purged) if purged else '(none present)'))+PY+fi+for macskill in "$HERE"/skills/*-mac/; do+  [ -d "$macskill" ] || continue+  base_name="$(basename "${macskill%/}")"+  base_name="${base_name%-mac}"+  base="$SKILLS/$base_name"+  if [ -e "$base" ]; then+    rm -rf "$base"+    log "purged windows-flavored base skill $base_name (the ${base_name}-mac fork is canonical on macOS)"+  fi+done+ log "macOS platform layer converged."

@@ -4,7 +4,7 @@   "type": "bootstrap",   "title": "Adom Hydrogen (macOS / Lima)",   "brief": "The macOS platform layer for Adom Hydrogen.",-  "version": "0.1.21",+  "version": "0.1.22",   "description": "The macOS platform layer for Adom Hydrogen, where the workspace runs in a Lima Ubuntu VM hosting the Adom-Workspace systemd-nspawn machine. Depends on adom/hydrogen-bootstrap (the platform-generic Hydrogen layer) and adds everything specific to the Lima/nspawn runtime: the container/networking/ports/setup/topology/volume/workspace-lifecycle hydrogen-* skills (the macOS-runtime bucket), the in-machine workspace-updater daemon, and the macOS code-server workbench seed. Sibling layers adom/hydrogen-windows-bootstrap (WSL2) and adom/hydrogen-ubuntu-bootstrap depend on the same adom/hydrogen-bootstrap. This is the package the golden Lima image installs.",   "org": "adom",   "tags": [

@@ -4,7 +4,7 @@   "slug": "hydrogen-mac-bootstrap",   "title": "Adom Hydrogen (macOS / Lima)",   "brief": "The macOS platform layer for Adom Hydrogen.",-  "version": "0.1.21",+  "version": "0.1.22",   "license": "proprietary",   "visibility": "public",   "metadata": {

@@ -51,7 +51,7 @@ signed in; a JSON `{"error":"no session token"}` object when not). The `adom` us has passwordless sudo:  ```bash-CTRL="$(cat ~/.adom/hd-control-url)"          # e.g. http://adom-host:<control> — see hydrogen-api-mac+CTRL="$(cat ~/.adom/hydrogen-control-url)"          # e.g. http://adom-host:<control> — see hydrogen-api-mac TOKEN="$(curl -sf "$CTRL/auth-token")" case "$TOKEN" in   ""|\{*) echo "NO SESSION on host — user must sign in to Hydrogen (see below)" ;;@@ -92,12 +92,12 @@ confirms they signed in.  `POST "$CTRL/setup/step/inject-api-key"` re-runs the injection through Hydrogen's Setup panel (the panel is force-shown; the user sees live progress; the step also-validates against carbon). Use this when you want the user-visible, HD-audited path+validates against carbon). Use this when you want the user-visible, Hydrogen-audited path instead of writing the file yourself. Do **NOT** use `POST /setup/run-step` — that endpoint is deprecated and hard-refused.  ## Related -- `hydrogen-api-mac` — `~/.adom/hd-control-url` discovery + the `adom-host` gateway (why+- `hydrogen-api-mac` — `~/.adom/hydrogen-control-url` discovery + the `adom-host` gateway (why   `127.0.0.1` doesn't reach Hydrogen from the machine). - `hydrogen-setup-steps` — where `inject-api-key` sits in the install cascade.

@@ -2,12 +2,12 @@ name: hydrogen-api-mac description: >   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+  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/hd-control-url discovery file, Hydrogen binding 0.0.0.0, and the+  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, hd-control-url, reach Hydrogen from the workspace,+  words — hydrogen control api macos, adom-host, hydrogen-control-url, reach Hydrogen from the workspace,   machine runtime endpoints, vz loopback, workspace health macos. --- @@ -26,13 +26,13 @@ a Mac.   the workspace reaches them through the **`adom-host` gateway**:   `http://adom-host:<dynamic>`. -## ⭐ Finding the control port — `~/.adom/hd-control-url`+## ⭐ Finding the control port — `~/.adom/hydrogen-control-url`  The port is dynamic. **From the workspace, read the discovery file** Hydrogen writes every launch (already pointed at the `adom-host` gateway):  ```bash-CTRL="$(cat ~/.adom/hd-control-url)"     # e.g. http://adom-host:<control>+CTRL="$(cat ~/.adom/hydrogen-control-url)"     # e.g. http://adom-host:<control> curl -sf "$CTRL/health" ``` @@ -56,4 +56,4 @@ resolves: `/test/probe-dialogs` classifies **macOS permission prompts** (Screen Recording / Accessibility / installer pkg) as blockers. -On macOS reachability is the `adom-host` gateway + `~/.adom/hd-control-url`, full stop.+On macOS reachability is the `adom-host` gateway + `~/.adom/hydrogen-control-url`, full stop.

@@ -5,7 +5,7 @@ description: >   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:+  (adom/hydrogen-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

@@ -4,7 +4,7 @@ description: >   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+  (adom/hydrogen-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,

@@ -95,10 +95,10 @@ If you want the same stats data your AI can hit directly via the control API:  ```bash # From inside the machine — query the control API on the host-curl -s "$(cat ~/.adom/hd-control-url)/container-stats"+curl -s "$(cat ~/.adom/hydrogen-control-url)/container-stats" ``` -(Reach the control API at the `adom-host` gateway — vz does NOT mirror loopback, so the machine's `/etc/hosts` maps `adom-host` to the gateway where Hydrogen's host listener lives. The port is **dynamic per launch**; read the live URL from `~/.adom/hd-control-url` — already pointing at the gateway host — rather than hardcoding it.)+(Reach the control API at the `adom-host` gateway — vz does NOT mirror loopback, so the machine's `/etc/hosts` maps `adom-host` to the gateway where Hydrogen's host listener lives. The port is **dynamic per launch**; read the live URL from `~/.adom/hydrogen-control-url` — already pointing at the gateway host — rather than hardcoding it.)  Returns JSON like: ```json

@@ -32,7 +32,7 @@ If you ever need to confirm: `cat /etc/os-release`, `uname -m` (expect `aarch64`  ## Setup is via Hydrogen's setup-steps -Hydrogen provisions this machine through its own **setup-steps** flow (Rust code in `adom-hydrogen/src-tauri/crates/hd-app/src/setup_steps_macos.rs`, with the runtime mechanics in `adom-hydrogen/src-tauri/crates/hd-app/src/runtime/macos.rs`), shown as the "Install Tools" panel in the Hydrogen UI. It is a **different code path** than cloud containers, which provision via the adompkg/wiki-package bootstrap (`adom/hd-bootstrap`).+Hydrogen provisions this machine through its own **setup-steps** flow (Rust code in `adom-hydrogen/src-tauri/crates/hd-app/src/setup_steps_macos.rs`, with the runtime mechanics in `adom-hydrogen/src-tauri/crates/hd-app/src/runtime/macos.rs`), shown as the "Install Tools" panel in the Hydrogen UI. It is a **different code path** than cloud containers, which provision via the adompkg/wiki-package bootstrap (`adom/hydrogen-bootstrap`).  The machine cascade is **18 steps** (state file `setup-steps-macos.json`) vs the legacy Docker flow's 24. Most tooling is NOT installed by a step — it's BAKED into `adom-golden.tar.gz` at image-build time (the 8 Adom CLIs, the claude CLI + Code extension, code-server, VS Code settings, and all `hd-*` skills). The Docker `pull-image` / `create-container` / `start-container` steps are collapsed into a single step 1, `ensure-workspace`, which runs `machinectl import-tar` of `adom-golden.tar.gz` if the machine isn't already present. The relay is started by the `start-relay` step. See `hydrogen-golden-image`. @@ -59,7 +59,7 @@ The adom-desktop relay runs on ports 8765 (WebSocket) / 8766 (HTTP) inside this Check health: `curl -sf http://127.0.0.1:8766/health` Check desktop connection: `adom-desktop ping` -The macOS host control API is reachable from inside the machine via the `adom-host` gateway alias — vz does NOT mirror loopback, so 127.0.0.1 inside the machine is NOT the Mac. The port is dynamic per launch, so read the live URL from `~/.adom/hd-control-url`: `BASE="$(cat ~/.adom/hd-control-url)"; curl "$BASE/health"`.+The macOS host control API is reachable from inside the machine via the `adom-host` gateway alias — vz does NOT mirror loopback, so 127.0.0.1 inside the machine is NOT the Mac. The port is dynamic per launch, so read the live URL from `~/.adom/hydrogen-control-url`: `BASE="$(cat ~/.adom/hydrogen-control-url)"; curl "$BASE/health"`.  ## Available bridge commands (when desktop is connected) 

@@ -6,7 +6,7 @@ description: >   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,+  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. ---@@ -85,11 +85,11 @@ listeners directly (the host binds `0.0.0.0`). Used for: - `ADOM_CARBON_URL=http://adom-host:{proxy_port}` - `ADOM_HYDROGEN_URL=http://adom-host:{proxy_port}` - Direct connect probe: `http://adom-host:8770/health`-- Hydrogen control API: the live URL in `~/.adom/hd-control-url` (`http://adom-host:<dynamic>`)+- Hydrogen control API: the live URL in `~/.adom/hydrogen-control-url` (`http://adom-host:<dynamic>`) -The control port is **dynamic per launch** — read it from `~/.adom/hd-control-url`+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/hd-control-url)"`.+alone is unreliable): `BASE="$(cat ~/.adom/hydrogen-control-url)"`.  ### From the host → machine services (via proxy) ```@@ -166,7 +166,7 @@ limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- <cmd>    Docker-ism Hydrogen doesn't use; inside the machine it resolves to the wrong interface.    Reach the host via the `adom-host` gateway (vz does NOT mirror loopback, so    `127.0.0.1` does NOT reach the host); read Hydrogen's live control URL from-   `~/.adom/hd-control-url`.+   `~/.adom/hydrogen-control-url`. 3. **NEVER assume the host's `127.0.0.1` is reachable from inside the machine.**    macOS/vz does NOT mirror loopback — use the `adom-host` gateway alias    (`adom-host:<port>`); the host binds `0.0.0.0` and the machine's `/etc/hosts`

@@ -3,7 +3,7 @@ name: hydrogen-notifications-mac description: >   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);+  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

@@ -5,11 +5,11 @@ description: >   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:+  (adom/hydrogen-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.+  (~/.adom/hydrogen-control-url). Trigger words — open url macos, open -a, native browser mac, Safari Chrome+  Arc Edge, fresh window mac, browser profiles mac, hydrogen-control-url. ---  # hydrogen-open-url (macOS) — opening URLs in native macOS browsers@@ -21,10 +21,10 @@ rationale for auth flows — is host-agnostic and lives in the generic **hydroge skill. Read that first; this skill only covers how the **native-browser path (#4)** launches on a Mac. -## Control-URL discovery — `~/.adom/hd-control-url`+## Control-URL discovery — `~/.adom/hydrogen-control-url` -Same as the generic skill: read the live base URL from `~/.adom/hd-control-url`-(`BASE="$(cat ~/.adom/hd-control-url)"`) — never hard-code the port. On macOS that file+Same as the generic skill: read the live base URL from `~/.adom/hydrogen-control-url`+(`BASE="$(cat ~/.adom/hydrogen-control-url)"`) — never hard-code the port. On macOS that file resolves to the **`adom-host` gateway** from inside the workspace machine, because the Apple `vz` VM does NOT mirror host loopback (`127.0.0.1` inside the machine is NOT the Mac, and Hydrogen's host services bind `0.0.0.0`). See `hydrogen-api-mac` for the gateway detail.

@@ -2,7 +2,7 @@ name: hydrogen-permissions-mac description: >   macOS platform companion to hydrogen-permissions — the Apple-specific half of the-  permission story. The generic skill (adom/hd-bootstrap) covers Hydrogen's webview+  permission story. The generic skill (adom/hydrogen-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,

@@ -30,7 +30,7 @@ because that `0.0.0.0` exposure has two gaps the watcher closes:    `localhost:{port}/auth/callback?code=...` but the Mac never had that port,    so it doesn't exist. 2. **Exposure lag / wedge.** macOS/Lima port exposure can lag or break-   even for `0.0.0.0` listeners (a real HD-logged failure mode:+   even for `0.0.0.0` listeners (a real Hydrogen-logged failure mode:    "code-server alive in the machine but the Mac can't reach 127.0.0.1:7380"). The    watcher gives Hydrogen a reliable host-side proxy that doesn't depend on Lima's    automatic exposure.@@ -120,7 +120,7 @@ The watcher reaches Hydrogen at the `adom-host` gateway plus the control port machine cannot reach Hydrogen at its own `127.0.0.1`; instead the machine's `/etc/hosts` maps `adom-host` to the gateway, and that's where Hydrogen's host listener lives. The control port is dynamic per launch; the live control URL-(already pointing at the gateway host) is in `~/.adom/hd-control-url`.+(already pointing at the gateway host) is in `~/.adom/hydrogen-control-url`.  ## Installation 

@@ -54,7 +54,7 @@ Examples: the machine, services that need to talk to "the host" use the `adom-host` gateway (`adom-host:<port>`) — macOS/vz does NOT mirror loopback, so `127.0.0.1` does NOT reach the Mac; the machine's `/etc/hosts` maps `adom-host` to the gateway — for-Hydrogen's own services (Hydrogen's live control URL is in `~/.adom/hd-control-url`), and the+Hydrogen's own services (Hydrogen's live control URL is in `~/.adom/hydrogen-control-url`), and the proxy URL for everything else.  ## The port-forward registry (for what Lima's exposure can't cover)@@ -85,7 +85,7 @@ adom-cli port-forward register 5555 --name "oauth-cb" --reason "127.0.0.1-only o ```  Visibility options:-- `external` — bind `localhost:5555` on the Mac via an HD-managed proxy AND+- `external` — bind `localhost:5555` on the Mac via an Hydrogen-managed proxy AND   keep the `/proxy/` URL working. Best for OAuth callbacks, native clients,   loopback-only servers. - `internal` — proxy URL only, no host binding. Best for webview panels that@@ -109,7 +109,7 @@ then navigate to the Ports tab. Shows:  - **Exposed ports** — `0.0.0.0` listeners Lima is exposing to the Mac - **Registered ports** — anything you've registered via `port-forward register`-  (HD-managed host proxies, for loopback-only / unreliable cases)+  (Hydrogen-managed host proxies, for loopback-only / unreliable cases)  Each row shows the direct URL (`http://localhost:<port>`) AND the proxy URL (`http://localhost:7380/proxy/<port>/`). Click either to open in your browser@@ -165,7 +165,7 @@ of truth every consumer reads. | Mac browser | A `0.0.0.0`-bound machine service | `http://localhost:N` (exposed by Lima) | | Mac browser | Any machine service (HTTP/WS) | `http://localhost:7380/proxy/N/` (proxy URL, preferred) | | Mac browser | A `127.0.0.1`-only machine service | `http://localhost:N` (only after `port-forward register ... external`) |-| Machine | Hydrogen's own control API (on macOS host) | `$(cat ~/.adom/hd-control-url)` → `http://adom-host:<dynamic>` (port is dynamic per launch) |+| Machine | Hydrogen's own control API (on macOS host) | `$(cat ~/.adom/hydrogen-control-url)` → `http://adom-host:<dynamic>` (port is dynamic per launch) |  ## Common bugs @@ -186,7 +186,7 @@ of truth every consumer reads.  **"`localhost:7380` shows nothing / code-server unreachable from the Mac"** - code-server is alive in the machine but Lima's port exposure wedged (a-  real HD-logged failure mode). The port-forward registry / port-watcher+  real Hydrogen-logged failure mode). The port-forward registry / port-watcher   daemon installs a host-side proxy to recover this — see `hydrogen-port-watcher`.   Or restart Hydrogen to re-establish the forward. 

@@ -4,16 +4,16 @@ description: >   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:+  in hydrogen-recording (adom/hydrogen-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+  goes through the in-app getDisplayMedia recorder, pup per-tab, or the Adom Bridge 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. --- -# hydrogen-recording (macOS) — no native recorder; use getDisplayMedia / pup / AD+# hydrogen-recording (macOS) — no native recorder; use getDisplayMedia / pup / Adom Bridge  This is the **macOS half** of `hydrogen-recording`. The recorder priority ladder, codec tradeoffs (h264 vs h265), the `maxSeconds` cap + `reason`, audio-only narration@@ -31,7 +31,7 @@ On macOS it is **not compiled in**: - `adom-cli hydrogen recording start --share …` routes to that endpoint, so it **fails   on macOS** — it does not produce a file. - **Per-window recording ("record kicad" scoped to one window) does not exist on-  macOS** — that capability is HD-native-only, hence Windows-only.+  macOS** — that capability is native-Hydrogen-only, hence Windows-only.  A ScreenCaptureKit / AVFoundation native recorder is the obvious macOS analog of the Windows WGC/DXGI path, but **it is not yet built.** Do not claim Hydrogen has a@@ -44,19 +44,19 @@ Per the source ladder, on macOS skip the native rungs and use: 1. **In-app `getDisplayMedia` recorder** — the Recording dropdown in the editor toolbar    (`EditorNav.svelte` + `recordingStore.ts`/`audioCaptureStore.ts`). Records the Hydrogen    workspace (and/or mic) → a single `.webm` uploaded to the workspace `recordings/`.-   This is the in-HD path. **It DOES assert a display wake-lock** while running (see+   This is the in-Hydrogen path. **It DOES assert a display wake-lock** while running (see    [hydrogen-screen-lock-mac]) — release it by stopping the recording. 2. **pup per-tab — `adom-desktop browser_record_start {sessionId}`** — a clean CDP    screencast of one Chrome tab, no wake-lock, coexists with everything.-3. **AD host desktop — `adom-desktop desktop_record_start {confirmDesktopNotTabRecording:true}`**+3. **Adom Bridge host desktop — `adom-desktop desktop_record_start {confirmDesktopNotTabRecording:true}`**    — the whole-desktop fallback on macOS. Whole-desktop ONLY (no per-window), Chrome-   `getDisplayMedia` → holds the wake-lock, writes a `.webm` into AD's bridges-cache+   `getDisplayMedia` → holds the wake-lock, writes a `.webm` into Adom Bridge's bridges-cache    (NOT `~/project/recordings/`). **Verify the cap first:** `adom-desktop status` must    list the `record` capability.  ## macOS gotcha — the Screen Recording TCC grant -The desktop-scoped paths (AD `desktop_record_start`, and any `getDisplayMedia` capture+The desktop-scoped paths (Adom Bridge `desktop_record_start`, and any `getDisplayMedia` capture of the screen) are gated by macOS **TCC: System Settings → Privacy & Security → Screen Recording** must allow the recording app. Without that grant the capture is black / empty even though the call "succeeds." If a desktop recording comes back blank, check

@@ -4,7 +4,7 @@ description: >   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+  the contention guard) lives in hydrogen-screen-lock (adom/hydrogen-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,@@ -30,7 +30,7 @@ This is the macOS analog of Windows' `SetThreadExecutionState(ES_DISPLAY_REQUIRE  On macOS Hydrogen itself does **not** assert this for screenshots (CDP is one-shot, assertion-free). It legitimately appears only when a **`getDisplayMedia` recording**-runs — the in-app recorder, an AD desktop recording, or a pup tab capture (see+runs — the in-app recorder, an Adom Bridge desktop recording, or a pup tab capture (see [hydrogen-recording-mac]). Release it by **stopping that recording**; a programmatic focus or the screensaver itself cannot clear another process's assertion. @@ -44,7 +44,7 @@ pmset -g assertions      # look for a PreventUserIdleDisplaySleep holder  - A **browser** holder (a Safari/Chrome "screen capture" assertion) = a `getDisplayMedia`   hold from web Hydrogen, the in-app recorder, or a pup tab — stop that capture (close-  the tab / `browser_record_stop` / stop the in-app recording), not an HD-shell problem.+  the tab / `browser_record_stop` / stop the in-app recording), not an Hydrogen-shell problem. - The **Hydrogen app process** holding `PreventUserIdleDisplaySleep` from a CDP **screenshot**   is unexpected (CDP capture holds no assertion) — capture it and file a bug. 

@@ -5,7 +5,7 @@ description: >   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);+  during-a-recording contention matrix live in hydrogen-self-screenshot (adom/hydrogen-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`

@@ -88,7 +88,7 @@ Setup writes its state to `~/Library/Application Support/adom-hydrogen/setup-ste  - `hydrogen-golden-image` — the baked-image model: what's pre-installed in `adom-golden.tar.gz` vs. what setup does - `hydrogen-container` — the workspace machine and runtime that setup configures-- `hydrogen-networking` — how the machine reaches the host (via the `adom-host` gateway alias; live control URL in `~/.adom/hd-control-url`) and how ports forward+- `hydrogen-networking` — how the machine reaches the host (via the `adom-host` gateway alias; live control URL in `~/.adom/hydrogen-control-url`) and how ports forward - `hydrogen-browser-picker` — used by step 12 (claude-auth) for the Claude auth OAuth flow - `hydrogen-adom-auth` — how the Adom session token (step 5) gets injected - `hydrogen-volume` — where your files live in the machine and what survives a virgin reset (or doesn't)

@@ -3,7 +3,7 @@ name: hydrogen-ui-mac description: >   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+  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

@@ -1,6 +1,6 @@ --- name: hydrogen-workspace-lifecycle-description: 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.+description: Workspace machine (`Adom-Workspace`) lifecycle management for Adom Hydrogen on macOS. Import/export/remove/terminate, code-server-as-Hydrogen-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. ---  # Adom Hydrogen — Workspace Machine Lifecycle@@ -60,7 +60,7 @@ then `machinectl import-tar Adom-Workspace adom-golden.tar.gz`, then start code- Log proof: `[golden-tarball] downloaded … SHA256 OK` → `[setup] machine setup_and_start completed` and `machinectl list` shows `Adom-Workspace` running. -### code-server is an HD-OWNED CHILD process+### code-server is an HYDROGEN-OWNED CHILD process code-server (`CODE_SERVER_CHILD` in `runtime/macos.rs`) runs as a child of Hydrogen, deliberately tied to Hydrogen's lifetime — **NOT a detached `nohup`** (a detached process dies when the machine tears down the session anyway). Consequence: every Hydrogen restart (rebuild / crash /@@ -95,7 +95,7 @@ so safe.) ## Control API  The Hydrogen control API is on loopback **`http://127.0.0.1:<dynamic>`** (NOT 9001). The-port is dynamic per launch — read the live URL from `~/.adom/hd-control-url`. From+port is dynamic per launch — read the live URL from `~/.adom/hydrogen-control-url`. From inside the machine, reach the host via the `adom-host` gateway alias (vz does NOT mirror loopback, so 127.0.0.1 inside the machine is NOT the Mac). @@ -106,7 +106,7 @@ mirror loopback, so 127.0.0.1 inside the machine is NOT the Mac). | `GET /container-stats` | Live CPU/RAM/disk from the `workspace_stats()` probe (see hydrogen-container-stats) |  ```bash-BASE="$(cat ~/.adom/hd-control-url)"   # http://127.0.0.1:<dynamic>+BASE="$(cat ~/.adom/hydrogen-control-url)"   # http://127.0.0.1:<dynamic>  # Workspace status (from inside the machine, via the adom-host gateway) curl -s "$BASE/workspace/status"

@@ -91,7 +91,7 @@ delegates to `MacosVmRuntime::setup_and_start`:   import-tar Adom-Workspace` + start code-server. - If the machine is present but code-server is down, it just (re-)starts code-server. -Importantly, code-server runs as an **HD-owned child process** (not a detached+Importantly, code-server runs as an **Hydrogen-owned child process** (not a detached `nohup`) — it dies with Hydrogen. So Hydrogen also **re-ensures code-server on every launch** (look for `[macos-startup] re-ensured code-server on launch` in the log). Without that, a freshly relaunched Hydrogen would show the machine running but the editor stuck on