Adom Hydrogen (macOS / Lima)

@@ -1,87 +1,40 @@ --- name: hydrogen-self-screenshot-mac description: >-  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/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`-  (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.+  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. --- -# hydrogen-self-screenshot (macOS) — screencapture / CoreGraphics + the CDP content path+# Screenshots on macOS — use `shot` -This is the **macOS half** of `hydrogen-self-screenshot`. The default flow — `adom-cli-hydrogen screenshot panel|workspace|screen` saving a PNG into the container's-`screenshots/` to `Read`, the `POST /screenshot {target,selector,b64,silent}` CDP-power-path, the sharing gate, and the multi-thread `capture_busy` / coexistence matrix-— is cross-platform and lives in the generic **hydrogen-self-screenshot** skill. Read that-first; this skill documents the token-efficient capture flow and what's Apple-specific-about how the bytes are grabbed.--## ⭐ ALWAYS capture with `shot` — 2 tool calls, ~20 bytes of output--**Never run `adom-cli hydrogen screenshot ...` bare.** It prints the capture as a-~300 KB base64 `dataUrl` JSON on stdout — that's ~85k tokens of noise in your context-per capture, plus a second decode step you'd have to improvise. This bootstrap installs-a wrapper that does the whole thing in one call and prints ONLY the PNG path:+**Never run `adom-cli hydrogen screenshot ...` bare** — it prints ~300 KB of+base64 into your context. This workspace installs a wrapper that prints ONLY+a PNG path:  ```bash-shot                        # whole workspace (all panels)  → /tmp/shot-workspace-<ts>.png-shot screen                 # entire screen (desktop, other apps)+shot                        # whole workspace (all panels)+shot screen                 # entire desktop (other apps too) shot panel --name "KiCad"   # one panel's content-shot workspace --reason "verify the flow viewer rendered"   # flags pass through+shot workspace --reason "verify the flow viewer rendered" ``` -Then **Read** the printed path — the Read tool attaches images efficiently. Total flow:-one Bash call + one Read. That's the floor; don't add steps.--- If no image comes back, `shot` exits 1 and prints the CLI's own JSON to stderr —-  usually the **sharing gate** (capture needs the user's sharing approval; pass-  `--reason "…"` so the approval dialog says why). Read the error, don't blind-retry.-- `SHOT_OUT=/path/out.png shot ...` overrides the output path if you need a stable name.-- If `shot` is missing (pre-0.1.3 workspace), re-converge: `adom-wiki pkg install-  adom/hydrogen-mac-bootstrap` — or inline the same pipe:-  `adom-cli hydrogen screenshot workspace 2>/dev/null | python3 -c "import sys,json,base64;d=json.load(sys.stdin);open('/tmp/ws.png','wb').write(base64.b64decode(d['dataUrl'].split(',',1)[1]));print('/tmp/ws.png')"`--## How Hydrogen grabs its own window on macOS--- **Whole-window / desktop:** Hydrogen uses the macOS **`screencapture` CLI** (and-  CoreGraphics window capture) to grab the Hydrogen window or the full screen — the macOS-  analog of the Windows `PrintWindow`/`BitBlt` path.-- **Webview / panel content:** the canonical content grab is **CDP-  `Page.captureScreenshot`** (the `/capture/viewport` · `/shot` path) — a one-shot,-  wake-lock-free capture of the rendered surface. This is the same `POST /screenshot`-  endpoint as everywhere; on macOS it backs the `target`/panel content capture.--## ⭐ The per-panel selector crop — `dom.measure`, not CDP--On Windows the `selector` region-clip can lean on CDP against the webview. On macOS the-Hydrogen shell uses **WKWebView, which exposes no CDP** to drive the page directly. So a-per-panel / per-selector crop resolves the rect a different way:--1. Resolve the element's rectangle via the **`dom.measure` ui-action RPC** (the-   UI-command bus measures the selector in the live DOM and returns its bounds).-2. Capture the content area (CDP `Page.captureScreenshot` / `screencapture`).-3. **Crop the captured image to that rect with the Rust `image` crate.**--So `{selector:".resource-bars"}` still clips to just that element — but the rect comes-from `dom.measure` and the crop is server-side in Rust, because WKWebView can't be-CDP-shot to a selector the way a Chromium webview can.+Then **Read** the printed path. Total flow: one Bash call + one Read — that's+the floor, don't add steps. -## macOS gotcha — the Screen Recording TCC grant+- Selector crops work: pass `--selector ".resource-bars"` style flags through+  — the crop lands server-side.+- On failure `shot` exits 1 and prints the CLI's own JSON to stderr — usually+  the sharing gate (pass `--reason "…"` so the approval dialog says why).+  Read the error; don't blind-retry.+- `SHOT_OUT=/path/out.png shot ...` pins the output path.+- If `shot` is missing, re-converge:+  `adom-wiki pkg install adom/hydrogen-mac-bootstrap`. -The OS-level capture (`screencapture` / CoreGraphics) is gated by macOS **TCC: System-Settings → Privacy & Security → Screen Recording** must allow Adom Hydrogen. Without-that grant a window/screen capture comes back **black or empty** even though the call-"succeeds." If screenshots are blank, check the Screen Recording grant first — it's the-same grant the desktop recording paths need ([hydrogen-recording-mac]).+## Blank/black capture? → the Screen Recording grant +OS-level screen capture is gated by **System Settings → Privacy & Security →+Screen Recording** (granted to Adom Bridge — see `hydrogen-permissions-mac`).+Without it, captures "succeed" but come back black. Check that grant first.

@@ -1,73 +1,38 @@ --- name: hydrogen-workspace-lifecycle-description: Workspace machine lifecycle for Adom Hydrogen on macOS — boot/stop/restart semantics, per-container systemd units, code-server under its own unit, recovery after sleep, and the hard scoping rules (NEVER a global teardown; touch only Hydrogen's own machines). MUST READ before any workspace operation. Trigger words — machine, workspace, Adom-Workspace, restart workspace, terminate machine, machinectl, code-server, workspace broken, workspace unhealthy, fix workspace.+description: 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. --- -# Hydrogen Workspace Lifecycle (macOS)+# Workspace lifecycle — the rules from inside -The workspace is a systemd-nspawn machine inside the `hydrogen-builder` Lima-VM. Hydrogen may manage SEVERAL such machines (one per container in the-profile menu; the default is `Adom-Workspace`). Each machine boots under its-OWN transient unit, and each serves its own code-server port.+Your machine is managed by Adom Hydrogen on the user's Mac (a systemd-nspawn+machine inside the `hydrogen-builder` Lima VM). You don't manage its+lifecycle — Hydrogen does. Two things you DO need: -## ABSOLUTE RULE — never a global teardown+## 1. If you touch the host, NEVER a global teardown -Operate ONLY on Hydrogen's own machines. Forbidden, no exceptions: stopping or-deleting the `hydrogen-builder` Lima VM; `machinectl terminate/remove` on any-machine Hydrogen doesn't own; blanket-killing machinectl/nsenter processes;-re-provisioning the VM. The user may have other Lima VMs and machines-(Docker-for-Mac included) — a "cleanup" that touches them looks like Hydrogen-broke their computer.+You can reach the Mac via `adom-bridge shell_execute`. If a task ever leads+you toward host-side VM/machine commands, the hard rules: -Allowed, scoped: `machinectl stop/terminate <machine>`, `machinectl remove-<machine>` (destructive, that machine only), `machinectl import-tar`,-and in-machine exec via-`limactl shell hydrogen-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc '<cmd>'`.-There is no `docker exec` in this runtime.+- ❌ never stop/delete the `hydrogen-builder` Lima VM (kills every machine in+  it, including things Hydrogen doesn't own)+- ❌ never `machinectl terminate/remove` any machine you don't positively know+  is Hydrogen's, and never as a "cleanup"+- ❌ never blanket-kill machinectl/nsenter processes+- ❌ never remove your OWN machine from inside — you'd be sawing off the+  branch you're sitting on, and destroying `/home/adom/project` -## code-server runs under systemd — it self-heals+The user may run other Lima VMs and machines (Docker-for-Mac included). A+"helpful" teardown looks like Hydrogen broke their computer. -code-server runs under the machine's **`code-server@adom` unit** with-`Restart=always` (RestartSec=4) and a converged drop-in pinning-`--bind-addr 0.0.0.0:<the container's port>`. A crash comes back in ~4s-whether Hydrogen is running or not; the editor pane's health watcher reloads-itself on recovery. Hydrogen also re-ensures the unit (and adopts any raw-orphan process holding the port) on every launch and every boot.+## 2. When the workspace feels broken, hand it to the user -## Lifecycle semantics+Editor dead, host unreachable, everything timing out after the laptop slept:+the fix lives in Hydrogen, not in here. Tell the user plainly: -- **Boot** — Hydrogen boots the machine under its per-container unit-  (`systemd-run … systemd-nspawn --boot`), serialized per machine; different-  machines can boot and run concurrently.-- **Restart Workspace** (menu) — synchronous stop (stop → terminate → unit-  kill escalation, waiting out the unit) then re-boot + code-server ensure.-  This is the fix for a workspace gone unreachable after laptop sleep.-- **Stop** — the machine deregisters; its files persist. Closing a container's-  window stops that container; quitting Hydrogen stops every machine, then the-  VM (per the user's quit choice).-- **Remove** (destructive) — `machinectl remove <machine>` deletes the machine-  and everything in it including `/home/adom/project`. Only via the-  confirm-gated flows (container delete, virgin reset).+> Open the Adom menu in Hydrogen and click **Restart Workspace** — that+> rebuilds the connection cleanly. -## Diagnosing--- Editor stuck "Starting AI Environment" → is the machine registered-  (`machinectl list`)? Is code-server answering on the container's port from-  the Mac? Restart Workspace covers the common wedge.-- The real health line in Hydrogen's log is `[macos] Workspace unhealthy …`;-  the authoritative runtime line is `[app] Active workspace runtime: MacosMachine`.-- Recovery order: check the VM (`limactl list` — never stop it) → check the-  machine → Restart Workspace → last resort, remove + re-import (destructive).--## Control API--Base URL from `~/.adom/hydrogen-control-url` (adom-host gateway from inside a-machine). `GET /workspace/status` and `GET /workspace/health` report the-FOCUSED window's container. `POST /workspace/unregister` is deprecated and-refused — destructive resets go through the setup panel's virgin reset.--## Related skills--- `hydrogen-workspace-monitoring` — how Hydrogen's UI watches this state-- `hydrogen-container` — what's inside the machine-- `hydrogen-setup-steps` — how a machine gets built in the first place+Then re-verify your side (`adom-cli carbon user get`,+`curl "$(cat ~/.adom/hydrogen-control-url)/health"`). For a dead Adom token+specifically, see `hydrogen-api-key-mac`.